docs(changeset): ✨ **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.

Author: mayank1513

.changeset/moody-poets-agree.md

@@ -0,0 +1,25 @@
+---
+"kosha": minor
+---
+
+✨ **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.

lib/package.json

@@ -53,6 +53,7 @@
     "esbuild-plugin-rdi": "^0.0.0",
     "esbuild-plugin-react18": "0.2.6",
     "esbuild-plugin-react18-css": "^0.0.4",
+    "immer": "^10.1.1",
     "jsdom": "^26.1.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",

lib/src/index.ts

@@ -18,14 +18,23 @@ export type Immutable<T> = {
     : T[K];
 };
 
+export type Mutable<T> = {
+  -readonly [K in keyof T]: T[K] extends object
+    ? T[K] extends Function
+      ? T[K]
+      : Mutable<T[K]>
+    : T[K];
+};
+
 export type BaseType = Omit<object, "__get">;
 type ListenerWithSelector<T, U> = [listener: () => void, selectorFunc?: (state: T) => U];
+
 export type StateSetterArgType<T> = ((newState: Immutable<T>) => T | Partial<T>) | Partial<T> | T;
 
 export type StateSetter<T> = {
-  _(state: StateSetterArgType<T>, replace?: false): void;
-  _(state: ((newState: Immutable<T>) => T) | T, replace: true): void;
-}["_"];
+  (state: StateSetterArgType<T>, replace?: false): void;
+  (state: ((newState: Immutable<T>) => T) | T, replace: true): void;
+};
 
 export type StoreCreator<T extends BaseType> = (
   set: StateSetter<T>,

lib/src/middleware/immer.ts

@@ -0,0 +1,30 @@
+import { produce } from "immer";
+import { BaseType, Mutable, StateSetter as KoshaStateSetter } from "..";
+
+type StateSetterArgType<T> = ((draft: Mutable<T>) => void | T) | Partial<T> | T;
+
+type StateSetter<T> = {
+  (state: StateSetterArgType<T>, replace?: false): void;
+  (state: ((draft: Mutable<T>) => void | T) | T, replace: true): void;
+};
+
+type StoreCreator<T extends BaseType> = (
+  set: StateSetter<T>,
+  get: () => T | null,
+) => T & { __get?: () => T | null };
+
+export const immer =
+  <T extends BaseType>(storeCreator: StoreCreator<T>) =>
+  (set: KoshaStateSetter<T>, get: () => T | null) => {
+    const immerSet: StateSetter<T> = (fnOrState, replace?) => {
+      const current = get()!;
+      let nextState = fnOrState instanceof Function ? produce(current, fnOrState) : fnOrState;
+
+      if (replace) set(nextState as T, true);
+      else set(nextState as Partial<T>);
+    };
+
+    return {
+      ...storeCreator(immerSet, get),
+    };
+  };

lib/src/middleware/index.ts

@@ -1 +1,2 @@
 export * from "./persist";
+export * from "./immer";

packages/shared/src/client/demo/compare/index.tsx

@@ -14,7 +14,7 @@ const P1 = ({ p1, setP1 }: Pick<ComponentProps, "p1" | "setP1">) => {
   renderCountRef.current++;
   return (
     <div>
-      <p className="display">
+      <p>
         p1:
         <button onClick={() => setP1(crypto.randomUUID())}>Update</button>
         {p1.slice(25)} | renderCount is {renderCountRef.current}
@@ -28,7 +28,7 @@ const P2 = ({ p2, setP2 }: Pick<ComponentProps, "p2" | "setP2">) => {
   renderCountRef.current++;
   return (
     <div>
-      <p className="display">
+      <p>
         p2:
         <button onClick={() => setP2(Math.random())}>Update</button>
         {p2.toFixed(6)} | renderCount is {renderCountRef.current}
@@ -79,7 +79,7 @@ export const Compare = () => (
       <P2ExtractAsObj type="kosha" />
       <hr />
       <h4>Extract as Array</h4>
-      <code>{`const [p2, setP2] = myStore(({ p2, setP2 }) => [p2, setP2] )`}</code>
+      <code>{`const [p2, setP2] = myStore(({ p2, setP2 }) => [p2, setP2])`}</code>
       <P1ExtractAsArray type="kosha" />
       <P2ExtractAsArray type="kosha" />
       <hr />
@@ -92,19 +92,39 @@ export const Compare = () => (
       <h2>Zustand</h2>
       <h4>Extract as Object</h4>
       <code>{`const { p2, setP2 } = myStore(({ p2, setP2 }) => ({ p2, setP2 }))`}</code>
-      <ErrorBoundary fallback={<p>⚠️Something went wrong</p>}>
+      <ErrorBoundary
+        fallback={
+          <div>
+            <p>⚠️Something went wrong</p>
+          </div>
+        }>
         <P1ExtractAsObj type="zustand" />
       </ErrorBoundary>
-      <ErrorBoundary fallback={<p>⚠️Something went wrong</p>}>
+      <ErrorBoundary
+        fallback={
+          <div>
+            <p>⚠️Something went wrong</p>
+          </div>
+        }>
         <P2ExtractAsObj type="zustand" />
       </ErrorBoundary>
       <hr />
       <h4>Extract as Array</h4>
-      <code>{`const [p2, setP2] = myStore(({ p2, setP2 }) => [p2, setP2] )`}</code>
-      <ErrorBoundary fallback={<p>⚠️Something went wrong</p>}>
+      <code>{`const [p2, setP2] = myStore(({ p2, setP2 }) => [p2, setP2])`}</code>
+      <ErrorBoundary
+        fallback={
+          <div>
+            <p>⚠️Something went wrong</p>
+          </div>
+        }>
         <P1ExtractAsArray type="zustand" />
       </ErrorBoundary>
-      <ErrorBoundary fallback={<p>⚠️Something went wrong</p>}>
+      <ErrorBoundary
+        fallback={
+          <div>
+            <p>⚠️Something went wrong</p>
+          </div>
+        }>
         <P2ExtractAsArray type="zustand" />
       </ErrorBoundary>
       <hr />

packages/shared/src/client/demo/compare/store.ts

@@ -1,4 +1,4 @@
-import { create as createKosha } from "kosha";
+import { create as createKosha, StoreCreator } from "kosha";
 import { create as createZustand } from "zustand";
 
 type SetStateAction<T> = (state: T | ((s: T) => T)) => void;
@@ -27,9 +27,7 @@ const defaultState: ICompareStore = {
   a: [],
 };
 
-const storeCreator = (
-  set: SetStateAction<Partial<ICompareStore & ICompareStoreActions>>,
-): ICompareStore & ICompareStoreActions => ({
+const storeCreator: StoreCreator<ICompareStore & ICompareStoreActions> = set => ({
   ...defaultState,
   setP1: p1 => set({ p1 }),
   setP2: p2 => set({ p2 }),

packages/shared/src/client/demo/demo.tsx

@@ -17,6 +17,8 @@ import PersistedCounterCode from "./persist?raw";
 import { Compare } from "./compare";
 import compareCode from "./compare?raw";
 import compareStoreCode from "./compare/store?raw";
+import { CounterWithImmer } from "./immer";
+import CounterWithImmerCode from "./immer?raw";
 
 const compareExCode = [
   { filename: "compare.tsx", code: compareCode },
@@ -61,6 +63,10 @@ export function Demo() {
         <PersistedCounter />
         <CodeDisplay code={[{ filename: "index.tsx", code: PersistedCounterCode }]} />
       </div>
+      <div className={styles.demo}>
+        <CounterWithImmer />
+        <CodeDisplay code={[{ filename: "index.tsx", code: CounterWithImmerCode }]} />
+      </div>
     </>
   );
 }

packages/shared/src/client/demo/immer/index.tsx

@@ -0,0 +1,28 @@
+import { create } from "kosha";
+import { immer } from "kosha/middleware";
+
+interface CounterStore {
+  count: number;
+  setCount: (count: number) => void;
+}
+
+const useKoshaWithImmer = create(
+  immer<CounterStore>(set => ({
+    count: 0,
+    setCount: (count: number) =>
+      set(state => {
+        state.count = count;
+      }),
+  })),
+);
+
+export const CounterWithImmer = () => {
+  const { count, setCount } = useKoshaWithImmer();
+  return (
+    <div>
+      <h2>Example using immer middleware</h2>
+      <div>Count: {count}</div>
+      <button onClick={() => setCount(count + 1)}>Increment</button>
+    </div>
+  );
+};

packages/shared/src/client/demo/persist/index.tsx

@@ -23,6 +23,7 @@ export const PersistedCounter = () => {
   const { count, localCount, setCount, setLocalCount } = usePersistedKosha();
   return (
     <div>
+      <h2>Example using persist middleware</h2>
       <div>Count: {count}</div>
       <button onClick={() => setCount(count + 1)}>Increment</button>
       <div>Local Count: {localCount}</div>