Apply changesets and update CHANGELOG [skip ci]

mayank1513 · mayank1513 · commit fd8364823bb5 · 2025-06-07T09:18:46.000Z
diff --git a/lib/README.md b/lib/README.md
@@ -10,7 +10,9 @@
 
 ### **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. Weighing in at just **~450 bytes minzipped**, it’s built for developers who care about performance, clean APIs, and full React 18+ compatibility.
+**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.
+
+Live demo: [https://kosha-six.vercel.app](https://kosha-six.vercel.app)
 
 ---
 
@@ -22,6 +24,7 @@
 - [⚖️ Zustand Comparison](#️-why-choose-kosha-over-zustand)
 - [📁 Examples](#-examples)
 - [❓ FAQ](#-faq)
+- [🚧 Known Limitations](#-known-limitations)
 - [🤝 Contributing](#-contributing)
 - [📜 License](#-license)
 
@@ -30,30 +33,40 @@
 ## 🚀 Features
 
 1. **Ultra-Lightweight**
-   - Minzipped size: ~**420–571 bytes**, making it ideal for performance-critical applications.
 
-2. **Zero Unnecessary Re-renders**
-   - Based on React’s `useSyncExternalStore`, Kosha ensures components only re-render when selected state changes.
-   - Example:
-     ```tsx
-     const count = useKosha(state => state.count);
-     ```
+   - Minzipped size: **\~420–460 bytes**, ideal for bundle-sensitive projects.
+
+2. **Optimized by Default: Zero Unnecessary Re-renders**
+
+   - Uses `useSyncExternalStore` for subscription handling and memoization.
+   - No need to manually optimize with `shallow` equality — Kosha uses `JSON.stringify` internally to compare selector outputs.
 
 3. **Partial State Updates**
-   - Update only what you need—no need to manually spread previous state:
+
+   - Update only what you need without spreading old state:
+
      ```tsx
      set({ count });
      set(state => ({ count: state.count + 1 }));
      ```
 
-4. **Flexible Consumption API**
-   - Select specific fields or use the entire store:
+4. **Concurrent Rendering Ready**
+
+   - Fully supports React 18+ and concurrent features.
+
+5. **Flexible Consumption API**
+
+   - Consume whole store or optimized slices via selectors.
+
      ```tsx
-     const { count, setCount } = useKosha();
+     const count = useKosha(state => state.count); // optimized - re-renders only when count changes
+     const { count, setCount } = useKosha(); // re-renders for every state change
      ```
 
-5. **Concurrent Rendering Ready**
-   - Fully compatible with React 18+ and the concurrent features thanks to `useSyncExternalStore`.
+6. **Middleware Architecture (BYO Middleware)**
+
+   - Middleware support is built-in. While Kosha doesn’t yet include a plugin ecosystem like Zustand, you can define and compose custom middlewares easily.
+   - Includes working [persist middleware](https://github.com/mayank1513/kosha/blob/main/lib/src/middleware/persist.ts) example out-of-the-box
 
 ---
 
@@ -65,13 +78,13 @@ Install using your preferred package manager:
 pnpm add kosha
 ```
 
-or
+**_or_**
 
 ```bash
 npm install kosha
 ```
 
-or
+**_or_**
 
 ```bash
 yarn add kosha
@@ -92,55 +105,36 @@ const useKosha = create(set => ({
 }));
 ```
 
-### 2. Consume the Store (No Selector)
+### 2. Consume the Store (Full Access)
 
 ```tsx
-const Counter = () => {
-  const { count, increment } = useKosha();
-
-  return (
-    <div>
-      <p>Count: {count}</p>
-      <button onClick={increment}>Increment</button>
-    </div>
-  );
-};
+const { count, increment } = useKosha();
 ```
 
-### 3. Use Selectors
+> This will trigger re-render even when count or increment are not changed but other states [part of the same store] change.
 
-```tsx
-const Counter = () => {
-  const count = useKosha(state => state.count);
-  const increment = useKosha(state => state.increment);
-
-  return (
-    <div>
-      <p>Count: {count}</p>
-      <button onClick={increment}>Increment</button>
-    </div>
-  );
-};
-```
+### 3. Select Specific State
 
-### 4. Enable Direct Updates via `set`
+```tsx
+const count = useKosha(state => state.count);
+const increment = useKosha(state => state.increment);
 
-Kosha no longer exposes `.set` by default. To update the state externally, expose `set` explicitly:
+// or use shorthand
+const { count, increment } = useKosha(({ count, increment }) => ({ count, increment }));
+```
 
-```ts
-import { create } from "kosha";
+### 4. Enable External Set Access (Optional)
 
+```tsx
 const useKosha = create(set => ({
   count: 0,
   increment: () => set(state => ({ count: state.count + 1 })),
-  set, // Exposed manually
+  set, // manually exposed
 }));
 ```
 
 ### 5. Update Outside React
 
-Update the store from anywhere (outside React) using `getState()`:
-
 ```ts
 useKosha.getState().increment();
 ```
@@ -149,69 +143,124 @@ useKosha.getState().increment();
 
 ## ⚖️ Why Choose Kosha Over Zustand?
 
-Kosha offers a streamlined alternative for projects where **performance, simplicity**, and **minimal bundle size** matter most.
+| Feature             | Kosha                     | Zustand                           |
+| ------------------- | ------------------------- | --------------------------------- |
+| Size (minzipped)    | \~450 bytes               | \~0.6–2.5kB+ (depending on usage) |
+| Optimized Selectors | ✅ Built-in via stringify | ⚠️ Manual / shallow equality      |
+| Partial Updates     | ✅                        | ✅                                |
+| Middleware Support  | ✅ (custom)               | ✅ (rich plugin ecosystem)        |
+| Devtools            | ❌ (custom only)          | ✅                                |
+| Plugin Ecosystem    | 🚧 (in development)       | ✅                                |
 
-| Feature                          | Kosha        | Zustand                                          |
-| -------------------------------- | ------------ | ------------------------------------------------ |
-| Size (minzipped)                 | \~420 bytes  | \~1.1–1.5 kB                                     |
-| Built-in Optimized Selectors     | ✅            | ⚠️ Needs shallow equality or manual optimization |
-| Partial Updates                  | ✅ (native)   | ✅                                                |
-| React 18+ `useSyncExternalStore` | ✅            | ✅                                                |
-| Learning Curve                   | Super simple | Simple                                           |
+Kosha is perfect for apps that prioritize bundle size, simplicity, and predictable updates without the need for extensive tooling.
 
-**Example (Selector-Based Optimization in Kosha):**
+---
+
+## 📁 Examples
+
+Explore the [`examples/`](https://github.com/react18-tools/kosha/tree/main/examples) directory for working codebases, including component and selector examples.
+
+---
+
+## ❓ FAQ
+
+### 1. Is Kosha production-ready?
+
+Yes. Kosha is small, stable, and well-tested.
+
+### 2. Does Kosha support async logic?
+
+Absolutely. Define `async` functions inside the store:
 
 ```tsx
-const fullName = useKosha(state => state.firstName + state.lastName);
+const useStore = create(set => ({
+  fetchUser: async () => {
+    const user = await fetch("/api/user").then(res => res.json());
+    set({ user });
+  },
+}));
 ```
 
-Zustand may still trigger re-renders here unless carefully optimized. See [Zustand’s official docs](https://github.com/pmndrs/zustand/blob/main/docs/guides/prevent-rerenders-with-use-shallow.md) for details.
+### 3. Does Kosha support middleware like Zustand?
 
----
+Yes. Middleware support is built-in. A working persist middleware is included. You can easily build your own or extend with logging, devtools, etc.
 
-## 📁 Examples
+### 4. Can I use it with `Set`, `Map`, or `Date` objects?
 
-You can find real-world usage examples inside the [`examples/`](https://github.com/react18-tools/kosha/tree/main/examples) directory of this repository.
+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?
+
+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.
 
 ---
 
-## ❓ FAQ
+## 🚧 Known Limitations
 
-### 1. Is Kosha production-ready?
+Kosha is intentionally minimal by design — built to offer just what most React apps need, without bloat. That comes with a few tradeoffs:
+
+### 🧠 Selector Comparison via `JSON.stringify`
+
+Kosha uses `JSON.stringify` internally to compare selector outputs for change detection. This works extremely well for the majority of cases — even with moderately large or deeply nested selectors.
 
-Yes! Kosha is stable, lightweight, and tested—suitable for production environments.
+However, there are a few caveats:
 
-### 2. Does Kosha support async actions?
+- **Avoid non-serializable values** in selectors like `Set`, `Map`, `WeakMap`, or circular objects.
+- **Very large selector outputs** may incur performance costs during diffing.
 
-Yes. Define asynchronous logic inside your store methods using `async/await` or promise chains.
+> To clarify:
+> ✅ It’s perfectly fine to have a large store or global state.
+> ⚠️ What matters is the **output of your selector**. If you’re selecting a large slice like `state => ({ a: state.a, ..., z: state.z })`, it’s more efficient to either:
+>
+> - Access the store directly without a selector (`useKosha()`), or
+> - Extract only the minimal fields you actually need.
 
-### 3. What happens if I don't expose `set`?
+### 🔌 Plugin Ecosystem Still Growing
 
-You won’t be able to update the store from outside React context. Expose `set` explicitly if needed.
+Kosha includes full support for custom middleware and already ships with a working [persist middleware](https://github.com/mayank1513/kosha/blob/main/lib/src/middleware/persist.ts). However:
 
-### 4. Does Kosha support React Server Components?
+- Built-in plugins like `devtools` are not yet included.
+- A community-driven plugin ecosystem is still in its early stages.
 
-Kosha is designed for client-side state management. Server Component integration isn’t a current goal, but discussions are welcome.
+> That said, the underlying architecture is solid and middleware-ready — you're free to build and compose your own middleware as needed.
 
 ---
 
 ## 🤝 Contributing
 
-We welcome contributions from the community!
+We welcome contributions!
+
+- 💬 Start a [discussion](https://github.com/react18-tools/kosha/discussions)
+- 🐛 Report bugs on the [issue tracker](https://github.com/react18-tools/kosha/issues)
+- 🧪 Submit PRs to improve or extend Kosha
+
+Got an idea for a middleware plugin or improvement? We'd love to collaborate.
+
+---
+
+## 🧠 Internals & Caveats
+
+### 🔍 Why use `JSON.stringify` for selector comparison?
+
+Kosha compares previous and next selector outputs using `JSON.stringify` to prevent unnecessary re-renders. This approach has several benefits:
+
+- It's **fast** and works for most serializable primitives and plain objects.
+- It ensures **deep comparison** out-of-the-box without manual equality functions.
+
+### ⚠️ What about key order in objects?
 
-* 💬 Start a [discussion](https://github.com/react18-tools/kosha/discussions)
-* 🐛 Report issues on the [Issue Tracker](https://github.com/react18-tools/kosha/issues)
-* 🧪 Submit PRs to improve or extend Kosha
+This is a common concern, but not an issue in Kosha:
 
-> Have an idea for a feature or roadmap suggestion? Open a discussion and help shape Kosha’s future.
+> Kosha always compares results of the **same selector function**, so the key order is preserved unless your selector behaves non-deterministically (e.g., relies on `Object.keys()` or mutation).
+> As long as your selector returns a consistent structure, `JSON.stringify` comparison will be reliable.
 
 ---
 
 ## 📜 License
 
 Kosha is licensed under the **MPL-2.0** license.
 
-<img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Explore [our courses](https://mayank-chaudhari.vercel.app/courses) or [support development](https://github.com/sponsors/mayank1513).
+<img src="https://raw.githubusercontent.com/mayank1513/mayank1513/main/popper.png" style="height: 20px"/> Explore [my courses](https://mayank-chaudhari.vercel.app/courses) or [support development](https://github.com/sponsors/mayank1513).
 
 ---
 
