/** * vapor-chamber - the store, once, for both entries. * * `vapor-chamber/store` (Vue) and `vapor-chamber/store/core` (no Vue) are this * implementation over a different runtime (`StoreRuntime`): the rules - actions * as commands, the registry per bus, takeover, undo, field events, sharing, * the coded refusals - exist once. The design notes on the store * are in src/store.ts and docs/store.md. */ import type { BaseBus } from './command-bus'; import type { ResultOn } from './shared-bus'; import type { PersistHooks, StorePersist, StoreWrite } from './store-persist'; import type { StateShare, StoreShare } from './store-share'; /** A reducer: current state plus the dispatched target, returning the NEXT state. */ export type StoreReducer = (state: S, target: any, payload?: any) => S; /** What defineChamberStore takes. */ export type ChamberStoreOptions | null>> = { /** * The store's reducers: each key names an action (`add` on store `cart` * dispatches `cartAdd`, and becomes the method `cart.add`), each value * returns the next state from the current one and the call's target and * payload. `actions` elsewhere in the library is an ActionScope (names), * so the map has its own word. `null` is an action a * transport sends with no local change: its state comes from `answer` or * the server's `stores`. A function for a sent action is refused unless the * store is `optimistic` (`core:invalid:handler`). * tests/register-shadow-check.test.ts. */ reducers: R; /** * A FACTORY, never a literal. Two stores of the same shape must not share a * nested reference, and `$reset` must not hand back the object a previous * reset already mutated - both are the same bug, and a factory makes it * unrepresentable. */ state: () => S; /** * URL-worthy fields (pattern 4B): `storeField -> query key`. The store does * NOT own a signal for these - reads and writes both go through the router, * so the URL stays the single writer and a shared link reproduces the view. * * The router arrives as an ARGUMENT rather than an import: a store with no * URL fields never pulls the router into its graph, which the boundary test * pins. */ url?: Record; /** Make actions and `$reset` undoable through `history` (docs/store.md, Undo). Off by default. */ undo?: boolean; /** * Write the state once per microtask: each write of the store's own * commands chains on the pending state, and an action's result is that * state. For a list a burst of dispatches fills. A state from outside (a * tab's, a server's, a seed) is written at once, after the pending one. * Refused with `undo`. tests/store-coalesce.test.ts, * tests/store-facts-lane.test.ts. */ coalesce?: boolean; /** * The Vue entry only: `state.value` is Vue's reactive view of the state, so * a nested field mutated in place (a `v-model`) is tracked by Vue readers. * The store keeps the raw state, and follows writes by identity: a * mutation in place is not a write. tests/store-deep.test.ts. */ deep?: boolean; /** * `saveTo({ key })`: save the store's state under `key` and read it back * when the store is created. The saved state is its first state, `$reset` * still gives `state()`. Saved once per microtask after any write of the * store (docs/store.md, Saved state). Imported, so a store without it * carries none of it. tests/store-persist.test.ts. */ persist?: StorePersist; /** * `shareTabs()`: the store across the tabs of one origin. Each write * crosses as its command and each tab applies it, an undo crosses as the * id of the command it reverses, and a tab opened later asks for the state * (docs/store.md, Across tabs). Imported, so a store without it carries * none of it. tests/store-propagate-undo.test.ts. */ share?: StoreShare; /** * The next state from a transport's answer to one of the store's actions: * a transport sends the action, the reducer does not run, and the store * takes `answer(state, value, cmd)`, the value being the answer's `state`. * `(_, value) => value` when the server answers the store's whole state. * Without it, a sent action leaves the state as it is (docs/store.md, * A store behind a transport). tests/store-bridged-answer.test.ts. */ answer?: (state: S, value: unknown, cmd: { action: string; target: any; payload?: any; }) => S; /** * The server's version of a state, a number that grows with every write it * applies: an answer is written only when its version is higher than the * one the store holds, so an older answer arriving last never replaces a * newer one. A version that is not a finite number falls back to arrival * order. Without it, the last answer to arrive wins. * tests/store-answer-version.test.ts. */ version?: (state: S) => number; /** * An action a transport sends applies its reducer at once, before the * server answers: a failure rolls it back (the later steps rebased), the * answer replaces it, and a plugin's refusal never shows it. The dispatch * answers an `Accepted` (`RegisterOptions.optimistic`). History undoes it * only with `undo`. Refused with `coalesce`. tests/store-optimistic.test.ts. */ optimistic?: boolean; /** * The store's sent actions go one at a time, in order, so the server * applies and answers them in the order they were sent, reads included * (`RegisterOptions.exclusive`, one key: the store's id). An action no * transport sends runs at once. tests/store-optimistic.test.ts. */ exclusive?: boolean; }; /** The router surface pattern 4B needs, named structurally so this module * imports nothing from `src/router`. */ export type StoreRouter = { currentRoute: { value: { location: { query: Record; }; }; }; setQuery: (patch: Record, opts?: { history?: 'push' | 'replace'; }) => void; }; /** A store on bus `B`: its actions and `$reset` return what `B`'s dispatch * returns (`ResultOn`). tests/store-result-types.test.ts. */ export type ChamberStore | null>, B extends BaseBus = BaseBus> = { readonly $id: string; /** Read-only by construction: there is no setter, so a direct write throws in * strict mode. The bus is the only mutation channel. */ readonly state: { readonly value: S; }; /** URL-backed fields (4B), absent when no `url` map was declared. */ readonly url: Record void; }>; /** Dispatches `$reset`, which sets `state()` afresh: a command like any * action, so plugins, listeners and history see it. Returns the dispatch * result, on an async bus its promise. */ $reset: () => ResultOn; /** Call `fn` with a field's new value each time a write changes it (by * identity), the store's own keyed event; returns the unsubscribe. A store * with no subscriber writes as it would without. docs/store.md. */ $onField: (key: K, fn: (value: S[K]) => void) => () => void; /** Resolves once the store holds the state it starts from: its saved state * read (`persist` on an async storage), its tabs' state taken (`share`), or * both. At once for a store with neither. Never waits on a field event, and * a failed read or a store disposed early resolves too. * tests/store-ready.test.ts. */ readonly $ready: Promise; $dispose: () => void; } & { [K in keyof R]: (target?: any, payload?: any) => ResultOn; }; /** * @internal A field of a store as its own cell, over the store's `$onField` * events: a reader of one field re-runs when that field changes, not on every * write of the store. One cell per store and field, for the store's life, * made by `make` (Vue's `shallowRef` for `fieldRef`, the library's `signal()` * for a form). Against a computed per field, it pays off from a few readers * (docs/store.md). */ export declare function _fieldCell(store: { readonly state: { readonly value: S; }; $onField: (key: K, fn: (value: S[K]) => void) => () => void; }, key: K, make: (value: V) => { value: V; }): { readonly value: S[K]; }; /** * What a store entry gives the one implementation below: the state cell, a * way to watch it, and the holder lifetime when there is one. The Vue entry * passes `shallowRef`, an `effect` and Vue's scopes; the Vue-less entry * (`vapor-chamber/store/core`) a cell over `signal()` and no scope. */ export type StoreRuntime = { cell(initial: T): { value: T; }; /** `deep`: the view a reader gets of the state (Vue's `reactive`). The core entry has none. */ view?(value: T): T; /** Call `fn(next, prev)` after each write that changes the cell; returns the * stop. A store starts one watch on its cell and stops it before another * (tests/store-one-watcher.test.ts). A write made during a call is delivered * after it, in order, and the last call is with the cell's value * (tests/store-write-during-delivery.test.ts). */ watch(cell: { value: T; }, fn: (next: T, prev: T) => void): () => void; scope?: { active(): boolean; onDispose(fn: () => void): void; }; }; /** @internal What a state half's owner gives it, read when a write runs. */ export type HalfOwner = { /** The owner's write of a reducer, which persist replays on a state read late. */ write: StoreWrite; /** Lands a write the owner holds, before another tab's state is written. Read only with `share`. */ land?: () => void; /** Writes another tab's state, merged by its owner (the outbox). Read only with `share`. */ put?: (next: S) => void; }; /** @internal A state half: a cell, its one watcher, and what the watcher feeds. */ export type StateHalf = { readonly cell: { value: S; }; /** Persist's hooks, while an async read is pending (`keep`, `held`); null without `persist`. */ readonly hooks: PersistHooks | null; /** Resolves when an async read of the saved state has landed; null when there was none to wait for. */ readonly ready: Promise | null; /** The field events (`$onField`). */ onField(key: string, fn: (value: unknown) => void): () => void; /** Stops the watcher, closes the share, marks every field subscriber off. */ dispose(): void; }; /** * @internal The state half: a cell, its one watcher, * and what that watcher feeds, in this order: persist's save, share's send, * the field events. A store builds its command half on it (reducers, the * ring, `coalesce`, facts). The library's own queues (the outbox, history, * the buffer) use it alone: no registration, no command on the user's bus, * no entry in the bus's stores, so `storeStates` and `liveStores` never see * them. Built once per owner. `first` maps the first state (DEV, a hot * update's carry). `owner` is read by persist and share only, so a half with * neither (history, the buffer) passes null. * tests/store-one-watcher.test.ts, tests/state-half.test.ts. */ export declare function _stateHalf(rt: StoreRuntime, options: { id: string; state: () => S; persist?: StorePersist; share?: StateShare; first?: (first: S) => S; }, owner: HalfOwner | null): StateHalf; export type DefineChamberStore = | null>>(id: string, options: ChamberStoreOptions) => (bus: B, router?: StoreRouter) => ChamberStore; /** @internal The store, over a runtime. */ export declare function createStoreDefiner(rt: StoreRuntime): DefineChamberStore; //# sourceMappingURL=store-base.d.ts.map