The undo button is the easy part

The whole API is two functions

apply mutates your local state synchronously and returns its inverse. commit persists it and returns a promise. That is the entire seam.

import { defineAction } from '@sharma/undoable';

defineAction('archiveItem', {
  apply: (id) => {
    const index = items.findIndex((i) => i.id === id);
    const [item] = items.splice(index, 1);
    render();
    return () => {                      // ← the inverse, returned inline
      items.splice(index, 0, item);
      render();
    };
  },
  commit: (id) => fetch(`/items/${id}/archive`, { method: 'POST' }).then(assertOk),
});

Binding is delegated from document, so rows inserted later just work. No registration step, no init call, no component wrapper:

<li data-undoable="archiveItem"
    data-undoable-arg="42"
    data-undoable-label="Item archived">
  <button data-undoable-trigger>Archive</button>
</li>

The runtime handles the undo window, the rollback on failure, the commit on timeout, the commit on pagehide, the focus, and the aria-live announcement. It ships no UI at all — the undo affordance is a listener:

document.addEventListener('undoable:pending', (e) => {
  const { label, undo, expiresAt } = e.detail;
  showToast(label, undo, expiresAt);
});

If nothing listens, actions still work — they are just visually silent. The accessibility announcement still fires.

Two constraints that look arbitrary and are not

ActionDef accepts exactly apply and commit. Any other key throws — not warns. configure() has exactly one option: window, default 5000 ms, global, no per-action override.

This is the load-bearing part of the design. Optimistic-UI libraries die by configuration growth: onSuccess, retries, toastPosition, priority, mergeStrategy. Each is individually reasonable and collectively fatal, because every key added is a decision moved out of the application and into a library with less context than the application has.

So when a new requirement appears, the answer is one of two things: an event listener, or a second named action. Never a new key.

Whether that holds is an empirical claim, and it was tested before a line of the runtime was written — three structurally different mutations (a removal, a reorder, a bulk action over a multi-selection) had to fit the API without adding a key, or the abstraction was at the wrong level.

The concurrency model is one integer

At most one action is pending at a time. Triggering a new one flushes the previous into committing immediately. No queue, no stack, no redo.

A revert is valid iff no later apply has run since. That is literally a generation counter:

applyGeneration += 1;      // before every apply, including ones that throw

// …later, if the commit rejects:
if (rec.generation === applyGeneration) rec.revert();   // still a real inverse
else emit('desync', …);                                // stale — do not touch state

desync is the interesting event: a commit failed, and the revert that would undo it is no longer safe to call, because a newer change is sitting on top of it. Calling it would silently discard that newer change. So the runtime refuses, and tells you instead. A sustained desync rate means the one-at-a-time flush model is wrong for your app — which is information worth having.

The spec was right and the behaviour was wrong

The runtime was built to a written spec with a 16-row acceptance matrix. It passed. Then I built an integration harness and drove it headlessly, checking things the matrix had not thought to check — mostly focus and the accessibility tree.

First run: 19 of 22. All three failures were the runtime implementing the spec correctly, and the spec being wrong.

All of it is written up, defect by defect, in FINDINGS.md — including the fix that recovered a case the conservative staleness rule was needlessly throwing away.

What it does not do

Deliberately, and permanently: no redo, no multi-level undo stack, no built-in toast, no per-action config, nothing requiring layout measurement, no server-side conflict resolution.

The one thing you must do

SPA route changes are invisible to the runtime. Call flushPending() in your router hook, or a pending change is silently dropped when the view unmounts:

router.beforeEach(() => undoable.flushPending());

pagehide and tab-hide are already handled.

Common questions

<script src="https://cdn.jsdelivr.net/npm/@sharma/undoable@0.1.1/dist/undoable.global.js"></script>

Status

MIT, TypeScript types included, Node ≥ 20, works with React, Vue, Angular and Svelte 5 (framework guide). The Chromium pass exists because jsdom structurally cannot answer questions about focus and the accessibility tree — and those turned out to be exactly the questions that mattered.