1.6.0

@zerolith/state

Import from @zerolith/state. Generated from the source; every signature below is what the published types declare.

Functions

stored

function stored<T>(key: string, initial: T, options?: StoredOptions<T>): Signal<T>

A writable signal kept in storage under key as JSON: read back on creation, written on every set, and set again when another tab writes the key, so every tab shows the same value. A missing value takes initial quietly; one that does not parse, or that the validate option refuses, takes initial and reports state_storage_unreadable. Setting undefined removes the key, so it reads back as initial; a value JSON cannot hold, such as a BigInt, stays in memory and reports state_value_not_json. Where the page has no storage, as on the server, the signal is a plain one and state_storage_unavailable is reported once, as it is for each write the storage refuses. Create each key once and share the signal: two stored signals for one key in the same tab do not hear each other, since the storage event tells other tabs alone, and the second reports state_key_duplicate. The write and the listener for other tabs are disposed with the enclosing owner when there is one, after which the signal keeps its value in memory alone; created in plain code, they live for the page.

Source: packages/state/src/stored.ts:129

history

function history<T>(source: Signal<T>, options?: HistoryOptions): History<T>

Undo and redo for source from explicit checkpoints: call checkpoint() before a change worth undoing, as an editor does before each edit, and undo() sets the signal back to it while redo() brings the undone value back. A new checkpoint after an undo starts a new branch, as in most editors, so what was undone is gone. limit checkpoints are kept, 50 by default. Each move writes the signal and both flags in one batch, so an effect over them runs once. Over a stored signal, a write from another tab makes the history forget its checkpoints, since going back to one would take that change back too; created inside an owner, the history stops listening for those writes when the owner is disposed.

Source: packages/state/src/history.ts:46

debounced

function debounced<T>(source: ReadableSignal<T>, ms: number): ReadableSignal<T>

A signal that follows source once it has been quiet for ms milliseconds, starting at its current value, so a search runs for the text a reader stopped typing rather than for every keystroke. The pending change is dropped with the enclosing owner when there is one.

Source: packages/state/src/timing.ts:12

throttled

function throttled<T>(source: ReadableSignal<T>, ms: number): ReadableSignal<T>

A signal that follows source at most once per ms milliseconds: the first change in a window shows at once, and the last one in it shows when the window ends, so a scroll position drives work at a steady rate. A change still pending is dropped when a newer one shows after the window, and with the enclosing owner when there is one.

Source: packages/state/src/timing.ts:37

selector

function selector<T>(source: ReadableSignal<T>): (key: T) => ReadableSignal<boolean>

A per-key view of source: selected(key) is a signal that is true while source holds key, and a change of source updates the two keys concerned alone, so a list of a thousand rows that each bind selected(row.id) runs two bindings on a selection, not a thousand comparisons. Keys are compared as Map keys are. A key's signal is shared by everyone who asks for it, and the selector keeps no hold of its own: the signal lives while a view reads it and goes with the row that did.

Source: packages/state/src/selector.ts:23

Interfaces

StoredOptions

interface StoredOptions<T>

Options for stored.

  • storage?: "local" | "session": Which storage keeps the value: localStorage, shared across tabs and kept across sessions, or sessionStorage, this tab's alone. Defaults to local.
  • equals?: (previous: T, next: T) => boolean: When two values count as the same, so a set of an equal value changes nothing; the signal's own option.
  • validate?: (value: unknown) => boolean: Whether a kept value, once parsed, is one the signal can hold. A value it refuses, or throws on, is read as initial and reported as state_storage_unreadable, on creation and when another tab writes the key, so data of another shape, such as another app's under the same key, never reaches the page.

Source: packages/state/src/stored.ts:7

History

interface History<T>

The undo and redo of one signal.

  • readonly canUndo: ReadableSignal<boolean>: True while undo() has somewhere to go, for a button to follow.
  • readonly canRedo: ReadableSignal<boolean>: True while redo() has somewhere to go.
  • readonly source: Signal<T>: The signal the history is of.
  • checkpoint(): void: Saves the signal's current value as the point undo() goes back to, and drops what redo() could have brought back.
  • undo(): boolean: Sets the signal back to the last checkpoint, keeping the current value for redo(); false when there is no checkpoint.
  • redo(): boolean: Sets the signal forward to the value the last undo() left; false when there is none.
  • dispose(): void: Forgets every checkpoint and every value redo() could bring back; the signal keeps its value.

Source: packages/state/src/history.ts:15

HistoryOptions

interface HistoryOptions

Options for history.

  • limit?: number: How many checkpoints are kept; the oldest goes when one more is saved. Defaults to 50, which a value that is not a finite number keeps.

Source: packages/state/src/history.ts:8