heddle

TypeScript library · version 0.8.0

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.

Add it in three steps Try it Pick a model

Runtime dependencies
0
heddle min + gzip
16.1 kB
heddle/ui min + gzip
12.9 kB

What Heddle does, in 33 seconds

The animation needs JavaScript, which has not run. Its captions follow.

  1. Your app keeps its state as plain data. Heddle keeps the history of that state, in the model the app picks.
  2. Hand Heddle the state each time it changes. Every version is stored as a commit.
  3. Go back to any earlier commit. The app shows that state again.
  4. In the graph model, a change made from an earlier commit starts a branch there. The first line of history is kept.
  5. 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.
  6. 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.

The state shape, the merge rule and the code

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
CapabilitylineargraphWhat it gates
model"linear""graph"The chosen model. Informational: render from the flags, not from this name.
undoRedoyesnoundo(), 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.
labelsyesyeslabel(). Labelled commits are checkpoints on the scrubber.
branchesnoyesbranch(), branches(), renameBranch(), deleteBranch(). In Details: the branch list and Branch here.
checkoutnoyescheckout(), undoCheckout(), a detachable HEAD. In Details: Check out.
mergenoyesmerge(), previewMerge(), mergeBase(). In Details: Merge from.
revertnoyesrevert(), previewRevert(). In Details: Revert.
partialRestorenoyesrestore(), previewRestore() and parts. In Details: Restore part.
graphnoyesgraph(), detachedTips(), more than one line of commits. In Details: the commit graph instead of a list.
syncnoyesimportBundle() for peer sync
verifyyesyesverify()
remotesnoyesremote.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.

model: "linear": undo, redo, one line

model-linear.ts
import { createHistory } from "heddle";
import { mountHistory } from "heddle/ui";

type Strip = { threads: string[] };

const doc = createHistory<Strip>({ model: "linear" });
doc.commit({ threads: ["red"] }, { message: "Start" });
doc.commit({ threads: ["red", "gold"] }, { message: "Add gold" });
doc.commit({ threads: ["red", "gold", "blue"] }, { message: "Add blue" });
doc.undo(); // back at "Add gold"; doc.redo() returns

const view = mountHistory(host, doc, { onChange: draw });

model: "graph": branches and merge

model-graph.ts
import { createHistory } from "heddle";
import { mountHistory } from "heddle/ui";

type Strip = { threads: { warp: string; weft: string } };

const repo = createHistory<Strip>({ model: "graph" });
repo.commit({ threads: { warp: "red", weft: "gold" } }, { message: "Start" });
repo.branch("idea", { checkout: true });
repo.commit({ threads: { warp: "red", weft: "blue" } }, { message: "Blue weft" });
repo.checkout("main");
repo.commit({ threads: { warp: "green", weft: "gold" } }, { message: "Green warp" });
repo.merge("idea"); // different threads changed: green warp, blue weft

const view = mountHistory(host, repo, { tab: "details", onChange: draw });

Changing the model later

Linear opens as graph. Always.

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.

    your app commit Start Paint Paint Paint one commit per change, oldest first
    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 back
    const first = history.state(0).cells.a1;              // "red": every earlier state is still there
  2. Mount the history. Save automatically.

    mountTimeline preview autosave localStorage
    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.

    main idea restore one part merge
    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.

Open the test lab Benchmark your machine Against other libraries

Time follows the state

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.

  1. a laptop a phone, offline hashhash c8426da c8426da =

    Same 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.

    both models Run it

  2. edit 3 nodes written · 6 reused

    A change rewrites one path

    State is stored as a tree. A commit writes the nodes from the changed value up to the root and reuses every other one.

    both models Run it

  3. restore(from, part) sunsky hilltext an old commitnow

    Lift one thread

    restore brings one part back from any commit, as a new commit. Everything else stays exactly as it is.

    graph model Run it

  4. sleeves trim both same part? you pick

    Merges never guess

    Different parts merge cleanly. The same part changed twice comes back as a conflict, and your app settles it.

    graph model Run it

  5. replay the ops → same hash? stops at the first commit that fails, and names it

    History can be checked

    verify() rehashes every object and replays each op log. It names the first commit that fails.

    both models Run it

Storage: pick your path

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, reflog

const 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:sqlite

const store = sqliteStore(process.env.HEDDLE_DB ?? ":memory:"); // a file path, or an open Database
const repo = createRepo<{ n: number }>({ store });
repo.commit({ n: 1 });        // every write goes straight to SQLite
const 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 along
const canRedo = copy.canRedo;     // true

Larger documents in a browser: IndexedDB through cachedStore. A shared copy on a server: remotes.

Replicated: two copies that both change

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.