RELEASING: Releasing 2 package(s)

Releases:
  kosha@1.2.0
  @repo/shared@0.0.12

Author: mayank1513

.changeset/moody-poets-agree.md

@@ -8,7 +8,7 @@
 ![Bundle Size](https://img.shields.io/bundlephobia/minzip/kosha)
 [![Gitpod Ready](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/from-referrer/)
 
-### **A Modern, Lightweight, and High-Performance State Management Library for React**
+> **_⚡Kosha_**: **A Modern, Lightweight, and High-Performance State Management Library for React**
 
 **Kosha** is a production-ready, minimalistic global state management solution for modern React applications. At just **\~450 bytes minzipped**, it's optimized for performance-critical applications, full React 18+ support, and clean developer ergonomics.
 
@@ -21,6 +21,7 @@ Live demo: [https://kosha-six.vercel.app](https://kosha-six.vercel.app)
 - [🚀 Features](#-features)
 - [📦 Installation](#-installation)
 - [🧑‍💻 Usage](#-usage)
+- [🧰 Immer Middleware](#-immer-middleware)
 - [⚖️ Zustand Comparison](#️-why-choose-kosha-over-zustand)
 - [📁 Examples](#-examples)
 - [❓ FAQ](#-faq)
@@ -125,22 +126,88 @@ const increment = useKosha(state => state.increment);
 const { count, increment } = useKosha(({ count, increment }) => ({ count, increment }));
 ```
 
-### 4. Enable External Set Access (Optional)
+### 4. Update Outside React
 
-```tsx
-const useKosha = create(set => ({
-  count: 0,
-  increment: () => set(state => ({ count: state.count + 1 })),
-  set, // manually exposed
+```ts
+useKosha.getState().increment();
+```
+
+## ⚠️ Avoid In-Place Mutations
+
+Kosha detects changes using shallow comparison (`JSON.stringify`) between the **previous and new result of the selector**.
+If you mutate state **in-place** and return the same object reference, **listeners will not be triggered**, and your UI will not re-render — even though the state has technically changed.
+
+### 🔴 Problem Example
+
+```ts
+create(set => ({
+  todos: [],
+  addTodo: item =>
+    set(state => {
+      state.todos.push(item); // ❌ in-place mutation
+      return state; // same reference!
+    }),
 }));
 ```
 
-### 5. Update Outside React
+### ✅ Correct Way – Return a New Object
 
 ```ts
-useKosha.getState().increment();
+create(set => ({
+  todos: [],
+  addTodo: item =>
+    set(state => ({
+      ...state,
+      todos: [...state.todos, item], // ✅ returns a new object
+    })),
+}));
 ```
 
+### ✅ Even Better – Use Immer
+
+```ts
+import { produce } from "immer";
+
+create(set => ({
+  todos: [],
+  addTodo: item =>
+    set(
+      produce(state => {
+        state.todos.push(item);
+      }),
+    ),
+}));
+```
+
+> ℹ️ Kosha does not bundle `immer` by default, but you can use it safely with your own setup or use immer middleware.
+
+---
+
+## 🧰 Immer Middleware
+
+Kosha provides a convenient **immer middleware** to simplify immutable state updates by enabling you to write mutative logic inside the store setter. It internally applies `immer`'s `produce` function automatically.
+
+Example usage:
+
+```ts
+import { create } from "kosha";
+import { immer } from "kosha/middleware";
+
+const useKosha = create(
+  immer(set => ({
+    todos: [],
+    addTodo: (item: string) =>
+      set(state => {
+        state.todos.push(item); // safe mutable update with immer middleware
+      }),
+  })),
+);
+```
+
+This middleware allows you to write concise, mutable-looking update code while keeping the state immutable under the hood.
+
+You can combine `immer` middleware with other middlewares like `persist` for powerful state management.
+
 ---
 
 ## ⚖️ Why Choose Kosha Over Zustand?
@@ -187,11 +254,15 @@ const useStore = create(set => ({
 
 Yes. Middleware support is built-in. A working persist middleware is included. You can easily build your own or extend with logging, devtools, etc.
 
-### 4. Can I use it with `Set`, `Map`, or `Date` objects?
+### 4. My state updates, but components don’t re-render. Why?
+
+You might be mutating the existing state object **in-place** instead of returning a new one. Kosha relies on reference comparison (`JSON.stringify`) to detect changes. Always return a new object, or use libraries like **immer** or the **immer middleware** from `kosha/middleware` to handle immutable updates safely.
+
+### 5. Can I use it with `Set`, `Map`, or `Date` objects?
 
 While `Date` serializes fine, **avoid storing `Set` or `Map`** directly in global state, since Kosha uses `JSON.stringify` to diff selector outputs. Use arrays or plain objects instead for best results.
 
-### 5. Isn’t JSON.stringify unreliable because key order might change?
+### 6. Isn’t JSON.stringify unreliable because key order might change?
 
 No — in Kosha, you’re comparing outputs of the same selector function across renders. Since the order of keys in JavaScript objects is preserved in deterministic function outputs, JSON.stringify remains stable and reliable in this context.
 

README.md

@@ -1,5 +1,31 @@
 # kosha
 
+## 1.2.0
+
+### Minor Changes
+
+- 303dd10: ✨ **Feature:** Introduced `immer` middleware for Kosha
+
+  You can now opt-in to immutable state updates via [Immer](https://github.com/immerjs/immer).
+
+  This enables writing simpler, more intuitive state updates using mutable-like syntax:
+
+  ```ts
+  const useStore = create(
+    immer(set => ({
+      count: 0,
+      increment: () =>
+        set(state => {
+          state.count++;
+        }),
+    })),
+  );
+  ```
+
+  💡 Listeners will still be triggered correctly as Immer tracks mutations internally and returns new state safely.
+
+  Use with care: avoid returning any value from the mutator function to ensure Immer can do its job properly.
+
 ## 1.1.2
 
 ### Patch Changes

lib/CHANGELOG.md

@@ -2,7 +2,7 @@
   "name": "kosha",
   "author": "Mayank Kumar Chaudhari <https://mayank-chaudhari.vercel.app>",
   "private": false,
-  "version": "1.1.2",
+  "version": "1.2.0",
   "description": "A modern, lightweight, fast, and powerful global state management library for modern React.js projects. ",
   "license": "MPL-2.0",
   "main": "./dist/index.js",

lib/package.json

@@ -1,5 +1,12 @@
 # @repo/shared
 
+## 0.0.12
+
+### Patch Changes
+
+- Updated dependencies [303dd10]
+  - kosha@1.2.0
+
 ## 0.0.11
 
 ### Patch Changes

packages/shared/CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "@repo/shared",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "private": true,
   "sideEffects": false,
   "main": "./dist/index.js",