JSON Delta History
Problem
The reversible state is a JSON document (a shared config, a form payload, a game entity) and you want history entries that are small, serializable, and transportable — closures over captured snapshots cannot be persisted to storage or shipped to peers, and whole-document snapshots per command grow with document size instead of change size.
Solution
Model each command as a JSON Patch plus its inverse. apply and revert stay two-line functions; the history entries themselves are plain JSON, so they can be logged, stored, or forwarded — and patchwork's copy-on-write apply makes even the untouched paths free.
import { createLedger } from '@vielzeug/ledger';
import { apply, diff, type JsonPatch, type JsonValue } from '@vielzeug/patchwork';
type Doc = { [key: string]: JsonValue };
const ledger = createLedger<{ label: string }>();
let doc: Doc = { budget: { coffee: 12 }, title: 'Roadmap', votes: [] };
/** Records `patch` as a reversible command; forward+inverse patches are plain JSON. */
async function edit(patch: JsonPatch, label: string): Promise<void> {
const next = apply(doc, patch);
if (next === doc) return; // no-op: nothing to remember
const inverse = diff(next, doc);
await ledger.do({
apply: () => {
doc = apply(doc, patch);
},
label,
meta: { label },
revert: () => {
doc = apply(doc, inverse);
},
});
}
await edit([{ op: 'replace', path: '/budget/coffee', value: 15 }], 'coffee budget');
await edit([{ op: 'add', path: '/votes/-', value: 'lgtm' }], 'vote');
await ledger.undo(); // drops the vote; the budget edit staysLocal edits do not need hand-written patches — diff computes the forward patch, which doubles as the payload you can broadcast to collaborators (a tavern guest applies the same patch, so history and wire format are one artifact):
await edit(diff(doc, { ...doc, title: 'Roadmap v2' }), 'rename');Pitfalls
- Compute the inverse against the exact document the command runs on (before submitting), not lazily inside
revert; Ledger serializes execution, but a lazily captured inverse reverts against whateverdocis by then. - A command reverting after external mutation throws
PatchPathErrorbecause its pointers no longer resolve. Either let the UI surface that as "history invalidated", or prefix submitted patches with a{ op: 'test', path: '/rev', … }operation — see the patchwork usage guide for the lock pattern. - Keep
Docinside the JSON domain:Date,undefined, maps, and functions must be encoded (or validated away with Spell) before they reach the document. - Skip no-ops (
applyreturns the same reference when nothing changed): a history full of empty patches makes undo feel broken. - If you never need to persist or ship history, storing the previous document reference (
revert: () => { doc = before; }) is cheaper than storing inverse patches, because structural sharing makes the old root nearly free to keep.