useDebouncedHistory

A hook that tracks Observable change history with debounce. A thin wrapper around useDataHistory with debounceFilter applied — it only records history after typing has stopped. Ideal for text inputs or search fields where you want to snapshot only when a burst of changes has "settled".

Demo

Settling editor

Commit after 600ms

Type quickly, pause, then inspect how only the settled value lands in history.

Debounce (ms)

Snapshots: 1

UndoRedo

Debounced timeline

Newest snapshot is pinned at the top.

#1

""

08:52:29 AM

Usage

Hook

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

function Component() {
  const search$ = useObservable("");
  // Record a snapshot 500ms after the user stops typing
  const { undo, redo, canUndo$ } = useDebouncedHistory(search$, { debounce: 500 });

  return <input value={search$.get()} onChange={(e) => search$.set(e.target.value)} />;
}

Scope

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

function Component() {
  "use scope"
  const search$ = observable("");
  const { undo, redo, canUndo$ } = createDebouncedHistory(search$, { debounce: 500 });

  return <input value={search$.get()} onChange={(e) => search$.set(e.target.value)} />;
}

maxWait — force commit after maximum delay

Even if the user keeps typing, a snapshot is forced after maxWait ms.

Hook

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

function Component() {
  const text$ = useObservable("");
  // Commit after 500ms idle, or every 2s at most even if still typing
  const { undo, redo } = useDebouncedHistory(text$, {
    debounce: 500,
    maxWait: 2000,
  });
}

Scope

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

function Component() {
  "use scope"
  const text$ = observable("");
  const { undo, redo } = createDebouncedHistory(text$, {
    debounce: 500,
    maxWait: 2000,
  });
}

Combined with capacity

Hook

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

function Component() {
  const note$ = useObservable("");
  const { undo, redo } = useDebouncedHistory(note$, {
    debounce: 800,
    capacity: 30,
  });
}

Scope

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

function Component() {
  "use scope"
  const note$ = observable("");
  const { undo, redo } = createDebouncedHistory(note$, {
    debounce: 800,
    capacity: 30,
  });
}

Type

Parameters

Parameter	Type	Description
source$	Observable<Raw>	- The Observable to track.
options	DebouncedHistoryOptions<Raw, Serialized> (optional)	- Debounce timing and history configuration.

DebouncedHistoryOptions

Option	Type	Default	Description
debounce	number	200	Debounce delay in milliseconds.
maxWait	number	-	Maximum time to wait before forcing a commit, regardless of activity.
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