LedgerUtilities

Serialized reversible command history with cancellation ownership and atomic reactive snapshots.

Version

v26.10.0

Size

1.9 KB gzip

Dependencies

Zero dependencies

Runtime support

BrowserNode ≥22SSRDeno

Key exports

composecreateLedgerLedgerErrorLedgerCancelledErrorLedgerConfigError View all 8 exports

Works well with

ripple keymap forge vault

Why Ledger?

Undo and redo require more than array manipulation when operations are asynchronous, cancellable, and visible in a UI. Ledger serializes only reversible commands, owns queue lifecycle, and publishes one atomic framework-neutral state snapshot without a reactive runtime dependency.

// Before
const undo = () => changes.pop()?.revert();

// After
import { createLedger } from '@vielzeug/ledger';

const ledger = createLedger();
await ledger.do({ apply: saveNext, revert: restorePrevious });
await ledger.undo();

Feature	Roll your own	Ledger
Bundle size	0 B	1.9 KB
Reversible history	Manual arrays
Serialized async work	Manual queue
Queue cancellation	Manual ownership	Abort-aware lifecycle
Framework-neutral state	Manual events	Structural Subscribable<LedgerState>
Composition	Custom transaction code	compose()

Use Ledger when you own reversible asynchronous state transitions and need undo, redo, or history UI.

Consider direct application code when work is irreversible, fire-and-forget, or does not need history.

Installation

pnpm

pnpm add @vielzeug/ledger

npm

npm install @vielzeug/ledger

yarn

yarn add @vielzeug/ledger

Quick Start

Submit a reversible command, read state, then dispose its owner.

import { createLedger } from '@vielzeug/ledger';

let value = 'before';
const ledger = createLedger();

await ledger.do({
  apply: () => { value = 'after'; },
  label: 'Rename value',
  revert: () => { value = 'before'; },
});

await ledger.undo();
console.log(ledger.state.getSnapshot().undo.length); // 0
ledger.dispose();

Features

• createLedger(): Create serialized reversible command history
• state: Read atomic queue, undo, redo, and acceptance state
• compose(): Combine reversible commands into one reversible command
• whenIdle(): Await queued and active operation settlement
• LedgerCancelledError: Distinguish cancellation from execution failure
• maxHistory: Keep a non-negative safe-integer undo depth
• [Symbol.dispose](): Seal, abort, and clear a ledger owner

Documentation

• Usage Guide
• API Reference
• Examples
• Migration Guide

See Also

• Ripple: Project Ledger's structural state readable into a signal when reactive derivations are needed.
• Keymap: Route undo and redo shortcuts to a Ledger error boundary.
• Forge: Record reversible form transitions.
• Vault: Persist application snapshots outside transient undo history.