travels

The travels repository provides several integration examples demonstrating how to use Travels with different state management libraries and complex application workflows. These examples move beyond simple counters to show product-shaped state management.

Framework Integrations

• React: Integration using useSyncExternalStore for efficient subscriptions.
• Zustand: Using Zustand as the UI store while leveraging Travels as the underlying history engine.
• Vue: Implementation via a Vue composable wrapper.
• Pinia: Setting up a Pinia store using Travels' mutable mode.
• MobX: Managing MobX observable state using mutable mode.

Advanced Workflows

• Form Builders: Using archive mode to manage multi-step form builder edits manually.
• Canvas/Editors: Implementing pointer-move batching for high-frequency editor workflows.

Persistence Patterns

• Versioned Persistence: Using localStorage with versioning.
• Custom Adapters: Patterns for localStorage, IndexedDB, and compression adapters.
• Local-first: Combining IndexedDB with BroadcastChannel for local-first persistence strategies.

The maxHistory option limits the number of patches (transitions) kept in memory. It does not limit the number of states directly.

When the limit is reached:

• The oldest patches are discarded.
• The current position is capped at maxHistory.
• You can still access maxHistory + 1 states (the window start plus the number of transitions).
• reset() can always return to the true initial state, even if it was trimmed from the history window.

Example Behavior (maxHistory: 3): If you perform 5 increments, the library keeps the last 3 transitions. You can go back to the state at position 0 (the window start), but you cannot go back to the original state using back()—you must use reset() for that.

const travels = createTravels({ count: 0 }, { maxHistory: 3 });

// After 5 increments:
// Position is capped at 3. 
// History contains patches for transitions: 2->3, 3->4, 4->5.
// You can go back to position 0 (count: 2).
// To get back to count: 0, you must call travels.reset().

Travels is storage-agnostic. To persist history, you must store the versioned snapshot returned by travels.serialize(). To restore, use Travels.deserialize(...) to validate the data, then pass the resulting history into createTravels(...).

Data Constraints for Durable Persistence: To ensure compatibility with JSON and JSON Patch, your state and retained patch values must use:

• Plain objects and dense arrays.
• Strings, finite numbers (excluding -0, NaN, or Infinity), booleans, and null.
• JSON Pointer strings or dense arrays of strings/finite non-negative integers for paths.

Unsupported Types:

• Map and Set are rejected as state or patch payloads.
• bigint must be encoded.
• Array holes and custom prototypes are not preserved; fill holes with null and use plain objects/arrays.

// To persist:
const snapshot = travels.serialize();
// Store 'snapshot' in your database...

// To restore:
const history = Travels.deserialize<DocumentState>(rawSnapshot, {
  validation: 'semantic',
  fallback: createEmptySnapshot,
  onError(error) {
    if (error instanceof TravelsPersistenceError) {
      console.warn('Ignoring invalid persisted history:', error.code);
    }
  },
});
const travels = createTravels(history.state, { history });

Travels offers two modes to control when state changes are committed to the undo/redo history.

Auto Archive Mode (autoArchive: true, default)

Every call to setState is automatically recorded as a new, separate history entry. This is the simplest mode for standard applications.

Manual Archive Mode (autoArchive: false)

Changes made via setState are treated as temporary and are not added to the history until you explicitly call archive(). This allows you to batch multiple mutations into a single undo/redo step.

Examples

Batching multiple changes (Manual Mode):

const travels = createTravels({ count: 0 }, { autoArchive: false });

travels.setState({ count: 1 });
travels.setState({ count: 2 });
travels.setState({ count: 3 });

// Commits all changes as a single entry
travels.archive(); 

// Undo goes back to 0, not 2 or 1
travels.back(); 

Explicit commit (Manual Mode):

function handleSave() {
  travels.setState((draft) => {
    draft.count += 1;
  });
  travels.archive(); // Commit immediately
}