dev-react-microstore 5.0.0 → 6.0.0

package/src/index.ts

@@ -8,19 +8,11 @@ type MiddlewareFunction<T extends object> = (
   next: (modifiedUpdate?: Partial<T>) => void
 ) => void;
 
-function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): T {
-  let timeoutId: ReturnType<typeof setTimeout> | undefined;
-  return ((...args: Parameters<T>) => {
-    clearTimeout(timeoutId);
-    timeoutId = setTimeout(() => fn(...args), delay);
-  }) as T;
-}
-
 /**
  * Creates a new reactive store with fine-grained subscriptions and middleware support.
  * 
  * @param initialState - The initial state object for the store
- * @returns Store object with methods: get, set, subscribe, select, addMiddleware
+ * @returns Store object with methods: get, set, subscribe, select, addMiddleware, onChange
  * 
  * @example
  * ```ts
@@ -32,20 +24,106 @@ function debounce<T extends (...args: any[]) => void>(fn: T, delay: number): T {
 export function createStoreState<T extends object>(
   initialState: T
 ) {
+  const _initialState = { ...initialState };
   let state = initialState;
-  const keyListeners = new Map<keyof T, Set<StoreListener>>();
-  const debouncedNotifiers = new Map<keyof T, () => void>();
+  const keyListeners: Record<string, Set<StoreListener> | undefined> = Object.create(null);
   
   // Middleware storage
   const middleware: Array<{ callback: MiddlewareFunction<T>; keys: (keyof T)[] | null }> = [];
 
+  // Per-key equality registry
+  const equalityRegistry: Record<string, ((prev: any, next: any) => boolean) | undefined> = Object.create(null);
 
+  // Batching
+  let batchedKeys: Set<keyof T> | null = null;
 
   const get = () => state;
 
-  const set = (update: Partial<T>, debounceDelay: number | boolean = false) => {
+  const getKey = <K extends keyof T>(key: K): T[K] => state[key];
+
+  const notifyKey = (key: keyof T) => {
+    if (batchedKeys) {
+      batchedKeys.add(key);
+      return;
+    }
+    keyListeners[key as string]?.forEach(listener => listener());
+  };
+
+  const applySingleKey = <K extends keyof T>(key: K, value: T[K]) => {
+    if (Object.is(state[key], value)) return;
+    const eq = equalityRegistry[key as string];
+    if (eq && eq(state[key], value)) return;
+    state[key] = value;
+    notifyKey(key);
+  };
+
+  const setKey = <K extends keyof T>(key: K, value: T[K]) => {
+    if (middleware.length === 0) {
+      applySingleKey(key, value);
+      return;
+    }
+    const partial = {} as Partial<T>;
+    partial[key] = value;
+    set(partial);
+  };
+
+  const merge = <K extends keyof T>(key: K, value: T[K] extends object ? Partial<T[K]> : never): T[K] => {
+    return { ...state[key], ...value };
+  };
+
+  const mergeSet = <K extends keyof T>(key: K, value: T[K] extends object ? Partial<T[K]> : never) => {
+    if (middleware.length === 0) {
+      applySingleKey(key, { ...state[key], ...value } as T[K]);
+      return;
+    }
+    const partial = {} as Partial<T>;
+    partial[key] = { ...state[key], ...value } as T[K];
+    set(partial);
+  };
+
+  const reset = (keys?: (keyof T)[]) => {
+    if (!keys) {
+      set({ ..._initialState });
+    } else {
+      const partial = {} as Partial<T>;
+      for (const key of keys) {
+        partial[key] = _initialState[key];
+      }
+      set(partial);
+    }
+  };
+
+  const batch = (fn: () => void) => {
+    if (batchedKeys) {
+      fn();
+      return;
+    }
+    batchedKeys = new Set();
+    try {
+      fn();
+    } finally {
+      const keys = batchedKeys;
+      batchedKeys = null;
+      const notified = new Set<StoreListener>();
+      for (const key of keys) {
+        keyListeners[key as string]?.forEach(listener => {
+          if (!notified.has(listener)) {
+            notified.add(listener);
+            listener();
+          }
+        });
+      }
+    }
+  };
+
+  const set = (update: Partial<T>) => {
     if (!update) return;
 
+    if (middleware.length === 0) {
+      applyUpdate(update);
+      return;
+    }
+
     // Run middleware chain
     let currentUpdate = update;
     let middlewareIndex = 0;
@@ -59,7 +137,7 @@ export function createStoreState<T extends object>(
       if (middlewareIndex >= middleware.length) {
         // All middleware processed, apply the update
         if (!blocked) {
-          applyUpdate(currentUpdate, debounceDelay);
+          applyUpdate(currentUpdate);
         }
         return;
       }
@@ -98,34 +176,41 @@ export function createStoreState<T extends object>(
     runMiddleware();
   };
 
-  const applyUpdate = (processedUpdate: Partial<T>, debounceDelay: number | boolean) => {
-    const updatedKeys: (keyof T)[] = [];
+  const applyUpdate = (processedUpdate: Partial<T>) => {
+    const changedKeys: string[] = [];
 
+    // Phase 1: update all state before notifying
     for (const key in processedUpdate) {
       const typedKey = key as keyof T;
-      const currentValue = state[typedKey];
-      const nextValue = processedUpdate[typedKey];
+      if (Object.is(state[typedKey], processedUpdate[typedKey])) continue;
+      const eq = equalityRegistry[key];
+      if (eq && eq(state[typedKey], processedUpdate[typedKey])) continue;
+      state[typedKey] = processedUpdate[typedKey]!;
+      changedKeys.push(key);
+    }
 
-      if (currentValue === nextValue) continue;
+    if (changedKeys.length === 0) return;
 
-      if (!Object.is(currentValue, nextValue)) {
-        state[typedKey] = nextValue!;
-        updatedKeys.push(typedKey);
+    // Phase 2: notify after state is fully consistent
+    if (batchedKeys) {
+      for (const key of changedKeys) {
+        batchedKeys.add(key as keyof T);
       }
+      return;
     }
 
-    if (updatedKeys.length === 0) return;
-
-    for (const key of updatedKeys) {
-      if (debounceDelay !== false) {
-        if (!debouncedNotifiers.has(key)) {
-          debouncedNotifiers.set(key, debounce(() => {
-            keyListeners.get(key)?.forEach(listener => listener());
-          }, typeof debounceDelay === 'number' ? debounceDelay : 0));
-        }
-        debouncedNotifiers.get(key)!();
-      } else {
-        keyListeners.get(key)?.forEach(listener => listener());
+    // Synchronous: deduplicate listeners across keys
+    if (changedKeys.length === 1) {
+      keyListeners[changedKeys[0]]?.forEach(listener => listener());
+    } else {
+      const notified = new Set<StoreListener>();
+      for (const key of changedKeys) {
+        keyListeners[key]?.forEach(listener => {
+          if (!notified.has(listener)) {
+            notified.add(listener);
+            listener();
+          }
+        });
       }
     }
   };
@@ -155,19 +240,16 @@ export function createStoreState<T extends object>(
     };
   };
 
-
-
   const subscribe = (keys: (keyof T)[], listener: StoreListener): (() => void) => {
     for (const key of keys) {
-      if (!keyListeners.has(key)) {
-        keyListeners.set(key, new Set());
-      }
-      keyListeners.get(key)!.add(listener);
+      const k = key as string;
+      if (!keyListeners[k]) keyListeners[k] = new Set();
+      keyListeners[k]!.add(listener);
     }
 
     return () => {
       for (const key of keys) {
-        keyListeners.get(key)?.delete(listener);
+        keyListeners[key as string]?.delete(listener);
       }
     };
   };
@@ -181,7 +263,52 @@ export function createStoreState<T extends object>(
     return result;
   };
 
-  return { get, set, subscribe, select, addMiddleware };
+  const onChange = <K extends keyof T>(
+    keys: K[],
+    callback: (values: Pick<T, K>, prev: Pick<T, K>) => void
+  ): (() => void) => {
+    let prev = {} as Pick<T, K>;
+    for (const key of keys) {
+      prev[key] = state[key];
+    }
+
+    let scheduled = false;
+
+    const listener = () => {
+      if (scheduled) return;
+      scheduled = true;
+      queueMicrotask(() => {
+        scheduled = false;
+        let hasChanges = false;
+        for (const key of keys) {
+          if (!Object.is(state[key], prev[key])) {
+            hasChanges = true;
+            break;
+          }
+        }
+        if (!hasChanges) return;
+        const next = {} as Pick<T, K>;
+        for (const key of keys) {
+          next[key] = state[key];
+        }
+        const snapshot = prev;
+        prev = next;
+        callback(next, snapshot);
+      });
+    };
+
+    return subscribe(keys, listener);
+  };
+
+  const skipSetWhen = <K extends keyof T>(key: K, fn: (prev: T[K], next: T[K]) => boolean) => {
+    equalityRegistry[key as string] = fn;
+  };
+
+  const removeSkipSetWhen = (key: keyof T) => {
+    delete equalityRegistry[key as string];
+  };
+
+  return { get, getKey, set, setKey, merge, mergeSet, reset, batch, subscribe, select, addMiddleware, onChange, skipSetWhen, removeSkipSetWhen, _eqReg: equalityRegistry };
 }
 
 type StoreType<T extends object> = ReturnType<typeof createStoreState<T>>;
@@ -237,28 +364,31 @@ export function useStoreSelector<T extends object, S extends SelectorInput<T>>(
   store: StoreType<T>,
   selector: S
 ): Picked<T, S> {
-  const lastSelected = useRef<Partial<T>>({});
-  const prevSelector = useRef<SelectorInput<T> | null>(null);
-  const normalizedRef = useRef<NormalizedSelector<T>[] | null>(null);
-  const keysRef = useRef<(keyof T)[] | null>(null);
-  const isFirstRunRef = useRef(true);
-  const lastValues = useRef<Partial<T>>({});
-  const subscribeRef = useRef<((onStoreChange: () => void) => () => void) | null>(null);
-  const storeRef = useRef(store);
-
-  const storeChanged = storeRef.current !== store;
+  const ref = useRef({
+    lastSelected: {} as Partial<T>,
+    prevSelector: null as SelectorInput<T> | null,
+    normalized: null as NormalizedSelector<T>[] | null,
+    keys: null as (keyof T)[] | null,
+    isFirstRun: true,
+    lastValues: {} as Partial<T>,
+    subscribe: null as ((onStoreChange: () => void) => () => void) | null,
+    store,
+  });
+
+  const r = ref.current;
+  const storeChanged = r.store !== store;
   if (storeChanged) {
-    storeRef.current = store;
-    lastSelected.current = {};
-    prevSelector.current = null;
-    normalizedRef.current = null;
-    keysRef.current = null;
-    isFirstRunRef.current = true;
-    lastValues.current = {};
-    subscribeRef.current = null;
+    r.store = store;
+    r.lastSelected = {};
+    r.prevSelector = null;
+    r.normalized = null;
+    r.keys = null;
+    r.isFirstRun = true;
+    r.lastValues = {};
+    r.subscribe = null;
   }
 
-  if (!prevSelector.current || !shallowEqualSelector(prevSelector.current, selector)) {
+  if (!r.prevSelector || !shallowEqualSelector(r.prevSelector, selector)) {
     const normalized: NormalizedSelector<T>[] = [];
     const keys: (keyof T)[] = [];
 
@@ -278,63 +408,54 @@ export function useStoreSelector<T extends object, S extends SelectorInput<T>>(
       }
     }
 
-    normalizedRef.current = normalized;
-    keysRef.current = keys;
-    prevSelector.current = selector;
-    subscribeRef.current = null;
+    r.normalized = normalized;
+    r.keys = keys;
+    r.prevSelector = selector;
+    r.subscribe = null;
   }
 
-  const normalized = normalizedRef.current!;
-  const keys = keysRef.current!;
+  const normalized = r.normalized!;
+  const keys = r.keys!;
 
   const getSnapshot = () => {
     const current = store.get();
-    const isFirstRun = isFirstRunRef.current;
 
-    if (isFirstRun) {
-      isFirstRunRef.current = false;
+    if (r.isFirstRun) {
+      r.isFirstRun = false;
       const result = {} as Partial<T>;
       for (const { key } of normalized) {
         const value = current[key];
-        lastValues.current[key] = value;
+        r.lastValues[key] = value;
         result[key] = value;
       }
-      lastSelected.current = result;
+      r.lastSelected = result;
       return result as Picked<T, S>;
     }
 
-    const hasChanges = () => {
-      for (const { key, compare } of normalized) {
-        const prevVal = lastValues.current[key];
-        const nextVal = current[key];
-        if (prevVal === undefined ? true : (compare ? !compare(prevVal, nextVal) : !Object.is(prevVal, nextVal))) {
-          return true;
+    // Single pass — lazy allocation on first change
+    let result: Partial<T> | null = null;
+    for (let i = 0; i < normalized.length; i++) {
+      const { key, compare } = normalized[i];
+      const prevVal = r.lastValues[key]!;
+      const nextVal = current[key];
+      if (!Object.is(prevVal, nextVal)) {
+        const cmp = compare || store._eqReg[key as string];
+        if (!cmp || !cmp(prevVal, nextVal)) {
+          if (!result) {
+            result = {} as Partial<T>;
+            for (let j = 0; j < i; j++) result[normalized[j].key] = r.lastValues[normalized[j].key];
+          }
+          r.lastValues[key] = nextVal;
+          result[key] = nextVal;
+          continue;
         }
       }
-      return false;
-    };
-
-    if (!hasChanges()) {
-      return lastSelected.current as Picked<T, S>;
+      if (result) result[key] = prevVal;
     }
 
-    const result = {} as Partial<T>;
-    for (const { key, compare } of normalized) {
-      const prevVal = lastValues.current[key];
-      const nextVal = current[key];
+    if (!result) return r.lastSelected as Picked<T, S>;
 
-      const isFirstTime = prevVal === undefined;
-      const changed = isFirstTime || (compare ? !compare(prevVal, nextVal) : !Object.is(prevVal, nextVal));
-
-      if (changed) {
-        lastValues.current[key] = nextVal;
-        result[key] = nextVal;
-      } else {
-        result[key] = prevVal;
-      }
-    }
-
-    lastSelected.current = result;
+    r.lastSelected = result;
     return result as Picked<T, S>;
   };
 
@@ -347,29 +468,66 @@ export function useStoreSelector<T extends object, S extends SelectorInput<T>>(
     return result as Picked<T, S>;
   }, [keys]);
 
-  if (!subscribeRef.current || storeChanged) {
-    subscribeRef.current = (onStoreChange: () => void) =>
+  if (!r.subscribe || storeChanged) {
+    r.subscribe = (onStoreChange: () => void) =>
       store.subscribe(keys, onStoreChange);
   }
 
-  return useSyncExternalStore(subscribeRef.current, getSnapshot, () => staticSnapshot);
+  return useSyncExternalStore(r.subscribe, getSnapshot, () => staticSnapshot);
 }
 
+/**
+ * Creates a pre-bound selector hook for a specific store instance.
+ * Infers the state type from the store — no manual generics needed.
+ * 
+ * @param store - The store created with createStoreState
+ * @returns A React hook with the same API as useStoreSelector, but with the store already bound
+ * 
+ * @example
+ * ```ts
+ * const useMyStore = createSelectorHook(myStore);
+ * 
+ * // In a component:
+ * const { count, name } = useMyStore(['count', 'name']);
+ * ```
+ */
+export function createSelectorHook<T extends object>(store: StoreType<T>) {
+  return function <S extends SelectorInput<T>>(selector: S): Picked<T, S> {
+    return useStoreSelector(store, selector);
+  };
+}
 
 /**
- * Interface for storage objects compatible with persistence middleware.
- * Includes localStorage, sessionStorage, AsyncStorage, or any custom storage.
+ * Interface for synchronous storage (localStorage, sessionStorage, etc.).
  */
 export interface StorageSupportingInterface {
   getItem(key: string): string | null;
   setItem(key: string, value: string): void;
 }
 
+/**
+ * Interface for asynchronous storage (React Native AsyncStorage, etc.).
+ */
+export interface AsyncStorageSupportingInterface {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+
+type AnyStorage = Storage | StorageSupportingInterface | AsyncStorageSupportingInterface;
+
+function isThenable(value: unknown): value is Promise<unknown> {
+  return value != null && typeof (value as any).then === 'function';
+}
+
 /**
  * Creates a persistence middleware that saves individual keys to storage.
  * Only writes when the specified keys actually change, using per-key storage.
  * Storage format: `${persistKey}:${keyName}` for each persisted key.
  * 
+ * Works with both synchronous storage (localStorage) and asynchronous storage
+ * (React Native AsyncStorage). Async writes are fire-and-forget — the state
+ * update is never blocked by a slow write.
+ * 
  * @param storage - Storage interface (localStorage, sessionStorage, AsyncStorage, etc.)
  * @param persistKey - Base key prefix for storage (e.g., 'myapp' creates 'myapp:theme')
  * @param keys - Array of state keys to persist
@@ -377,30 +535,38 @@ export interface StorageSupportingInterface {
  * 
  * @example
  * ```ts
- * // Add persistence for theme and user settings
+ * // Sync — localStorage
  * store.addMiddleware(
  *   createPersistenceMiddleware(localStorage, 'myapp', ['theme', 'isLoggedIn'])
  * );
+ * 
+ * // Async — React Native AsyncStorage
+ * store.addMiddleware(
+ *   createPersistenceMiddleware(AsyncStorage, 'myapp', ['theme', 'isLoggedIn'])
+ * );
  * ```
  */
 export function createPersistenceMiddleware<T extends object>(
-  storage: Storage | StorageSupportingInterface,
+  storage: AnyStorage,
   persistKey: string,
   keys: (keyof T)[]
 ): [MiddlewareFunction<T>, (keyof T)[]] {
   const middlewareFunction: MiddlewareFunction<T> = (_, update, next) => {
-    // Check if any of the persisted keys are being updated
     const changedKeys = keys.filter(key => key in update);
     if (changedKeys.length === 0) {
       return next();
     }
 
-    // Save each changed key individually
     for (const key of changedKeys) {
       try {
         const value = update[key];
         const storageKey = `${persistKey}:${String(key)}`;
-        storage.setItem(storageKey, JSON.stringify(value));
+        const result = storage.setItem(storageKey, JSON.stringify(value));
+        if (isThenable(result)) {
+          result.catch(error => {
+            console.warn(`Failed to persist key ${String(key)}:`, error);
+          });
+        }
       } catch (error) {
         console.warn(`Failed to persist key ${String(key)}:`, error);
       }
@@ -416,41 +582,65 @@ export function createPersistenceMiddleware<T extends object>(
  * Loads persisted state from individual key storage during store initialization.
  * Reads keys saved by createPersistenceMiddleware and returns them as partial state.
  * 
+ * Returns synchronously for sync storage and a Promise for async storage.
+ * 
  * @param storage - Storage interface to read from (same as used in middleware)
  * @param persistKey - Base key prefix used for storage (same as used in middleware)
  * @param keys - Array of keys to restore (should match middleware keys)
- * @returns Partial state object with persisted values, or empty object if loading fails
+ * @returns Partial state object (sync) or Promise of partial state (async)
  * 
  * @example
  * ```ts
- * // Load persisted state before creating store
- * const persistedState = loadPersistedState(localStorage, 'myapp', ['theme', 'isLoggedIn']);
+ * // Sync — localStorage
+ * const persisted = loadPersistedState(localStorage, 'myapp', ['theme']);
+ * const store = createStoreState({ theme: 'light', ...persisted });
  * 
- * const store = createStoreState({
- *   theme: 'light',
- *   isLoggedIn: false,
- *   ...persistedState // Apply persisted values
- * });
+ * // Async — React Native AsyncStorage
+ * const persisted = await loadPersistedState(AsyncStorage, 'myapp', ['theme']);
+ * const store = createStoreState({ theme: 'light', ...persisted });
  * ```
  */
 export function loadPersistedState<T extends object>(
   storage: Storage | StorageSupportingInterface,
   persistKey: string,
   keys: (keyof T)[]
-): Partial<T> {
+): Partial<T>;
+export function loadPersistedState<T extends object>(
+  storage: AsyncStorageSupportingInterface,
+  persistKey: string,
+  keys: (keyof T)[]
+): Promise<Partial<T>>;
+export function loadPersistedState<T extends object>(
+  storage: AnyStorage,
+  persistKey: string,
+  keys: (keyof T)[]
+): Partial<T> | Promise<Partial<T>> {
   const result: Partial<T> = {};
-  
+  const pending: Promise<void>[] = [];
+
   for (const key of keys) {
+    const storageKey = `${persistKey}:${String(key)}`;
     try {
-      const storageKey = `${persistKey}:${String(key)}`;
       const stored = storage.getItem(storageKey);
-      if (stored !== null) {
-        result[key] = JSON.parse(stored);
+      if (isThenable(stored)) {
+        pending.push(
+          stored.then(value => {
+            if (value !== null) result[key] = JSON.parse(value as string);
+          }).catch(error => {
+            console.warn(`Failed to load persisted key ${String(key)}:`, error);
+          })
+        );
+      } else if (stored !== null) {
+        result[key] = JSON.parse(stored as string);
       }
     } catch (error) {
       console.warn(`Failed to load persisted key ${String(key)}:`, error);
     }
   }
-  
+
+  if (pending.length > 0) {
+    return Promise.all(pending).then(() => result);
+  }
+
   return result;
 }