useThrottledHistory

A hook that tracks Observable change history with throttle. A thin wrapper around useHistory with throttleFilter applied — for rapidly changing values like sliders or drag interactions, it records snapshots at fixed intervals instead of on every change.

Demo

Sampled slider

Up to 1 commit / 300ms

Drag aggressively and notice how the timeline keeps only periodic checkpoints.

Value: 50

Throttle (ms)

UndoRedo

Throttled timeline

Newest snapshot is pinned at the top.

#1

50

08:52:29 AM

Usage

Hook

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

function Component() {
  const slider$ = useObservable(50);
  // Record at most once every 300ms
  const { undo, redo, canUndo$ } = useThrottledHistory(slider$, { throttle: 300 });

  return <input type="range" value={slider$.get()} onChange={(e) => slider$.set(+e.target.value)} />;
}

Scope

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

function Component() {
  "use scope"
  const slider$ = observable(50);
  const { undo, redo, canUndo$ } = createThrottledHistory(slider$, { throttle: 300 });

  return <input type="range" value={slider$.get()} onChange={(e) => slider$.set(+e.target.value)} />;
}

leading / trailing edges

By default both leading and trailing edges fire. Disable either to customize behavior.

Hook

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

function Component() {
  const value$ = useObservable(0);
  // Only record on the trailing edge (end of throttle window)
  const { undo } = useThrottledHistory(value$, {
    throttle: 500,
    leading: false,
    trailing: true,
  });
}

Scope

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

function Component() {
  "use scope"
  const value$ = observable(0);
  const { undo } = createThrottledHistory(value$, {
    throttle: 500,
    leading: false,
    trailing: true,
  });
}

Combined with capacity

Hook

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

function Component() {
  const position$ = useObservable({ x: 0, y: 0 });
  const { undo, redo } = useThrottledHistory(position$, {
    throttle: 200,
    capacity: 20, // keep at most 20 throttled snapshots
  });
}

Scope

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

function Component() {
  "use scope"
  const position$ = observable({ x: 0, y: 0 });
  const { undo, redo } = createThrottledHistory(position$, {
    throttle: 200,
    capacity: 20,
  });
}

Type

Parameters

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

ThrottledHistoryOptions

Option	Type	Default	Description
throttle	MaybeObservable<number>	200	Throttle interval in milliseconds.
trailing	boolean	true	Fire on the trailing edge of the throttle window.
leading	boolean	true	Fire on the leading edge of the throttle window.
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