# @zerolith/state

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

## Functions

### stored

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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

```ts
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`