useRefHistory

v0.0.14testeddemo

Track the change history of a ref with undo/redo, pause/resume, batching, and manual commits.

Examples

const count = ref(0);
const { history, undo, redo, canUndo, canRedo } = useRefHistory(count);

count.value = 1;
count.value = 2;
undo(); // count.value === 1
redo(); // count.value === 2

// Deep tracking with bounded capacity and a custom serializer
const state = ref({ items: [] });
const { history } = useRefHistory(state, { deep: true, capacity: 10 });

Demo

Loading demo…

Signature

export function useRefHistory<Raw, Serialized = Raw>(
  source: Ref<Raw>,
  options: UseRefHistoryOptions<Raw, Serialized> ={ ... }

Type Parameters

Raw

Serialized= Raw

Parameters

Parameter	Type	Default	Description
`source`	`Ref<Raw>`	—	The ref whose changes are tracked
`options`?	`UseRefHistoryOptions<Raw, Serialized>`	`{}`	Tracking options (`deep`, `flush`, `capacity`, `clone`, `dump`, `parse`, `eventFilter`, `shouldCommit`)

Returns

UseRefHistoryReturn<Raw, Serialized>History records plus undo/redo/commit/reset/clear/pause/resume/batch/dispose

Property	Type	Default	Description
`history`	`Ref<Array<UseRefHistoryRecord<Serialized>>>`	—	Bidirectional list of recorded snapshots, newest first
`last`	`Ref<UseRefHistoryRecord<Serialized>>`	—	The most recent snapshot record
`undoStack`	`Ref<Array<UseRefHistoryRecord<Serialized>>>`	—	Undo history records (the redo stack), newest first
`redoStack`	`Ref<Array<UseRefHistoryRecord<Serialized>>>`	—	Redo history records, newest first
`isTracking`	`Ref<boolean>`	—	Whether change tracking is currently active
`canUndo`	`ComputedRef<boolean>`	—	Whether an undo operation is available
`canRedo`	`ComputedRef<boolean>`	—	Whether a redo operation is available
`undo`	`() => void`	—	Step the source back to the previous snapshot
`redo`	`() => void`	—	Step the source forward to the next snapshot
`clear`	`() => void`	—	Clear all recorded history (keeps the current value as the only record)
`commit`	`() => void`	—	Manually record the current value as a new snapshot
`reset`	`() => void`	—	Reset the source back to the most recent snapshot, discarding uncommitted changes
`pause`	`() => void`	—	Pause change tracking
`resume`	`(commit?: boolean) => void`	—	Resume change tracking
`batch`	`(fn: (cancel: () => void) => void) => void`	—	Run a function with tracking suspended, committing once on completion. Call the provided `cancel` to skip the trailing commit.
`dispose`	`() => void`	—	Stop the underlying watcher and clear all history