@arcmantle/chronicle / history

history

Interfaces

ChronicleHistoryOptions

Defined in: history.ts:11

Extended by

• ChronicleOptions

Properties

cacheProxies?

optional cacheProxies: boolean

Defined in: history.ts:84

When enabled, proxies for nested objects at a given path are cached and reused, providing stable identity for the same path across multiple accesses. Without this, each access to a nested property creates a new proxy. Caching improves performance and enables reference equality checks but requires cache invalidation on mutations.

Default

true

clone()?

optional clone: (value) => any

Defined in: history.ts:61

Custom deep clone function used when creating snapshots for diff, reset, and undo operations. Defaults to structuredClone. Provide a custom implementation if you need special handling for certain object types (e.g., using JSON serialization, custom class cloning, or handling non-cloneable objects).

Parameters

value

any

Returns

any

compactSamePath?

optional compactSamePath: boolean

Defined in: history.ts:39

When enabled, consecutive 'set' operations on the same path within the same undo group are compacted into a single history record, keeping only the original oldValue and the final newValue. This reduces history size for rapid updates to the same property. Does not compact array index updates or length changes to preserve array operation fidelity.

Default

true

compare()?

optional compare: (a, b, path) => boolean

Defined in: history.ts:68

Custom equality comparison function used during diff operations to determine if two values are equal. Return true if values are equal, false otherwise. Defaults to Object.is. The path parameter provides context about where in the object tree the comparison is occurring.

Parameters

a

any

b

any

path

string[]

Returns

boolean

diffFilter()?

optional diffFilter: (path) => boolean | "shallow"

Defined in: history.ts:75

Filter function to control diff traversal depth. Return false to skip a path entirely, 'shallow' to compare the value at this path without recursing into it, or true to recurse normally. Useful for excluding internal properties from diffs or avoiding deep traversal of large subtrees.

Parameters

path

string[]

Returns

boolean | "shallow"

filter()?

optional filter: (record) => boolean

Defined in: history.ts:54

Custom filter function to selectively exclude certain change records from history. Return false to prevent recording; return true to record normally. The actual change still occurs in the object, but filtered records won't appear in history and can't be undone. Useful for excluding temporary properties or noisy updates.

Parameters

record

ChangeRecord

Returns

boolean

maxHistory?

optional maxHistory: number

Defined in: history.ts:47

Maximum number of history records to retain. When the limit is exceeded, entire undo groups are trimmed from the front of history to keep groups coherent. This creates a rolling window of recent changes while preventing unbounded memory growth.

Default

1000

mergeUngrouped?

optional mergeUngrouped: boolean

Defined in: history.ts:20

When enabled, consecutive ungrouped changes (those not in a batch or transaction) are merged into a single undo group. If mergeWindowMs is also set, only changes within that time window are merged together. Without this option, each individual change creates its own undo group.

Default

true

mergeWindowMs?

optional mergeWindowMs: number

Defined in: history.ts:29

Time window in milliseconds for merging ungrouped changes. Only effective when mergeUngrouped is true. Changes occurring within this window are grouped together for undo/redo. If omitted, all consecutive ungrouped changes are merged regardless of timing.

Default

300

Variables

defaultHistoryOptions

const defaultHistoryOptions: ChronicleHistoryOptions

Defined in: history.ts:87

Functions

clearLastUngrouped()

clearLastUngrouped(root): void

Defined in: history.ts:149

Parameters

root

object

Returns

void

---

ensureHistory()

ensureHistory(root): ChangeRecord[]

Defined in: history.ts:95

Parameters

root

object

Returns

ChangeRecord[]

---

getLastUngrouped()

getLastUngrouped(root): { at: number; id: string; } | undefined

Defined in: history.ts:147

Parameters

root

object

Returns

{ at: number; id: string; } | undefined

---

historyDelete()

historyDelete(root): void

Defined in: history.ts:106

Parameters

root

object

Returns

void

---

historyGet()

historyGet(root): ChangeRecord[] | undefined

Defined in: history.ts:105

Parameters

root

object

Returns

ChangeRecord[] | undefined

---

nextGroupId()

nextGroupId(root): string

Defined in: history.ts:140

Parameters

root

object

Returns

string

---

setLastUngrouped()

setLastUngrouped(root, v): void

Defined in: history.ts:148

Parameters

root

object

v

at

number

id

string

Returns

void

---

trimHistoryByGroups()

trimHistoryByGroups(history, max): void

Defined in: history.ts:110

Parameters

history

ChangeRecord[]

max

number

Returns

void