feat(store): implement useTravelStore with useSyncExternalStore (#11)

Author: unadlib

README.md

@@ -117,6 +117,47 @@ const App = () => {
 | `controls.go`         | (nextPosition: number) => void | Go to the specific position of the state                               |
 | `controls.archive`    | () => void                     | Archive the current state(the `autoArchive` options should be `false`) |
 
+### useTravelStore
+
+When you need to manage a single `Travels` instance outside of React—e.g. to share the same undo/redo history across multiple components—create the store manually and bind it with `useTravelStore`. The hook keeps React in sync with the external store, exposes the same controls object, and rejects mutable stores to ensure React can observe updates.
+
+```tsx
+// store.ts
+import { Travels } from 'travels';
+
+export const travels = new Travels({ count: 0 }); // mutable: true is not supported
+```
+
+```tsx
+// Counter.tsx
+import { useTravelStore } from 'use-travel';
+import { travels } from './store';
+
+export function Counter() {
+  const [state, setState, controls] = useTravelStore(travels);
+
+  return (
+    <div>
+      <span>{state.count}</span>
+      <button
+        onClick={() =>
+          setState((draft) => {
+            draft.count += 1;
+          })
+        }
+      >
+        Increment
+      </button>
+      <button onClick={() => controls.back()} disabled={!controls.canBack()}>
+        Undo
+      </button>
+    </div>
+  );
+}
+```
+
+`useTravelStore` stays reactive even when the `Travels` instance is updated elsewhere (for example, in services or other components) and forwards manual archive helpers when the store is created with `autoArchive: false`.
+
 ### Archive Mode
 
 `use-travel` provides two archive modes to control how state changes are recorded in history:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-travel",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "A React hook for state time travel with undo, redo, reset and archive functionalities.",
   "main": "dist/index.cjs.js",
   "unpkg": "dist/index.umd.js",
@@ -69,7 +69,7 @@
     "react-dom": "^18.2.0",
     "rimraf": "^4.4.0",
     "rollup": "^4.52.3",
-    "travels": "^0.5.2",
+    "travels": "^0.7.0",
     "ts-node": "^10.9.2",
     "tslib": "^2.8.1",
     "typedoc": "^0.26.11",
@@ -87,6 +87,10 @@
     "@types/react": "^17.0 || ^18.0 || ^19.0",
     "mutative": "^1.3.0",
     "react": "^17.0 || ^18.0 || ^19.0",
-    "travels": "^0.5.2"
+    "travels": "^0.7.0"
+  },
+  "dependencies": {
+    "@types/use-sync-external-store": "^1.5.0",
+    "use-sync-external-store": "^1.6.0"
   }
 }

src/index.ts

@@ -9,6 +9,7 @@ import type {
   PatchesOption,
 } from 'travels';
 import { Travels } from 'travels';
+import { useSyncExternalStore } from 'use-sync-external-store/shim';
 
 export type { TravelPatches };
 
@@ -24,7 +25,21 @@ type Result<
 ];
 
 /**
- * A hook to travel in the history of a state
+ * Creates a component-scoped {@link Travels} instance with undo/redo support and returns its reactive API.
+ *
+ * The hook memoises the underlying `Travels` instance per component, wires it to React's lifecycle, and forces
+ * re-renders whenever the managed state changes. Consumers receive a tuple containing the current state, a `setState`
+ * updater that accepts either a mutative draft function or partial state, and the history controls exposed by
+ * {@link Travels}.
+ *
+ * @typeParam S - Shape of the state managed by the travel store.
+ * @typeParam F - Whether draft freezing is enabled.
+ * @typeParam A - Whether the instance auto-archives changes; determines the controls contract.
+ * @typeParam P - Additional patches configuration forwarded to Mutative.
+ * @param initialState - Value used to initialise the travel store.
+ * @param _options - Optional configuration mirrored from {@link Travels}.
+ * @returns A tuple with the current state, typed updater, and history controls.
+ * @throws {Error} When `setState` is invoked multiple times within the same render cycle (development-only guard).
  */
 export function useTravel<S, F extends boolean>(
   initialState: S
@@ -176,3 +191,54 @@ export function useTravel<
 
   return [state, cachedSetState, cachedControls] as Result<S, F, A>;
 }
+
+/**
+ * Subscribes to an existing {@link Travels} store and bridges it into React via `useSyncExternalStore`.
+ *
+ * The hook keeps React in sync with the store's state and exposes the same tuple shape as {@link useTravel}, but it
+ * does not create or manage the store lifecycle. Mutable Travels instances are rejected because they reuse the same
+ * state reference, which prevents React from observing updates.
+ *
+ * @typeParam S - Shape of the state managed by the travel store.
+ * @typeParam F - Whether draft freezing is enabled.
+ * @typeParam A - Whether the instance auto-archives changes; determines the controls contract.
+ * @typeParam P - Additional patches configuration forwarded to Mutative.
+ * @param travels - Existing {@link Travels} instance to bind to React.
+ * @returns A tuple containing the current state, typed updater, and history controls.
+ * @throws {Error} If the provided `Travels` instance was created with `mutable: true`.
+ */
+export function useTravelStore<
+  S,
+  F extends boolean,
+  A extends boolean,
+  P extends PatchesOption = {},
+>(
+  travels: Travels<S, F, A, P>
+): [
+  Value<S, F>,
+  (updater: Updater<S>) => void,
+  A extends false ? ManualTravelsControls<S, F, P> : TravelsControls<S, F, P>,
+] {
+  const isMutable = Boolean((travels as any)?.mutable);
+
+  if (isMutable) {
+    throw new Error(
+      'useTravelStore only supports immutable Travels instances. Remove `mutable: true` or use useTravel instead.'
+    );
+  }
+  const state = useSyncExternalStore(
+    travels.subscribe.bind(travels),
+    travels.getState.bind(travels),
+    travels.getState.bind(travels)
+  );
+  const setState = useCallback(
+    (updater: Updater<S>) => travels.setState(updater),
+    [travels]
+  );
+  const controls = useMemo(() => travels.getControls(), [travels]);
+  return [state as Value<S, F>, setState, controls] as [
+    Value<S, F>,
+    (updater: Updater<S>) => void,
+    A extends false ? ManualTravelsControls<S, F, P> : TravelsControls<S, F, P>,
+  ];
+}

test/use-travel-store.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { Travels } from 'travels';
+import { useTravelStore } from '../src/index';
+
+describe('useTravelStore', () => {
+  it('throws when used with a mutable Travels instance', () => {
+    const travels = new Travels({ count: 0 }, { mutable: true });
+
+    expect(() =>
+      renderHook(() => useTravelStore(travels))
+    ).toThrowError(
+      /useTravelStore only supports immutable Travels instances/
+    );
+  });
+
+  it('syncs state and controls with an immutable Travels instance', () => {
+    const travels = new Travels({ count: 0 });
+
+    const { result } = renderHook(() => useTravelStore(travels));
+
+    let [state, setState, controls] = result.current;
+    expect(state).toEqual({ count: 0 });
+    expect(typeof setState).toBe('function');
+    expect(controls.getHistory()).toEqual(travels.getHistory());
+
+    act(() =>
+      setState((draft) => {
+        draft.count = 1;
+      })
+    );
+    [state, setState, controls] = result.current;
+
+    expect(state).toEqual({ count: 1 });
+    expect(travels.getState()).toEqual({ count: 1 });
+    expect(controls.getHistory()).toEqual(travels.getHistory());
+
+    act(() =>
+      travels.setState((draft) => {
+        draft.count = 42;
+      })
+    );
+    [state, setState, controls] = result.current;
+
+    expect(state).toEqual({ count: 42 });
+    expect(controls.getHistory()).toEqual(travels.getHistory());
+  });
+
+  it('exposes manual archive controls when autoArchive is disabled', () => {
+    const travels = new Travels(
+      { todos: [] as string[] },
+      { autoArchive: false }
+    );
+
+    const { result } = renderHook(() => useTravelStore(travels));
+
+    let [state, setState, controls] = result.current;
+    const manualControls = controls as ReturnType<typeof travels.getControls>;
+    expect(typeof (manualControls as any).archive).toBe('function');
+    expect(typeof (manualControls as any).canArchive).toBe('function');
+    expect((manualControls as any).canArchive()).toBe(false);
+
+    act(() =>
+      setState((draft) => {
+        draft.todos.push('todo 1');
+      })
+    );
+    [state, setState, controls] = result.current;
+
+    const manualControlsAfterUpdate =
+      controls as ReturnType<typeof travels.getControls>;
+
+    expect(state.todos).toEqual(['todo 1']);
+    expect((manualControlsAfterUpdate as any).canArchive()).toBe(true);
+
+    act(() => (manualControlsAfterUpdate as any).archive());
+    [state, setState, controls] = result.current;
+
+    const manualControlsAfterArchive =
+      controls as ReturnType<typeof travels.getControls>;
+
+    expect((manualControlsAfterArchive as any).canArchive()).toBe(false);
+    expect(manualControlsAfterArchive.getHistory()).toEqual(
+      travels.getHistory()
+    );
+  });
+});

yarn.lock

@@ -813,6 +813,11 @@
   resolved "https://registry.yarnpkg.com/@types/unist/-/unist-3.0.3.tgz#acaab0f919ce69cce629c2d4ed2eb4adc1b6c20c"
   integrity sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==
 
+"@types/use-sync-external-store@^1.5.0":
+  version "1.5.0"
+  resolved "https://registry.yarnpkg.com/@types/use-sync-external-store/-/use-sync-external-store-1.5.0.tgz#222c28a98eb8f4f8a72c1a7e9fe6d8946eca6383"
+  integrity sha512-5dyB8nLC/qogMrlCizZnYWQTA4lnb/v+It+sqNl5YnSRAPMlIqY/X0Xn+gZw8vOL+TgTTr28VEbn3uf8fUtAkw==
+
 "@typescript-eslint/eslint-plugin@^8.44.1":
   version "8.44.1"
   resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.44.1.tgz#011a2b5913d297b3d9d77f64fb78575bab01a1b3"
@@ -4387,10 +4392,10 @@ tr46@^6.0.0:
   dependencies:
     punycode "^2.3.1"
 
-travels@^0.5.2:
-  version "0.5.2"
-  resolved "https://registry.yarnpkg.com/travels/-/travels-0.5.2.tgz#25d167d9feb2bce987bdb463c69bf98852456090"
-  integrity sha512-2cr4HJ02keoD1DrGCjhguKY2j55ySKkrFGZpZT9u264orhQd+Df6njXOUcFEHGxfoKBOwXlHK+RJ2IKlLYjTeQ==
+travels@^0.7.0:
+  version "0.7.0"
+  resolved "https://registry.yarnpkg.com/travels/-/travels-0.7.0.tgz#8c6ddf2802f6cb4c59c5857cf1c92912e0f7a1ef"
+  integrity sha512-4MVdWct7TWVIU5jPYz6rWQmML3iVlUzXv1YBqyBO4ONpERlg3Z/PfOoUCFCXY8lzc57BsJlRvHuPKqN1WML2+Q==
 
 trim-lines@^3.0.0:
   version "3.0.1"
@@ -4600,6 +4605,11 @@ uri-js@^4.2.2:
   dependencies:
     punycode "^2.1.0"
 
+use-sync-external-store@^1.6.0:
+  version "1.6.0"
+  resolved "https://registry.yarnpkg.com/use-sync-external-store/-/use-sync-external-store-1.6.0.tgz#b174bfa65cb2b526732d9f2ac0a408027876f32d"
+  integrity sha512-Pp6GSwGP/NrPIrxVFAIkOQeyw8lFenOHijQWkUTrDvrF4ALqylP2C/KCkeS9dpUM3KvYRQhna5vt7IL95+ZQ9w==
+
 util-deprecate@^1.0.1:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/util-deprecate/-/util-deprecate-1.0.2.tgz#450d4dc9fa70de732762fbd2d4a28981419a0ccf"