@b2m9/reversible 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bob Massarczyk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# @b2m9/reversible
+
+Headless, framework-agnostic undo/redo for any state. You give it reversible
+operations; it gives you `undo`/`redo`/`jump` traversal, grouped transactions,
+checkpoints, and timeline scrubbing. It does **not** own your state, but composes
+with whatever store you already have.
+
+```bash
+npm install @b2m9/reversible
+```
+
+ESM-only. Zero runtime dependencies.
+
+## The model: command, not snapshot
+
+Most undo libraries snapshot your whole state into a `past`/`future` stack.
+`reversible` stores **inverse operations** instead. You `commit` a `do`/`undo`
+pair; the engine runs `do` and remembers how to reverse it.
+
+|                        | Snapshot-based                      | **@b2m9/reversible**                        |
+| ---------------------- | ----------------------------------- | ------------------------------------------- |
+| Coupling               | Higher-order reducer / store plugin | Headless, zero-dep, any store or none       |
+| History model          | Full copies of `present`            | Inverse operations (`do`/`undo`)            |
+| Memory cost            | State size × history depth          | Inverse-payload size — usually ≪ a snapshot |
+| Non-serializable state | Effectively unsupported             | Supported — you write the inverse           |
+| Grouping               | Auto-capture heuristics             | Explicit `transaction()` boundary           |
+| What's undoable        | Filter config                       | Caller decides — just don't `commit()` it   |
+
+The engine holds one ordered list of entries and a **cursor**:
+
+```
+   committed entries
+   ┌──────┬──────┬──────┐           ┌──────┐
+   │  e1  │  e2  │  e3  │   cursor  │  e4  │
+   └──────┴──────┴──────┘     ▲     └──────┘
+          undoable           here   redoable
+```
+
+Everything left of the cursor can be undone; everything right can be redone.
+"Present state" is **your app's**, not the engine's and it only knows how to move
+along the timeline of effects.
+
+> **The one responsibility you own:** `do` and `undo` must be true inverses.
+> The engine keeps its own bookkeeping consistent; it cannot fix a broken inverse.
+
+## One tiny example
+
+The external `count` is the point: your state, wherever it lives.
+
+```ts
+import { createHistory } from "@b2m9/reversible";
+
+const history = createHistory();
+let count = 0;
+
+history.commit({
+  label: "increment",
+  do: () => {
+    count += 1;
+  },
+  undo: () => {
+    count -= 1;
+  },
+});
+
+history.undo(); // count === 0
+history.redo(); // count === 1
+history.jump(-1); // count === 0 — scrub the whole timeline
+```
+
+## One transaction example
+
+Group many operations into one atomic entry — undone and redone as a unit.
+
+```ts
+history.transaction('type "hello"', (tx) => {
+  for (const ch of "hello") {
+    tx.commit({
+      do: () => doc.append(ch),
+      undo: () => doc.trimEnd(1),
+    });
+  }
+});
+
+history.undo(); // removes the whole word, not one letter
+```
+
+Wire it to UI with `subscribe`, which hands each listener a meta snapshot:
+
+```ts
+const off = history.subscribe((m) => {
+  undoBtn.disabled = !m.canUndo;
+  undoBtn.title = m.undoLabel ? `Undo: ${m.undoLabel}` : "Undo";
+});
+```
+
+## Failure rules
+
+- **Synchronous only.** `do`/`undo` must run synchronously. If one returns a
+  thenable, the engine throws loudly rather than fire-and-forget a promise it
+  can't reverse.
+- **Atomic transactions (best-effort).** If anything throws before a
+  `transaction` builder returns, the applied operations roll back in reverse and
+  the entry never enters history. "Best-effort" because atomicity holds only as
+  far as your inverses allow.
+- **Failed `commit` is a no-op.** If `do` throws, nothing is recorded, the cursor
+  doesn't move, and the redo branch is left intact.
+- **Boundaries clamp.** `undo()`/`redo()` return `false` at the ends. `jump(n)`
+  clamps and returns the signed count of steps actually moved (`jump(n) === n`
+  means fully moved). A throw mid-`jump` stops at the last successful step.
+- **A new commit after undo clears the redo branch.** Traversal never does.
+- **Reentrancy throws.** Calling back into the engine from inside a running
+  `do`/`undo`/rollback throws. `subscribe` listeners fire after the operation
+  settles, so calling back from a listener is fine.
+
+## API
+
+```ts
+const history = createHistory({ limit: 100 }); // limit is optional
+
+history.commit({ label?, do, undo });
+history.transaction(label, (tx) => tx.commit({ do, undo }));
+
+history.undo();    // boolean
+history.redo();    // boolean
+history.jump(n);   // signed steps moved
+
+history.canUndo;   // booleans / derived meta
+history.canRedo;
+history.undoLabel; // string | undefined
+history.redoLabel;
+history.position;  // cursor in [0, length]
+history.length;
+
+history.checkpoint(name);
+history.hasCheckpoint(name); // gate revertTo the way canUndo gates undo
+history.revertTo(name);      // throws if the name is unknown or was pruned
+
+history.clear();
+history.subscribe((meta) => { /* ... */ }); // returns unsubscribe
+```
+
+With `limit`, the oldest entries are evicted past the cap. Checkpoints anchor to
+the entry they sit after, so they stay correct as eviction renumbers positions; a
+checkpoint whose anchor is evicted (or dropped when a commit clears a redo branch)
+is pruned, and `revertTo` on it throws.
+
+## Non-goals
+
+- **It doesn't own your state.** No `present`, no store, no deep-clone. A thin
+  state-owning convenience wrapper may land later, layered on top.
+- **No async.** Reversing remote or async effects is a compensation-and-idempotency
+  problem this package deliberately does not solve.
+- **No branching timelines.** Checkpoints are markers on one line, not forks.
+
+## License
+
+MIT © 2026 Bob Massarczyk

package/dist/index.d.mts

@@ -0,0 +1,86 @@
+//#region src/types.d.ts
+/**
+ * A reversible operation: a `do`/`undo` pair the engine runs and remembers how
+ * to reverse. Both must be **synchronous** and **true inverses** of each other —
+ * that is the one responsibility the caller owns.
+ */
+interface Reversible {
+  /** Optional label, surfaced as `undoLabel`/`redoLabel` for UI tooltips. */
+  label?: string;
+  /** Run now and on every redo. Must be synchronous. */
+  do: () => void;
+  /** Run on undo. Must be synchronous. */
+  undo: () => void;
+}
+/** The builder handed to a {@link History.transaction} callback. */
+interface TransactionBuilder {
+  commit(action: Reversible): void;
+}
+/** A read-only snapshot of the engine's derived state, delivered to subscribers. */
+interface HistoryMeta {
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoLabel?: string;
+  readonly redoLabel?: string;
+  readonly position: number;
+  readonly length: number;
+}
+interface History {
+  /** Run an operation now and append it as a single undoable entry. */
+  commit(action: Reversible): void;
+  /**
+   * Group many operations into one atomic entry. Operations apply eagerly; if
+   * anything throws before `build` returns, the applied operations roll back in
+   * reverse, the entry never enters history, and the error rethrows.
+   */
+  transaction(label: string, build: (tx: TransactionBuilder) => void): void;
+  /** Undo one entry. Returns `false` (a no-op) at the start of history. */
+  undo(): boolean;
+  /** Redo one entry. Returns `false` (a no-op) at the end of history. */
+  redo(): boolean;
+  /**
+   * Move `n` steps (`n < 0` undo, `n > 0` redo), clamped at the ends. Returns
+   * the signed number of steps actually moved, so `jump(n) === n` means "fully
+   * moved". A throw mid-jump stops at the last successful step and rethrows.
+   */
+  jump(n: number): number;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoLabel?: string;
+  readonly redoLabel?: string;
+  /**
+   * Cursor index in `[0, length]`. `canUndo === position > 0` and
+   * `canRedo === position < length`.
+   */
+  readonly position: number;
+  readonly length: number;
+  /** Tag the current position with a name. Re-tagging an existing name moves it. */
+  checkpoint(name: string): void;
+  hasCheckpoint(name: string): boolean;
+  /** Jump to a checkpoint. Throws if the name is unknown or was pruned. */
+  revertTo(name: string): void;
+  /** Drop all entries and checkpoints; reset the cursor to 0. */
+  clear(): void;
+  /**
+   * Subscribe to history changes for UI binding; the listener reads its own
+   * application state. Returns an unsubscribe function.
+   */
+  subscribe(listener: (meta: HistoryMeta) => void): () => void;
+}
+interface HistoryOptions {
+  /**
+   * Cap on retained entries. When exceeded, the oldest entries are evicted
+   * (observable through `length`/`canUndo`). Must be a positive integer.
+   */
+  limit?: number;
+}
+//#endregion
+//#region src/core.d.ts
+/**
+ * Create a headless undo/redo engine. It tracks only the undo/redo stacks and a
+ * cursor — your application state lives wherever it already does. See the
+ * package brief for the full design.
+ */
+declare function createHistory(options?: HistoryOptions): History;
+//#endregion
+export { type History, type HistoryMeta, type HistoryOptions, type Reversible, type TransactionBuilder, createHistory };

package/dist/index.mjs

@@ -0,0 +1,257 @@
+//#region src/transaction.ts
+/**
+* True if `value` is a thenable (exposes a callable `then`). The single source of
+* truth for the engine's synchronous-only contract: a `do`/`undo` or transaction
+* builder that returns one has detached work the engine can never reverse.
+*/
+function isThenable(value) {
+	return value !== null && value !== void 0 && typeof value.then === "function";
+}
+/**
+* Run a transaction: apply each committed operation eagerly, and on success
+* collapse them into one entry whose `do` replays forward and whose `undo`
+* replays the inverses in strict reverse order.
+*
+* If anything throws before `build` returns — a committed op or the build
+* callback itself — the applied operations roll back in reverse and no entry is
+* recorded. Best-effort: if a rollback inverse itself throws, that error
+* surfaces and rollback stops.
+*/
+function runTransaction(engine, label, build) {
+	engine.assertIdle();
+	engine.beginMutation();
+	const ops = [];
+	let closed = false;
+	const tx = { commit(action) {
+		if (closed) throw new Error("reversible: transaction builder used after the transaction finished");
+		engine.runGuarded(action.do);
+		ops.push({
+			do: action.do,
+			undo: action.undo
+		});
+	} };
+	try {
+		const result = build(tx);
+		closed = true;
+		if (isThenable(result)) {
+			if (result instanceof Promise) result.catch(() => {});
+			throw new TypeError("reversible: transaction builder must be synchronous (it returned a thenable)");
+		}
+	} catch (error) {
+		closed = true;
+		try {
+			for (let i = ops.length - 1; i >= 0; i -= 1) engine.runGuarded(ops[i].undo);
+		} finally {
+			engine.endMutation();
+		}
+		throw error;
+	}
+	engine.endMutation();
+	if (ops.length === 0) return;
+	engine.append({
+		label,
+		do() {
+			for (const op of ops) engine.runGuarded(op.do);
+		},
+		undo() {
+			for (let i = ops.length - 1; i >= 0; i -= 1) engine.runGuarded(ops[i].undo);
+		}
+	});
+	engine.notify();
+}
+//#endregion
+//#region src/core.ts
+/** Sentinel anchor for a checkpoint at position 0 (before all entries). */
+const START = Symbol("reversible.start");
+/**
+* Create a headless undo/redo engine. It tracks only the undo/redo stacks and a
+* cursor — your application state lives wherever it already does. See the
+* package brief for the full design.
+*/
+function createHistory(options = {}) {
+	const { limit } = options;
+	if (limit !== void 0 && (!Number.isInteger(limit) || limit < 1)) throw new TypeError("reversible: limit must be a positive integer");
+	const entries = [];
+	let cursor = 0;
+	const checkpoints = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	let mutating = false;
+	/** Reentrancy guard: reject any public mutation while user code is running. */
+	const assertIdle = () => {
+		if (mutating) throw new Error("reversible: reentrant engine call from inside a do/undo/rollback");
+	};
+	/** Run a user operation, throwing loudly if it returns a thenable. */
+	const runGuarded = (fn) => {
+		if (isThenable(fn())) throw new TypeError("reversible: do/undo must be synchronous (it returned a thenable)");
+	};
+	const buildMeta = () => Object.freeze({
+		canUndo: cursor > 0,
+		canRedo: cursor < entries.length,
+		undoLabel: cursor > 0 ? entries[cursor - 1].label : void 0,
+		redoLabel: cursor < entries.length ? entries[cursor].label : void 0,
+		position: cursor,
+		length: entries.length
+	});
+	const notify = () => {
+		if (listeners.size === 0) return;
+		const meta = buildMeta();
+		for (const listener of listeners) listener(meta);
+	};
+	const pruneCheckpoints = (removed) => {
+		if (checkpoints.size === 0 || removed.length === 0) return;
+		const removedSet = new Set(removed);
+		for (const [name, anchor] of checkpoints) if (anchor !== START && removedSet.has(anchor)) checkpoints.delete(name);
+	};
+	const append = (entry) => {
+		if (cursor < entries.length) pruneCheckpoints(entries.splice(cursor));
+		entries.push(entry);
+		cursor += 1;
+		if (limit !== void 0 && entries.length > limit) {
+			const overflow = entries.length - limit;
+			pruneCheckpoints(entries.splice(0, overflow));
+			cursor -= overflow;
+		}
+	};
+	/**
+	* Walk the cursor `n` steps, running each inverse/forward op. Clamps at the
+	* ends. May throw mid-way, leaving the cursor at the last successful step.
+	*/
+	const traverse = (n) => {
+		const dir = n < 0 ? -1 : 1;
+		let remaining = Math.abs(n);
+		while (remaining > 0) {
+			if (dir < 0) {
+				if (cursor === 0) break;
+				runGuarded(entries[cursor - 1].undo);
+				cursor -= 1;
+			} else {
+				if (cursor === entries.length) break;
+				runGuarded(entries[cursor].do);
+				cursor += 1;
+			}
+			remaining -= 1;
+		}
+	};
+	/** Guarded traversal shared by jump/undo/redo/revertTo. Returns steps moved (signed). */
+	const move = (n) => {
+		const before = cursor;
+		mutating = true;
+		let caught;
+		try {
+			traverse(n);
+		} catch (error) {
+			caught = { error };
+		} finally {
+			mutating = false;
+		}
+		const moved = cursor - before;
+		if (moved !== 0) notify();
+		if (caught) throw caught.error;
+		return moved;
+	};
+	const commit = (action) => {
+		assertIdle();
+		mutating = true;
+		try {
+			runGuarded(action.do);
+		} catch (error) {
+			mutating = false;
+			throw error;
+		}
+		mutating = false;
+		append({
+			label: action.label,
+			do: action.do,
+			undo: action.undo
+		});
+		notify();
+	};
+	const undo = () => {
+		assertIdle();
+		if (cursor === 0) return false;
+		move(-1);
+		return true;
+	};
+	const redo = () => {
+		assertIdle();
+		if (cursor === entries.length) return false;
+		move(1);
+		return true;
+	};
+	const jump = (n) => {
+		assertIdle();
+		if (n === 0) return 0;
+		return move(n);
+	};
+	const checkpoint = (name) => {
+		assertIdle();
+		checkpoints.set(name, cursor === 0 ? START : entries[cursor - 1]);
+	};
+	const hasCheckpoint = (name) => checkpoints.has(name);
+	const revertTo = (name) => {
+		assertIdle();
+		const anchor = checkpoints.get(name);
+		if (anchor === void 0) throw new Error(`reversible: unknown checkpoint "${name}"`);
+		move((anchor === START ? 0 : entries.indexOf(anchor) + 1) - cursor);
+	};
+	const clear = () => {
+		assertIdle();
+		if (entries.length === 0 && checkpoints.size === 0) return;
+		entries.length = 0;
+		cursor = 0;
+		checkpoints.clear();
+		notify();
+	};
+	const subscribe = (listener) => {
+		listeners.add(listener);
+		return () => {
+			listeners.delete(listener);
+		};
+	};
+	const internals = {
+		assertIdle,
+		beginMutation: () => {
+			mutating = true;
+		},
+		endMutation: () => {
+			mutating = false;
+		},
+		runGuarded,
+		append,
+		notify
+	};
+	return {
+		commit,
+		transaction: (label, build) => {
+			runTransaction(internals, label, build);
+		},
+		undo,
+		redo,
+		jump,
+		checkpoint,
+		hasCheckpoint,
+		revertTo,
+		clear,
+		subscribe,
+		get canUndo() {
+			return cursor > 0;
+		},
+		get canRedo() {
+			return cursor < entries.length;
+		},
+		get undoLabel() {
+			return cursor > 0 ? entries[cursor - 1].label : void 0;
+		},
+		get redoLabel() {
+			return cursor < entries.length ? entries[cursor].label : void 0;
+		},
+		get position() {
+			return cursor;
+		},
+		get length() {
+			return entries.length;
+		}
+	};
+}
+//#endregion
+export { createHistory };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@b2m9/reversible",
+  "version": "0.1.0",
+  "description": "Headless, framework-agnostic undo/redo for any state — a small command stack of reversible operations with grouped transactions, checkpoints, and timeline scrubbing.",
+  "keywords": [
+    "checkpoint",
+    "command-pattern",
+    "headless",
+    "history",
+    "redo",
+    "state",
+    "time-travel",
+    "transaction",
+    "undo"
+  ],
+  "homepage": "https://github.com/b2m9/reversible#readme",
+  "bugs": {
+    "url": "https://github.com/b2m9/reversible/issues"
+  },
+  "license": "MIT",
+  "author": "Bob Massarczyk <bob@b2m9.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/b2m9/reversible.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test run",
+    "check": "vp check",
+    "check:exports": "vp pack && vp dlx publint && vp dlx @arethetypeswrong/cli --pack --profile esm-only",
+    "prepublishOnly": "vp run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "bumpp": "^11.1.0",
+    "typescript": "^6.0.3",
+    "vite-plus": "catalog:"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "packageManager": "pnpm@11.7.0"
+}