useManualHistory

A hook for manually managing Observable change history. It only records a snapshot when commit() is called, and allows navigating previous states via undo/redo. Useful when auto-tracking is not needed, or when you want to record history only on explicit "save" actions.

Demo

Counter draft

Saved

Increment or decrement first, then decide when that state deserves a place in history.

-1

0

+1

Save snapshotUndoRedo

Saved timeline

Newest snapshot is pinned at the top.

#1

0

08:52:29 AM

Usage

Hook

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

function Component() {
  const counter$ = useObservable(0);
  const { commit, undo, redo, canUndo$, canRedo$ } = useManualHistory(counter$);

  return (
    <div>
      <button onClick={() => { counter$.set((v) => v + 1); commit(); }}>Save</button>
      <button onClick={undo} disabled={!canUndo$.get()}>Undo</button>
      <button onClick={redo} disabled={!canRedo$.get()}>Redo</button>
    </div>
  );
}

Scope

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

function Component() {
  "use scope"
  const counter$ = observable(0);
  const { commit, undo, redo, canUndo$, canRedo$ } = createManualHistory(counter$);

  return (
    <div>
      <button onClick={() => { counter$.set((v) => v + 1); commit(); }}>Save</button>
      <button onClick={undo} disabled={!canUndo$.get()}>Undo</button>
      <button onClick={redo} disabled={!canRedo$.get()}>Redo</button>
    </div>
  );
}

capacity — limit history size

Hook

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

function Component() {
  const value$ = useObservable(0);
  // Keep at most 10 undo steps; older records are discarded automatically
  const { commit, undo } = useManualHistory(value$, { capacity: 10 });
}

Scope

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

function Component() {
  "use scope"
  const value$ = observable(0);
  const { commit, undo } = createManualHistory(value$, { capacity: 10 });
}

dump / parse — custom serialization

Use dump and parse to store a compact or transformed representation instead of raw value clones.

Hook

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

function Component() {
  const items$ = useObservable<string[]>([]);
  const { commit, undo, history$ } = useManualHistory(items$, {
    // Store as comma-separated string to save memory
    dump: (arr) => arr.join(","),
    parse: (str) => (str ? str.split(",") : []),
  });
}

Scope

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

function Component() {
  "use scope"
  const items$ = observable<string[]>([]);
  const { commit, undo } = createManualHistory(items$, {
    dump: (arr) => arr.join(","),
    parse: (str) => (str ? str.split(",") : []),
  });
}

reset — revert uncommitted changes

reset() restores the source to the last committed value without touching the undo/redo stacks.

Hook

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

function Component() {
  const text$ = useObservable("saved");
  const { commit, reset } = useManualHistory(text$);
}

Scope

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

function Component() {
  "use scope"
  const text$ = observable("saved");
  const { commit, reset } = createManualHistory(text$);
}

clear — wipe all history

Hook

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

function Component() {
  const value$ = useObservable(0);
  const { commit, clear, history$ } = useManualHistory(value$);
}

Scope

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

function Component() {
  "use scope"
  const value$ = observable(0);
  const { commit, clear, history$ } = createManualHistory(value$);
}

Type

Parameters

Parameter	Type	Description
source$	Observable<Raw>	- The Observable to track.
options	ManualHistoryOptions<Raw, Serialized> (optional)	- Configuration for capacity, cloning, and serialization.

ManualHistoryOptions

Option	Type	Default	Description
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

ManualHistoryReturn<Raw, Serialized>

Name	Type	Description
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