zundo

If you need your React components to re-render when the history changes (e.g., to show the number of past states or disable an undo button when no history exists), use a custom hook built on useStoreWithEqualityFn to subscribe to the temporal object.

This makes properties like pastStates and futureStates reactive.

import { useStoreWithEqualityFn } from 'zustand/traditional';
import type { TemporalState } from 'zundo';

// Implementation of the reactive hook
function useTemporalStore<T>(selector: (state: TemporalState<MyState>) => T): T {
  return useStoreWithEqualityFn(useStoreWithUndo.temporal, selector!);
}

const App = () => {
  const { bears, increasePopulation } = useStoreWithUndo();
  
  // This hook makes pastStates and futureStates reactive
  const { undo, redo, clear, pastStates, futureStates } = useTemporalStore(
    (state) => state,
  );

  return (
    <>
      <p>bears: {bears}</p>
      <p>pastStates: {JSON.stringify(pastStates)}</p>
      <button onClick={increasePopulation}>increase</button>
      <button onClick={() => undo()}>undo</button>
    </>
  );
};

v2.0.0 is a complete rewrite that is smaller and more flexible. Key changes include:

Breaking Changes

• Middleware Name: undoMiddleware is now temporal.
• Field Filtering: include and exclude are replaced by the partialize option.
• Equality Checks: allowUnchanged is replaced by the equality option (accepts any equality function).
• History Limit: historyDepthLimit is renamed to limit.
• Throttling/Debouncing: coolOffDurationMs is replaced by the handleSet option, which allows you to wrap the setter function with a throttle or debounce function.

Migration Steps

1. Update zustand to v4.3.0 or higher.
2. Update zundo to v2.0.0 or higher.
3. Update imports from undoMiddleware to temporal.
4. Update configuration options as described in the code examples below.

- import { undoMiddleware } from 'zundo';
+ import { temporal } from 'zundo';

By default, Zundo records a snapshot whenever any Zustand state setter is called, even if the values haven't changed. To prevent unnecessary history entries, provide an equality function. This function compares the pastState and currentState and returns true if they are considered equal (meaning no history should be saved).

You can use:

• Deep equality functions (e.g., fast-deep-equal).
• Shallow equality functions (e.g., zustand/shallow).
• Custom logic for specific field comparisons.

import isDeepEqual from 'fast-deep-equal';
import shallow from 'zustand/shallow';

// Using deep equality
const useStoreDeep = create<StoreState>()(
  temporal((set) => ({ /* ... */ }), { equality: isDeepEqual })
);

// Using shallow equality
const useStoreShallow = create<StoreState>()(
  temporal((set) => ({ /* ... */ }), { equality: shallow })
);

// Using custom logic
const useStoreCustom = create<StoreState>()(
  temporal((set) => ({ /* ... */ }), {
    equality: (past, current) => past.field1 === current.field1
  })
);

By default, the entire state object is tracked. Use the partialize option to provide a callback that returns only the fields you want to include in the history. This is useful for excluding large or non-essential fields from the undo/redo buffer.

Note for TypeScript users: When using useTemporalStore (the React hook wrapper) with partialize, you must explicitly define the type of your partialized state to ensure type safety.

// Only field1 and field2 will be tracked
const useStoreWithUndoA = create<StoreState>()(
  temporal(
    (set) => ({ /* your store fields */ }),
    {
      partialize: (state) => {
        const { field1, field2, ...rest } = state;
        return { field1, field2 };
      },
    },
  ),
);

// TypeScript pattern for React hooks with partialized state
interface StoreState {
  bears: number;
  untrackedStateField: number;
}

type PartializedStoreState = Pick<StoreState, 'bears'>;

const useStoreWithUndo = create<StoreState>()(
  temporal(
    (set) => ({ bears: 0, untrackedStateField: 0 }),
    { partialize: (state) => ({ bears: state.bears }) }
  ),
);

const useTemporalStore = <T,>( 
  selector: (state: TemporalState<PartializedStoreState>) => T,
) => useStore(useStoreWithUndo.temporal, selector);