@arcmantle/chronicle 0.0.4

package/src/collection-adapters.ts

@@ -0,0 +1,224 @@
+import { computeActiveGroupId } from './grouping.ts';
+import { ensureHistory, getOptions, trimHistoryByGroups } from './history.ts';
+import { computeAffectedListeners } from './listener-affinity.ts';
+import { notifyListeners } from './schedule-queue.ts';
+import type { ChangeMeta, ChangeRecord } from './types.ts';
+import { clearRedoCache, isSuspended } from './undo-redo.ts';
+
+
+export interface CollectionAdapterDeps {
+	getBatchFrames: (root: object) => { marker: number; id: string; }[] | undefined;
+}
+
+
+/**
+ * Create a history-and-notify callback for Map/Set mutations.
+ * This shared helper records the change and notifies listeners.
+ */
+const createRecordAndNotify = (
+	rootObject: object,
+	currentPath: string[],
+) => (rec: ChangeRecord, newValForListener: any, oldValForListener: any): void => {
+	// Record in history (Map/Set records have collection/key metadata, so push directly)
+	if (!isSuspended(rootObject)) {
+		const history = ensureHistory(rootObject);
+		clearRedoCache(rootObject);
+		const cfg = getOptions(rootObject);
+		if (!cfg?.filter || cfg.filter(rec))
+			history.push(rec);
+		if (cfg && typeof cfg.maxHistory === 'number')
+			trimHistoryByGroups(history, cfg.maxHistory);
+	}
+
+	// Notify listeners
+	const affected = computeAffectedListeners(rootObject, currentPath);
+	if (affected.size > 0) {
+		const meta: ChangeMeta = { type: rec.type, existedBefore: rec.existedBefore, groupId: rec.groupId };
+		notifyListeners(rootObject, affected, [ currentPath, newValForListener, oldValForListener, meta ]);
+	}
+};
+
+
+/**
+ * Wrap Map mutating methods to record changes and notify listeners.
+ *
+ * @param target - The Map instance
+ * @param currentPath - The path to the Map
+ * @param rootObject - The root object
+ * @param deps - Dependencies (getBatchFrames)
+ * @param method - The method name being accessed
+ * @returns Wrapped method or undefined if not a mutating method
+ */
+export const adaptMapMethod = (
+	target: Map<any, any>,
+	currentPath: string[],
+	rootObject: object,
+	deps: CollectionAdapterDeps,
+	method: string,
+): ((...args: any[]) => any) | undefined => {
+	const recordHistoryAndNotify = createRecordAndNotify(rootObject, currentPath);
+
+	if (method === 'set') {
+		return function(this: any, key: any, value: any) {
+			const m = target;
+			const had = m.has(key);
+			const oldV = had ? m.get(key) : undefined;
+			m.set(key, value);
+
+			const rec: ChangeRecord = {
+				path:          currentPath.slice(),
+				type:          'set',
+				oldValue:      oldV,
+				newValue:      value,
+				timestamp:     Date.now(),
+				existedBefore: had,
+				groupId:       computeActiveGroupId(rootObject, deps.getBatchFrames),
+				collection:    'map',
+				key,
+			};
+			recordHistoryAndNotify(rec, value, oldV);
+
+			return this;
+		};
+	}
+
+	if (method === 'delete') {
+		return function(this: any, key: any) {
+			const m = target;
+			const had = m.has(key);
+			const oldV = had ? m.get(key) : undefined;
+			const res = m.delete(key) as boolean;
+			if (had) {
+				const rec: ChangeRecord = {
+					path:       currentPath.slice(),
+					type:       'delete',
+					oldValue:   oldV,
+					newValue:   undefined,
+					timestamp:  Date.now(),
+					groupId:    computeActiveGroupId(rootObject, deps.getBatchFrames),
+					collection: 'map',
+					key,
+				};
+				recordHistoryAndNotify(rec, undefined, oldV);
+			}
+
+			return res;
+		};
+	}
+
+	if (method === 'clear') {
+		return function(this: any) {
+			const m = target;
+			const entries = Array.from(m.entries()) as [ any, any ][];
+			const gid = computeActiveGroupId(rootObject, deps.getBatchFrames);
+			m.clear();
+			for (const [ k, v ] of entries) {
+				const rec: ChangeRecord = {
+					path:       currentPath.slice(),
+					type:       'delete',
+					oldValue:   v,
+					newValue:   undefined,
+					timestamp:  Date.now(),
+					groupId:    gid,
+					collection: 'map',
+					key:        k,
+				};
+				recordHistoryAndNotify(rec, undefined, v);
+			}
+		};
+	}
+
+	return undefined;
+};
+
+
+/**
+ * Wrap Set mutating methods to record changes and notify listeners.
+ *
+ * @param target - The Set instance
+ * @param currentPath - The path to the Set
+ * @param rootObject - The root object
+ * @param deps - Dependencies (getBatchFrames)
+ * @param method - The method name being accessed
+ * @returns Wrapped method or undefined if not a mutating method
+ */
+export const adaptSetMethod = (
+	target: Set<any>,
+	currentPath: string[],
+	rootObject: object,
+	deps: CollectionAdapterDeps,
+	method: string,
+): ((...args: any[]) => any) | undefined => {
+	const recordHistoryAndNotify = createRecordAndNotify(rootObject, currentPath);
+
+	if (method === 'add') {
+		return function(this: any, value: any) {
+			const s = target;
+			const had = s.has(value);
+			s.add(value);
+			if (!had) {
+				const rec: ChangeRecord = {
+					path:          currentPath.slice(),
+					type:          'set',
+					oldValue:      undefined,
+					newValue:      value,
+					timestamp:     Date.now(),
+					existedBefore: false,
+					groupId:       computeActiveGroupId(rootObject, deps.getBatchFrames),
+					collection:    'set',
+					key:           value,
+				};
+				recordHistoryAndNotify(rec, value, undefined);
+			}
+
+			return this; // chaining
+		};
+	}
+
+	if (method === 'delete') {
+		return function(this: any, value: any) {
+			const s = target;
+			const had = s.has(value);
+			const res = s.delete(value) as boolean;
+			if (had) {
+				const rec: ChangeRecord = {
+					path:       currentPath.slice(),
+					type:       'delete',
+					oldValue:   value,
+					newValue:   undefined,
+					timestamp:  Date.now(),
+					groupId:    computeActiveGroupId(rootObject, deps.getBatchFrames),
+					collection: 'set',
+					key:        value,
+				};
+				recordHistoryAndNotify(rec, undefined, value);
+			}
+
+			return res; // boolean
+		};
+	}
+
+	if (method === 'clear') {
+		return function(this: any) {
+			const s = target;
+			const values = Array.from(s.values()) as any[];
+			const gid = computeActiveGroupId(rootObject, deps.getBatchFrames);
+			s.clear();
+			for (const v of values) {
+				const rec: ChangeRecord = {
+					path:       currentPath.slice(),
+					type:       'delete',
+					oldValue:   v,
+					newValue:   undefined,
+					timestamp:  Date.now(),
+					groupId:    gid,
+					collection: 'set',
+					key:        v,
+				};
+				recordHistoryAndNotify(rec, undefined, v);
+			}
+		};
+	}
+
+	return undefined;
+};

package/src/config.ts

@@ -0,0 +1,16 @@
+import type { ChronicleOptions } from './history.ts';
+import { clearLastUngrouped, getOptions, setOptions } from './history.ts';
+
+
+export type ConfigureOptions = ChronicleOptions;
+
+
+/**
+ * Configure per-root observe behavior by merging options and managing mergeUngrouped window reset.
+ */
+export const configureRoot = (root: object, options: ConfigureOptions): void => {
+	const prev = getOptions(root) ?? {};
+	setOptions(root, { ...prev, ...options });
+	if (!options.mergeUngrouped)
+		clearLastUngrouped(root);
+};

package/src/grouping.ts

@@ -0,0 +1,47 @@
+import { clearLastUngrouped, getLastUngrouped, getOptions, nextGroupId, setLastUngrouped } from './history.ts';
+
+
+/**
+ * Compute the active group ID for a change.
+ *
+ * If inside a batch, uses the current batch frame's ID.
+ * Otherwise, if mergeUngrouped is enabled and within the merge window,
+ * reuses the last ungrouped ID. Otherwise generates a new group ID.
+ *
+ * @param root - The root object
+ * @param getBatchFrames - Function to get batch frames for the root
+ * @param nowProvider - Function to get current timestamp (defaults to Date.now)
+ * @returns The group ID to use for the current change
+ */
+export const computeActiveGroupId = (
+	root: object,
+	getBatchFrames: (root: object) => { marker: number; id: string; }[] | undefined,
+	nowProvider: () => number = Date.now,
+): string => {
+	const batchFrames = getBatchFrames(root);
+	if (batchFrames && batchFrames.length > 0)
+		return batchFrames[batchFrames.length - 1]!.id;
+
+	const opts = getOptions(root);
+	if (opts && opts.mergeUngrouped) {
+		const now = nowProvider();
+		const prev = getLastUngrouped(root);
+		const within = opts.mergeWindowMs == null
+			|| (prev ? (now - prev.at) <= opts.mergeWindowMs : false);
+
+		if (prev && within) {
+			setLastUngrouped(root, { id: prev.id, at: now });
+
+			return prev.id;
+		}
+
+		const gid = nextGroupId(root);
+		setLastUngrouped(root, { id: gid, at: now });
+
+		return gid;
+	}
+
+	clearLastUngrouped(root);
+
+	return nextGroupId(root);
+};

package/src/history-recorder.ts

@@ -0,0 +1,145 @@
+import { ensureHistory, getOptions, trimHistoryByGroups } from './history.ts';
+import type { ChangeRecord } from './types.ts';
+import { clearRedoCache, isSuspended } from './undo-redo.ts';
+
+
+/**
+ * Record a 'set' operation in history with filtering, compaction, and trimming.
+ *
+ * Handles optional compaction of consecutive sets on the same path within the same group,
+ * avoiding compaction of array indices and length properties.
+ *
+ * @param root - The root object
+ * @param path - The path where the set occurred
+ * @param oldValue - The previous value
+ * @param newValue - The new value
+ * @param existedBefore - Whether the property existed before
+ * @param groupId - The group ID for this change
+ */
+export const recordSet = (
+	root: object,
+	path: string[],
+	oldValue: any,
+	newValue: any,
+	existedBefore: boolean,
+	groupId: string,
+): void => {
+	if (isSuspended(root))
+		return;
+
+	const history = ensureHistory(root);
+	clearRedoCache(root);
+	const cfg = getOptions(root);
+
+	const rec: ChangeRecord = {
+		path:      path.slice(),
+		type:      'set',
+		oldValue,
+		newValue,
+		timestamp: Date.now(),
+		existedBefore,
+		groupId,
+	};
+
+	if (!cfg?.filter || cfg.filter(rec))
+		history.push(rec);
+
+	// Optional compaction: merge consecutive sets on the same path within the same group
+	if (cfg && cfg.compactConsecutiveSamePath && history.length >= 2) {
+		const a = history[history.length - 2]!;
+		const b = history[history.length - 1]!;
+		const sameGroup = (a.groupId ?? `__g#${ history.length - 2 }`) === (b.groupId ?? `__g#${ history.length - 1 }`);
+		const samePath = a.path.length === b.path.length && a.path.every((seg, i) => seg === b.path[i]);
+		const isSetSet = a.type === 'set' && b.type === 'set';
+		// Avoid compacting array index updates and length changes
+		const lastSeg = b.path[b.path.length - 1]!;
+		const isArrayIndex = /^(?:0|[1-9]\d*)$/.test(lastSeg);
+		const isLengthProp = lastSeg === 'length';
+		if (sameGroup && samePath && isSetSet && !isArrayIndex && !isLengthProp) {
+			// Merge: keep 'a' with oldValue from original and update newValue/timestamp from 'b'; drop 'b'
+			a.newValue = b.newValue;
+			a.timestamp = b.timestamp;
+			history.pop();
+		}
+	}
+
+	// Enforce maxHistory by trimming whole groups from the front
+	if (cfg && typeof cfg.maxHistory === 'number')
+		trimHistoryByGroups(history, cfg.maxHistory);
+};
+
+/**
+ * Record a 'delete' operation in history with filtering and trimming.
+ *
+ * @param root - The root object
+ * @param path - The path where the delete occurred
+ * @param oldValue - The value that was deleted
+ * @param groupId - The group ID for this change
+ */
+export const recordDelete = (
+	root: object,
+	path: string[],
+	oldValue: any,
+	groupId: string,
+): void => {
+	if (isSuspended(root))
+		return;
+
+	const history = ensureHistory(root);
+	clearRedoCache(root);
+	const cfg = getOptions(root);
+
+	const rec: ChangeRecord = {
+		path:      path.slice(),
+		type:      'delete',
+		oldValue,
+		newValue:  undefined,
+		timestamp: Date.now(),
+		groupId,
+	};
+
+	if (!cfg?.filter || cfg.filter(rec))
+		history.push(rec);
+
+	// Enforce maxHistory by trimming whole groups from the front
+	if (cfg && typeof cfg.maxHistory === 'number')
+		trimHistoryByGroups(history, cfg.maxHistory);
+};
+
+/**
+ * Record delete operations for array elements removed by length shrinkage.
+ *
+ * Used when array.length is decreased, synthesizing delete records for removed indices.
+ * Does not apply compaction or other optimizations - just records the deletes.
+ *
+ * @param root - The root object
+ * @param basePath - The path to the array (not including indices)
+ * @param removed - Array of {index, value} pairs that were removed
+ * @param groupId - The group ID for these changes
+ */
+export const recordArrayShrinkDeletes = (
+	root: object,
+	basePath: string[],
+	removed: { index: number; value: any; }[],
+	groupId: string,
+): void => {
+	if (isSuspended(root) || removed.length === 0)
+		return;
+
+	const history = ensureHistory(root);
+	const cfg = getOptions(root);
+
+	for (const { index, value: oldVal } of removed) {
+		const rec: ChangeRecord = {
+			path:      [ ...basePath, String(index) ],
+			type:      'delete',
+			oldValue:  oldVal,
+			newValue:  undefined,
+			timestamp: Date.now(),
+			groupId,
+		};
+
+		if (!cfg?.filter || cfg.filter(rec))
+			history.push(rec);
+	}
+};

package/src/history.ts

@@ -0,0 +1,75 @@
+import type { ChangeRecord } from './types.ts';
+
+// History records per root
+const historyCache: WeakMap<object, ChangeRecord[]> = new WeakMap();
+
+// Group/merge state per root
+const groupCounter: WeakMap<object, number> = new WeakMap();
+const lastUngrouped: WeakMap<object, { id: string; at: number; }> = new WeakMap();
+
+// Observe options per root
+export interface ChronicleOptions {
+	mergeUngrouped?:             boolean;
+	mergeWindowMs?:              number;
+	compactConsecutiveSamePath?: boolean;
+	maxHistory?:                 number;
+	filter?:                     (record: ChangeRecord) => boolean;
+	clone?:                      (value: any) => any;
+	compare?:                    (a: any, b: any, path: string[]) => boolean; // true => equal
+	diffFilter?:                 (path: string[]) => boolean | 'shallow';
+	cacheProxies?:               boolean;
+}
+
+const optionsCache: WeakMap<object, ChronicleOptions> = new WeakMap();
+
+export const ensureHistory = (root: object): ChangeRecord[] => {
+	let h = historyCache.get(root);
+	if (!h) {
+		h = [];
+		historyCache.set(root, h);
+	}
+
+	return h;
+};
+
+export const historyGet = (root: object): ChangeRecord[] | undefined => historyCache.get(root);
+export const historyDelete = (root: object): void => { historyCache.delete(root); };
+
+// Trim history by removing whole groups from the front until length <= max.
+// This keeps undoGroups coherent and avoids splitting groups.
+export const trimHistoryByGroups = (history: ChangeRecord[], max: number): void => {
+	if (!(typeof max === 'number') || max < 0)
+		return;
+
+	if (history.length <= max)
+		return;
+
+	let removeCount = 0;
+	let i = 0;
+	while (history.length - removeCount > max && i < history.length) {
+		const gid = history[i]!.groupId ?? `__g#${ i }`;
+		let j = i;
+		while (j < history.length && (history[j]!.groupId ?? `__g#${ j }`) === gid)
+			j++;
+
+		removeCount += (j - i);
+		i = j;
+	}
+
+	if (removeCount > 0)
+		history.splice(0, removeCount);
+};
+
+export const nextGroupId = (root: object): string => {
+	const n = (groupCounter.get(root) ?? 0) + 1;
+	groupCounter.set(root, n);
+
+	return `g${ n }`;
+};
+
+export const getOptions = (root: object): ChronicleOptions => optionsCache.get(root) ?? {};
+export const setOptions = (root: object, options: ChronicleOptions): void => { optionsCache.set(root, options); };
+
+export const getLastUngrouped = (root: object): { id: string; at: number; } | undefined => lastUngrouped.get(root);
+export const setLastUngrouped = (root: object, v: { id: string; at: number; }): void => { lastUngrouped.set(root, v); };
+export const clearLastUngrouped = (root: object): void => { lastUngrouped.delete(root); };

package/src/listener-affinity.ts

@@ -0,0 +1,69 @@
+import { getListenerBucket, getNode } from './listener-trie.ts';
+import type { ChangeListener, PathTrieNode } from './types.ts';
+
+
+/**
+ * Compute the set of listeners affected by a change at the given path.
+ *
+ * Collects listeners in this order:
+ * - Global listeners (onAny)
+ * - Down listeners on the path and all ancestors (listen for descendants)
+ * - Exact listeners at the exact path
+ * - Up listeners on all descendants (listen for ancestors)
+ *
+ * @param root - The root object
+ * @param path - The path where the change occurred
+ * @returns Set of all affected listeners
+ */
+export const computeAffectedListeners = (root: object, path: string[]): Set<ChangeListener> => {
+	const bucket = getListenerBucket(root);
+	const affected: Set<ChangeListener> = new Set();
+
+	if (!bucket)
+		return affected;
+
+	// Global listeners
+	bucket.global.forEach(l => affected.add(l));
+
+	const rootNode = bucket.trie;
+
+	// Down listeners on ancestors (including root)
+	{
+		let node: PathTrieNode | undefined = rootNode;
+		if (node && node.modes.size > 0)
+			node.modes.get('down')?.forEach(l => affected.add(l));
+
+		for (const seg of path) {
+			node = node?.children.get(seg);
+			if (!node)
+				break;
+
+			node.modes.get('down')?.forEach(l => affected.add(l));
+		}
+	}
+
+	// Exact listeners at the path
+	{
+		const node = getNode(rootNode, path);
+		if (node)
+			node.modes.get('exact')?.forEach(l => affected.add(l));
+	}
+
+	// Up listeners on descendants (strictly deeper than path)
+	{
+		const start = getNode(rootNode, path);
+		if (start) {
+			for (const child of start.children.values()) {
+				const stack: PathTrieNode[] = [ child ];
+				while (stack.length) {
+					const n = stack.pop()!;
+					n.modes.get('up')?.forEach(l => affected.add(l));
+					for (const c of n.children.values())
+						stack.push(c);
+				}
+			}
+		}
+	}
+
+	return affected;
+};

package/src/listener-trie.ts

@@ -0,0 +1,103 @@
+import type { ChangeListener, ListenerBucket, PathMode, PathTrieNode } from './types.ts';
+
+// Per-root listener registry (global + trie)
+const listenerCache: WeakMap<object, ListenerBucket> = new WeakMap();
+
+export const getListenerBucket = (root: object): ListenerBucket | undefined => listenerCache.get(root);
+
+export const ensureListenerBucket = (root: object): ListenerBucket => {
+	let bucket = listenerCache.get(root);
+
+	if (!bucket) {
+		bucket = {
+			global: new Set<ChangeListener>(),
+			trie:   { children: new Map<string, PathTrieNode>(), modes: new Map<PathMode, Set<ChangeListener>>() },
+		};
+		listenerCache.set(root, bucket);
+	}
+
+	return bucket;
+};
+
+const isNodeEmpty = (node: PathTrieNode): boolean => node.children.size === 0 && (node.modes.size === 0);
+
+export const cleanupListenerBucket = (root: object, bucket: ListenerBucket): void => {
+	if (bucket.global.size === 0 && isNodeEmpty(bucket.trie))
+		listenerCache.delete(root);
+};
+
+export const getOrCreateNode = (root: PathTrieNode, segs: string[]): PathTrieNode => {
+	let node = root;
+	for (const s of segs) {
+		let next = node.children.get(s);
+		if (!next) {
+			next = { children: new Map<string, PathTrieNode>(), modes: new Map<PathMode, Set<ChangeListener>>() };
+			node.children.set(s, next);
+		}
+
+		node = next;
+	}
+
+	return node;
+};
+
+export const getNode = (root: PathTrieNode, segs: string[]): PathTrieNode | undefined => {
+	let node: PathTrieNode | undefined = root;
+	for (const s of segs) {
+		node = node?.children.get(s);
+		if (!node)
+			return undefined;
+	}
+
+	return node;
+};
+
+export const prunePathIfEmpty = (root: PathTrieNode, segs: string[]): void => {
+	const stack: { seg: string; node: PathTrieNode; }[] = [];
+	let node: PathTrieNode | undefined = root;
+	for (const s of segs) {
+		if (!node)
+			return;
+
+		stack.push({ seg: s, node });
+		node = node.children.get(s);
+	}
+	// node is the target node
+	if (!node)
+		return;
+
+	// Walk back up pruning empty nodes
+	for (let i = segs.length - 1; i >= 0; i--) {
+		const parent = stack[i]!.node;
+		const seg = stack[i]!.seg;
+		const child = parent.children.get(seg)!;
+		if (child.children.size === 0 && child.modes.size === 0)
+			parent.children.delete(seg);
+		else
+			break;
+	}
+};
+
+export const addListenerToTrie = (root: PathTrieNode, segs: string[], mode: PathMode, listener: ChangeListener): PathTrieNode => {
+	const node = getOrCreateNode(root, segs);
+	const set = node.modes.get(mode) ?? new Set<ChangeListener>();
+	set.add(listener);
+	node.modes.set(mode, set);
+
+	return node;
+};
+
+export const removeListenerFromTrie = (root: PathTrieNode, segs: string[], mode: PathMode, listener: ChangeListener): void => {
+	const node = getNode(root, segs);
+	if (!node)
+		return;
+
+	const set = node.modes.get(mode);
+	if (set) {
+		set.delete(listener);
+		if (set.size === 0)
+			node.modes.delete(mode);
+	}
+
+	prunePathIfEmpty(root, segs);
+};