State options
state(value, options) accepts these options. They combine freely, except debounce with throttle.
| Option | Type | What it does |
|---|---|---|
equals |
(a, b) => boolean |
Replaces Object.is to decide whether a write is a change. |
validate |
(next, prev) => value |
Coerces or rejects writes. Return prev to reject. |
persist |
string |
Saves to localStorage under this key and syncs across tabs. |
url |
string or { param, replace? } |
Two-way sync with a query parameter. Back and forward work. |
history |
number |
Keeps this many past values for undo() and redo(). |
debounce |
number (ms) |
Applies a write only after writes stop for this long. |
throttle |
number (ms) |
Applies at most one write per interval: the first one now, the last one at the end. |
save |
(next, prev, { signal }) => unknown |
Sends each change to a server. Writes apply at once and roll back if the save fails. |
#equals
import { deepEqual } from '@inflector/keeno'
const filters = state({ tags: [] as string[] }, { equals: deepEqual })
filters.set({ tags: [] }) // no change, nothing re-runsdeepEqual compares primitives, arrays, plain objects and dates structurally.
#validate
validate(next, prev) runs on every write, and also on the initial value and on values loaded from storage or the URL. Return the value to store. Return prev to reject the write.
const volume = state(50, { validate: (v) => Math.min(100, Math.max(0, v)) })
const age = state(30, { validate: (v, prev) => (Number.isInteger(v) && v >= 0 ? v : prev) })With bind:value, the input shows the stored value after a coerced or rejected write.
#persist
const todos = state<Todo[]>([], { persist: 'todos' })- On creation, the saved value (JSON) replaces the initial value, after
validate. Unreadable data is ignored. - Every change is saved, and other tabs with a state on the same key receive it through
BroadcastChannel. - Values must be JSON-serializable. Writing
undefinedremoves the key.
#url
const page = state(1, { url: 'page' }) // ?page=2
const q = state('', { url: { param: 'q', replace: true }, debounce: 300 })- Reading: the initial value comes from the query parameter, parsed according to the default's type:
- strings as-is
- numbers with
Number(an invalid number falls back to the default) - booleans from
true,1or an empty value - anything else as JSON
- Writing: writes update the query. All URL states changed in the same tick produce a single history entry. When the value equals the default, the parameter is removed.
- Back and forward: both restore earlier values without adding entries.
replace: true: useshistory.replaceState, for values like a search box that shouldn't fill the history.
#history
<script lang="ts">
const text = state('', { history: 100 })
</script>
<textarea bind:value={text}></textarea>
<button disabled={!text.canUndo} onClick={() => text.undo()}>Undo</button>
<button disabled={!text.canRedo} onClick={() => text.redo()}>Redo</button>- Each change pushes the old value, and the stack keeps the last
historyvalues. Because updates are immutable, this stores references and doesn't copy. - A new write clears the redo stack.
canUndoandcanRedoare reactive.undo()andredo()notify like normal writes, so persistence and URL sync follow.- Without the option,
undo()andredo()do nothing.
#debounce and throttle
const search = state('', { debounce: 300 })
update(() => {
fetchResults(search) // runs 300 ms after typing stops
})- debounce: the value changes only when writes stop for that long.
- throttle: the first write applies immediately, and later writes in the window collapse into one at the end.
- Inputs: with
bind:valuethe input keeps what the user types while a write is pending. - Unmount: pending writes are dropped when the component unmounts.
#save
save makes a state optimistic: a write shows at once, then save(next, prev, { signal }) sends it. If the returned promise rejects, the state goes back to the last saved value and the error goes to the nearest <ErrorBoundary>.
<script lang="ts">
const todos = state<Todo[]>(initial, {
save: (next, prev, { signal }) =>
fetch('/api/todos', { method: 'PUT', body: JSON.stringify(next), signal }).then((r) => {
if (!r.ok) throw new Error('Could not save')
}),
})
</script>
<button onClick={() => todos.set([...todos, { id: Date.now(), title: 'New' }])}>Add</button>
{pending(() => todos) && <small>Saving…</small>}- Concurrency: a newer write aborts the older save (pass
signaltofetch). Only the latest save decides the outcome. - Server response: resolve with a value to replace the state with it, for example the saved record with its new id. Resolving with
undefinedkeeps the state as it is. - pending:
pending(() => todos)is true while a save is in flight, andbind:valuedoesn't overwrite what the user is typing during it. - Other options:
saveruns afterdebounce/throttle, and also forundo()/redo(). Values loaded from storage, the URL or another tab don't trigger it.