@wildgrowth/voltix 1.0.0

package/docs/patterns.md

@@ -0,0 +1,291 @@
+# Patterns
+
+Complete recipes you can copy into an app.
+
+- [Sending requests](#sending-requests)
+- [Fetching by a parameter](#fetching-by-a-parameter)
+- [Mutations with optimistic updates](#mutations-with-optimistic-updates)
+- [Live updates with polling](#live-updates-with-polling)
+- [A live table: a lookup + polling](#a-live-table-a-lookup--polling)
+
+See also [Composition](./composition.md) for lookups and nesting, [Guides](./guides.md) for the feature-level reference, and [Core concepts](./core-concepts.md) for how re-rendering works.
+
+## Sending requests
+
+Keep a request in the store as three keys: `status`, `data`, `error`. The spinner reads `status`, the table reads `data`, and each re-renders only when its own key changes.
+
+Put the fetch in a function next to the store. `set` writes several keys in one update, so a component reading two of them re-renders once.
+
+```tsx
+import { createStore } from '@wildgrowth/voltix';
+
+type User = { id: string; name: string };
+type Status = 'idle' | 'loading' | 'success' | 'error';
+
+export const users = createStore({
+  status: 'idle' as Status,
+  data: [] as User[],
+  error: null as string | null,
+});
+
+export async function loadUsers() {
+  users.setKey('status', 'loading');
+  try {
+    const res = await fetch('/api/users');
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data: User[] = await res.json();
+    users.set({ data, error: null, status: 'success' });
+  } catch (err) {
+    users.set({ error: (err as Error).message, status: 'error' });
+  }
+}
+```
+
+In components, split the reads: the shell reads `status`, the list reads `data`. Refetching a fresh list never re-runs the spinner branch.
+
+```tsx
+import { useStoreKey, useStoreSelector } from '@wildgrowth/voltix';
+import { users, loadUsers } from './users';
+
+function UserList() {
+  const { status, error } = useStoreSelector(users, ['status', 'error']);
+  if (status === 'loading') return <Spinner />;
+  if (status === 'error') return <Error message={error} onRetry={loadUsers} />;
+  return <Rows />;
+}
+
+function Rows() {
+  const data = useStoreKey(users, 'data'); // re-renders only when the list changes
+  return <ul>{data.map((u) => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+```
+
+Start the load as early as you can. An effect in a leaf component fires only after everything above it has rendered and mounted, so every level you move the call up starts the request sooner. The store lives outside React, so the earliest spot is outside React entirely — your entry file — where the fetch runs in parallel with the first render:
+
+```tsx
+// main.tsx — the fetch races the initial render
+loadUsers();
+createRoot(document.getElementById('root')!).render(<App />);
+```
+
+In an SSR framework, module scope and the entry file run on the server too, so start client loads from the top component's effect instead — or pass server-fetched data down as props, see [server rendering](./guides.md#server-rendering). For data only some screens need, put the kick-off in the highest component that knows it's needed:
+
+```tsx
+function useUsers() {
+  useEffect(() => {
+    if (users.getKey('status') === 'idle') loadUsers();
+  }, []);
+  return useStoreSelector(users, ['status', 'data', 'error']);
+}
+```
+
+Because the store lives outside React, mounting two `UserList` components does not fetch twice: the `idle` guard runs once, and both components read the same slice.
+
+## Fetching by a parameter
+
+When the request depends on an input (a selected id, a search query), keep the input in the store and fetch when it changes. Before writing the response, check the store still wants it — switch documents quickly and a slow old response can land after a newer one:
+
+```tsx
+import { createStore } from '@wildgrowth/voltix';
+
+type Doc = { id: string; title: string; body: string };
+
+export const viewer = createStore({
+  id: null as string | null,
+  status: 'idle' as 'idle' | 'loading' | 'success' | 'error',
+  data: null as Doc | null,
+});
+
+export async function openDocument(id: string) {
+  if (viewer.getKey('id') === id) return;
+  viewer.set({ id, status: 'loading' });
+  const res = await fetch(`/api/documents/${id}`);
+  const data: Doc = await res.json();
+  if (viewer.getKey('id') !== id) return; // the user opened another document; drop this one
+  viewer.set({ data, status: 'success' });
+}
+```
+
+The guard is plain store usage: the store holds the current selection, so reading it answers "is this response still the one on screen?". If a fetching library (React Query, SWR) handles your requests, it owns this problem — write its results into the store and skip the guard.
+
+```tsx
+function DocumentView({ id }: { id: string }) {
+  useEffect(() => { openDocument(id); }, [id]);
+  const { status, data } = useStoreSelector(viewer, ['status', 'data']);
+  return status === 'success' && data ? <article>{data.body}</article> : <Spinner />;
+}
+```
+
+## Mutations with optimistic updates
+
+Write the change immediately, then tell the server. Snapshot the old value first so you can roll back if the request fails.
+
+```tsx
+export const settings = createStore({ theme: 'light' as 'light' | 'dark', saving: false });
+
+export async function setTheme(theme: 'light' | 'dark') {
+  const prev = settings.getKey('theme');
+  settings.set({ theme, saving: true }); // optimistic: UI updates now
+  try {
+    const res = await fetch('/api/settings', {
+      method: 'PATCH',
+      body: JSON.stringify({ theme }),
+    });
+    if (!res.ok) throw new Error('save failed');
+    settings.setKey('saving', false);
+  } catch {
+    settings.set({ theme: prev, saving: false }); // roll back to the snapshot
+  }
+}
+```
+
+For a list, snapshot the array, update it optimistically, and restore the snapshot on failure.
+
+## Live updates with polling
+
+For data that changes on the server, load a full snapshot once, then poll for what changed. The server returns a cursor with every response; send it back as `?since=` and you get only the rows that moved since. Payloads stay small no matter how long the tab is open.
+
+The store holds the rows by id, their order, and the current cursor.
+
+```tsx
+import { createStore } from '@wildgrowth/voltix';
+
+type Order = { id: string; total: number; status: string };
+
+type Snapshot = { orders: Order[]; cursor: string };
+type Delta = { changed: Order[]; removed: string[]; cursor: string };
+
+export const orders = createStore({
+  byId: {} as Record<string, Order>,
+  ids: new Set<string>(),
+  cursor: null as string | null,
+  status: 'idle' as 'idle' | 'ready' | 'error',
+});
+
+export async function bootstrapOrders() {
+  const res = await fetch('/api/orders');
+  const snap: Snapshot = await res.json();
+  const byId: Record<string, Order> = {};
+  for (const o of snap.orders) byId[o.id] = o;
+  orders.set({ byId, ids: new Set(snap.orders.map((o) => o.id)), cursor: snap.cursor, status: 'ready' });
+}
+
+export function applyOrdersDelta(delta: Delta) {
+  if (delta.changed.length === 0 && delta.removed.length === 0) {
+    orders.setKey('cursor', delta.cursor);
+    return;
+  }
+  const byId = { ...orders.getKey('byId') };
+  const ids = new Set(orders.getKey('ids'));   // fresh copies — reference equality drives notify
+  for (const o of delta.changed) { byId[o.id] = o; ids.add(o.id); }
+  for (const id of delta.removed) { delete byId[id]; ids.delete(id); }
+  orders.set({ byId, ids, cursor: delta.cursor });
+}
+```
+
+Drive it with a loop that never overlaps its own requests and pauses when the tab is hidden. A recursive timeout waits for each poll to finish before scheduling the next; an error backs off instead of hammering.
+
+```ts
+export function startPolling(intervalMs = 4000) {
+  let stopped = false;
+
+  async function tick() {
+    if (stopped) return;
+    if (document.hidden) return schedule(intervalMs);
+
+    const cursor = orders.getKey('cursor');
+    if (cursor === null) {
+      await bootstrapOrders();
+      return schedule(intervalMs);
+    }
+    try {
+      const res = await fetch(`/api/orders?since=${encodeURIComponent(cursor)}`);
+      applyOrdersDelta(await res.json());
+      schedule(intervalMs);
+    } catch {
+      schedule(intervalMs * 2); // back off on failure
+    }
+  }
+
+  function schedule(ms: number) {
+    if (!stopped) setTimeout(tick, ms);
+  }
+
+  tick();
+  return () => { stopped = true; };
+}
+```
+
+Start it once and stop it on teardown. The cursor is opaque to the client; the server decodes it, and falls back to "from the start" when it can't. Upserts are by id, so a row sent twice across two polls is harmless.
+
+```tsx
+useEffect(() => startPolling(), []);
+```
+
+## A live table: a lookup + polling
+
+The single-map version above re-renders every reader of `byId` on any delta. When a poll touches three rows out of thousands, exactly three components should re-render. Give each row its own store with a [lookup](./composition.md#lookups-a-store-per-id): an index store holds the id list and the cursor, and each row reads its own store.
+
+```tsx
+import { createStore } from '@wildgrowth/voltix';
+
+type Row = { id: string; total: number; status: string };
+type Snapshot = { rows: Row[]; cursor: string };
+type Delta = { changed: Row[]; removed: string[]; cursor: string };
+
+const rows = createLookup((id: string) => ({ total: 0, status: '' }));
+
+export const table = createStore({ ids: new Set<string>(), cursor: null as string | null, ready: false });
+
+export async function bootstrapTable() {
+  const snap: Snapshot = await (await fetch('/api/rows')).json();
+  for (const r of snap.rows) rows.at(r.id).set({ total: r.total, status: r.status });
+  table.set({ ids: new Set(snap.rows.map((r) => r.id)), cursor: snap.cursor, ready: true });
+}
+
+export function applyTableDelta(delta: Delta) {
+  // Only rows that changed touch their own store; siblings never re-render.
+  for (const r of delta.changed) rows.at(r.id).set({ total: r.total, status: r.status });
+  for (const id of delta.removed) rows.remove(id);
+
+  if (delta.changed.length || delta.removed.length) {
+    const ids = new Set(table.getKey('ids'));
+    for (const r of delta.changed) ids.add(r.id);
+    for (const id of delta.removed) ids.delete(id);
+    table.setKey('ids', ids); // fresh Set — the list re-renders only on add/remove
+  }
+  table.setKey('cursor', delta.cursor);
+}
+
+export { rows };
+```
+
+A delta that changes one row's `status` wakes that one `<TableRow>` and nothing else. `<Table>` re-renders only when a row is added or removed, because that is the only time `ids` changes.
+
+```tsx
+import { useStoreSelector } from '@wildgrowth/voltix';
+import { table, rows } from './table';
+
+function Table() {
+  const { ids, ready } = useStoreSelector(table, ['ids', 'ready']);
+  if (!ready) return <Spinner />;
+  return (
+    <table>
+      <tbody>{[...ids].map((id) => <TableRow key={id} id={id} />)}</tbody>
+    </table>
+  );
+}
+
+function TableRow({ id }: { id: string }) {
+  const { total, status } = useStoreSelector(rows.at(id), ['total', 'status']);
+  return (
+    <tr>
+      <td>{id}</td>
+      <td>{total}</td>
+      <td>{status}</td>
+    </tr>
+  );
+}
+```
+
+Drive it with the same polling loop, reading `table.getKey('cursor')` and calling `bootstrapTable` and `applyTableDelta`. Use this shape for dashboards, order books, and live grids.

package/docs/walkthrough.md

@@ -0,0 +1,334 @@
+# Walkthrough
+
+A task board, built step by step: one store first, then actions, contracts, a store per task, and server loading. Each step adds one idea and the code keeps working between steps.
+
+- [1. A store and a component](#1-a-store-and-a-component)
+- [2. Several keys, independent re-renders](#2-several-keys-independent-re-renders)
+- [3. Put the writes in actions](#3-put-the-writes-in-actions)
+- [4. A task that owns itself](#4-a-task-that-owns-itself)
+- [5. A store per id](#5-a-store-per-id)
+- [6. Compose the app](#6-compose-the-app)
+- [7. Derived keys and counters](#7-derived-keys-and-counters)
+- [8. Render it](#8-render-it)
+- [9. Load from a server](#9-load-from-a-server)
+- [10. Persist what should outlive a reload](#10-persist-what-should-outlive-a-reload)
+- [The finished shape](#the-finished-shape)
+
+## 1. A store and a component
+
+A store is a flat object of keys, created once at module scope. No provider, no context.
+
+```tsx
+// ui.ts
+import { createStore } from '@wildgrowth/voltix';
+
+export type Filter = 'all' | 'open' | 'done';
+
+export const ui = createStore({
+  filter: 'all' as Filter,
+  search: '',
+});
+```
+
+Read one key with `useStoreKey`. It returns the value itself.
+
+```tsx
+import { useStoreKey } from '@wildgrowth/voltix';
+import { ui } from './ui';
+
+function SearchBox() {
+  const search = useStoreKey(ui, 'search');
+  return <input value={search} onChange={(event) => ui.setKey('search', event.target.value)} />;
+}
+```
+
+## 2. Several keys, independent re-renders
+
+`useStoreSelector` takes an array of keys and returns just those keys.
+
+```tsx
+function Toolbar() {
+  const { filter, search } = useStoreSelector(ui, ['filter', 'search']);
+  return <span>{filter} · {search}</span>;
+}
+```
+
+Subscriptions are per key: writing `filter` never wakes a component that only reads `search`.
+
+```ts
+ui.subscribe(['filter'], () => console.log('filter'));
+ui.subscribe(['search'], () => console.log('search'));
+
+ui.setKey('filter', 'open');   // logs 'filter'
+ui.setKey('search', 'milk');   // logs 'search'
+ui.setKey('filter', 'open');   // logs nothing — same value, no write
+```
+
+## 3. Put the writes in actions
+
+`createActions` collects a store's writes in one place and returns them as a plain object. The store itself is untouched.
+
+```tsx
+// ui.ts
+import { createStore, createActions } from '@wildgrowth/voltix';
+
+export const ui = createStore({ filter: 'all' as Filter, search: '' });
+
+export const uiActions = createActions(ui, (store) => ({
+  setFilter: (filter: Filter) => store.setKey('filter', filter),
+  setSearch: (query: string) => store.setKey('search', query),
+  clear: () => store.reset(),
+}));
+
+uiActions.setFilter('open');
+ui.setKey('search', 'milk');   // the store is still just a store
+```
+
+Actions are plain functions in a plain object: import them where needed, and combine sets with object spread.
+
+## 4. A task that owns itself
+
+A task has rules (the title), behaviour, and a place to record a rejected write. Build it as a complete store before it joins any collection.
+
+```tsx
+// task.ts
+import { z } from 'zod';
+import { createStore } from '@wildgrowth/voltix';
+
+export function makeTask(id: string) {
+  const task = createStore(
+    { title: '', done: false, error: '' },
+    { schema: { title: z.string().trim().min(1).max(80) } }   // its contract
+  );
+
+  task.onSchemaError((error) => task.setKey('error', error.issues[0].message)); // its failure policy
+
+  return task;
+}
+```
+
+Every task now behaves like this, wherever it ends up:
+
+```ts
+const task = makeTask('t1');
+
+task.set({ title: '   ', error: '' });   // rejected by the contract
+task.getKey('title');                    // '' — the write never landed
+task.getKey('error');                    // 'Too small: expected string to have >=1 characters'
+
+task.set({ title: '  Buy milk  ', error: '' });
+task.getKey('title');                    // 'Buy milk' — the schema trimmed it on the way in
+task.getKey('error');                    // '' — cleared by the same write
+```
+
+The contract runs on every write, and the error handler runs after the write settles. That is why `set({ title, error: '' })` can clear an old error without erasing the message a rejection just wrote.
+
+## 5. A store per id
+
+`createLookup` makes a **lookup**: a store per id. `at(id)` creates the store on first use and returns the same one after. The factory returns a finished store, so every task comes with its contract and error handling attached. Task actions go over the lookup, id first:
+
+```ts
+// tasks.ts
+import { createLookup, createActions } from '@wildgrowth/voltix';
+import { makeTask } from './task';
+
+export const tasks = createLookup(makeTask);
+
+export const taskActions = createActions(tasks, (lookup) => ({
+  rename: (id: string, title: string) => lookup.at(id).set({ title, error: '' }),
+  toggle: (id: string) => lookup.at(id).toggle('done'),
+}));
+
+taskActions.rename('t1', 'Buy milk');
+taskActions.toggle('t1');
+tasks.at('t1') === tasks.at('t1');   // true — memoized, the exact node makeTask built
+```
+
+`at(id)` is how you reach the store for an id. `has`, `keys`, `size`, `remove`, and `clear` handle the lifecycle.
+
+## 6. Compose the app
+
+Bind the finished stores under one root. A key holding a store is a child; the other keys stay plain data.
+
+```ts
+// app.ts
+import { createStore, createActions } from '@wildgrowth/voltix';
+import { ui } from './ui';
+import { tasks, taskActions } from './tasks';
+
+export const app = createStore({
+  ids: new Set<string>(),   // membership is the semantic — a Set can't hold a duplicate row
+  count: 0,
+  open: 0,
+  loading: false,
+  ui,        // child store
+  tasks,     // child lookup
+});
+
+export const appActions = createActions(app, (store) => ({
+  add(id: string, title: string) {
+    if (store.getKey('ids').has(id)) return;            // idempotent — a double add is a no-op
+    taskActions.rename(id, title);
+    store.update('ids', (ids) => new Set(ids).add(id)); // fresh Set, so subscribers notify
+    store.increment('open');
+  },
+  remove(id: string) {
+    if (!store.getKey('ids').has(id)) return;
+    if (!store.select('tasks').at(id).getKey('done')) store.increment('open', -1);
+    store.update('ids', (ids) => {
+      const next = new Set(ids);
+      next.delete(id);
+      return next;
+    });
+    store.select('tasks').remove(id);
+  },
+  toggle(id: string) {
+    taskActions.toggle(id);
+    store.increment('open', store.select('tasks').at(id).getKey('done') ? -1 : 1);
+  },
+}));
+```
+
+`ids` is a `Set`: duplicates are impossible and `has` is O(1). The guards make `add` and `remove` safe to call twice, so a double-click can't duplicate a row or corrupt the counters. Writes always build a **fresh** `Set`, because Voltix compares by reference and mutating the current one changes data without notifying anyone.
+
+Children stay out of the parent's state, and binding changes nothing about them:
+
+```ts
+app.get();                    // { ids: Set(0), count: 0, open: 0, loading: false }
+app.children();               // ['ui', 'tasks']
+app.select('ui') === ui;                         // true
+app.select('tasks').at('t1') === tasks.at('t1');  // true
+```
+
+Both ways of reaching a child are the same call; use whichever reads better. `ui.setKey('filter', 'open')` does the same as `app.select('ui').setKey('filter', 'open')`. `at` is for dynamic ids, like `app.select('tasks').at(someId)`. Note that `appActions` calls `taskActions` directly: actions are plain functions, so app behaviour is built out of task behaviour with ordinary calls.
+
+## 7. Derived keys and counters
+
+`derive` computes a key from other keys in the same store, inside the write that changes an input:
+
+```ts
+app.derive('count', ['ids'], ({ ids }) => ids.size);
+
+appActions.add('t1', 'Buy milk');
+app.getKey('count');   // 1, already committed
+```
+
+`open` depends on state spread across the lookup's stores, which `derive` cannot see. Update it from the actions that change it (`add`, `remove`, `toggle` above): O(1) per change instead of re-scanning every task.
+
+## 8. Render it
+
+Each component subscribes to exactly what it reads.
+
+```tsx
+import { useStoreKey, useStoreSelector } from '@wildgrowth/voltix';
+import { app, appActions } from './app';
+import { tasks } from './tasks';
+
+function Header() {
+  const { count, open } = useStoreSelector(app, ['count', 'open']);
+  return <h1>{open} open / {count} total</h1>;
+}
+
+function Row({ id }: { id: string }) {
+  const { title, done, error } = useStoreSelector(tasks.at(id), ['title', 'done', 'error']);
+  return (
+    <li>
+      <input type="checkbox" checked={done} onChange={() => appActions.toggle(id)} />
+      {title}
+      {error && <em>{error}</em>}
+      <button onClick={() => appActions.remove(id)}>×</button>
+    </li>
+  );
+}
+
+function Board() {
+  const ids = useStoreKey(app, 'ids');
+  return (
+    <>
+      <Header />
+      <ul>{[...ids].map((id) => <Row key={id} id={id} />)}</ul>
+    </>
+  );
+}
+```
+
+Toggling one task re-renders **that `Row` only**. `Header` re-renders when `count` or `open` actually changed. Adding a task changes `ids` and `count`, so the list and `Header` update.
+
+## 9. Load from a server
+
+Async work goes in an action:
+
+```ts
+export async function loadBoard() {
+  app.setKey('loading', true);
+  try {
+    const res = await fetch('/api/tasks');
+    const rows: { id: string; title: string; done: boolean }[] = await res.json();
+
+    tasks.clear();
+    for (const r of rows) tasks.at(r.id).set({ title: r.title, done: r.done });
+
+    app.set({
+      ids: new Set(rows.map((r) => r.id)),
+      open: rows.filter((r) => !r.done).length,
+      loading: false,
+    });
+  } catch {
+    app.setKey('loading', false);
+  }
+}
+```
+
+Server data is written straight into the task stores with `set`. It still passes each task's contract, so a malformed row is rejected per key instead of landing on the board.
+
+Call it once where the data is first needed:
+
+```tsx
+useEffect(() => { loadBoard(); }, []);
+```
+
+## 10. Persist what should outlive a reload
+
+Persist preferences; server data reloads from the server. Seed the initial state from storage, then attach `persist`.
+
+```ts
+import { createStore, persist, loadPersistedState } from '@wildgrowth/voltix';
+
+type UiState = { filter: Filter; search: string };
+
+const persisted = loadPersistedState<UiState>(localStorage, 'board', ['filter']);
+
+export const ui = createStore<UiState>(
+  { filter: 'all', search: '', ...persisted },
+  { schema: { filter: z.enum(['all', 'open', 'done']).catch('all') } }
+);
+
+persist<UiState>(ui, localStorage, 'board', ['filter']);
+```
+
+`.catch('all')` handles junk in storage (users edit it, old deploys leave old shapes behind): a bad value becomes `'all'` at construction instead of an impossible filter in your UI.
+
+## The finished shape
+
+```
+app                      leaves: ids, count, open, loading
+├── ui                   filter, search        (+ actions, persisted, contract)
+└── tasks                lookup
+    └── <id>             title, done, error    (+ actions, contract, error handler)
+```
+
+Reading back what each piece did:
+
+| Step | Idea |
+|---|---|
+| 1–2 | One store, per-key subscriptions |
+| 3 | `createActions` co-locates writes, the store stays clean |
+| 4 | A child owns its contract, actions, and failure policy |
+| 5 | A lookup is that store, once per id |
+| 6 | Binding children into a root changes nothing about them |
+| 7 | `derive` for same-store values, write-through for cross-store counts |
+| 8 | Components subscribe to keys, so one row's write re-renders one row |
+| 9 | Async in actions |
+| 10 | Persist preferences, and let a contract repair corrupt storage |
+
+Next: [Patterns](./patterns.md) for polling and live tables, [Composition](./composition.md) for deeper trees, [API reference](./api-reference.md) for the full surface.