signal-timeline.

All projects

Public repository

Undo and history for SignalStore

Undo and redo, transactions, a branching undo tree, shared history across stores and a time-travel panel for NgRx SignalStore. History is kept as patches, so the memory footprint stays small on large states.

Drawing shapes in the demo editor, undoing, branching the history, jumping between branches and scrubbing the timeline.

The demo interface is in English. Recording from the repository, no sound.

Why I built it.

I use signals based Angular daily, and the diagram editors I build at work require undo that never loses a step. SignalStore already has linear undo (withUndoRedo in @ngrx-toolkit/core), and linear undo is sufficient for many apps. An editor requires more. A change made after an undo should not clobber the redo history. A gesture that touches two stores should undo in one step. And moving through history should not save the document to a server again.

So this library picks up where linear undo leaves off: a branching tree, transactions, multi-store history and time travel that leaves side effects alone. It is all built from scratch, and the demo is a small SVG editor made specifically for this project.

Try it in the demo.

The demo is a vector editor with a history panel: the entry tree, a timeline scrubber and a diff table.

Undo and redo
Draw a few shapes and use Ctrl+Z and Ctrl+Shift+Z, or the Undo and Redo buttons.
A branch instead of lost history
Undo a few steps and draw something new. The old future stays: a new branch appears next to it in the history tree.
Jump and scrub
In the history panel click any entry in the tree or drag the timeline slider to jump to that state.
One undo for a delete
Connect two shapes with a connector and delete one of them. It goes together with its connectors, and a single undo brings everything back.
An autosave that stays quiet
The counter under the history shows how often autosave ran. It grows while you draw, and undo, redo and jumps do not move it.
Reload and keyboard
Reload the page, and the drawing and the whole tree come back from session storage. The editor works with the keyboard alone: hit Add rectangle, Tab to the shape, then use the arrow keys.

signal-timeline.adrianturbinski.pl

Three hard parts.

Each decision has its ADR in the repository, with the alternatives that lost.

  • Effects must stay quiet during undo.

    An effect that saves the document runs after patchState, during the next change detection pass. By then, a flag that is true only while the timeline is writing the state is already false. So the timeline maintains a replay window that closes after the next render, and skipReplay and ignoreReplays read from it. The tests run four kinds of listener through undo, redo, jump and a live change, with zone.js and without, and pnpm negative-controls breaks the helpers intentionally to check that the tests notice.

    The price you pay: undo should live inside event handlers and methods. When you start a replay from within an effect, its window closes one render too late, so the effects it triggers are not skipped.

    What lost: a boolean set around patchState (which is already false for effects) and asking each effect to compare the state to the previous one.

    ADR 0007 on GitHub
  • Recording has to stay cheap on large state.

    patchState is a free function, so the library cannot wrap it and records changes through watchState instead. Diffing a 10,000 entity map in that callback would scan it on every write. A new entry just stores the before and after references, and the patches are calculated in a microtask or on demand.

    The cost: the work moves behind the call. Computing the patch for a single entity update in a 10,000 entity map takes about 1.2 ms in Node, because the diff has to examine every key. The 0.1 ms target is not met for that work.

    What lost: an eager diff in the watcher (100 to 1,000 times over the target), a store.patch method in place of patchState, and storing snapshots only, where memory grows with the state on every change.

    ADR 0006 on GitHub
  • Jumping on a long history.

    Applying patches from the beginning is slow, and a snapshot for each entry is bulky. A checkpoint every 250 entries bounds the walk, and a checkpoint is a reference to a structurally shared state, not a copy.

    The tradeoff: maxEntries has to prune history without breaking the tree structure. The library prunes the oldest leaf that is not on the path to the current entry, so entire branches can disappear.

    Lost: a flat array of entries (no branches), a full snapshot per node (the memory overhead this project exists to avoid) and recomputing from the root on every jump (correct, but slow).

    ADR 0005 on GitHub

Numbers.

Only what the scripts in the repository measured.

0.005 ms
Median extra time on a patchState call (updateEntity) with 10,000 entities, in Node, against a plain store. Target: under 0.1 ms per call.
1.2 ms
Time taken to calculate the patches after one entity changes in a map of 10,000 entities, in Node (7.9 ms at 50,000). This work happens after the call, and the 0.1 ms target does not cover it.
98.7x
Heap reduction compared to snapshots after 10,000 small edits on a state of 10,000 entities (26.62 MB against 2,626.62 MB). At 100 entities, the history takes more memory than snapshots.
0.6 ms
Median of a jump to a random entry: a history of 10,000 entries spanning 1,000 entities, checkpointEvery 250, Node. Undoing one step takes 0.021 ms.
662
Vitest tests: 548 in the library and 114 in the demo, plus 25 Cypress tests on the production build and 32 checks against the packed tarball. Line coverage is 98.4% for the library and 97.0% for the demo.
100
Lighthouse accessibility score on the production build of the demo, for mobile and desktop. Since Lighthouse only loads the blank editor, Cypress also runs axe with shapes added to the canvas.

Measured on 2026-10-04 on a laptop shared with other processes, so tiny differences in timings are just noise: Intel Core i7-12700H, 15 GB RAM, WSL2, Node 24.21.0 and Chromium 153 (headless). The Node numbers are more precise, because Chromium’s timer only has 0.1 ms resolution.

The result files in bench/results

What is not built.

Typed migration of persisted history, a Redux DevTools bridge and merging of remote changes were cut.

State must be plain data
Dates, Maps and class instances are treated as atomic values, and persisted state must be JSON safe.
No move detection
Reordering a long array produces a patch the size of the changed middle.
Persistence
Each save stores the entire history. Persisted history is validated by replaying its forward patches, but I do not verify that an inverse patch really undoes its forward patch. So if a payload was edited by hand, an undo can land on the wrong state.
A screen reader and a narrow screen
I ran axe and keyboard tests on the ARIA tree, but not a screen reader, and role tree on SVG is less consistently supported than on HTML. The demo was designed with a laptop in mind, and shape names are tiny on a 360 px screen.
Comparisons with other libraries
I read the source of the closest projects but did not benchmark them. In withUndoRedo 22.0.1 the maxStackSize option limited nothing in my test.

What comes next.

First I would test the tree with a screen reader, then make entries() incremental and add a typed migration.

ADR 0011: the ARIA tree and its fallback

Tech

  • Angular
  • TypeScript
  • NgRx
  • SignalStore
  • Signals
  • RxJS
  • Cypress
  • GitHub Actions
  • npm
  • Keyboard support

Let's talk about the role.

contact@adrianturbinski.pl

Tell me about the team, the product and the stack.

Got a project to build? There's a client edition too.