dev-react-microstore 4.0.1 → 6.0.0

package/README.md

@@ -1,188 +1,254 @@
-# react-microstore
+# dev-react-microstore
 
-A minimal global state manager for React with fine-grained subscriptions.
+Probably the fastest store library ever created for React.
+
+A minimal, zero-dependency global state manager with fine-grained subscriptions, full TypeScript inference, and a tiny footprint (< 2KB minified).
 
 ## Installation
 
 ```bash
-npm install react-microstore
+npm install dev-react-microstore
 ```
 
-## Usage
+## Quick Start
 
 ```tsx
-import { createStoreState, useStoreSelector } from 'react-microstore';
+import { createStoreState, createSelectorHook } from 'dev-react-microstore';
+
+const store = createStoreState({
+  count: 0,
+  user: { name: 'Alice', age: 30 },
+});
 
-const counterStore = createStoreState({ count: 0 });
+export const useStore = createSelectorHook(store);
 
 function Counter() {
-  const { count } = useStoreSelector(counterStore, ['count']);
-
-  return (
-    <div>
-      <p>{count}</p>
-      <button onClick={() => counterStore.set({ count: count + 1 })}>
-        Increment
-      </button>
-    </div>
-  );
+  const { count } = useStore(['count']);
+  return <button onClick={() => store.setKey('count', count + 1)}>{count}</button>;
 }
 ```
 
-## Custom Comparison Function
+One line to create the hook, all types inferred from the store instance — no manual generics.
+
+## API
+
+### `createStoreState(initialState)`
+
+Creates a reactive store. Returns:
+
+| Method | Description |
+|--------|-------------|
+| `get()` | Returns the full state object |
+| `getKey(key)` | Returns the value of a single key |
+| `set(partial)` | Partially updates state. Middleware runs, listeners fire for changed keys only |
+| `setKey(key, value)` | Sets a single key |
+| `merge(key, partial)` | **Pure read** — returns `{ ...state[key], ...partial }` without writing. Type-safe: only works on object-valued keys |
+| `mergeSet(key, partial)` | `merge` + `set` — shallow-merges and writes. Middleware & listeners fire as normal |
+| `reset(keys?)` | Resets keys to their initial values. No args = full reset |
+| `batch(fn)` | Groups multiple `set`/`setKey`/`mergeSet` calls — listeners fire once at the end |
+| `subscribe(keys, listener)` | Fine-grained subscription. Returns unsubscribe function |
+| `select(keys)` | Returns a `Pick<T, K>` snapshot of specific keys |
+| `onChange(keys, callback)` | Non-React listener with `(newValues, prevValues)` — batched per microtask |
+| `addMiddleware(fn, keys?)` | Express-style middleware to intercept, block, or transform updates |
+| `skipSetWhen(key, fn)` | Skip updates for a key when `fn(prev, next)` returns `true`. Runs after `Object.is` |
+| `removeSkipSetWhen(key)` | Remove the skip condition, restoring default `Object.is` behavior |
+
+### `createSelectorHook(store)`
+
+Returns a pre-bound React hook with full type inference:
 
 ```tsx
-import { createStoreState, useStoreSelector } from 'react-microstore';
-
-const taskStore = createStoreState({
-  tasks: [
-    { id: 1, title: 'Learn React', completed: false, priority: 'high' },
-    { id: 2, title: 'Build app', completed: false, priority: 'medium' }
-  ],
-  filters: {
-    showCompleted: true,
-    priorityFilter: null
-  }
-});
+const useStore = createSelectorHook(store);
 
-function TaskList() {
-  // Only re-render when task completion status changes
-  const { tasks } = useStoreSelector(taskStore, [
-    { 
-      tasks: (prev, next) => 
-        !prev.some((task, i) => task.id === next?.[i]?.id && task.completed !== next[i].completed)
-    }
-  ]);
-  
-  const toggleTask = (id) => {
-    const currentTasks = taskStore.get().tasks;
-    const updatedTasks = currentTasks.map(task => 
-      task.id === id ? { ...task, completed: !task.completed } : task
-    );
-    
-    taskStore.set({ tasks: updatedTasks });
-  };
-  
-  return (
-    <ul>
-      {tasks.map(task => (
-        <li key={task.id}>
-          {task.title} - {task.completed ? 'Done' : 'Pending'}
-          <button onClick={() => toggleTask(task.id)}>
-            Toggle
-          </button>
-        </li>
-      ))}
-    </ul>
-  );
-}
+// In a component — types are inferred, no generics needed
+const { user } = useStore(['user']);
+// user is { name: string; age: number }
+```
+
+### `useStoreSelector(store, selector)`
+
+Low-level React hook. Prefer `createSelectorHook` for cleaner usage.
+
+## merge vs mergeSet
+
+`merge` is a pure read helper — it returns the merged object without touching the store:
+
+```tsx
+const updated = store.merge('user', { age: 31 });
+// updated = { name: 'Alice', age: 31 }
+// store is unchanged
 ```
 
-## Example of setting store from outside components
+`mergeSet` writes it:
 
 ```tsx
-import { createStoreState, useStoreSelector } from 'react-microstore';
+store.mergeSet('user', { age: 31 });
+// store.user is now { name: 'Alice', age: 31 }
+```
+
+Both are type-safe — calling on a primitive key (e.g. `merge('count', ...)`) is a compile error.
+
+## Batching
 
-// Create store
-const userStore = createStoreState({
-  user: null,
-  isLoading: false,
-  error: null
+Group multiple updates so listeners fire once:
+
+```tsx
+store.batch(() => {
+  store.setKey('count', 10);
+  store.mergeSet('user', { age: 25 });
+  store.setKey('name', 'Bob');
 });
+// Listeners fire once with all changes
+```
+
+## reset
 
-// Function to update store from anywhere
-export async function fetchUserData(userId) {
-  // Update loading state
-  userStore.set({ isLoading: true, error: null });
-  
-  try {
-    // API call
-    const response = await fetch(`/api/users/${userId}`);
-    const userData = await response.json();
-    
-    // Update store with fetched data
-    userStore.set({ 
-      user: userData,
-      isLoading: false 
-    });
-    
-    return userData;
-  } catch (error) {
-    // Update store with error
-    userStore.set({ 
-      error: error.message,
-      isLoading: false 
-    });
-    
-    throw error;
+```tsx
+store.reset();              // Full reset to initial state
+store.reset(['count']);      // Reset specific keys
+```
+
+## Middleware
+
+Express-style middleware to intercept, block, or transform updates:
+
+```tsx
+// Validation — block negative counts
+store.addMiddleware(
+  (state, update, next) => {
+    if (update.count !== undefined && update.count < 0) return;
+    next();
+  },
+  ['count']
+);
+
+// Transform — normalize user input
+store.addMiddleware((state, update, next) => {
+  if (update.user?.name) {
+    next({ ...update, user: { ...update.user, name: update.user.name.trim() } });
+  } else {
+    next();
   }
-}
+});
 
-// Components can use the store
-function UserProfile() {
-  const { user, isLoading, error } = useStoreSelector(userStore, ['user', 'isLoading', 'error']);
-  
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error}</div>;
-  if (!user) return <div>No user data</div>;
-  
-  return (
-    <div>
-      <h2>{user.name}</h2>
-      <p>Email: {user.email}</p>
-    </div>
-  );
-}
+// Logging
+store.addMiddleware((state, update, next) => {
+  console.log('Update:', update);
+  next();
+});
+```
+
+No-middleware fast path: when no middleware is registered, `set()` skips the pipeline entirely.
+
+## Persistence
+
+Built-in middleware for automatic state persistence. Supports both sync (`localStorage`) and async (`AsyncStorage`) backends:
+
+```tsx
+import { createStoreState, createPersistenceMiddleware, loadPersistedState } from 'dev-react-microstore';
+
+// Sync (localStorage / sessionStorage)
+const persisted = loadPersistedState<AppState>(localStorage, 'app', ['theme', 'user']);
 
-// Can call the function from anywhere
-// fetchUserData('123');
+const store = createStoreState<AppState>({ theme: 'light', user: null, ...persisted });
+store.addMiddleware(createPersistenceMiddleware(localStorage, 'app', ['theme', 'user']));
+
+// Async (React Native AsyncStorage)
+const persisted = await loadPersistedState<AppState>(AsyncStorage, 'app', ['theme', 'user']);
+
+const store = createStoreState<AppState>({ theme: 'light', user: null, ...persisted });
+store.addMiddleware(createPersistenceMiddleware(AsyncStorage, 'app', ['theme', 'user']));
 ```
 
-## Features
+Each key is stored individually (`app:theme`, `app:user`) — no serializing the entire state blob.
+
+## Change Listeners (outside React)
 
-- Extremely lightweight (less than 2KB minified)
-- Fine-grained subscriptions to minimize re-renders
-- Custom comparison functions for complex state updates
-- Fully Type-safe
-- No dependencies other than React
-- Update store from anywhere in your application
+Listen for value changes anywhere — module scope, event handlers, async functions:
 
-## Development Tools
+```tsx
+const unsub = store.onChange(['theme', 'locale'], (values, prev) => {
+  document.body.className = values.theme;
+  console.log(`Theme: ${prev.theme} → ${values.theme}`);
+});
 
-### ESLint Plugin
+// Multiple synchronous set() calls are batched into one notification
+unsub();
+```
 
-[eslint-plugin-react-microstore](https://www.npmjs.com/package/eslint-plugin-react-microstore) provides ESLint rules to help you write with react-microstore.
+## Custom Comparison
 
-#### Installation
+Control when re-renders happen with custom equality functions:
 
-```bash
-npm install --save-dev eslint-plugin-react-microstore
+```tsx
+const { tasks } = useStore([
+  {
+    tasks: (prev, next) =>
+      !prev.some((t, i) => t.completed !== next?.[i]?.completed)
+  }
+]);
 ```
 
-#### Usage
+## skipSetWhen
 
-ESLint configuration:
+Skip updates for a key when a condition is met. `Object.is` always runs first as a fast path; `skipSetWhen` is an additional check when references differ. Return `true` = skip the update:
 
 ```tsx
-import reactMicrostore from 'eslint-plugin-react-microstore';
-
-const eslintConfig = [{
-    "plugins": {
-      "react-microstore": reactMicrostore
-    },
-    "rules": {
-      "react-microstore/no-unused-selector-keys": "warn"
-    }
-}]
+const store = createStoreState({ user: { id: 1, name: 'Alice' }, tags: ['a', 'b'] });
+
+// Skip update if id and name haven't changed
+store.skipSetWhen('user', (prev, next) => prev.id === next.id && prev.name === next.name);
+
+// Skip if array contents are the same
+store.skipSetWhen('tags', (prev, next) => prev.length === next.length && prev.every((t, i) => t === next[i]));
+
+// mergeSet with identical content is now a no-op — no listeners, no middleware
+store.mergeSet('user', { name: 'Alice' }); // skipped
+
+// Remove when no longer needed
+store.removeSkipSetWhen('user');
 ```
 
- `react-microstore/no-unused-selector-keys`  
-  Warns when you select keys in `useStoreSelector` but don't destructure or use them.
+Type-safe: `prev` and `next` types are inferred from the key.
+
+## Features
+
+- Probably the fastest React store library ever created
+- Extremely lightweight (< 2KB minified)
+- Fine-grained subscriptions — components only re-render when their keys change
+- `createSelectorHook` for one-line, fully-typed per-store hooks
+- `merge` / `mergeSet` for ergonomic object updates
+- `batch` to group updates and fire listeners once
+- `reset` to restore initial state (full or per-key)
+- `onChange` for non-React listeners with value tracking
+- `skipSetWhen` to prevent unnecessary updates on object-valued keys
+- Custom comparison functions for complex equality
+- Express-style middleware (validation, transforms, logging)
+- Automatic persistence to localStorage, sessionStorage, or AsyncStorage
+- Fully type-safe — all types inferred from store instance
+- Zero dependencies (peer: React >= 17)
+
+## ESLint Plugin
+
+[eslint-plugin-dev-react-microstore](https://www.npmjs.com/package/eslint-plugin-dev-react-microstore) warns on unused selector keys:
+
+```bash
+npm install --save-dev eslint-plugin-dev-react-microstore
+```
+
+```tsx
+import reactMicrostore from 'eslint-plugin-dev-react-microstore';
+
+export default [{
+  plugins: { 'dev-react-microstore': reactMicrostore },
+  rules: { 'dev-react-microstore/no-unused-selector-keys': 'warn' }
+}];
+```
 
 ```tsx
-// ❌ This will trigger the rule
-const { a } = useStoreSelector(store, ['a', 'b']); // 'b' is unused
+// ❌ Warns — 'b' is selected but unused
+const { a } = useStore(['a', 'b']);
 
-// ✅ This is fine
-const { a, b } = useStoreSelector(store, ['a', 'b']);
-```
+// ✅ Fine
+const { a, b } = useStore(['a', 'b']);
+```

package/dist/index.d.mts

@@ -1,9 +1,34 @@
 type StoreListener = () => void;
+type MiddlewareFunction<T extends object> = (currentState: T, update: Partial<T>, next: (modifiedUpdate?: Partial<T>) => void) => void;
+/**
+ * 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, onChange
+ *
+ * @example
+ * ```ts
+ * const store = createStoreState({ count: 0, name: 'John' });
+ * store.set({ count: 1 }); // Update state
+ * const { count } = useStoreSelector(store, ['count']); // Subscribe in React
+ * ```
+ */
 declare function createStoreState<T extends object>(initialState: T): {
     get: () => T;
-    set: (next: Partial<T>, debounceDelay?: number | boolean) => void;
+    getKey: <K extends keyof T>(key: K) => T[K];
+    set: (update: Partial<T>) => void;
+    setKey: <K extends keyof T>(key: K, value: T[K]) => void;
+    merge: <K extends keyof T>(key: K, value: T[K] extends object ? Partial<T[K]> : never) => T[K];
+    mergeSet: <K extends keyof T>(key: K, value: T[K] extends object ? Partial<T[K]> : never) => void;
+    reset: (keys?: (keyof T)[]) => void;
+    batch: (fn: () => void) => void;
     subscribe: (keys: (keyof T)[], listener: StoreListener) => (() => void);
     select: <K extends keyof T>(keys: K[]) => Pick<T, K>;
+    addMiddleware: (callbackOrTuple: MiddlewareFunction<T> | [MiddlewareFunction<T>, (keyof T)[]], affectedKeys?: (keyof T)[] | null) => () => void;
+    onChange: <K extends keyof T>(keys: K[], callback: (values: Pick<T, K>, prev: Pick<T, K>) => void) => (() => void);
+    skipSetWhen: <K extends keyof T>(key: K, fn: (prev: T[K], next: T[K]) => boolean) => void;
+    removeSkipSetWhen: (key: keyof T) => void;
+    _eqReg: Record<string, ((prev: any, next: any) => boolean) | undefined>;
 };
 type StoreType<T extends object> = ReturnType<typeof createStoreState<T>>;
 type PrimitiveKey<T extends object> = keyof T;
@@ -17,6 +42,108 @@ type ExtractSelectorKeys<T extends object, S extends SelectorInput<T>> = {
     [K in S[number] extends infer Item ? Item extends keyof T ? Item : keyof Item : never]: T[K];
 };
 type Picked<T extends object, S extends SelectorInput<T>> = ExtractSelectorKeys<T, S>;
+/**
+ * React hook that subscribes to specific keys in a store with fine-grained re-renders.
+ * Only re-renders when the selected keys actually change (using Object.is comparison).
+ *
+ * @param store - The store created with createStoreState
+ * @param selector - Array of keys to subscribe to, or objects with custom compare functions
+ * @returns Selected state values from the store
+ *
+ * @example
+ * ```ts
+ * // Subscribe to specific keys
+ * const { count, name } = useStoreSelector(store, ['count', 'name']);
+ *
+ * // Custom comparison for complex objects
+ * const { tasks } = useStoreSelector(store, [
+ *   { tasks: (prev, next) => prev.length === next.length }
+ * ]);
+ * ```
+ */
 declare function useStoreSelector<T extends object, S extends SelectorInput<T>>(store: StoreType<T>, selector: S): Picked<T, S>;
+/**
+ * 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']);
+ * ```
+ */
+declare function createSelectorHook<T extends object>(store: StoreType<T>): <S extends SelectorInput<T>>(selector: S) => Picked<T, S>;
+/**
+ * Interface for synchronous storage (localStorage, sessionStorage, etc.).
+ */
+interface StorageSupportingInterface {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+}
+/**
+ * Interface for asynchronous storage (React Native AsyncStorage, etc.).
+ */
+interface AsyncStorageSupportingInterface {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+}
+type AnyStorage = Storage | StorageSupportingInterface | AsyncStorageSupportingInterface;
+/**
+ * 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
+ * @returns Tuple of [middleware function, affected keys] for use with addMiddleware
+ *
+ * @example
+ * ```ts
+ * // Sync — localStorage
+ * store.addMiddleware(
+ *   createPersistenceMiddleware(localStorage, 'myapp', ['theme', 'isLoggedIn'])
+ * );
+ *
+ * // Async — React Native AsyncStorage
+ * store.addMiddleware(
+ *   createPersistenceMiddleware(AsyncStorage, 'myapp', ['theme', 'isLoggedIn'])
+ * );
+ * ```
+ */
+declare function createPersistenceMiddleware<T extends object>(storage: AnyStorage, persistKey: string, keys: (keyof T)[]): [MiddlewareFunction<T>, (keyof T)[]];
+/**
+ * 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 (sync) or Promise of partial state (async)
+ *
+ * @example
+ * ```ts
+ * // Sync — localStorage
+ * const persisted = loadPersistedState(localStorage, 'myapp', ['theme']);
+ * const store = createStoreState({ theme: 'light', ...persisted });
+ *
+ * // Async — React Native AsyncStorage
+ * const persisted = await loadPersistedState(AsyncStorage, 'myapp', ['theme']);
+ * const store = createStoreState({ theme: 'light', ...persisted });
+ * ```
+ */
+declare function loadPersistedState<T extends object>(storage: Storage | StorageSupportingInterface, persistKey: string, keys: (keyof T)[]): Partial<T>;
+declare function loadPersistedState<T extends object>(storage: AsyncStorageSupportingInterface, persistKey: string, keys: (keyof T)[]): Promise<Partial<T>>;
 
-export { createStoreState, useStoreSelector };
+export { type AsyncStorageSupportingInterface, type StorageSupportingInterface, createPersistenceMiddleware, createSelectorHook, createStoreState, loadPersistedState, useStoreSelector };