Skip to main content

Interface: Amnesia

Defined in: types.ts:464

Public API exposed by AmnesiaProvider and consumed by useAmnesia().

The store is intentionally framework-agnostic so non-React layers (e.g. a CodeMirror plugin or a canvas renderer) can interact with it directly via the context bridge.

Properties​

amend​

amend: (patch) => Promise<number | null>

Defined in: types.ts:499

Amend the most recent past entry in place.

  • Targets past[past.length - 1] only; no key/window matching.
  • Preserves original fields unless overridden by patch.
  • Preserves the original pushedAt timestamp.
  • Clears the future stack (same as push).

Resolves to the amended entry id, or null when no amend occurred (empty past, busy, disposed).

Parameters​

ParameterType
patchAmendPatch

Returns​

Promise<number | null>

clear​

clear: () => void

Defined in: types.ts:528

Drop the entire past and future stacks without invoking any commands.

Use when the application enters a state where existing history would no longer be valid (e.g. a document switch).

clear() is always synchronous. It bumps the epoch counter so any in-flight async op resolves to a stale-drop on resume.

Returns​

void

dispose​

dispose: () => void

Defined in: types.ts:583

Tear down the store. Bumps epoch and empties the pending set so in-flight async ops resolve as no-ops without committing. Listeners are not notified.

Idempotent: safe to call multiple times.

AmnesiaProvider does not call dispose() automatically on unmount: doing so would conflict with React 18 StrictMode's simulated effect cleanup. The store will be garbage-collected along with the provider. Call dispose() yourself when sharing a store with non-React code that needs explicit teardown.

Returns​

void

getSnapshot​

getSnapshot: () => AmnesiaState

Defined in: types.ts:593

Read the latest snapshot.

Returns​

AmnesiaState

push​

push: (command, options?) => Promise<number | null>

Defined in: types.ts:486

Push a new command onto the past stack.

By default the command's redo() is called immediately. Pass { applied: true } to skip that initial invocation when the caller has already mutated the underlying state.

Pushing always clears the future (redo) stack — branching is not supported in the v0 API.

Always returns a Promise. For synchronous commands the Promise is already resolved by the time push returns (no microtask delay relative to side effects).

  • Resolves to the entry id on success.
  • Resolves to null when the call was dropped because another op was in flight (onError({ phase: "busy" })) or because clear() / provider unmount raced the await (onError({ phase: "stale" })).
  • Rejects with the original error when the command's redo throws on initial application; the entry is not added to the stack.

Parameters​

ParameterType
commandCommand
options?PushOptions

Returns​

Promise<number | null>

redo​

redo: () => Promise<number | null>

Defined in: types.ts:517

Redo the most recent future entry. No-op when canRedo is false.

Resolves to the entry id on success, null when nothing was redone or the op was dropped (busy / stale). A handler that throws leaves the entry in place and surfaces via onError({ phase: "redo" }).

Returns​

Promise<number | null>

subscribe​

subscribe: (listener) => () => void

Defined in: types.ts:590

Subscribe to store mutations. Returns an unsubscribe function. Mainly used by useSyncExternalStore; application code should prefer useAmnesia().

Parameters​

ParameterType
listener() => void

Returns​

() => void

transaction​

transaction: {(work): Promise<number | null>; (label, work): Promise<number | null>; }

Defined in: types.ts:562

Run a series of pushes as a single undoable composite entry.

The work function receives a TransactionApi handle. Each tx.push(command) runs the command's first-apply immediately and buffers the redo / undo pair. On successful resolution of work, a single composite entry is appended to the past stack whose redo re-runs all buffered redos in order and whose undo runs all buffered undos in reverse.

Behavior:

  • Sync work: commits a single notification at the end. Subscribers never observe an intermediate pending: true state.
  • Async work: notifies once on entry (pending: true) and once on commit (pending: false).
  • Throw / reject: every buffered undo runs in reverse to restore application state. The original error is re-thrown to the caller. Each rollback failure surfaces as onError({ phase: "rollback" }).
  • Stale: if clear() or dispose() runs during an async work, the transaction rolls back its buffered undos and resolves to null with onError({ phase: "stale" }).
  • Empty: if work resolves without calling tx.push, no entry is committed and the call resolves to null.
  • Nested: a transaction(...) call inside another transaction's work flattens into the outer. Its label argument is ignored (the outermost label or any tx.label(...) call wins) and it resolves to null immediately after its own work finishes.

The composite entry is never coalesced with stack neighbors; the transaction is always its own entry.

Call Signature​

(work): Promise<number | null>

Parameters​
ParameterType
work(tx, signal) => void | Promise<void>
Returns​

Promise<number | null>

Call Signature​

(label, work): Promise<number | null>

Parameters​
ParameterType
labelstring
work(tx, signal) => void | Promise<void>
Returns​

Promise<number | null>

undo​

undo: () => Promise<number | null>

Defined in: types.ts:508

Undo the most recent past entry. No-op when canUndo is false.

Resolves to the entry id on success, null when nothing was undone or the op was dropped (busy / stale). A handler that throws leaves the entry in place and surfaces via onError({ phase: "undo" }).

Returns​

Promise<number | null>