docs(changeset): Improve type inference and documentation.

Author: mayank1513

.changeset/gold-moons-swim.md

@@ -0,0 +1,5 @@
+---
+"kosha": patch
+---
+
+Improve type inference and documentation.

README.md

@@ -189,6 +189,10 @@ Yes. Middleware support is built-in. A working persist middleware is included. Y
 
 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.
+
 ---
 
 ## 🚧 Known Limitations
@@ -234,6 +238,24 @@ 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?
+
+This is a common concern, but not an issue in Kosha:
+
+> 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.

lib/src/index.ts

@@ -21,7 +21,13 @@ export type StoreCreator<T extends BaseType> = (
 
 export type Middleware<T extends BaseType> = (storeCreator: StoreCreator<T>) => StoreCreator<T>;
 
-export const create = <T extends BaseType>(storeCreator: StoreCreator<T>) => {
+export const create: <T extends BaseType>(
+  storeCreator: StoreCreator<T>,
+) => {
+  (): T;
+  <U>(selectorFunc: (state: T) => U): U;
+  getState: () => T | null;
+} = <T extends BaseType>(storeCreator: StoreCreator<T>) => {
   const listeners = new Set<ListenerWithSelector<T, unknown>>();
   const stateRef: { k: T | null } = { k: null };
   let get = () => stateRef.k;
@@ -45,13 +51,13 @@ export const create = <T extends BaseType>(storeCreator: StoreCreator<T>) => {
   stateRef.k = rest;
   get = __get ?? get;
 
+  const map = new Map<(state: T) => unknown, unknown>();
   /**
    * A React hook to access the store's state or derived slices of it.
    * @param {(state: T) => U} [selectorFunc]
    * A function to extract a slice of the state for optimization.
    * @returns {U | T} The selected slice or the entire state.
    */
-  const map = new Map<(state: T) => unknown, unknown>();
   const useHook = <U = T>(selectorFunc?: (state: T) => U): U => {
     const getSlice = () => {
       const newValue = selectorFunc!(get()!);

packages/shared/src/client/demo/basic-example/counter.tsx

@@ -12,7 +12,7 @@ const useKosha = create<CounterStore>(set => ({
 
 /** Counter Controller */
 export const CounterController = () => {
-  const { count, setCount } = useKosha();
+  const [count, setCount] = useKosha(({ count, setCount }) => [count, setCount]);
   return <input type="number" value={count} onChange={e => setCount(Number(e.target.value))} />;
 };