Umkehr

The no-nonsense undo/redo library for json state.

Pronounced "oom-care". from the german for "a turning back", "changing one's ways", or "repentance".

What does it do? It allows you to make surgical edits to a large state document, handles undo/redo and arbitrary jumps around the history tree, with extremely handy type-safe update builders.

Inspired by the JSON Patch standard and CRDTs, though different from both.

Install

npm install umkehr

pnpm add umkehr

bun add umkehr

Entry Points

Import	Use
umkehr	Core patch builders, patch application, and history helpers
umkehr/react	React contexts, hooks, and updater types

React is an optional peer dependency. Non-React users should import from umkehr.

Examples

Small runnable examples live in examples:

Example	Shows
examples/basic	Draft patches, realized changes, applying and inverting patches
examples/history	Dispatch, undo, redo, branching, and jump
examples/react	React context setup, useValue, preview updates, undo, and redo
examples/tagged-union	$variant with direct and callback forms

Quick Start

import {createPatchBuilder, resolveAndApply} from 'umkehr';

type State = {
    title: string;
    tags: string[];
};

const state: State = {
    title: 'Draft',
    tags: ['local'],
};

const $ = createPatchBuilder<State>();

const {current, changes} = resolveAndApply(
    state,
    [$.title('Published'), $.tags.$push('featured')],
    undefined,
    'type',
    Object.is,
);

current.title; // "Published"
current.tags; // ["local", "featured"]
changes; // realized, invertible patch operations

Core Terms

DraftPatch

DraftPatch<T> is the authoring form of a patch operation. It records what the caller wants to do, but it may omit data that can only be known by reading the current state.

For example:

Draft operation	State-dependent realization
replace	Adds the previous value so the patch can be inverted
remove	Adds the removed value so the patch can be inverted
push	Resolves to an add at the current array length
add, move, reorder	Already contain enough information to apply

Patch

Patch<T> is the realized, invertible form of a patch operation. These are the operations to store in history because they can be applied and inverted later.

Most callers should use resolveAndApply, dispatch, createStateContext, or createHistoryContext, which realize drafts for you.

Path

Path is an array of structured path segments:

[
    {type: 'key', key: 'items'},
    {type: 'key', key: 0},
];

Umkehr patch objects are inspired by JSON Patch, but they are not JSON Patch compatible. Paths are structured arrays, not JSON Pointer strings like "/items/0", and tagged-union path segments are Umkehr-specific.

Building Draft Operations

Use createPatchBuilder<T>() to create typed draft operations without applying them:

import {createPatchBuilder, type DraftPatch} from 'umkehr';

type State = {
    title: string;
    tags: string[];
    settings?: {
        archived: boolean;
    };
};

const $ = createPatchBuilder<State>();

const rename: DraftPatch<State> = $.title('New title');
const addTag: DraftPatch<State> = $.tags.$push('featured');
const removeSettings: DraftPatch<State> = $.settings.$remove();

Every property access extends the path. Calling a node is shorthand for replacing that path:

$.title('New title');
$.settings.archived(true);

When you pass a function instead of a value, Umkehr treats it as a nested update. The function gets the current value at that path and an up helper rooted at the same path:

$.settings((settings, up) => up.archived(!settings?.archived));

up looks like the normal patch builder, but it only creates draft operations. It does not dispatch or apply them by itself. Return one draft or an array of drafts, and Umkehr will rebase them onto the outer path and apply them together as a single update (so that they "undo" and "redo" together).

Use createPatchBuilder('kind') when your tagged unions use a discriminant other than 'type'.

Use createPatchBuilderWithContext when nested $update callbacks need caller-provided context:

import {createPatchBuilderWithContext} from 'umkehr';

const $ = createPatchBuilderWithContext<State, {source: string}>('type', {source: 'example'});

Use createPatchDispatcher when you want the same builder API to immediately call an application function:

import {createPatchDispatcher} from 'umkehr';

const $ = createPatchDispatcher<State, undefined, 'type'>(
    (draft, timing) => dispatch(draft, timing),
    undefined,
    'type',
);

Builder Methods

Method	Available on	Result
some.path.$replace(value)	Any path	Draft replace
some.path(value)	Any path	Alias for .$replace
some.path.$update((value, up) => draft / draft[])	Any path	Nested draft update based on current value. Can be used to combine multiple changes into a single "history item"
some.path((value, up) => draft)	Any path	Alias for .$update
some.path.$add(value)	Any path	Draft add
some.path.$remove()	Any path	Draft remove
some.path.$push(value)	Arrays	Draft push, realized as an add at the current array length
some.path.$move(from, to)	Arrays and objects	Draft move within the current path
some.path.$reorder(indices)	Arrays	Realized reorder using old indices in their new order
some.path.$variant(tag)	Tagged unions	Refines the updater to one union arm
some.path.$variant(value, handlers)	Tagged unions	Runs the handler for the active union arm

$reorder([2, 0, 1]) changes ['a', 'b', 'c'] into ['c', 'a', 'b'].

Applying Drafts

resolveAndApply realizes one or more draft operations, applies them in order, and returns the new state plus realized patch operations:

import {createPatchBuilder, resolveAndApply} from 'umkehr';

const $ = createPatchBuilder<State>();

const {current, changes} = resolveAndApply(
    state,
    [$.title('New title'), $.tags.$push('featured')],
    undefined,
    'type',
    Object.is,
);

History

Use blankHistory(initialState) to create a history tree:

import {blankHistory, createPatchBuilder, dispatch} from 'umkehr';

const $ = createPatchBuilder<State>();
const history = blankHistory(initialState);
const nextHistory = dispatch(history, [$.title('New title')]);
const undone = dispatch(nextHistory, {op: 'undo'});
const redone = dispatch(undone, {op: 'redo'});

The simple dispatch overload uses the default 'type' discriminant, no builder context, and fast-deep-equal. The lower-level overload accepts a context value, tag key, equality function, and ID generator.

History is a tree. If you undo and then dispatch a new change, the new node becomes another child of the current history node rather than deleting the old branch.

React Quick Start

import {blankHistory} from 'umkehr';
import {createHistoryContext, useValue} from 'umkehr/react';

type State = {
    title: string;
};

const [ProvideState, useStateContext] = createHistoryContext<State, never>('type');

export function App() {
    return (
        <ProvideState initial={blankHistory<State>({title: 'Draft'})}>
            <TitleEditor />
        </ProvideState>
    );
}

function TitleEditor() {
    const ctx = useStateContext();
    const title = useValue(ctx.$.title);

    return (
        <>
            <input value={title} onChange={(event) => ctx.$.title(event.target.value)} />
            <button onClick={() => ctx.undo()} disabled={!ctx.canUndo()}>
                Undo
            </button>
            <button onClick={() => ctx.redo()} disabled={!ctx.canRedo()}>
                Redo
            </button>
        </>
    );
}

The history context exposes:

API	Use
ctx.$	Root patch builder for the current state
ctx.latest()	Current state value
ctx.undo() / ctx.redo()	History navigation
ctx.canUndo() / ctx.canRedo()	History availability
ctx.previewJump(id)	Temporarily previews the state at another history node
ctx.clearPreview()	Clears temporary preview state without committing it
ctx.useHistory()	React hook for subscribing to history changes
ctx.dispatch(...)	Lower-level dispatch for draft ops or history commands

Use useValue(ctx.$.path) to read and subscribe to a specific path. Components re-render when that path, an ancestor, or a descendant is notified:

const title = useValue(ctx.$.title);
const firstTag = useValue(ctx.$.tags[0]);

useValue also accepts a selector and equality function for derived values:

const parity = useValue(
    ctx.$.count,
    (count) => ({parity: count % 2}),
    true,
    (a, b) => a.parity === b.parity,
);

The default selector returns the path value itself, and the default equality function is fast-deep-equal.

For state without undo/redo, use createStateContext:

import {createStateContext, useValue} from 'umkehr/react';

const [ProvideState, useStateContext] = createStateContext<State>('type');

The non-history context exposes ctx.$, ctx.latest(), ctx.clearPreview(), and ctx.dispatch(...).

Preview Updates

Most updater methods accept an optional timing argument:

ctx.$.title('Preview title', 'preview');
ctx.$.title('Committed title');

Preview changes are applied to temporary state and notify path subscribers, but they are cleared before the next committed update.

This is to enable interactions such as "scrubbing through a color picker" where you want the update the UI with the currently-hovered-value, but you don't want to spam history with these temporary updates or persist them. The next "non-preview" update is based on the state before any preview updates were processed, and clears all preview updates.

Note that preview updates are queued via requestAnimationFrame, whereas non-preview updates are processed immediately.

Tagged Unions

Pass the discriminant key to createPatchBuilder, createStateContext, or createHistoryContext. The default is 'type'.

type Item = {type: 'shape'; radius: number} | {type: 'text'; text: string};

ctx.$.item.$variant('shape').radius(10);

There is also a callback form for code that has the current value:

ctx.$.item.$variant(item, {
    shape: (value, up) => up.radius(value.radius + 1),
    text: (value, up) => up.text(`${value.text}!`),
});

Supported Data Model

Umkehr is intended for plain JSON-like data:

Area	Support
Objects and arrays	Supported; changed ancestors are cloned
Primitive values	Supported as leaves and root values
undefined	Treated as absence by draft realization for add/remove decisions
Equality	Defaults to fast-deep-equal in history and React helpers; lower-level APIs accept a custom equality function
Paths	Structured PathSegment[]; no JSON Pointer strings
Tagged unions	Supported through Umkehr-specific tag path segments
CRDT behavior	Not supported
Arbitrary object diffing	Not supported

Limitations

• Umkehr patches are not JSON Patch compatible.
• copy is not part of the public patch operation set.
• Preview updates are temporary React-context state; they are cleared before the next committed update.
• Array paths use numeric indices. Realized array operations are tied to the array state they were realized against.
• Persisted patch history assumes compatible application state shape. If your schema changes, you need to migrate stored history or start a new history root.