@arcmantle/chronicle / config

config

Interfaces

ChronicleOptions

Defined in: config.ts:4

Extends

• ChronicleHistoryOptions

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

Inherited from

ChronicleHistoryOptions.cacheProxies

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

Inherited from

ChronicleHistoryOptions.clone

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

Inherited from

ChronicleHistoryOptions.compactSamePath

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

Inherited from

ChronicleHistoryOptions.compare

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"

Inherited from

ChronicleHistoryOptions.diffFilter

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

Inherited from

ChronicleHistoryOptions.filter

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

Inherited from

ChronicleHistoryOptions.maxHistory

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

Inherited from

ChronicleHistoryOptions.mergeUngrouped

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

Inherited from

ChronicleHistoryOptions.mergeWindowMs

Type Aliases

ConfigureOptions

ConfigureOptions = Partial<ChronicleOptions>

Defined in: config.ts:30

Functions

configureRoot()

configureRoot(root, options): void

Defined in: config.ts:36

Configure per-root observe behavior by merging options and managing mergeUngrouped window reset.

Parameters

root

object

options

ConfigureOptions

Returns

void

---

getOptions()

getOptions(root): ChronicleOptions

Defined in: config.ts:15

Parameters

root

object

Returns

ChronicleOptions

---

setOptions()

setOptions(root, options): void

Defined in: config.ts:26

Parameters

root

object

options

ChronicleOptions

Returns

void