@wildgrowth/voltix 1.0.0

package/docs/comparison.md

@@ -0,0 +1,64 @@
+# Comparison
+
+Where Voltix fits, and how it performs. If you already know you want per-key subscriptions in a single store, skip to [Getting started](./getting-started.md).
+
+- [Getting started](./getting-started.md)
+- [Core concepts](./core-concepts.md)
+- [Composition](./composition.md)
+- [Patterns](./patterns.md)
+
+## The model
+
+Voltix is one store of keys with listeners per key. A component names the keys it reads, and a write re-renders the readers of the keys that changed.
+
+```tsx
+// Voltix — subscribe to a key
+const name = useStoreKey(user, 'name');
+
+// Zustand — subscribe with a selector function
+const name = useUserStore((state) => state.name);
+```
+
+For a single field the two behave the same. The difference shows as reads widen: several keys in Voltix is still an array — `useStoreSelector(user, ['name', 'plan'])` — while a selector that returns an object needs an equality strategy (`useShallow`, memoized selectors) to avoid re-rendering on every write.
+
+| Library | Subscription unit |
+|---|---|
+| **Voltix** | A key in a shared store |
+| Zustand | A selector function over one store |
+| Jotai | An atom in a dependency graph |
+| Valtio | Properties touched on a proxy |
+| nanostores | An individual atom or map |
+| Preact Signals | A signal read inside an effect |
+| Solid | A signal read inside a computation |
+| Legend-State | A node of an observable tree |
+
+## Performance
+
+Store-engine microbenchmarks (vanilla stores, no React), in operations per second, higher is faster. Each case runs in its own process and reports the median of 40 runs of about 10 ms each (Node 25, Apple M4 Pro). Reproduce with `npm run bench` ([`bench/vs.ts`](https://github.com/wildgrowth-oss/voltix/blob/main/bench/vs.ts)).
+
+| operation | **Voltix** | Preact Signals | Zustand | nanostores | Solid | Valtio | Jotai | Legend-State |
+|---|---|---|---|---|---|---|---|---|
+| update a value + notify | **187.8M** | 47.4M | 39.1M | 31.0M | 13.1M | 6.7M | 2.7M | 2.7M |
+| functional update (`x => x + 1`) | **192.0M** | 49.4M | 37.8M | 30.3M | 13.7M | 6.5M | 2.3M | 2.7M |
+| fine-grained update (1 of 1000) | **184.2M** | 47.9M | 39.1M † | 30.4M | 12.5M | 161K ‡ | 2.6M | 1.1M |
+| notify 1000 subscribers | **563K** | 35K | 232K | 111K | 24K | — | 64K | 35K |
+| update 50 keys as one transaction | 617K | **820K** | 530K | 516K | 279K | — | 51K | 26K |
+| subscribe + unsubscribe | **44.4M** | 29.1M | 31.4M | 41.7M | 8.9M | 15.5M | 3.1M | 26.5M |
+| create 1,000 units | 42K | **199K** | 39K | 6K | 86K | 388 | 44K | 15K |
+
+<sub>† Zustand's fine-grained row uses separate stores; its single-store selector pattern is O(N) in the number of subscribers. ‡ Valtio batches notifications asynchronously and its per-key subscribe is O(N). The transaction row uses each library's batch where it has one and Voltix's `set`; a signal is a smaller unit than a keyed store, which is what the creation row shows.</sub>
+
+Every library here re-renders only the components whose data changed. The throughput gap shows up under a high rate of writes: drags, streaming data, animation, large grids of independently updating cells.
+
+## Where Voltix fits
+
+Pick Voltix for views made of many independent values where each write should re-render only its readers: grids and tables with per-row state, editors with many fields, dashboards with live numbers, anything written at high frequency. Stores [compose](./composition.md) into a tree (nested stores with `select(key)`, a store per id with `at(id)`), so a large app stays one tree. The [Patterns](./patterns.md) page shows the request, polling, and live-table shapes end to end.
+
+Cases where another shape fits better:
+
+- Deep mutation of one big nested object: a proxy store (Valtio) tracks nested writes for you; Voltix updates by key.
+- State as an async dependency graph, where values derive from other async values: an atom library (Jotai).
+- One store shared across frameworks: nanostores.
+- Caching server data (queries, retries, invalidation): a fetching layer such as React Query owns that; Voltix holds the app state beside it.
+
+See [Getting started](./getting-started.md) to try it, or the [API reference](./api-reference.md) for the full surface.

package/docs/composition.md

@@ -0,0 +1,248 @@
+# Composition
+
+A key can hold another store. That is the whole mechanism: build small stores, bind them under keys, and you get a tree.
+
+Build the child first, bind it after. Binding changes nothing about the child, and a nested store is exactly as fast as a flat one.
+
+- [The example](#the-example)
+- [Nesting a store](#nesting-a-store)
+- [Leaves and children](#leaves-and-children)
+- [Lookups: a store per id](#lookups-a-store-per-id)
+- [Navigating: `select` and `at`](#navigating-select-and-at)
+- [Nested lookups](#nested-lookups)
+- [What re-renders](#what-re-renders)
+
+See also [Core concepts](./core-concepts.md) for the vocabulary and the [API reference](./api-reference.md) for signatures.
+
+## The example
+
+Everything below builds one thing: a **workspace** with user settings and a set of documents, where each document has its own comments.
+
+```
+workspace                leaves: name, syncing
+├── settings             theme, fontSize              (a nested store)
+└── documents            a lookup: one store per document id
+    └── <docId>          title, body, dirty, error    (contract + actions + error policy)
+        └── comments     a lookup: one store per comment id
+            └── <id>     author, text, resolved
+```
+
+## Nesting a store
+
+Build the child first. Settings is a normal store with its own actions. It works on its own and knows nothing about any workspace:
+
+```tsx
+import { createStore, createActions } from '@wildgrowth/voltix';
+
+export const settings = createStore({ theme: 'dark' as 'dark' | 'light', fontSize: 14 });
+
+export const settingsActions = createActions(settings, (store) => ({
+  toggleTheme: () => store.setKey('theme', store.getKey('theme') === 'dark' ? 'light' : 'dark'),
+  setFontSize: (px: number) => store.setKey('fontSize', px),
+}));
+```
+
+Then bind it under a key:
+
+```tsx
+export const workspace = createStore({
+  name: 'Personal',
+  syncing: false,
+  settings,            // ← a finished store becomes a child
+});
+
+workspace.setKey('name', 'Team');           // a parent leaf
+settingsActions.toggleTheme();               // the child's actions still work
+workspace.select('settings') === settings;   // true — binding did not copy or rebuild it
+```
+
+Passing a store *as* the shape is a `TypeError`. A store goes under a key: write `createStore({ settings })`, never `createStore(settings)`.
+
+## Leaves and children
+
+What you put under a key decides what the key is:
+
+- Data (numbers, strings, booleans, objects, arrays) makes a **leaf**: the store's own state. `get()` returns leaves, `setKey` writes them, components subscribe to them.
+- A store or a lookup makes a **child**. The child keeps its own state; the parent just holds the reference. You read and write a child on the child itself.
+
+The `workspace` from above has two leaves and one child:
+
+```tsx
+workspace.get();        // { name: 'Team', syncing: false } — the workspace's own state
+workspace.children();   // ['settings'] — the settings data lives in `settings`, so `get()` has none of it
+
+workspace.setKey('syncing', true);                    // leaf write
+workspace.select('settings').setKey('fontSize', 16);  // child state is written on the child
+```
+
+`workspace.setKey('settings', …)` is a compile error: a child key holds no workspace state to write.
+
+A plain object never becomes a child. `cursor: { line: 1, column: 1 }` is one leaf value: replace the whole object to update it, and subscribers to `cursor` hear one change. When the fields should update independently, use a store instead: `cursor: createStore({ line: 1, column: 1 })`.
+
+## Lookups: a store per id
+
+`createLookup(factory)` makes a **lookup**: a store per id. `at(id)` returns the store for that id — the first call runs your factory to create it, later calls return the same one. Use a lookup for per-item state: documents, rows, entities.
+
+The factory builds each store completely, so every document comes with its contract and error handling attached. Actions go over the lookup, taking the id first:
+
+```tsx
+import { z } from 'zod';
+import { createStore, createLookup, createActions } from '@wildgrowth/voltix';
+
+export function makeDocument(id: string) {
+  const document = createStore(
+    { title: 'Untitled', body: '', dirty: false, error: '' },
+    { schema: { title: z.string().trim().min(1).max(120) } }
+  );
+
+  document.onSchemaError((error) => document.setKey('error', error.issues[0].message));
+
+  return document;
+}
+
+export const documents = createLookup(makeDocument);
+
+export const documentActions = createActions(documents, (lookup) => ({
+  rename: (id: string, title: string) => lookup.at(id).set({ title, error: '' }),
+  edit: (id: string, body: string) => lookup.at(id).set({ body, dirty: true }),
+  markSaved: (id: string) => lookup.at(id).setKey('dirty', false),
+}));
+```
+
+Each document checks its own writes and reports its own failures:
+
+```tsx
+documentActions.rename('spec', '   ');   // rejected by the contract
+documents.at('spec').getKey('title');    // 'Untitled' — the write never landed
+documents.at('spec').getKey('error');    // 'Too small: expected string to have >=1 characters'
+
+documentActions.rename('spec', '  Design spec  ');
+documents.at('spec').getKey('title');    // 'Design spec' — the contract trimmed it on the way in
+```
+
+When the per-item state is plain data with no behaviour, return a shape from the factory instead and the lookup builds the stores for you. A second argument applies [`StoreOptions`](./api-reference.md#storeoptions) to each one:
+
+```tsx
+const presence = createLookup(
+  (userId: string) => ({ online: false, lastSeen: 0 }),
+  { schema: { lastSeen: z.number().int().min(0) } }
+);
+```
+
+Options apply to shape factories only. A factory that builds its own stores configures them itself, so lookup options are ignored there (with a dev warning).
+
+A lookup has no keys of its own. Its surface is `at` plus lifecycle:
+
+```tsx
+documents.has('readme');    // true
+documents.keys();           // ['readme', 'spec'] — live ids, insertion order
+documents.size();           // 2
+documents.remove('spec');   // true; a later at('spec') builds a fresh store
+documents.clear();          // drop every store
+```
+
+`remove` and `clear` drop the store and its subscriptions. One thing they can't clean up: wiring to something **external** (a subscription on another store, a timer, a socket). Keep those disposers where you can reach them and call one before removing:
+
+```tsx
+const stopSync = new Map<string, () => void>();
+
+function makePresence(userId: string) {
+  const presence = createStore({ online: false });
+  stopSync.set(userId, socket.onChange(['users'], () => presence.setKey('online', socket.has(userId))));
+  return presence;
+}
+
+stopSync.get(userId)?.();
+stopSync.delete(userId);
+presence.remove(userId);
+```
+
+In React, a component subscribes to one store from the lookup, so editing one document re-renders one row:
+
+```tsx
+function DocumentRow({ id }: { id: string }) {
+  const { title, dirty } = useStoreSelector(documents.at(id), ['title', 'dirty']);
+  return <li>{title}{dirty && ' •'}</li>;
+}
+```
+
+A lookup binds under a key exactly like a store. With both pieces built, the workspace takes its full shape from [the example](#the-example):
+
+```tsx
+export const workspace = createStore({
+  name: 'Personal',
+  syncing: false,
+  settings,     // child — a store
+  documents,    // child — a lookup
+});
+```
+
+## Navigating: `select` and `at`
+
+Two methods, one argument each:
+
+- **`select(key)`** steps into a fixed child. The key is typed, autocompleted, and checked at compile time.
+- **`at(id)`** steps into a lookup. The id is runtime data.
+
+```tsx
+documentActions.rename('readme', 'README');
+
+workspace.select('documents').at('readme') === documents.at('readme');  // true — same store
+```
+
+Use `at` when the id comes from data, like `documents.at(currentDocId)`. For a fixed child you usually already have the reference, and `settings.setKey('fontSize', 16)` does the same thing as `workspace.select('settings').setKey('fontSize', 16)`, so use the shorter one.
+
+`.children()` lists a store's child keys. Selecting a key that is not a child throws a `RangeError` (and is a compile error first).
+
+## Nested lookups
+
+Children and lookups mix freely and nest as deep as you need. Each document owns a lookup of comments:
+
+```tsx
+function makeDocument(id: string) {
+  return createStore({
+    title: 'Untitled',
+    body: '',
+    dirty: false,
+    comments: createLookup((commentId: string) =>
+      createStore({ author: '', text: '', resolved: false })
+    ),                                       // a lookup inside each document
+  });
+}
+```
+
+The chain follows the tree: child, id, child, id.
+
+```tsx
+workspace.select('documents').at('readme').select('comments').at('c1').set({ author: 'ada', text: 'Looks good' });
+
+workspace.select('documents').at('readme').select('comments').keys();  // ['c1']
+documents.at('readme').select('comments').at('c1').getKey('text');     // 'Looks good'
+```
+
+## What re-renders
+
+The tree is only for organizing state. Re-rendering works like it does in a flat store: writing a key re-renders the components reading that key, and nobody else. Take two small components:
+
+```tsx
+function Title({ id }: { id: string }) {
+  const title = useStoreKey(documents.at(id), 'title');
+  return <h2>{title}</h2>;
+}
+
+function Body({ id }: { id: string }) {
+  const body = useStoreKey(documents.at(id), 'body');
+  return <article>{body}</article>;
+}
+```
+
+Now edit one document's body and walk through who re-renders:
+
+```tsx
+documentActions.edit('readme', '# Hello');   // writes `body` on the readme document
+
+// <Body id="readme" />      re-renders — it reads that key on that document
+// <Title id="readme" />     unchanged — same document, different key
+// <Body id="changelog" />   unchanged — different document
+// anything reading `workspace.name` etc. — unchanged; a write inside a child never touches the parent
+```

package/docs/core-concepts.md

@@ -0,0 +1,145 @@
+# Core concepts
+
+How Voltix decides what re-renders: subscriptions are per key, the state object keeps one identity, writes that change nothing are skipped, and writes can be grouped.
+
+- [Getting started](./getting-started.md)
+- [Composition](./composition.md)
+- [API reference](./api-reference.md)
+- [Guides](./guides.md)
+- [Patterns](./patterns.md)
+
+## The vocabulary
+
+The words the docs use, in plain terms:
+
+**Store.** An object of keys, created with `createStore`. It lives outside React, so any module can import it and read or write it. No provider.
+
+**Key.** One named value in a store. Components subscribe to keys. Writing a key re-renders only the components reading that key.
+
+**Leaf.** A key holding data: a number, string, boolean, object, or array. Read it with `getKey`, write it with `setKey`.
+
+**Child.** A key holding another store or a lookup. The child keeps its own state; you reach it with `select(key)`.
+
+**Node.** A store or a lookup. Both bind under a key, and both work with `createActions`.
+
+**Lookup.** A store per id, made with `createLookup`. `at(id)` returns the store for that id, creating it on first use. Use it for lists where each row should update on its own.
+
+**Action.** A function that writes to a store. `createActions` groups a store's actions in one place and returns them as a plain object.
+
+**Contract.** A schema (zod, valibot, arktype) attached to a key with `options.schema`. Every write to that key is validated and a bad write is rejected. Use it on data that comes from outside your code: fetch responses, storage, forms.
+
+**Derived key.** A key computed from other keys with `derive`. It updates inside the same write that changed its inputs.
+
+## Fine-grained by key
+
+Every key has its own listeners. A write notifies the listeners of the keys that changed and nobody else.
+
+```tsx
+const store = createStore({ theme: 'dark', unread: 3 });
+
+function Unread() {
+  const unread = useStoreKey(store, 'unread');
+  return <span>{unread}</span>;
+}
+
+function Theme() {
+  const theme = useStoreKey(store, 'theme');
+  return <span>{theme}</span>;
+}
+
+store.setKey('theme', 'light'); // only <Theme /> re-renders
+store.increment('unread');       // only <Unread /> re-renders
+```
+
+`useStoreSelector` works the same way: it re-renders for its selected keys and ignores every other write. When one `set` changes several keys a component reads, the component re-renders once.
+
+## Identity-stable state
+
+`get()` always returns the same object. Writes change the values inside it.
+
+```tsx
+const before = store.get();
+store.setKey('unread', 5);
+const after = store.get();
+before === after; // true, always the same reference
+```
+
+What that means for you:
+
+- Reading is free. `getKey` and `get` return live values, no copies.
+- Comparing snapshots of `get()` tells you nothing, because the reference never changes. Subscribe to keys instead.
+- To change an object value, assign a new object. Mutating the current one changes data without telling anyone:
+
+```tsx
+const store = createStore({ user: { name: 'Ada', role: 'admin' } });
+
+store.get().user.name = 'Bob';                 // mutates in place, no notification
+store.mergeSet('user', { name: 'Bob' });       // new object for `user`, listeners notified
+store.setKey('user', { name: 'Bob', role: 'admin' }); // also notifies
+```
+
+`mergeSet` spreads your patch onto the current value and writes the result, so you skip building the new object yourself. See [`mergeSet`](./api-reference.md#mergeset); to merge without writing, use the [`merge` helper](./api-reference.md#merge-helper).
+
+## Leaves and children
+
+What you put under a key decides what the key is. Data makes a **leaf**: normal state you read and write. A store (or a [lookup](./composition.md#lookups-a-store-per-id)) makes a **child**: it keeps its own state, and you reach it with `select(key)`.
+
+```tsx
+const settings = createStore({ theme: 'dark', fontSize: 14 });
+
+const workspace = createStore({
+  name: 'Personal',   // leaf — data
+  settings,           // child — a store
+});
+
+workspace.get();                                      // { name: 'Personal' } — the workspace's own state
+workspace.select('settings').setKey('fontSize', 16);  // the settings data lives in `settings`
+```
+
+This is how one store grows into a tree. See [Composition](./composition.md).
+
+## Equality
+
+A write only counts when the value actually changed (`Object.is`). Writing the same value again does nothing: no write, no re-render.
+
+Some values are new objects that mean the same thing, like a re-fetched user. Give that key its own equality check at creation and those writes are skipped too:
+
+```tsx
+const store = createStore(
+  { user: { id: 1, name: 'Ada' } },
+  { equals: { user: (prev, next) => prev.id === next.id } }
+);
+```
+
+### The compare-by-`.id` pattern
+
+A fetch or a form often produces a fresh object for the same entity. Compare by id and the noise disappears:
+
+```tsx
+const store = createStore(
+  { user: { id: 1, name: 'Ada' } },
+  { equals: { user: (prev, next) => prev.id === next.id } }
+);
+
+store.setKey('user', { id: 1, name: 'Ada' });          // renders
+store.setKey('user', { id: 1, name: 'Ada Lovelace' }); // same id, skipped
+```
+
+This runs at write time, so the skipped value never lands and nobody re-renders. To guard one component instead of the store, pass a compare function inside its [`useStoreSelector`](./api-reference.md#usestoreselector) selector.
+
+## Batching
+
+`batch` groups several writes into one notification per subscription, after the callback ends. Separate subscriptions using the same callback remain independent.
+
+```tsx
+store.batch(() => {
+  store.setKey('count', 10);
+  store.increment('count', 5);
+  store.setKey('label', 'moved');
+});
+// a component reading count and label re-renders once, not three times
+```
+
+Use `batch` for a loop of writes, or when calling several functions that each write on their own. If you already know the keys, `set({ count: 15, label: 'moved' })` is one update and needs no batch. Nested `batch` calls flush once, at the end of the outermost one.
+
+Derived keys commit in the same update as their inputs, so their subscribers wake in the same round. See [derived keys](./guides.md#derived-keys).

package/docs/getting-started.md

@@ -0,0 +1,110 @@
+# Getting started
+
+Voltix is a fine-grained state manager for React. You create a store that holds a flat object of keys, and components subscribe to the individual keys they read. Writing one key re-renders only the components reading that key.
+
+- [Walkthrough](./walkthrough.md)
+- [Core concepts](./core-concepts.md)
+- [Composition](./composition.md)
+- [API reference](./api-reference.md)
+- [Guides](./guides.md)
+- [Patterns](./patterns.md)
+- [Comparison](./comparison.md)
+
+## Install
+
+```bash
+npm i @wildgrowth/voltix
+```
+
+`react` is the only peer dependency. The package is about 5.0 KB gzipped and ships its own types.
+
+## Your first store
+
+Create a store once, at module scope, from an initial state object. It lives outside React: any module can read or write it, and there is no provider to set up.
+
+```tsx
+import { createStore } from '@wildgrowth/voltix';
+
+export const store = createStore({
+  count: 0,
+  step: 1,
+});
+```
+
+Every key in the initial object becomes part of the store's typed shape. Reading or writing a key that does not exist is a compile error.
+
+## Read one key with `useStoreKey`
+
+`useStoreKey` subscribes to one key and returns its value. The component re-renders only when that key changes.
+
+```tsx
+import { useStoreKey } from '@wildgrowth/voltix';
+import { store } from './store';
+
+function Count() {
+  const count = useStoreKey(store, 'count');
+  return <span>{count}</span>;
+}
+```
+
+## Read several keys with `useStoreSelector`
+
+For more than one key, `useStoreSelector` takes an array of keys and returns just those keys. The component re-renders when any of them changes.
+
+```tsx
+import { useStoreSelector } from '@wildgrowth/voltix';
+import { store } from './store';
+
+function Status() {
+  const { count, step } = useStoreSelector(store, ['count', 'step']);
+  return <span>{count} (step {step})</span>;
+}
+```
+
+The selector is always an array: key strings, plus `{ key: compareFn }` entries when a key needs its own comparison. See [`useStoreSelector`](./api-reference.md#usestoreselector).
+
+## Pre-bind a hook with `createStoreHook`
+
+`createStoreHook` binds the store into a hook once, so components stop passing it around. Types are inferred from the store.
+
+```tsx
+import { createStoreHook } from '@wildgrowth/voltix';
+import { store } from './store';
+
+export const useCounter = createStoreHook(store);
+
+function Controls() {
+  const { count, step } = useCounter(['count', 'step']);
+  return <span>{count} / {step}</span>;
+}
+```
+
+## A complete counter
+
+```tsx
+import { createStore, useStoreKey } from '@wildgrowth/voltix';
+
+const store = createStore({ count: 0 });
+
+function Counter() {
+  const count = useStoreKey(store, 'count');
+  return (
+    <div>
+      <button onClick={() => store.increment('count', -1)}>-</button>
+      <span>{count}</span>
+      <button onClick={() => store.increment('count')}>+</button>
+    </div>
+  );
+}
+```
+
+`increment` adds to a numeric key (default amount is `1`). The type system allows it only on keys whose value is a number. Writing to the store from an event handler, an effect, or any module updates every subscribed component.
+
+## Next steps
+
+- [Walkthrough](./walkthrough.md) builds one app end to end, from a single store to a composed tree.
+- [Core concepts](./core-concepts.md) explains per-key subscriptions, identity-stable state, equality, and batching.
+- [Composition](./composition.md) covers nesting stores and lookups (a store per id), navigated with `select` and `at`.
+- [Guides](./guides.md) covers actions, contracts, derived keys, middleware, persistence, and reacting outside React.
+- [Patterns](./patterns.md) shows real-world recipes: sending requests, polled live updates, and a live table.
+- [API reference](./api-reference.md) documents every export and every store method.