Convex Timeline

A Convex component for undo/redo state management with named checkpoints.

Overview#

Timeline maintains a linear history of state snapshots organized by scope. It provides:

• Undo/Redo: Navigate backward and forward through state history
• Checkpoints: Named snapshots that persist independently of the timeline
• Automatic Pruning: Configurable limits to prevent unbounded growth

https://github.com/user-attachments/assets/22bb5e41-89ac-4273-9bb7-7ab298e5d012

Read the How It Works section for details on the pruning strategy and possible future improvements.

Installation#

npm install convex-timeline

// convex/convex.config.ts
import { defineApp } from "convex/server";
import timeline from "convex-timeline/convex.config.js";

const app = defineApp();
app.use(timeline);
export default app;

Usage#

import { Timeline } from "convex-timeline";
import { components } from "./_generated/api";

const timeline = new Timeline(components.timeline);

// Use directly with scope
await timeline.push(ctx, "doc:123", { text: "Hello" });
await timeline.undo(ctx, "doc:123");

// Or create a scoped facade
const doc = timeline.forScope("doc:123");
await doc.push(ctx, { text: "Hello" });
await doc.undo(ctx);

See example/convex for a full example.

https://github.com/user-attachments/assets/75f3a2da-f2b4-43c2-aade-aa537afb5bb3

Hosted version

Constructor Options#

// Unlimited history (default)
new Timeline(components.timeline);

// Global limit
new Timeline(components.timeline, { maxNodesPerScope: 100 });

// Per-prefix limits (longest match wins)
new Timeline(components.timeline, {
  maxNodesPerScope: { "doc:": 200, "scratch:": 50 },
});

API#

All methods are available both on Timeline (with scope parameter) and on the scoped facade from forScope().

Timeline Operations#

Checkpoints#

Checkpoints are named snapshots stored independently—they persist even when nodes are pruned.

Inspection#

How It Works#

After three pushes:
    [A] → [B] → [C]
                head

After undo:
    [A] → [B] → [C]
          head

After push(D) — C is pruned:
    [A] → [B] → [D]
                head

This pruning behavior matches the standard undo/redo model used by editors like Google Docs, VSCode, and Notion, where pushing new state after an undo discards the forward history. Future versions may support alternative models such as manual branching, time travel, and reconciliation strategies, depending on community interest.

Checkpoints persist through pruning:

createCheckpoint("v1") at C → saves C's state
After C is pruned → checkpoint "v1" still holds C
restoreCheckpoint("v1") → pushes C as new node (undoable)

Example#

See example/ for a complete todo app with undo/redo.

cd example && npm install && npm run dev

FAQ#

Why do we prune the redo branch?#

I looked at many text editing programs (Google docs, VSCode, Notion, etc) and mimicked their behavior. When we undo and push, the redo branch can not be accessed again so we prune it to save on storage space.

Why are checkpoints stored in a separate table?#

Consider the case where we checkpoint a node that gets pruned, either because the scope reaches capacity or it's part of the redo branch. In this case, we can no longer restore to that state if we stored the checkpoint as a property of the node.

Why does restoring a checkpoint create a new node instead of traveling back to it?#

The original node might not exist anymore if it was pruned. Even if it does exist, creating a new node makes the restore undoable, meaning you can go back to where you were before restoring. It also protects the restored state from being pruned if you undo and push new state later. There is a future where I introduce a time-travel mode if there is demand for it.

Why not use the Convex transaction log?#

Ideally the Convex transaction log (described here) can be used so we can specify pointers to data (obviously this would be more complicated since we'd need to consider indexes) but unfortunately Convex does not currently expose the transaction log.

In addition to this, it's not necessary the case that the timeline component is only used for tracking documents in tables. It can be used for any data!

License#

MIT