Interface: Command

Defined in: types.ts:49

A single reversible action on the history.

Commands are stored as a pair of imperative thunks:

• redo() — apply the action (called on every redo, and on initial push when do is omitted).
• undo() — revert the action.

An optional do field lets the initial application differ from a redo replay. Use it when first-apply requires setup that re-apply does not (e.g. inserting a freshly-created object whose id was just minted).

Implementations are responsible for capturing whatever closure state they need to perform the inverse. Amnesia does not introspect the value.

All handlers may be synchronous or asynchronous. When a handler returns a Promise, the surrounding push / undo / redo call awaits it; the store stays in a pending state for the duration of the await and other concurrent operations are dropped (see AmnesiaState.pending).

Each handler is called with an AbortSignal argument. The signal aborts when clear(), dispose(), or scope teardown runs while the handler is in flight. Async handlers can pass the signal to fetch (which cancels the network call automatically) or check signal.aborted in long loops. A rejection thrown after signal.aborted === true is treated as a silent no-op — no onError event fires, the entry is dropped. Handlers that ignore the signal still drop the commit via the existing epoch check; the difference is that onError({ phase: "stale" }) then fires. Synchronous handlers receive a signal too, but it is never aborted before they return.

Properties

coalesceKey?

optional coalesceKey?: string

Defined in: types.ts:106

Coalesce key. Consecutive pushes with the same non-empty key collapse into one entry on the stack: only the most recent redo is kept, but the original entry's undo is preserved so a single undo restores the pre-coalesce state.

Typical use: rapid keystrokes in a text input share a coalesceKey like "edit:title" so a single Ctrl+Z undoes the burst rather than each key.

Coalescing also requires passing the effective coalescing window for this push:

• command.coalesceWindowMs when defined, otherwise scope/provider coalesceWindowMs
• Number.POSITIVE_INFINITY disables time-bound checks
• <= 0 disables coalescing for this push

---

coalesceWindowMs?

optional coalesceWindowMs?: number

Defined in: types.ts:115

Optional per-command override for coalescing window resolution.

• undefined uses the scope/provider coalesceWindowMs.
• Number.POSITIVE_INFINITY disables the time bound (pure adjacency).
• <= 0 disables coalescing for this push.

---

do?

optional do?: (signal) => void | Promise<void>

Defined in: types.ts:71

Optional initial-apply handler. When present and push is called without applied: true, do(signal) is invoked exactly once at push time instead of redo(signal).

do is consumed at push time and is not stored on the entry — subsequent redo() calls always invoke command.redo. Use this when the inverse of "first apply" and "re-apply after undo" need different closures (e.g. inserting a freshly-minted node vs. restoring it by id).

When do is omitted, the store falls back to redo for the initial application. Most reversible state changes do not need do.

May be synchronous or return a Promise.

Parameters

Parameter	Type
signal	AbortSignal

Returns

void | Promise<void>

---

label?

optional label?: string

Defined in: types.ts:54

Human-readable label, surfaced through the history snapshot. Useful for "Undo last edit" style UI. Optional but recommended.

---

meta?

optional meta?: Record<string, unknown>

Defined in: types.ts:120

Free-form metadata for tooling. Not interpreted by Amnesia.

---

redo

redo: (signal) => void | Promise<void>

Defined in: types.ts:81

Apply (or re-apply) the action.

Called on every redo() for this entry. Also invoked once on push when do is absent and applied: true is not set.

May be synchronous or return a Promise.

Parameters

Parameter	Type
signal	AbortSignal

Returns

void | Promise<void>

---

undo

undo: (signal) => void | Promise<void>

Defined in: types.ts:88

Revert the action. Called on every undo() for this entry.

May be synchronous or return a Promise.

Parameters

Parameter	Type
signal	AbortSignal

Returns

void | Promise<void>