10 KiB
10 KiB
@suaveplan/undo - Enterprise-grade undo/redo engine with branching history, async commands, history compression, selective undo, and command merging
Summary
Enterprise-grade undo/redo engine with branching history, async commands, history compression, selective undo, and command merging. Built for collaborative editors, document tools, and any application requiring robust, reversible state management.
Documentation tree
- async-command — Provides factory functions and execution helpers for asynchronous commands in
@suaveplan/undo. Async commands follow… - async-stack — Implements
AsyncUndoStack<T>, the asynchronous counterpart toUndoStack<T>. All mutation methods (push,undo, `… - branch — (no submodules)
- branch — (no submodules)
- command — (no submodules)
- command — (no submodules)
- compression — (no submodules)
- history-compressor — (no submodules)
- errors — (no submodules)
- undo-error — (no submodules)
- merge — (no submodules)
- command-merger — (no submodules)
- schemas — (no submodules)
- undo.schemas — (no submodules)
- selective — (no submodules)
- selective-undo — (no submodules)
- stack — (no submodules)
- stack — (no submodules)
Install
bun add @suaveplan/undo
Quick Start
import { UndoStack, createCommand } from "@suaveplan/undo";
interface Counter { value: number }
const stack = new UndoStack<Counter>({ value: 0 });
const inc = createCommand(
"Increment",
(s) => ({ value: s.value + 1 }),
(s) => ({ value: s.value - 1 }),
);
stack.push(inc);
console.log(stack.current.value); // 1
stack.undo();
console.log(stack.current.value); // 0
stack.redo();
console.log(stack.current.value); // 1
Branching History
import { BranchingHistory, createCommand } from "@suaveplan/undo";
const h = new BranchingHistory({ value: 0 });
h.push(createCommand("A", (s) => ({ value: s.value + 1 }), (s) => ({ value: s.value - 1 })));
h.undo();
h.push(createCommand("B", (s) => ({ value: s.value + 2 }), (s) => ({ value: s.value - 2 }))); // forks
console.log(h.branches.length); // 2
Modules
| Module | Description |
|---|---|
src/command/command.md |
Command factories and execution helpers |
src/stack/stack.md |
Synchronous linear undo/redo stack |
src/branch/branch.md |
Branching history manager |
src/async/async-command.md |
Async command factories |
src/async/async-stack.md |
Async undo/redo stack |
src/compression/history-compressor.md |
History compression |
src/selective/selective-undo.md |
Selective undo by command ID |
src/merge/command-merger.md |
Command merging / coalescing |
src/types/undo.types.md |
All types and type guards |
src/schemas/undo.schemas.md |
Zod option schemas |
src/errors/undo-error.md |
Structured errors and codes |
Benchmarks
Measured on an AMD Ryzen 5 (WSL2), 1000 iterations:
| Operation | Throughput |
|---|---|
| UndoStack push/undo/redo (closure) | ~250k ops/s |
| UndoStack push/undo (patch, 50 fields) | ~15k ops/s |
| compressHistory (1000 entries, depth 100) | ~2k ops/s |
A >10% regression from baseline fails the CI performance gate.