Interface: HistoryEngine
@roomful/vue / HistoryEngine
Interface: HistoryEngine
Section titled “Interface: HistoryEngine”Defined in: core/dist/types.d.ts:1939
Exposes collaborative undo/redo plus a shared activity timeline for a room.
Undo/redo is per-peer: each peer only reverts and replays its own changes to the shared CRDT document, conflict-free, so one peer’s undo never destroys another peer’s concurrent work. The timeline, by contrast, is shared: every peer’s captures converge into one ordered log that the whole room observes.
Scope and limits (see the engine implementation for the full rationale):
undo/redo act on the local peer’s mutations to the shared CRDT Y.Doc — the
data behind useState({ strategy: 'crdt' }). App-local React state and the
'lww' state strategy are NOT auto-reverted; reverting those is the app’s
responsibility. A bare capture() records a timeline entry (metadata) and is
only undoable when it is paired with transaction() mutations.
Methods
Section titled “Methods”canRedo()
Section titled “canRedo()”canRedo():
boolean
Defined in: core/dist/types.d.ts:1985
Reports whether the local peer has an undone transaction available to redo.
Returns
Section titled “Returns”boolean
true when HistoryEngine.redo would have an effect.
canUndo()
Section titled “canUndo()”canUndo():
boolean
Defined in: core/dist/types.d.ts:1979
Reports whether the local peer has a tracked transaction available to undo.
Returns
Section titled “Returns”boolean
true when HistoryEngine.undo would have an effect.
capture()
Section titled “capture()”capture(
action,payload?):void
Defined in: core/dist/types.d.ts:1950
Records a timeline entry without wrapping any mutation. Use this to log an
action that the app applies itself; pair it with transaction when the
action should also be undoable.
Parameters
Section titled “Parameters”action
Section titled “action”string
The action label for the entry.
payload?
Section titled “payload?”unknown
Optional metadata; a string is used as the entry
description, otherwise the description defaults to action.
Returns
Section titled “Returns”void
Nothing.
redo()
Section titled “redo()”redo():
Promise<void>
Defined in: core/dist/types.d.ts:1973
Redoes the local peer’s most recently undone transaction.
Returns
Section titled “Returns”Promise<void>
A promise that resolves once the redo is applied.
subscribe()
Section titled “subscribe()”subscribe(
callback):Unsubscribe
Defined in: core/dist/types.d.ts:2000
Subscribes to timeline changes. Fires immediately with the current
timeline, then on every local or remote change (including undo/redo
affecting canUndo/canRedo).
Parameters
Section titled “Parameters”callback
Section titled “callback”(timeline) => void
The callback invoked with the latest timeline.
Returns
Section titled “Returns”Unsubscribe
A function that removes the listener.
timeline()
Section titled “timeline()”timeline():
TimelineEntry[]
Defined in: core/dist/types.d.ts:1991
Returns the full shared timeline of every peer’s entries, oldest first.
Returns
Section titled “Returns”The current timeline entries.
transaction()
Section titled “transaction()”transaction(
name,fn):void
Defined in: core/dist/types.d.ts:1960
Runs fn, capturing every shared-CRDT mutation it makes as a single
undoable timeline entry. The mutations are committed under the local peer’s
tracked transaction origin so a later undo() reverts exactly this unit.
Parameters
Section titled “Parameters”string
The action label recorded on the timeline entry.
() => void
The function whose mutations form one undoable unit.
Returns
Section titled “Returns”void
Nothing.
undo()
Section titled “undo()”undo():
Promise<void>
Defined in: core/dist/types.d.ts:1967
Undoes the local peer’s most recent tracked transaction, reverting only that peer’s changes to the shared CRDT document.
Returns
Section titled “Returns”Promise<void>
A promise that resolves once the undo is applied.