useDataHistory

A hook that automatically tracks changes to an Observable and manages undo/redo history. Records a snapshot automatically whenever the source Observable changes. Built on top of useManualHistory, with additional support for auto-commit, pause/resume, and transaction.

Demo

Live editor

Tracking on

Every change commits immediately while tracking is active.

UndoRedoPause tracking

History timeline

Newest snapshot is pinned at the top.

#1

""

08:52:29 AM

Usage

Hook

import { useDataHistory, useObservable } from "@usels/web";

function Component() {
  const text$ = useObservable("hello");
  const { undo, redo, canUndo$, canRedo$ } = useDataHistory(text$);

  return (
    <div>
      <input value={text$.get()} onChange={(e) => text$.set(e.target.value)} />
      <button onClick={undo} disabled={!canUndo$.get()}>Undo</button>
      <button onClick={redo} disabled={!canRedo$.get()}>Redo</button>
    </div>
  );
}

Scope

import { createDataHistory, observable } from "@usels/web";

function Component() {
  "use scope"
  const text$ = observable("hello");
  const { undo, redo, canUndo$, canRedo$ } = createDataHistory(text$);

  return (
    <div>
      <input value={text$.get()} onChange={(e) => text$.set(e.target.value)} />
      <button onClick={undo} disabled={!canUndo$.get()}>Undo</button>
      <button onClick={redo} disabled={!canRedo$.get()}>Redo</button>
    </div>
  );
}

pause / resume — stop and restart auto-tracking

Hook

import { useDataHistory, useObservable } from "@usels/web";

function Component() {
  const text$ = useObservable("hello");
  const { pause, resume, isTracking$ } = useDataHistory(text$);
}

Scope

import { createDataHistory, observable } from "@usels/web";

function Component() {
  "use scope"
  const text$ = observable("hello");
  const { pause, resume, isTracking$ } = createDataHistory(text$);
}

transaction — group mutations into one record

Multiple changes inside transaction() are recorded as a single undo step. Call the provided cancel() to abort the commit entirely.

Hook

import { useDataHistory, useObservable } from "@usels/web";

function Component() {
  const value$ = useObservable(0);
  const { transaction, undo } = useDataHistory(value$);
}

Scope

import { createDataHistory, observable } from "@usels/web";

function Component() {
  "use scope"
  const value$ = observable(0);
  const { transaction, undo } = createDataHistory(value$);
}

shouldCommit — conditional auto-commit

Return false from shouldCommit to skip recording specific values.

Hook

import { useDataHistory, useObservable } from "@usels/web";

function Component() {
  const count$ = useObservable(0);
  // Only record even numbers
  const { undo } = useDataHistory(count$, {
    shouldCommit: (value) => value % 2 === 0,
  });
}

Scope

import { createDataHistory, observable } from "@usels/web";

function Component() {
  "use scope"
  const count$ = observable(0);
  const { undo } = createDataHistory(count$, {
    shouldCommit: (value) => value % 2 === 0,
  });
}

capacity — limit undo depth

Hook

import { useDataHistory, useObservable } from "@usels/web";

function Component() {
  const text$ = useObservable("");
  // Keep at most 50 undo steps
  const { undo, redo } = useDataHistory(text$, { capacity: 50 });
}

Scope

import { createDataHistory, observable } from "@usels/web";

function Component() {
  "use scope"
  const text$ = observable("");
  const { undo, redo } = createDataHistory(text$, { capacity: 50 });
}

Type

Parameters

Parameter	Type	Description
source$	Observable<Raw>	- The Observable to track.
options	DataHistoryOptions<Raw, Serialized> (optional)	- Configuration for auto-tracking, filtering, and serialization.

DataHistoryOptions

Option	Type	Default	Description
eventFilter	EventFilter	-	Custom EventFilter to control when auto-commits fire. Used internally by throttledHistory / debouncedHistory.
shouldCommit	((newValue: Raw) => boolean)	-	Gate function called before each auto-commit. Return false to skip recording the current value.
capacity	number	Infinity	Maximum number of undo records to keep. When exceeded, the oldest records are discarded.
clone	boolean | ((value: Raw) => Raw)	-	Clone strategy for snapshots. - true (default): uses structuredClone - false: stores references (safe for primitives only) - (value) => cloned: custom clone function
dump	((value: Raw) => Serialized)	-	Custom serializer: Raw → Serialized for storage. When provided, clone is ignored and parse must also be provided.
parse	((value: Serialized) => Raw)	-	Custom deserializer: Serialized → Raw for restore. When provided, clone is ignored and dump must also be provided.

Returns

DataHistoryReturn<Raw, Serialized>

Name	Type	Description
isTracking$	ReadonlyObservable<boolean>	Whether auto-tracking is currently active.
pause	Fn	Stop auto-committing.
resume	(commitCurrent?: boolean | undefined) => void	Restart auto-committing. If commitCurrent is true, immediately commit current value.
transaction	(fn: (cancel: Fn) => void) => void	Group multiple mutations into a single history record. Call cancel() inside fn to abort.
canUndo$	ReadonlyObservable<boolean>	Whether undo is possible (undoStack is non-empty).
canRedo$	ReadonlyObservable<boolean>	Whether redo is possible (redoStack is non-empty).
history$	ReadonlyObservable<UseHistoryRecord<Serialized>[]>	Full history array, newest first: [current, previous, ...].
last$	ReadonlyObservable<UseHistoryRecord<Serialized>>	The most recent (current) history record.
commit	Fn	Record the current source value as a new history point. Clears redo stack.
undo	Fn	Restore the previous committed value.
redo	Fn	Re-apply the next value after an undo.
clear	Fn	Wipe all history and create a fresh initial record from current source.
reset	Fn	Restore source to the last committed value without modifying stacks.

Source

View on GitHub