Version history for any app state, in the model you choose.
Hand Heddle your state each time it changes: a diagram, a meme, a whole game level. It keeps every version as a commit, inside your app, with no server. Pick linear for one timeline with undo and redo and nothing else. Pick graph for git-shaped history: branches, merge, and restoring one part of an old version. One UI component renders either.
The animation needs JavaScript, which has not run. Its captions follow.
Your app keeps its state as plain data. Heddle keeps the history of that state, in the model the app picks.
Hand Heddle the state each time it changes. Every version is stored as a commit.
Go back to any earlier commit. The app shows that state again.
In the graph model, a change made from an earlier commit starts a branch there. The first line of history is kept.
The graph model can also restore one part of an old version as a new commit. The rest of the state stays as it is.
An app that only needs undo and redo picks the linear model: one line, no branches. Same call, same storage.
Try it
A game level with its whole state versioned. Play it, then drag the slider back. Ten steps, eleven commits, made by the library when this page loaded. The slider calls goto() and the level is drawn from the state it returns. The panel lists every value in that state and marks the ones the last move changed. A 2.5D game editor is a planned consumer of Heddle. This figure sketches that use; it is not that editor.
This figure is live. It needs JavaScript, which has not run.
Multiplayer: many hands, one history
Four people, one board. Every copy converges, and nothing here is a server. Heddle sends nothing. It has the parts live sync is made of: state that merges key by key, a merge that takes a rule, and bundles that carry only what the other side lacks. heddle/sync adds the last-writer-wins register and the rule. heddle/stream carries the cursors.
This figure is live. It needs JavaScript, which has not run.
You are the orange one: click to add, drag to move, click a shape to paint. Ann, Ben and Cy are scripted. Each person edits their own copy, so a shape lands on your board at the next sync while its owner's cursor is already there. Slow the sync down or take Cy offline and the copies drift apart, then come back together. The graph is the room's real history: click a commit, or drag the slider, and the board and the cursors go back to that moment.
How one edit travels
1
Commit on your own copy
No round trip, no lock. Ann drops a star. Her copy commits at once. The star's position is a register: a clock, her name, the value.
2
Send the difference
Only what the room lacks. exportBundle({ have }) leaves out everything the room already holds. One edit travels as the nodes it changed, not as the board.
3
The room merges
The last writer wins. Different shapes merge by key. Two writes to one field go to the rule: the higher clock wins. The choice is recorded in the merge commit.
4
Everyone fast-forwards
One commit id on every copy. Each copy pulls the room's line. When the board goes quiet, every copy is at the same commit id, which is how you know they agree.
Decisions are commits
Every edit and every merge, replayable. Each edit is a commit that names who made it. Each merge records the overlaps it settled. The whole session can be replayed, branched from or restored in part, like any other history.
Ticks are a stream
Cursors, selections, anything you send often. A drag in progress is not a decision, and sixty of them a second should not be commits. They go in a stream: kept by time, capped, sent as plain chunks. The whiteboard keeps each person's cursor there, which is why the slider brings the cursors back too.
Where it fits
Boards, diagrams, levels people build. For two people typing in one paragraph, use a sequence CRDT and commit its snapshots. Last writer wins replaces whole values.
Pick a model: one thread, every thread, or a stream
linear: one timeline, undo and redo. graph: every thread, and merge. stream: ticks by time. Git is one history model, not the only one. linear has no branch, HEAD or merge in its API or in its UI. graph keeps every thread you start and can merge them. Both version a state and run on the same core, so storage, hashing, saving and verify() are shared. stream is for values that change many times a second: it hashes nothing and commits nothing. The app picks per kind of data, and most apps use two.
This figure is live. It needs JavaScript, which has not run.
Pick a rule, then pick yarns. Each pick is a commit of the whole sweater. The threads are drawn from the history object, and the console prints each call the app made and what it returned. Under linear: press undo() twice and pick a yarn, and the stitches ahead are cut from the line and kept as undone/1. The graph history starts with a second thread, idea-1, already forked from main: merge it, or go back and pick a yarn to start idea-2. Change the same part on two threads and the merge reports a conflict instead of guessing. Switching the rule starts again.
The third model: a stream
For ticks: live cursors, selections, sensor samples, price data. createStream({ capacity }) from heddle/stream keeps values by time in named channels. A push is an array append: no hash, no commit, no undo. at(channel, t) reads what was current at a time, buckets(channel, ms) groups ticks into candles, and exportChunk({ since }) makes plain JSON for your transport. Each channel keeps its newest ticks up to its capacity and drops the rest. It is not a history: it has no branches, and nothing in it can be merged or verified.
This figure is live. It needs JavaScript, which has not run.
About twenty ticks a second. The candles are buckets() over what the stream holds. The API and a sample
What each model can do
Every history carries these flags as history.capabilities. mountHistory renders from the flags, never from the model name, and your own UI can do the same. The yes and no cells below are printed from the library's CAPABILITIES export when this page is built.
Capabilities of the linear and graph models
Capability
linear
graph
What it gates
model
"linear"
"graph"
The chosen model. Informational: render from the flags, not from this name.
undoRedo
yes
no
undo(), redo(), goto(), canUndo, canRedo on the history object. The component has Undo and Redo in both models: on a graph history they step along the line HEAD is on.
labels
yes
yes
label(). Labelled commits are checkpoints on the scrubber.
branches
no
yes
branch(), branches(), renameBranch(), deleteBranch(). In Details: the branch list and Branch here.
checkout
no
yes
checkout(), undoCheckout(), a detachable HEAD. In Details: Check out.
merge
no
yes
merge(), previewMerge(), mergeBase(). In Details: Merge from.
revert
no
yes
revert(), previewRevert(). In Details: Revert.
partialRestore
no
yes
restore(), previewRestore() and parts. In Details: Restore part.
graph
no
yes
graph(), detachedTips(), more than one line of commits. In Details: the commit graph instead of a list.
sync
no
yes
importBundle() for peer sync
verify
yes
yes
verify()
remotes
no
yes
remote.add(), remote.list(), remote.remove(), fetch(), pull(), push(). Linear histories have none: upgrade to graph first.
The code for each
One sample per model. Flip it to Rendered to run exactly the code shown and use the result.
The model is recorded with the saved history. Opening a linear history with model: "graph" is an upgrade and needs no migration: the line becomes the main branch, and an undone position becomes a detached HEAD.
Graph opens as linear while it is one line.
That means one branch (not counting undone/*), no merge commit on it, and the current position on it. Otherwise opening throws E_MODEL and changes nothing.
The undone tail is kept.
Undo and redo write no commit. When the app commits after an undo, the commits that were ahead leave the line and can no longer be redone. They are not deleted: the tail is parked under undone/<n>, and is still hashed, saved, exported and checked by verify(). After an upgrade to graph, each parked tail is a branch.
Upgrade and downgrade
model-upgrade.ts
import { createHistory, loadHistory, saveHistory } from"heddle";
type Count = { n: number };
const doc = createHistory<Count>({ model: "linear" });
doc.commit({ n: 1 }, { message: "One" });
doc.commit({ n: 2 }, { message: "Two" });
doc.undo();
doc.commit({ n: 9 }, { message: "Nine" }); // edit after undo: "Two" leaves the line, and is kept
saveHistory(doc, kv, "doc");
// Upgrade: a linear history always opens as graph. The undone tail is a branch.const repo = loadHistory<Count>(kv, "doc", { model: "graph" });
const branches = repo.branches().map((b) => b.name); // ["main", "undone/1"]// Downgrade: opens as linear while it is one line. Otherwise it throws E_MODEL.const again = loadHistory<Count>(kv, "doc", { model: "linear" });
Add it in three steps
Your app keeps its own state shape. Heddle only needs the state as JSON. Each sample below runs as written against 0.8.0. Steps one and two are the whole job for an app that needs undo and redo.
1
Pick a model. Commit on every change.
One commit per change.
createHistory({ model: "linear" }), then commit(state) wherever your app updates its state. Heddle stores only what changed.
step1-commit.ts
import { createHistory } from"heddle";
type Grid = { cells: Record<string, string> };
// Pick the model. "linear" is one line with undo and redo. "graph" adds branches and merge.const history = createHistory<Grid>({ model: "linear" });
const grid: Grid = { cells: { a1: "red", a2: "blue" } };
history.commit(grid, { message: "Start" });
// Call commit wherever your app changes its state.function paint(cell: string, colour: string) {
grid.cells[cell] = colour;
history.commit(grid, { message: `Paint ${cell} ${colour}` });
}
paint("a1", "gold");
paint("b1", "slate");
const messages = history.log().map((c) => c.message); // ["Start", "Paint a1 gold", "Paint b1 slate"]const undone = history.undo().cells; // { a1: "gold", a2: "blue" }: one step backconst first = history.state(0).cells.a1; // "red": every earlier state is still there
2
Mount the history. Save automatically.
Drag to preview. Every change is saved.
mountHistory adds Undo, Redo and a scrubber. autosave saves every change, and loadHistory reads it back.
step2-timeline.ts
import { autosave, loadHistory } from"heddle";
import { mountHistory } from"heddle/ui";
type Grid = { cells: Record<string, string> };
const drawn: Grid[] = [];
const render = (grid: Grid) => void drawn.push(grid); // stand-in for your app's draw function// Load the saved history (empty the first time), then save after every change.const history = loadHistory<Grid>(localStorage, "my-doc", { model: "linear" });
const stop = autosave(history, localStorage, "my-doc");
if (!history.length()) history.commit({ cells: {} }, { message: "Start" });
// Undo, Redo and one scrubber. The component reads history.capabilities, so the same call works for "graph".const view = mountHistory(document.querySelector<HTMLElement>("#history")!, history, {
onPreview: (grid) => render(grid), // while dragging: nothing has moved
onChange: (grid) => render(grid), // undo, redo, drag released, a row clicked in Details
});
render(history.state());
3
Need branches? Pick graph.
Branch, restore one part, merge back.
Change one word: model: "graph". You get branches, restore for one part of an old commit, and merge.
step3-branch.ts
import { createHistory } from"heddle";
type Doc = { title: string; layers: Record<string, { colour: string }> };
// The graph model. createRepo(options) is the same call.const repo = createHistory<Doc>({ model: "graph", parts: { layer: (id) => `/layers/${id}` } });
const v1 = repo.commit({ title: "Poster", layers: { sky: { colour: "blue" }, sun: { colour: "gold" } } });
repo.commit({ title: "Poster", layers: { sky: { colour: "black" }, sun: { colour: "white" } } });
// Branch: try something without touching main.
repo.branch("idea", { checkout: true });
repo.commit({ ...repo.state(), title: "Night poster" }, { message: "New title" });
// Restore one part: only the sun goes back to v1. The sky and the title stay.
repo.checkout("main");
const restored = repo.restore(v1.id, "layer:sun");
// Merge: main changed the sun, idea changed the title. Different parts, so no conflict.const merged = repo.merge("idea");
const status = merged.status; // "merged"const state = repo.state();
// { layers: { sky: { colour: "black" }, sun: { colour: "gold" } }, title: "Night poster" }
Performance, tracked
A test lab runs the library and keeps every result. This is its record. 9 deterministic scenarios make real calls and check what each one did: undo and redo, branches, merge, restore, sync, storage, ids and a load test held to a budget. Every run is committed to a Heddle history tracked in the repository, and these charts are drawn from it. The lab page runs the same scenarios in your browser and has a benchmark for your machine.
Scenarios passing
9 of 9
Checks
111 of 111
Commit of one change, p95
1.4 ms budget 60 ms
Undo, p95
0.085 ms budget 40 ms
Objects written per commit
4 at most, on 300 items
Runs on record
4 in a Heddle history
✓ Undo, redo and the cut tail13/13
✓ Branches, checkout and a detached HEAD13/13
✓ Merge, conflict and revert14/14
✓ Restore one part12/12
✓ Bundles and live sync15/15
✓ Save, load and change the model12/12
✓ Ids from content, storage from change10/10
✓ Latency under load11/11
✓ Recordings replay exactly11/11
The charts need JavaScript, which has not run. The numbers above are from the latest run.
A commit hashes the whole state. Every commit walks every node of the state to find what changed, so its time grows with the size of the state, not with the size of the change. Undo, redo and jumps read stored nodes and stay fast.
Storage follows the change
A commit writes one path. Only the nodes from the changed value up to the root are new. Everything else is shared with the commit before.
Keep objects narrow
Group long lists of entries. An object is one stored node that lists all its keys. Change one entry of a 2,000-key object and that whole list is written again, and a long history of such edits can take more room than snapshots. Group the entries, by tile, layer or page, and the same edit rewrites one small group. The lab's benchmark has a Flat and Grouped switch that shows the difference.
Core ideas
Five rules carry the library. One picture each.
1Same content, same id
A commit's id is the hash of its state, its parents and its ops. Messages and times stay out of it, so two devices that never met agree.
A history lives in memory until you say where else. Walk as far as you need. There are four more places a history can live, each a few lines, and each works without the next. They stack: a browser app that syncs to a server uses memory, the browser and the server together. Async stores such as IndexedDB or a key-value service go behind cachedStore, which keeps the history in memory and writes changes back in the background.
This figure is live. It needs JavaScript, which has not run.
The recipes below light up for the stops on your path.
In memory
createHistory({ model }) and nothing else. Every commit is kept in a memory store, which is all an app needs for undo and redo within a session. Closing the page ends it. Every other recipe adds to this one: the working history stays in memory and is copied somewhere that lasts.
On this device, in a browser
autosave(history, localStorage, key). Tick boxes, undo a few, reload. autosave saves after every change, and loadHistory(localStorage, key, { model }) opens it on the next visit: the checklist, its history, the undo position and what can still be redone. saveHistory and loadHistory take any synchronous string store with get and set. saveRepo and loadRepo are the graph-model names for the same thing. Reads and writes are wrapped in try/catch: if the browser blocks storage, this demo says so and keeps its state in memory.
This figure is live. It needs JavaScript, which has not run.
Show the code
storage-kv.ts
import { createRepo, loadRepo, saveRepo } from"heddle";
// Any synchronous string store works: { get, set } or a Web Storage.const map = new Map<string, string>();
const kv = { get: (k: string) => map.get(k), set: (k: string, v: string) => void map.set(k, v) };
const repo = createRepo<{ n: number }>();
repo.commit({ n: 1 });
repo.commit({ n: 2 });
saveRepo(repo, kv, "my-doc"); // one JSON string: objects, branches, HEAD, reflogconst copy = loadRepo<{ n: number }>(kv, "my-doc");
const same = copy.head().commit === repo.head().commit; // true
On this device, on Bun
heddle/sqlite: every write goes to a file as it happens. It writes each object through bun:sqlite as it is made, so nothing is serialised twice and a crash loses nothing that was committed. Open the same file again and the history, its branches and its position are there. It runs on Bun only, so this page shows the code and does not run it. The test suite does. A custom adapter is four functions over strings: get(ns, key), set(ns, key, value), delete(ns, key) and keys(ns).
sqlite.ts
import { createRepo } from"heddle";
import { sqliteStore } from"heddle/sqlite"; // Bun only: uses bun:sqliteconst store = sqliteStore(process.env.HEDDLE_DB ?? ":memory:"); // a file path, or an open Databaseconst repo = createRepo<{ n: number }>({ store });
repo.commit({ n: 1 }); // every write goes straight to SQLiteconst n = repo.state().n; // 1, read back from the database
store.close();
On a server
A history is plain JSON: send the string, keep the string. Heddle makes the string and, when it comes back, checks every object against its hash before it trusts it. The key-value stores are synchronous, so await the text first and load it second. For a graph history, a hub repository behind one route with fetch, pull and push sends only the difference each way.
storage-remote.ts
import { createHistory, loadHistory } from"heddle";
// Your API stands in here as a Map: one string per document, read and written asynchronously.const server = new Map<string, string>();
const put = async (id: string, text: string) => void server.set(id, text);
const get = async (id: string) => server.get(id);
type Doc = { title: string };
const doc = createHistory<Doc>({ model: "linear" });
doc.commit({ title: "Draft" });
doc.commit({ title: "Final" });
doc.undo();
// Save: a history is plain JSON. This is the same text autosave writes on the device.
await put("doc-1", JSON.stringify(doc.exportBundle({ reflog: true })));
// Open it on another device. The stores are synchronous, so await the text first, then load it.const text = await get("doc-1");
const copy = loadHistory<Doc>({ get: () => text, set: () => {} }, "doc-1", { model: "linear" });
const title = copy.state().title; // "Draft": the undo position came alongconst canRedo = copy.canRedo; // true
Send what the other copy lacks. A diverged copy is merged, never overwritten. Replication is a graph-model capability. A bundle is plain JSON: objects, branches and HEAD. exportBundle({ have }) leaves out what the other copy already holds. importBundle checks every object's hash, fast-forwards branches, and parks a diverged tip under <remote>/<branch> for you to merge. Heddle does not send the bundle. Your app does. Remotes do the same exchange for you over one transport: pull and push.
This figure is live. It needs JavaScript, which has not run.
Show the code
bundles.ts
import { createRepo } from"heddle";
type Notes = { notes: Record<string, string> };
const ann = createRepo<Notes>();
const ben = createRepo<Notes>();
ann.commit({ notes: { a1: "Buy thread" } });
ben.importBundle(ann.exportBundle({ reflog: true }), { restore: true }); // exact copy
ann.commit({ notes: { a1: "Buy thread", a2: "Warp the loom" } });
ben.commit({ notes: { a1: "Buy thread", b1: "Fix the shuttle" } });
// Send only what Ben lacks. His main has moved too, so Ann's tip is parked on "ann/main".const delta = ann.exportBundle({ have: [ben.get("main").parents[0]!] });
const result = ben.importBundle(delta, { remote: "ann" });
// { objects: 3, created: [], updated: [], diverged: [{ branch: "main", savedAs: "ann/main" }] }if (result.diverged.length) ben.merge("ann/main");
const notes = ben.state().notes; // { a1: "Buy thread", a2: "Warp the loom", b1: "Fix the shuttle" }
On a timer, with a merge rule, this is live: see Multiplayer.
For developers
The code, the reference and the lab have pages of their own.