/** * vapor-chamber - the command state: what is in flight on a bus, and what failed. * * Framework-neutral. It is the bus's one internal observer (`Facts`: each * command's start and settle), never a user hook or listener, so a sealed bus * needs no unseal and nothing of it appears in `inspectBus`. Its values are * `signal()` cells: Vue refs once Vue is wired, so a Vue view copies nothing. * Without a reactive backing, `subscribe(fn)` says when a value moved. * * One state per bus, shared and ref-counted: every `commandState(bus)` gets a * handle on it, and the last handle's `dispose()` releases it. While a command * it saw start is in flight, the state outlives its last handle, so the next * one sees that key still pending (tests/shared-state-handover.test.ts). Once * released, the bus's observer is handed back as null and the bus is bare * again: keeping it armed for ever cost an unheld bus 232 ns per dispatch * against 35 (docs/decisions.md, 2026-10-01). */ import { type Signal } from './signal'; import { type BaseBus } from './command-bus'; /** One handle on a bus's command state (`commandState`). */ export type CommandState = { /** * In flight for this key, bus-wide: any dispatch counts, from any caller. * Keyed like `commandKey`, so object targets match by value. `pending(action)` * is the exact key `(action, undefined)`, not "any target of this action". * Its own signal, written only when its count crosses 0 <-> 1. Counting * starts at the first `pending()` call or `anyPending` read: a dispatch * already in flight then is not counted. */ pending(action: string, target?: unknown): Readonly>; /** Any command in flight on the bus, written on 0 <-> 1. Reading it starts counting. */ readonly anyPending: Readonly>; /** The bus's recent failures, newest last, at most `maxSize`. */ readonly errors: Readonly>; /** The bus's most recent failure. */ readonly lastError: Readonly>; /** Wipe `errors` and `lastError`. Pending keys are untouched. */ clear(): void; /** Call `fn` after a fact moved a value this state holds. Returns the unsubscribe. */ subscribe(fn: () => void): () => void; /** Release this handle, once. The last one releases the state. */ dispose(): void; }; export type CommandStateOptions = { /** How many recent errors `errors` keeps. Default 10. A later handle may * lower it, never raise it. */ maxSize?: number; }; /** * commandState - what is in flight on `bus`, and what failed, for any * framework or none. * * Returns a handle on the bus's one shared state: `pending(action, target?)`, * `anyPending`, `errors`, `lastError`, `clear()`, `subscribe(fn)` and * `dispose()`. Every handle reads the same signals. Throws * `core:invalid:bus` for a bus this library did not make. * * @example * const state = commandState(bus); * const saving = state.pending('cartAdd', { id: 1 }); * state.subscribe(() => render(saving.value)); * // later * state.dispose(); */ export declare function commandState(bus: BaseBus, options?: CommandStateOptions): CommandState; //# sourceMappingURL=command-state.d.ts.map