10x Faster Undo/Redo Using JSON Patches – Travels.js

Travels.js is a framework-agnostic JavaScript library for undo, redo, and time-travel state history.

It records forward and inverse JSON Patches. For large states with small edits, this can use less storage than full snapshots.

Travels can own state updates or record commits from an existing store. Editors and form builders can group related changes into undo steps and restore saved history across sessions.

Features:

• Stores forward and inverse JSON Patches for undo and redo history.
• Jumps to any retained history position and limits history size.
• Groups related state updates into one undo step through transactions or manual archiving.
• Serializes state, cursor position, patches, and metadata for persistent history.
• Validates restored history before replaying changes from storage.
• Exposes read-only timeline views and detached history snapshots.
• Supports mutable state updates for observable objects and immutable updates by default.
• Records externally generated patches through a controlled journal API.

Use Cases:

• Document editors with labeled undo commands, long editing sessions, and saved history.
• Canvas and diagram editors that track changes to layers, shapes, and properties.
• Form builders that group a series of field edits into one undo operation.
• Applications with an existing state manager that need an independent patch history journal.

How To Use It:

Installation

Travels 3 requires mutative@^2.0.0. Install the two packages together:

npm install travels@3 mutative@2
# or
pnpm add travels@3 mutative@2
# or
yarn add travels@3 mutative@2

Basic Undo and Redo

Create a history instance from JSON-compatible state. The subscriber receives one event object containing the current state, operation type, cursor position, and history length.

import { createTravels } from 'travels';
const travels = createTravels({ count: 0 });
const unsubscribe = travels.subscribe(({ type, state, position, historyLength }) => {
  console.log(type, state.count, position, historyLength);
});
travels.setState((draft) => {
  draft.count += 1;
});
travels.setState((draft) => {
  draft.count += 1;
});
travels.back();
console.log(travels.getState().count); // 1
travels.forward();
console.log(travels.getState().count); // 2
unsubscribe();

Group Related Updates

Use transaction() for one undo step that contains several synchronous updates. Travels publishes one final transaction event after a successful commit.

const travels = createTravels({ x: 0, y: 0 });
travels.transaction({ label: 'Move selection' }, () => {
  travels.setState((draft) => { draft.x += 10; });
  travels.setState((draft) => { draft.y += 20; });
});
travels.back(); // Both coordinates return to 0.

Manual Archive Mode

For edits that must stay pending until a form blur or save action, choose autoArchive: false when creating the timeline. The archive() and canArchive() methods exist only in this mode.

const travels = createTravels({ title: '' }, { autoArchive: false });
travels.setState((draft) => { draft.title = 'Draft'; });
travels.setState((draft) => { draft.title = 'Final draft'; });
if (travels.canArchive()) {
  travels.archive({ label: 'Edit title' });
}
travels.back(); // Restores the empty title.

Save and Restore Undo History

Use serialize() to save a complete snapshot, including the history baseline and cursor. On load, validate the stored data with Travels.deserialize() and recreate the timeline with restoreTravels(). Use semantic validation for untrusted storage and keep state and metadata JSON-compatible. This replaces the older initialPatches and initialPosition configuration.

import { createTravels, restoreTravels, Travels } from 'travels';
const initialState = { title: '', blocks: [] };
const storageKey = 'editor-history';
function createEditorHistory() {
  const saved = localStorage.getItem(storageKey);
  if (!saved) return createTravels(initialState, { maxHistory: 50 });
  const snapshot = Travels.deserialize(saved, {
    validation: 'semantic',
    fallback: {
      version: 1,
      state: initialState,
      patches: { patches: [], inversePatches: [] },
      position: 0,
    },
  });
  return restoreTravels(snapshot, { maxHistory: 50 });
}
const editorHistory = createEditorHistory();
editorHistory.subscribe(() => {
  localStorage.setItem(storageKey, JSON.stringify(editorHistory.serialize({ strict: true })));
});

React Integration

A React component can subscribe to getRevision() through useSyncExternalStore(). The revision changes for timeline-only operations too, including rebase(). The example uses the Travels core directly.

import { useSyncExternalStore } from 'react';
import { createTravels } from 'travels';
const travels = createTravels({ count: 0 });
function Counter() {
  useSyncExternalStore(travels.subscribe, travels.getRevision);
  const state = travels.getState();
  const controls = travels.getControls();
  return (
    <div>
      <p>Count: {state.count}</p>
      <button onClick={() => travels.setState(draft => { draft.count++; })}>
        Increment
      </button>
      <button disabled={!controls.canBack()} onClick={() => controls.back()}>
        Undo
      </button>
      <button disabled={!controls.canForward()} onClick={() => controls.forward()}>
        Redo
      </button>
    </div>
  );
}

Zustand Integration

For a basic Zustand store, subscribe to Travels events and copy the new state into Zustand. Keep navigation controls outside the undoable state fields.

import { create } from 'zustand';
import { createTravels } from 'travels';
const travels = createTravels({ count: 0 });
const useCounter = create(() => ({
  count: travels.getState().count,
  increment: () => travels.setState(draft => { draft.count++; }),
  undo: () => travels.back(),
  redo: () => travels.forward(),
}));
travels.subscribe(({ state }) => {
  useCounter.setState({ count: state.count });
});

Vue Integration

Vue ref() can follow Travels events, including changes to undo and redo availability. For a reactive object that needs a stable identity, use mutable: true and pass that object to createTravels().

import { ref, readonly } from 'vue';
import { createTravels } from 'travels';
export function useEditorHistory(initialState) {
  const travels = createTravels(initialState);
  const state = ref(travels.getState());
  const canUndo = ref(travels.canBack());
  const canRedo = ref(travels.canForward());
  const unsubscribe = travels.subscribe(({ state: nextState }) => {
    state.value = nextState;
    canUndo.value = travels.canBack();
    canRedo.value = travels.canForward();
  });
  return {
    state: readonly(state),
    canUndo: readonly(canUndo),
    canRedo: readonly(canRedo),
    setState: (updater) => travels.setState(updater),
    controls: travels.getControls(),
    unsubscribe,
  };
}

TypeScript Usage

Travels includes TypeScript declarations. createTravels<State>() types state updates. createPatchableTravels() checks the JSON-shaped PatchableState contract at compile time and validates the initial value at runtime.

import { createTravels, createPatchableTravels, type JsonValue } from 'travels';
type EditorState = {
  title: string;
  blocks: Array<{ id: string; text: string }>;
};
const initialState: EditorState = { title: 'Untitled', blocks: [] };
const travels = createTravels<EditorState>(initialState);
travels.setState((draft) => {
  draft.blocks.push({ id: 'intro', text: 'Hello' });
});
const durable = createPatchableTravels(initialState);
const jsonState: JsonValue = durable.getState();

React and Zustand Wrapper Compatibility

The published [email protected] and [email protected] packages declare peer dependencies on Travels 2.x and Mutative 1.x. These releases cannot be installed as compatible wrappers for Travels 3. The React and Zustand examples here integrate directly with the travels core.

Controlled Journal for External State

An application that already owns state and produces forward and inverse patches can record its history through createTravelJournal(). Supply a synchronous apply() callback for navigation and commit state before calling recordPatches(). Do not record delegated navigation as a fresh commit. The journal does not expose setState(), transactions, tracking methods, or getControls(). For persisted journals use restoreTravelJournal(snapshot, { apply }).

import { apply as applyPatches, create } from 'mutative';
import { createTravelJournal } from 'travels';
let state = { count: 0 };
const journal = createTravelJournal(state, {
  apply({ patches }) {
    state = applyPatches(state, patches);
    return state;
  },
});
function increment() {
  const [nextState, patches, inversePatches] = create(
    state,
    (draft) => { draft.count++; },
    { enablePatches: true }
  );
  state = nextState;
  journal.recordPatches(state, { patches, inversePatches });
}
increment();
journal.back();

Advanced Usage:

Skip No-Op Updates

An updater that leaves state unchanged produces no patch entry. Travels also avoids notifications for updates with no actual changes.

const travels = createTravels({ count: 0 });
travels.setState((draft) => {
  if (draft.count > 10) draft.count = 0;
});
console.log(travels.getPosition()); // 0
travels.setState((draft) => { draft.count = 5; });
console.log(travels.getPosition()); // 1

Limit Retained History

maxHistory counts retained patch transitions. After the limit is reached, undo stops at the oldest state in the current history window. reset() returns to the initial baseline.

const travels = createTravels({ count: 0 }, { maxHistory: 3 });
for (let i = 0; i < 5; i++) {
  travels.setState((draft) => { draft.count += 1; });
}
travels.back(3);
console.log(travels.getState().count); // 2
console.log(travels.canBack()); // false
travels.reset();
console.log(travels.getState().count); // 0

Keep Pinia State Reactive

For a Vue/Pinia store that must keep its observable root object, pass the reactive object to Travels with mutable: true. Do not set enableAutoFreeze: true in this mode.

import { defineStore } from 'pinia';
import { reactive } from 'vue';
import { createTravels } from 'travels';
export const useTasks = defineStore('tasks', () => {
  const state = reactive({ items: [] });
  const travels = createTravels(state, { mutable: true });
  function addTask(text) {
    travels.setState((draft) => {
      draft.items.push({ id: crypto.randomUUID(), text });
    });
  }
  return { state, addTask, history: travels.getControls() };
});

Validate State Updates

Keep domain validation in application code before recording an edit. A dedicated update function can reject invalid changes before they enter Travels history.

const travels = createTravels({ count: 0 });
function setCount(value) {
  if (!Number.isInteger(value) || value < 0) return false;
  travels.setState((draft) => { draft.count = value; });
  return true;
}
setCount(-5); // false
setCount(5);  // true

Configuration Options:

Pass the configuration object as the second argument of createTravels(initialState, options?). The initialState argument is required and should use the durable state types described later.

API Reference:

State and Timeline Methods

Controls Object

getControls() returns read-only properties and functions. Manual-archive controls also expose the manual methods.

Factories, Persistence, and Validation Utilities

History Deserialization Options

Controlled Journal Methods

The returned TravelJournal facade is frozen. It shares history-read, subscription, persistence, revision, and navigation methods with ordinary timelines. It adds recordPatches() and delegates state changes to the external owner through apply().

Events and Callbacks

Subscribers and the devtools hook receive one TravelsEvent object. Event patch data describes the change for that notification, not the full retained history.

Lifecycle and Error Callbacks

The lifecycle callbacks are onError(error), onObserverError({ source, error }), onBranchDiscard({ position, discarded }), and onWarning({ code, message }). The devtools(event) hook and subscribe(listener) use the event fields above. Subscriptions return an unsubscribe function.

The onWarning callback uses the codes HISTORY_DISABLED, HISTORY_DISCARDED, HISTORY_TRIMMED, INVALID_POSITION, MUTABLE_FALLBACK, MUTABLE_ROOT_REPLACEMENT, PERSISTENCE_COMPATIBILITY, and POSITION_CLAMPED. The event type union is open to future values. Use a default case in exhaustive event handlers.

Alternatives & Related Resources:

• Framework-Agnostic Undo/Redo History Management Library – Reddo.js

FAQs:

Q: Why does new Travels() or instanceof Travels fail in version 3?
A: Travels is a persistence namespace, not a constructor. Create a timeline with createTravels() and check an existing timeline with isTravels(value).

Q: Why does installing use-travel or zustand-travel produce a peer-dependency conflict?
A: Their published 2.2 releases require Travels 2.x and Mutative 1.x. The core examples above work directly with Travels 3. For a wrapper, select a release that explicitly accepts travels@^3.

Q: Why can undo after loading saved history throw HISTORY_REPLAY_FAILED?
A: Structural validation checks the snapshot format but does not replay patches. Use Travels.deserialize(saved, { validation: 'semantic' }) before restoring unverified data. Semantic validation can reject patch histories that cannot be replayed and reversed.

Q: Why does getHistorySnapshot() reject some state values?
A: The method cannot safely detach functions, accessors, class instances, and certain runtime collections while preserving their types. Normalize these values into plain data before recording history.

Q: Why does manual-mode navigation no longer emit a separate archive event?
A: Travels 3 commits pending manual changes and the cursor move as one go event. A persistence listener that saves only on archive misses that navigation. Save on each committed subscription event.

Changelog:

v3.0.1 (October 20, 2026)

• Bugfixes

v3.0.0 (October 19, 2026)

• Requires Mutative 2 and Node.js 22 or newer for Node.js use.
• Introduces dedicated restore factories, state-owning timelines, and controlled journal capabilities.
• Removes legacy history initialization options and direct Travels construction.
• Returns read-only shared history views and introduces getRevision() and isTravels().
• Restricts manual archive controls to manual archive instances.

v2.2.0 (July 26, 2026)

• Introduced createPatchableTravels() and detached getHistorySnapshot() results.
• Introduced structured warnings and stricter validation of externally supplied patch history.

v2.1.0 (July 19, 2026)

• Introduced createTravelJournal() for history owned by another state manager.
• Introduced journal recordPatches events and external navigation callbacks.

v2.0.0 (July 18, 2026)

• Changed subscribers to a unified event object.
• Introduced optional semantic replay validation of stored histories.

v1.4.0 (July 12, 2026)

• Improved history consistency for manual changes, transactions, and mutable state.
• Rejected asynchronous update callbacks and invalid patch configurations.

v1.3.1 (May 16, 2026)

• Improved patch snapshot handling for subscriber and devtools callbacks.

v1.3.0 (May 15, 2026)

• Introduced versioned persistence and metadata-related history features.

v1.2.0 (April 22, 2026)

• Introduced rebase() for changing the undo and reset baseline.