@arcmantle/chronicle / api-methods
api-methods
Interfaces
ApiDeps
Defined in: api-methods.ts:13
Properties
getRoot()
getRoot: (
obj) =>object
Defined in: api-methods.ts:14
Parameters
obj
object
Returns
object
ChronicleApiMethods
Defined in: api-methods.ts:21
Extended by
Properties
canRedo()
canRedo: (
obj) =>boolean
Defined in: api-methods.ts:239
Check if redo is available (there are undone changes that can be reapplied).
Parameters
obj
object
The chronicled object
Returns
boolean
True if redo is possible, false otherwise
canUndo()
canUndo: (
obj) =>boolean
Defined in: api-methods.ts:231
Check if undo is available (history has changes that can be undone).
Parameters
obj
object
The chronicled object
Returns
boolean
True if undo is possible, false otherwise
clearHistory()
clearHistory: (
obj) =>void
Defined in: api-methods.ts:123
Clear all change history and redo cache. The object's current state is preserved, but undo/redo will no longer work until new changes are made.
Parameters
obj
object
The chronicled object
Returns
void
clearRedo()
clearRedo: (
obj) =>void
Defined in: api-methods.ts:247
Clear the redo cache, making undone changes un-re-doable. The object's current state and undo history are preserved.
Parameters
obj
object
The chronicled object
Returns
void
configure()
configure: (
obj,options) =>void
Defined in: api-methods.ts:275
Configure chronicle options for this object. Options include history limits, merge behavior, custom clone/compare functions, and proxy caching. Can be called multiple times; new options are merged with existing ones.
Parameters
obj
object
The chronicled object
options
Configuration options to apply
Returns
void
diff()
diff: (
obj) =>DiffRecord[]
Defined in: api-methods.ts:148
Get the differences between the current state and the pristine state. Returns an array of changes showing what was added, removed, or modified.
Parameters
obj
object
The chronicled object
Returns
Array of diff records with path, kind ('added'|'removed'|'changed'), and values
flush()
flush: (
obj) =>void
Defined in: api-methods.ts:106
Immediately flush any pending change notifications that are scheduled asynchronously. Useful when you need synchronous notification delivery.
Parameters
obj
object
The chronicled object to flush
Returns
void
getHistory()
getHistory: (
obj) =>ChangeRecord[]
Defined in: api-methods.ts:115
Get a copy of the complete change history for this object. Each record contains path, type, oldValue, newValue, timestamp, and groupId for undo/redo operations.
Parameters
obj
object
The chronicled object
Returns
Array of change records (copy, safe to modify)
isPristine()
isPristine: (
obj) =>boolean
Defined in: api-methods.ts:157
Check if the object has any changes from its pristine state. Returns true if the object matches its original or last markPristine() state.
Parameters
obj
object
The chronicled object
Returns
boolean
True if no changes exist, false otherwise
mark()
mark: (
obj) =>number
Defined in: api-methods.ts:196
Get a marker representing the current history length. Use with undoSince() to undo changes made after this point. Useful for transaction-like rollback behavior.
Parameters
obj
object
The chronicled object
Returns
number
Current history length (marker value)
markPristine()
markPristine: (
obj) =>void
Defined in: api-methods.ts:139
Mark the current state as the new pristine baseline. Clears history and resets the snapshot used for diff() and reset(). Useful after saving to server or committing changes.
Parameters
obj
object
The chronicled object
Returns
void
merge()
merge: (
obj,incomingObject,resolutions?) =>MergeResult
Defined in: api-methods.ts:187
Perform a three-way merge between the pristine state (base), current state (ours), and incoming changes (theirs). Detects conflicts and allows resolution strategies. Useful for syncing local changes with server updates.
Parameters
obj
object
The chronicled object
incomingObject
object
The incoming state to merge
resolutions?
Optional conflict resolution strategies per path
Returns
Merge result with success status, conflicts array, and count of applied changes
onAny()
onAny: (
obj,listener,options?) => () =>void
Defined in: api-methods.ts:82
Subscribe to all changes on the object, regardless of path. Useful for broad monitoring.
Parameters
obj
object
The chronicled object to listen to
listener
Callback invoked on any change with (path, newValue, oldValue, meta)
options?
Optional listener configuration (once, debounceMs, throttleMs, schedule)
Returns
Unsubscribe function to stop listening
():
void
Returns
void
pause()
pause: (
obj) =>void
Defined in: api-methods.ts:90
Temporarily pause change notifications for this object. Changes still occur and are recorded in history, but listeners won't be notified until resume() is called.
Parameters
obj
object
The chronicled object to pause
Returns
void
redo()
redo: (
obj,steps?) =>void
Defined in: api-methods.ts:256
Redo the last N undone changes (or all undone changes if steps not specified). Changes are redone individually.
Parameters
obj
object
The chronicled object
steps?
number
Number of changes to redo (default: all)
Returns
void
redoGroups()
redoGroups: (
obj,groups?) =>void
Defined in: api-methods.ts:265
Redo the last N undo groups. Unlike redo() which works on individual changes, this respects the grouping from batches and transactions.
Parameters
obj
object
The chronicled object
groups?
number
Number of groups to redo (default: 1)
Returns
void
reset()
reset: (
obj) =>void
Defined in: api-methods.ts:131
Reset the object to its pristine state (the state when first chronicled or when markPristine was last called). This is an un-doable operation.
Parameters
obj
object
The chronicled object to reset
Returns
void
resume()
resume: (
obj) =>void
Defined in: api-methods.ts:98
Resume change notifications that were paused. Accumulated changes are not batched; call flush() if you want to trigger pending notifications immediately.
Parameters
obj
object
The chronicled object to resume
Returns
void
snapshot()
snapshot: <
T>(obj) =>T
Defined in: api-methods.ts:166
Create a deep clone snapshot of the current state. The snapshot is a plain object, not a chronicle proxy, and can be serialized or stored independently.
Type Parameters
T
T extends object
Parameters
obj
T
The chronicled object
Returns
T
Deep clone of the current state
undo()
undo: (
obj,steps?) =>void
Defined in: api-methods.ts:205
Undo the last N changes (or all changes if steps not specified). Changes are undone individually. For grouped operations, use undoGroups() instead.
Parameters
obj
object
The chronicled object
steps?
number
Number of changes to undo (default: all)
Returns
void
undoGroups()
undoGroups: (
obj,groups?) =>void
Defined in: api-methods.ts:223
Undo the last N undo groups (batches/transactions). Unlike undo() which works on individual changes, this respects the grouping from batches and transactions.
Parameters
obj
object
The chronicled object
groups?
number
Number of groups to undo (default: 1)
Returns
void
undoSince()
undoSince: (
obj,historyLengthBefore) =>void
Defined in: api-methods.ts:214
Undo all changes made since the specified marker. The marker should come from mark(). This undoes everything after that point in history.
Parameters
obj
object
The chronicled object
historyLengthBefore
number
The marker value from mark()
Returns
void
unwrap()
unwrap: <
T>(obj) =>T
Defined in: api-methods.ts:175
Get the original unwrapped object (removes the chronicle proxy). Use with caution: changes to the unwrapped object won't be tracked or trigger listeners.
Type Parameters
T
T extends object
Parameters
obj
T
The chronicled object
Returns
T
The underlying object without proxy wrapper
Methods
listen()
Call Signature
listen<
T>(object,selector,listener): () =>void
Defined in: api-methods.ts:38
Subscribe to changes at a specific path in the object. The listener is called whenever the selected property or any of its descendants change. Returns an unsubscribe function.
Type Parameters
T
T extends object
Parameters
object
T
The chronicled object to listen to
selector
PathSelector<T>
Function that selects the path to watch (e.g., obj => obj.user.name)
listener
Callback invoked on changes with (path, newValue, oldValue, meta)
Returns
Unsubscribe function to stop listening
():
void
Returns
void
Example
const unsubscribe = chronicle.listen(state, s => s.count, (path, newVal, oldVal) => {
console.log(`count changed from ${oldVal} to ${newVal}`);
});Call Signature
listen<
T>(object,selector,listener,options): () =>void
Defined in: api-methods.ts:49
Subscribe to changes at a specific path with listener options like debouncing or throttling.
Type Parameters
T
T extends object
Parameters
object
T
The chronicled object to listen to
selector
PathSelector<T>
Function that selects the path to watch
listener
Callback invoked on changes
options
Listener configuration (once, debounceMs, throttleMs, schedule)
Returns
Unsubscribe function
():
void
Returns
void
Call Signature
listen<
T>(object,selector,listener,mode): () =>void
Defined in: api-methods.ts:60
Subscribe to changes at a specific path with a traversal mode.
Type Parameters
T
T extends object
Parameters
object
T
The chronicled object to listen to
selector
PathSelector<T>
Function that selects the path to watch
listener
Callback invoked on changes
mode
Path matching mode: 'exact' (only this path), 'up' (ancestors), 'down' (descendants)
Returns
Unsubscribe function
():
void
Returns
void
Call Signature
listen<
T>(object,selector,listener,mode,options): () =>void
Defined in: api-methods.ts:72
Subscribe to changes at a specific path with both traversal mode and listener options.
Type Parameters
T
T extends object
Parameters
object
T
The chronicled object to listen to
selector
PathSelector<T>
Function that selects the path to watch
listener
Callback invoked on changes
mode
Path matching mode: 'exact', 'up', or 'down'
options
Listener configuration (once, debounceMs, throttleMs, schedule)
Returns
Unsubscribe function
():
void
Returns
void
Functions
createApiMethods()
createApiMethods(
deps):ChronicleApiMethods
Defined in: api-methods.ts:278