dev-react-microstore 5.0.0 → 6.0.0

package/README.md

@@ -1,287 +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
 ```
 
-## Basic 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>;
 }
 ```
 
-## Middleware Support
+One line to create the hook, all types inferred from the store instance — no manual generics.
 
-Add Express-style middleware to intercept and control state updates:
+## API
 
-```tsx
-const store = createStoreState({ count: 0, user: null });
+### `createStoreState(initialState)`
 
-// Validation middleware - can block updates
-store.addMiddleware(
-  (currentState, update, next) => {
-    if (update.count !== undefined && update.count < 0) {
-      // Don't call next() to block the update
-      console.log('Blocked negative count');
-      return;
-    }
-    next(); // Allow the update
-  },
-  ['count'] // Only run for count updates
-);
+Creates a reactive store. Returns:
 
-// Transform middleware - can modify updates
-store.addMiddleware(
-  (currentState, update, next) => {
-    if (update.user?.name) {
-      const modifiedUpdate = {
-        ...update,
-        user: {
-          ...update.user,
-          name: update.user.name.trim().toLowerCase()
-        }
-      };
-      next(modifiedUpdate); // Pass modified update
-    } else {
-      next(); // Pass original update
-    }
-  }
-);
+| 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 |
 
-// Logging middleware
-store.addMiddleware(
-  (currentState, update, next) => {
-    console.log('Processing update:', update);
-    next(); // Continue
-  }
-);
-```
+### `createSelectorHook(store)`
 
-## Persistence
+Returns a pre-bound React hook with full type inference:
+
+```tsx
+const useStore = createSelectorHook(store);
 
-The store supports automatic state persistence using middleware with per-key storage:
+// In a component — types are inferred, no generics needed
+const { user } = useStore(['user']);
+// user is { name: string; age: number }
+```
 
-```typescript
-import { createStoreState, createPersistenceMiddleware, loadPersistedState } from '@ohad/react-microstore'
+### `useStoreSelector(store, selector)`
 
-// Load persisted state during initialization
-const persistedState = loadPersistedState<AppState>(
-  localStorage, 
-  'my-app-state', 
-  ['theme', 'userName', 'isLoggedIn']
-);
+Low-level React hook. Prefer `createSelectorHook` for cleaner usage.
 
-// Create store with merged initial + persisted state
-const store = createStoreState<AppState>({
-  theme: 'light',
-  userName: '',
-  isLoggedIn: false,
-  tempData: { cache: [] },
-  ...persistedState // Apply persisted values
-});
+## merge vs mergeSet
 
-// Add persistence middleware - saves each key individually
-store.addMiddleware(
-  createPersistenceMiddleware(localStorage, 'my-app-state', ['theme', 'userName', 'isLoggedIn'])
-);
+`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
 ```
 
-**Key benefits:**
+`mergeSet` writes it:
 
-✅ **Per-key storage** - Each key stored separately (e.g., `my-app-state:theme`, `my-app-state:userName`)  
-✅ **Efficient writes** - Only writes to storage when specified keys actually change  
-✅ **No state blobs** - Avoids serializing/storing entire state objects  
-✅ **Composable** - Uses the same middleware system as validation/logging  
-✅ **Flexible** - Easy to swap storage backends or add custom logic
+```tsx
+store.mergeSet('user', { age: 31 });
+// store.user is now { name: 'Alice', age: 31 }
+```
 
-## Debouncing
+Both are type-safe — calling on a primitive key (e.g. `merge('count', ...)`) is a compile error.
 
-Control when updates are applied:
+## Batching
+
+Group multiple updates so listeners fire once:
 
 ```tsx
-// Debounce updates for 300ms
-store.set({ searchQuery: 'new value' }, 300);
+store.batch(() => {
+  store.setKey('count', 10);
+  store.mergeSet('user', { age: 25 });
+  store.setKey('name', 'Bob');
+});
+// Listeners fire once with all changes
+```
+
+## reset
 
-// Or use boolean for default debounce (0ms)
-store.set({ count: count + 1 }, true);
+```tsx
+store.reset();              // Full reset to initial state
+store.reset(['count']);      // Reset specific keys
 ```
 
-## Custom Comparison Function
+## Middleware
+
+Express-style middleware to intercept, block, or transform updates:
 
 ```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
+// 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();
   }
 });
 
-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>
-  );
-}
+// Logging
+store.addMiddleware((state, update, next) => {
+  console.log('Update:', update);
+  next();
+});
 ```
 
-## Example of setting store from outside components
+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, useStoreSelector } from 'react-microstore';
+import { createStoreState, createPersistenceMiddleware, loadPersistedState } from 'dev-react-microstore';
 
-// Create store
-const userStore = createStoreState({
-  user: null,
-  isLoading: false,
-  error: null
-});
+// Sync (localStorage / sessionStorage)
+const persisted = loadPersistedState<AppState>(localStorage, 'app', ['theme', 'user']);
 
-// 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;
-  }
-}
+const store = createStoreState<AppState>({ theme: 'light', user: null, ...persisted });
+store.addMiddleware(createPersistenceMiddleware(localStorage, 'app', ['theme', 'user']));
 
-// 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>
-  );
-}
+// Async (React Native AsyncStorage)
+const persisted = await loadPersistedState<AppState>(AsyncStorage, 'app', ['theme', 'user']);
 
-// Can call the function from anywhere
-// fetchUserData('123');
+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
-- Simple middleware support with `addMiddleware()` 
-- Automatic persistence to localStorage/sessionStorage
-- Debouncing support to control update frequency
-- Fully Type-safe with TypeScript
-- 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

@@ -4,7 +4,7 @@ type MiddlewareFunction<T extends object> = (currentState: T, update: Partial<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
@@ -15,10 +15,20 @@ type MiddlewareFunction<T extends object> = (currentState: T, update: Partial<T>
  */
 declare function createStoreState<T extends object>(initialState: T): {
     get: () => T;
-    set: (update: 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;
@@ -53,18 +63,45 @@ type Picked<T extends object, S extends SelectorInput<T>> = ExtractSelectorKeys<
  */
 declare function useStoreSelector<T extends object, S extends SelectorInput<T>>(store: StoreType<T>, selector: S): Picked<T, S>;
 /**
- * Interface for storage objects compatible with persistence middleware.
- * Includes localStorage, sessionStorage, AsyncStorage, or any custom storage.
+ * 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
@@ -72,34 +109,41 @@ 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'])
+ * );
  * ```
  */
-declare function createPersistenceMiddleware<T extends object>(storage: Storage | StorageSupportingInterface, persistKey: string, keys: (keyof T)[]): [MiddlewareFunction<T>, (keyof T)[]];
+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 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']);
- *
- * const store = createStoreState({
- *   theme: 'light',
- *   isLoggedIn: false,
- *   ...persistedState // Apply persisted values
- * });
+ * // 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 { type StorageSupportingInterface, createPersistenceMiddleware, createStoreState, loadPersistedState, useStoreSelector };
+export { type AsyncStorageSupportingInterface, type StorageSupportingInterface, createPersistenceMiddleware, createSelectorHook, createStoreState, loadPersistedState, useStoreSelector };