pocket-state 0.0.8 → 0.0.9

package/README.md

@@ -1,121 +1,140 @@
-# Pocket State
+# pocket-state
 
-A lightweight state management library for React, built on top of `useSyncExternalStore`.  
-Designed to be **tiny, fast, and predictable**
+A lightweight, typed, and framework-agnostic state management library.  
+Supports **selectors**, **middleware**, and **Immer-style updates**.  
+Works seamlessly **inside React** with hooks or **outside React** with a simple API.
 
 ---
 
-## Installation
+## ✨ Features
 
-Install with your favorite package manager:
+- ⚡ Minimal API – Simple and powerful.
+- 🎯 Selectors – Subscribe to slices of state (store-level and hook-level).
+- 🌀 Immer support – Mutate drafts safely with `setImmer`.
+- 🔌 Framework-agnostic – Works in plain TS/JS and React.
+- 🛠 Middleware – Logging, persistence, batching, devtools bridges, etc.
+- 🔔 Event Emitter – Subscribe to store and custom events.
+- ✅ TypeScript-first – Fully type-safe.
+
+---
+
+## 📦 Installation
 
 ```bash
-# npm
 npm install pocket-state
-
-# yarn
+# or
 yarn add pocket-state
-
+# or
+pnpm add pocket-state
 ```
 
 ---
 
-## API
-
-### `createStore<T>(initialState: T, middlewares?: Middleware<T>[])`
+## 🚀 Usage
 
-Create a new store.
+### 1) Create a Store
 
 ```ts
 import {createStore} from 'pocket-state';
 
-type Counter = {count: number};
+interface Counter {
+  count: number;
+  flag: boolean;
+}
 
-const counterStore = createStore<Counter>({count: 0});
+export const counterStore = createStore<Counter>({
+  count: 0,
+  flag: false,
+});
 ```
 
----
+### 2) Read & Write
 
-### `useStore(store, selector?, equalityFn?)`
+```ts
+// Read full state
+console.log(counterStore.getValue()); // { count: 0, flag: false }
 
-Subscribe to store state inside a React component.  
-It only re-renders when the selected slice changes.
+// Read by key
+console.log(counterStore.getValue('count')); // 0
 
-```tsx
-import {useStore} from 'pocket-state';
-import {counterStore} from './counterStore';
+// Update via partial
+counterStore.setValue({flag: true});
 
-function CounterDisplay() {
-  const count = useStore(counterStore, s => s.count);
-  return <Text>Count: {count}</Text>;
-}
-```
+// Update via function
+counterStore.setValue(s => ({count: s.count + 1}));
 
----
+// Async update
+counterStore.setValue(async s => {
+  const delta = await Promise.resolve(2);
+  return {count: s.count + delta};
+});
+```
 
-### `useShallowStore(store, selector)`
+### 3) Immer Updates
 
-Like `useStore` but uses shallow equality. Useful when selecting an object.
+📦 Install immer
 
-```tsx
-import {useShallowStore} from 'pocket-state';
-
-function Info() {
-  const {count, active} = useShallowStore(counterStore, s => ({
-    count: s.count,
-    active: s.active,
-  }));
-  return (
-    <Text>
-      {count} {active ? 'ON' : 'OFF'}
-    </Text>
-  );
-}
+```bash
+npm install immer
+# or
+yarn add immer
+# or
+pnpm add immer
 ```
 
----
+```ts
+counterStore.setImmer(draft => {
+  draft.count++;
+  draft.flag = !draft.flag;
+});
+```
 
-### Store API
+### 4) Reset & Dirty Check
 
-Each store exposes:
+```ts
+counterStore.reset(); // reset to initial
+counterStore.reset({count: 10}); // reset with override
 
-- `getValue()` → current state
-- `setValue(updater)` → update state (`updater` can be partial or producer)
-- `reset(nextState?)` → reset to initial or custom state
-- `subscribe(listener)` → subscribe to all changes
-- `getNumberOfSubscriber()` → count active subscribers
+console.log(counterStore.isDirty()); // true/false
+```
 
-Example:
+### 5) Subscriptions (Outside React)
 
 ```ts
-counterStore.setValue(s => ({count: s.count + 1}));
-const state = counterStore.getValue();
-console.log(state.count); // → 1
+// Entire state
+const unsub = counterStore.subscribe(state => {
+  console.log('New state:', state);
+});
+
+// With selector (push model)
+const unsubCount = counterStore.subscribe(
+  s => s.count,
+  count => console.log('Count changed:', count),
+);
+
+// cleanup
+unsub();
+unsubCount();
 ```
 
----
-
-## Example
+### 6) Using with React
 
 ```tsx
 import React from 'react';
 import {Text, Button, View} from 'react-native';
-import {createStore, useStore} from 'pocket-state';
-
-// Create store
-const counterStore = createStore({count: 0});
+import {useStore} from 'pocket-state';
+import {counterStore} from './counterStore';
 
-export default function App() {
+export function CounterComponent() {
   const count = useStore(counterStore, s => s.count);
 
   return (
     <View>
       <Text>Count: {count}</Text>
       <Button
-        title="Increment"
+        title="Inc"
         onPress={() => counterStore.setValue(s => ({count: s.count + 1}))}
       />
-      <Button title="Reset" onPress={() => counterStore.reset()} />
     </View>
   );
 }
@@ -123,4 +142,199 @@ export default function App() {
 
 ---
 
-🔥 That’s it — no boilerplate, no context providers.
+## 🎯 Selectors
+
+Selectors let you subscribe to **just part of the state**.
+
+### React
+
+```tsx
+function FlagDisplay() {
+  const flag = useStore(counterStore, s => s.flag);
+  return <Text>Flag is {flag ? 'ON' : 'OFF'}</Text>;
+}
+```
+
+### Non‑React
+
+```ts
+// Only listen to count changes
+const off = counterStore.subscribe(
+  s => s.count,
+  c => console.log('Count updated:', c),
+);
+```
+
+### Derived selectors (memoized)
+
+For CPU‑heavy derivations, memoize a selector factory:
+
+```ts
+// simple memo (per invocation)
+const makeExpensiveSelector = () => {
+  let lastIn: number | undefined;
+  let lastOut: number | undefined;
+  return (s: {count: number}) => {
+    if (lastIn === s.count && lastOut !== undefined) return lastOut;
+    // expensive calculation here
+    const out = s.count * 2;
+    lastIn = s.count;
+    lastOut = out;
+    return out;
+  };
+};
+
+const selectDouble = makeExpensiveSelector();
+const double = useStore(counterStore, selectDouble);
+```
+
+> Tip: When selecting multiple fields, prefer returning an **object** and use a shallow equality helper at the hook, or do slice comparison at the store level.
+
+---
+
+## 🧪 Advanced Usage
+
+### A) Multiple stores & cross‑updates
+
+```ts
+interface Auth {
+  user?: {id: string; name: string} | null;
+}
+interface Todos {
+  items: {id: string; title: string; done: boolean}[];
+}
+
+export const authStore = createStore<Auth>({user: null});
+export const todoStore = createStore<Todos>({items: []});
+
+// react to auth changes
+authStore.subscribe(s => {
+  if (!s.user) {
+    todoStore.reset({items: []}); // clear todos on logout
+  }
+});
+```
+
+### B) Derived state without reselect libraries
+
+```ts
+type Cart = {items: {id: string; price: number; qty: number}[]};
+export const cartStore = createStore<Cart>({items: []});
+
+const selectTotal = (s: Cart) =>
+  s.items.reduce((sum, it) => sum + it.price * it.qty, 0);
+
+// React:
+const total = useStore(cartStore, selectTotal);
+```
+
+### C) Persist middleware (conceptual)
+
+```ts
+import type {Middleware} from 'pocket-state';
+
+const persist =
+  <T>(key: string): Middleware<T> =>
+  (next, get) =>
+  patch => {
+    next(patch);
+    try {
+      localStorage.setItem(key, JSON.stringify(get()));
+    } catch {}
+  };
+
+const store = createStore({count: 0}, [persist('app:store')]);
+```
+
+### D) Logger middleware
+
+```ts
+const logger =
+  (name = 'store'): Middleware<any> =>
+  (next, get) =>
+  patch => {
+    const prev = get();
+    console.log(`[${name}] prev`, prev);
+    next(patch);
+    console.log(`[${name}] next`, get());
+  };
+```
+
+### E) Push vs Pull model
+
+- **Push** (store filters): `store.subscribe(selector, listener)` fires **only when slice changes**.  
+  Hook can be very light (keep last slice, no equality check).
+- **Pull** (hook filters): store emits on any change; `useStore` runs `selector + equality`.  
+  Useful if your store lacks selector subscriptions.
+
+Pick **one** place to compare slices to avoid double work.
+
+### F) Coalesced emits
+
+If your store batches emits in a microtask, multiple updates in a burst trigger one notify:
+
+```ts
+for (let i = 0; i < 10; i++) {
+  counterStore.setValue(s => ({count: s.count + 1}));
+}
+// With coalescing, subscribers run once.
+```
+
+### G) Using outside React (workers, Node, services)
+
+```ts
+// service.ts
+import {counterStore} from './counterStore';
+
+export function increment() {
+  counterStore.setValue(s => ({count: s.count + 1}));
+}
+
+export function onCountChange(cb: (n: number) => void) {
+  return counterStore.subscribe(s => s.count, cb);
+}
+```
+
+### H) Testing
+
+```ts
+import {expect, test} from 'vitest';
+import {counterStore} from './counterStore';
+
+test('increments', () => {
+  counterStore.reset({count: 0, flag: false});
+  counterStore.setValue(s => ({count: s.count + 1}));
+  expect(counterStore.getValue('count')).toBe(1);
+});
+```
+
+### I) Type‑safe key reads with `getValue(key)`
+
+```ts
+const c = counterStore.getValue('count'); // typed as number
+```
+
+---
+
+## 🧩 API Reference
+
+### `Store<T>`
+
+- `getValue(): T` and `getValue(key: K): T[K]`
+- `setValue(patch | (state) => patch | Promise<patch>)`
+- `setImmer((draft) => void)`
+- `reset(next?: T | Partial<T>)`
+- `subscribe(listener)` and `subscribe(selector, listener)`
+- `isDirty()`
+- `getInitialValue()`
+- `getNumberOfSubscriber()`
+
+### `useStore(store, selector?)` (React)
+
+Lightweight hook built on `useSyncExternalStore` that subscribes to your store and returns the selected slice. It supports both full‑state and slice subscriptions.
+
+---
+
+## 📜 License
+
+ISC — use it however you like.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pocket-state",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "description": "tiny global store",
   "main": "src/index",
   "codegenConfig": {