@arcmantle/chronicle 0.0.4

package/src/api-methods.ts

@@ -0,0 +1,292 @@
+import { clearLastUngrouped, historyDelete, historyGet } from './history.ts';
+import { addListenerToTrie, cleanupListenerBucket, ensureListenerBucket, removeListenerFromTrie } from './listener-trie.ts';
+import { nameofSegments } from './nameof.ts';
+import { clearProxyCache as pfClearProxyCache } from './proxy-factory.ts';
+import { buildEffectiveListener, flush as scheduleFlush, pause as schedulePause, resume as scheduleResume } from './schedule-queue.ts';
+import { cloneWithOptions, diffValues, originalSnapshotCache } from './snapshot-diff.ts';
+import type { ChangeListener, ChangeRecord, DiffRecord, ListenerOptions, PathMode, PathSelector } from './types.ts';
+import { canRedo as coreCanRedo, canUndo as coreCanUndo, clearRedoCache, redo as coreRedo, redoGroups as coreRedoGroups, resumeWrites, suspendWrites, undo as coreUndo, undoGroups as coreUndoGroups, undoSince as coreUndoSince } from './undo-redo.ts';
+
+
+export interface ApiDeps {
+	getRoot: (obj: object) => object;
+}
+
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null;
+
+
+export interface ChronicleApiMethods {
+	listen: <T extends object>(
+		object: T,
+		selector: PathSelector<T>,
+		listener: ChangeListener,
+		modeOrOptions?: PathMode | ListenerOptions,
+		maybeOptions?: ListenerOptions,
+	) => () => void;
+	onAny:        (obj: object, listener: ChangeListener, options?: ListenerOptions) => () => void;
+	pause:        (obj: object) => void;
+	resume:       (obj: object) => void;
+	flush:        (obj: object) => void;
+	getHistory:   (obj: object) => ChangeRecord[];
+	clearHistory: (obj: object) => void;
+	reset:        (obj: object) => void;
+	markPristine: (obj: object) => void;
+	diff:         (obj: object) => DiffRecord[];
+	isPristine:   (obj: object) => boolean;
+	mark:         (obj: object) => number;
+	undo:         (obj: object, steps?: number) => void;
+	undoSince:    (obj: object, historyLengthBefore: number) => void;
+	undoGroups:   (obj: object, groups?: number) => void;
+	canUndo:      (obj: object) => boolean;
+	canRedo:      (obj: object) => boolean;
+	clearRedo:    (obj: object) => void;
+	redo:         (obj: object, steps?: number) => void;
+	redoGroups:   (obj: object, groups?: number) => void;
+}
+
+export const createApiMethods = (deps: ApiDeps): ChronicleApiMethods => {
+	// listen/onAny --------------------------------------------------------------
+	const listen = <T extends object>(
+		object: T,
+		selector: PathSelector<T>,
+		listener: ChangeListener,
+		modeOrOptions?: PathMode | ListenerOptions,
+		maybeOptions?: ListenerOptions,
+	) => {
+		const segs = nameofSegments(selector);
+		const root = deps.getRoot(object as object);
+		const bucket = ensureListenerBucket(root);
+
+		let mode: PathMode = 'down';
+		let options: ListenerOptions | undefined;
+		if (typeof modeOrOptions === 'string') {
+			mode = modeOrOptions;
+			options = maybeOptions;
+		}
+		else {
+			options = modeOrOptions;
+		}
+
+		let unsubscribe: (() => void) | undefined;
+		const { effective: effectiveListener, setUnsubscribe } = buildEffectiveListener(listener, options);
+		setUnsubscribe(() => {
+			if (unsubscribe)
+				unsubscribe();
+		});
+
+		if (segs.length === 0) {
+			bucket.global.add(effectiveListener);
+
+			unsubscribe = () => {
+				bucket.global.delete(effectiveListener);
+				cleanupListenerBucket(root, bucket);
+			};
+
+			return unsubscribe;
+		}
+
+		addListenerToTrie(bucket.trie, segs, mode, effectiveListener);
+
+		unsubscribe = () => {
+			removeListenerFromTrie(bucket.trie, segs, mode, effectiveListener);
+			cleanupListenerBucket(root, bucket);
+		};
+
+		return unsubscribe;
+	};
+
+	const onAny = (obj: object, listener: ChangeListener, options?: ListenerOptions): () => void => {
+		return listen(obj as any, s => s as any, listener, options);
+	};
+
+	// pause/resume/flush --------------------------------------------------------
+	const pause = (obj: object): void => {
+		const root = deps.getRoot(obj);
+		schedulePause(root);
+	};
+
+	const resume = (obj: object): void => {
+		const root = deps.getRoot(obj);
+		scheduleResume(root);
+	};
+
+	const flush = (obj: object): void => {
+		const root = deps.getRoot(obj);
+		scheduleFlush(root);
+	};
+
+	// history ------------------------------------------------------------------
+	const getHistory = (obj: object): ChangeRecord[] => {
+		const root = deps.getRoot(obj);
+
+		return (historyGet(root) ?? []).slice();
+	};
+
+	const clearHistory = (obj: object): void => {
+		const root = deps.getRoot(obj);
+		historyDelete(root);
+		clearLastUngrouped(root);
+		clearRedoCache(root);
+	};
+
+	// reset/markPristine/diff/pristine ----------------------------------------
+	const markPristine = (obj: object): void => {
+		const root = deps.getRoot(obj);
+		originalSnapshotCache.set(root, cloneWithOptions(root, root));
+		historyDelete(root);
+		clearLastUngrouped(root);
+		clearRedoCache(root);
+		pfClearProxyCache(root);
+	};
+
+	const reset = (obj: object): void => {
+		const root = deps.getRoot(obj);
+		const snapshot = originalSnapshotCache.get(root);
+		if (!snapshot) {
+			markPristine(root);
+
+			return;
+		}
+
+		const overwriteDeep = (target: any, source: any) => {
+			if (Array.isArray(target) && Array.isArray(source)) {
+				target.length = source.length;
+				for (let i = 0; i < source.length; i++)
+					target[i] = cloneWithOptions(root, source[i]);
+
+				return;
+			}
+
+			const isPlainObject = (v: any) => Object.prototype.toString.call(v) === '[object Object]';
+			if (isObject(target) && isObject(source) && isPlainObject(target) && isPlainObject(source)) {
+				for (const k of Reflect.ownKeys(target)) {
+					if (!Object.prototype.hasOwnProperty.call(source, k))
+						// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+						delete (target as any)[k as any];
+				}
+				for (const k of Reflect.ownKeys(source)) {
+					const sv = (source as any)[k as any];
+					const tv = (target as any)[k as any];
+					const bothArrays = Array.isArray(sv) && Array.isArray(tv);
+					const bothObjects = isObject(sv) && isObject(tv) && isPlainObject(sv) && isPlainObject(tv);
+					if (bothArrays || bothObjects)
+						overwriteDeep(tv, sv);
+					else
+						(target as any)[k as any] = cloneWithOptions(root, sv);
+				}
+
+				return;
+			}
+
+			for (const k of Reflect.ownKeys(target))
+				// eslint-disable-next-line @typescript-eslint/no-dynamic-delete
+				delete (target as any)[k];
+			for (const k of Reflect.ownKeys(source))
+				(target as any)[k] = cloneWithOptions(root, (source as any)[k]);
+		};
+
+		suspendWrites(root);
+		try {
+			overwriteDeep(root as any, snapshot);
+		}
+		finally {
+			resumeWrites(root);
+		}
+
+		markPristine(root);
+		clearRedoCache(root);
+	};
+
+	const diff = (obj: object): DiffRecord[] => {
+		const root = deps.getRoot(obj);
+		const original = originalSnapshotCache.get(root) ?? cloneWithOptions(root, root as any);
+		const out: DiffRecord[] = [];
+		diffValues(original, root, [], out, root);
+
+		return out;
+	};
+
+	const isPristine = (obj: object): boolean => {
+		const diffs = diff(obj);
+
+		return diffs.length === 0;
+	};
+
+	// marks/undo/redo -----------------------------------------------------------
+	const mark = (obj: object): number => {
+		const root = deps.getRoot(obj);
+		const history = historyGet(root);
+
+		return history ? history.length : 0;
+	};
+
+	const undo = (obj: object, steps: number = Number.POSITIVE_INFINITY): void => {
+		const root = deps.getRoot(obj);
+		coreUndo(root, steps);
+	};
+
+	const undoSince = (obj: object, historyLengthBefore: number): void => {
+		const root = deps.getRoot(obj);
+		coreUndoSince(root, historyLengthBefore);
+		clearLastUngrouped(root);
+	};
+
+	const undoGroups = (obj: object, groups: number = 1): void => {
+		const root = deps.getRoot(obj);
+		coreUndoGroups(root, groups);
+		clearLastUngrouped(root);
+	};
+
+	const canUndo = (obj: object): boolean => {
+		const root = deps.getRoot(obj);
+
+		return coreCanUndo(root);
+	};
+
+	const canRedo = (obj: object): boolean => {
+		const root = deps.getRoot(obj);
+
+		return coreCanRedo(root);
+	};
+
+	const clearRedo = (obj: object): void => {
+		const root = deps.getRoot(obj);
+		clearRedoCache(root);
+	};
+
+	const redo = (obj: object, steps: number = Number.POSITIVE_INFINITY): void => {
+		const root = deps.getRoot(obj);
+		coreRedo(root, steps);
+		clearLastUngrouped(root);
+	};
+
+	const redoGroups = (obj: object, groups: number = 1): void => {
+		const root = deps.getRoot(obj);
+		coreRedoGroups(root, groups);
+		clearLastUngrouped(root);
+	};
+
+	return {
+		listen:       listen,
+		onAny:        onAny,
+		pause:        pause,
+		resume:       resume,
+		flush:        flush,
+		getHistory:   getHistory,
+		clearHistory: clearHistory,
+		reset:        reset,
+		markPristine: markPristine,
+		diff:         diff,
+		isPristine:   isPristine,
+		mark:         mark,
+		undo:         undo,
+		undoSince:    undoSince,
+		undoGroups:   undoGroups,
+		canUndo:      canUndo,
+		canRedo:      canRedo,
+		clearRedo:    clearRedo,
+		redo:         redo,
+		redoGroups:   redoGroups,
+	};
+};

package/src/api.ts

@@ -0,0 +1,53 @@
+import type { ProxyFactory } from './proxy-factory.ts';
+import { createProxyFactory } from './proxy-factory.ts';
+import { cloneWithOptions, originalSnapshotCache } from './snapshot-diff.ts';
+
+
+export interface ChronicleCoreDeps {
+	getBatchFrames: (root: object) => { marker: number; id: string; }[] | undefined;
+}
+
+export interface ChronicleCore {
+	chronicle: <T extends object>(object: T) => T;
+	getRoot:   (obj: object) => object;
+}
+
+
+export const createChronicleCore = (deps: ChronicleCoreDeps): ChronicleCore => {
+	const proxyToRoot: WeakMap<object, object> = new WeakMap();
+	let proxyFactory: ProxyFactory | undefined;
+
+	const chronicle = (object => {
+		const existingRoot = proxyToRoot.get(object);
+		if (!proxyFactory) {
+			proxyFactory = createProxyFactory({
+				getBatchFrames: (r) => deps.getBatchFrames(r),
+				setProxyRoot:   (proxy, r) => proxyToRoot.set(proxy, r),
+			});
+		}
+
+		// If called on an already observed proxy, return it to avoid double-proxying
+		if (existingRoot) {
+			if (!originalSnapshotCache.has(existingRoot)) {
+				originalSnapshotCache.set(
+					existingRoot,
+					cloneWithOptions(existingRoot, existingRoot),
+				);
+			}
+
+			return object;
+		}
+
+		const root = (object as object);
+		const { createProxy } = proxyFactory!;
+
+		if (!originalSnapshotCache.has(root))
+			originalSnapshotCache.set(root, cloneWithOptions(root, root));
+
+		return createProxy(root as object, [], root);
+	}) as (<T extends object>(object: T) => T);
+
+	const getRoot = (obj: object): object => proxyToRoot.get(obj) ?? obj;
+
+	return { chronicle: chronicle, getRoot };
+};

package/src/array-mutations.ts

@@ -0,0 +1,64 @@
+import { isArrayIndexKey } from './path.ts';
+import { isSuspended, resumeWrites, suspendWrites } from './undo-redo.ts';
+
+
+/**
+ * Capture array elements that will be removed when shrinking array length.
+ *
+ * @param targetArray - The array being modified
+ * @param oldLen - The current length
+ * @param newLen - The new (smaller) length
+ * @returns Array of {index, value} pairs for elements that will be removed
+ */
+export const captureShrinkRemovals = (
+	targetArray: any[],
+	oldLen: number,
+	newLen: number,
+): { index: number; value: any; }[] => {
+	const removed: { index: number; value: any; }[] = [];
+	for (let i = oldLen - 1; i >= newLen; i--)
+		removed.push({ index: i, value: targetArray[i] });
+
+	return removed;
+};
+
+
+/**
+ * Delete an array element by index using splice to avoid sparse arrays.
+ * Suspends write notifications during the splice to avoid noisy intermediate records.
+ *
+ * @param root - The root object (for suspend/resume context)
+ * @param arrayTarget - The array to modify
+ * @param index - The numeric index to delete
+ * @returns true if deletion succeeded
+ */
+export const deleteIndex = (root: object, arrayTarget: any[], index: number): boolean => {
+	if (isSuspended(root)) {
+		// Already suspended, just splice
+		arrayTarget.splice(index, 1);
+
+		return true;
+	}
+
+	// Suspend writes to avoid intermediate shift/length records
+	suspendWrites(root);
+	try {
+		arrayTarget.splice(index, 1);
+
+		return true;
+	}
+	finally {
+		resumeWrites(root);
+	}
+};
+
+
+/**
+ * Check if a delete operation is for an array index.
+ *
+ * @param target - The target object
+ * @param key - The normalized key
+ * @returns true if this is an array index deletion
+ */
+export const isArrayIndexDeletion = (target: any, key: string): boolean =>
+	Array.isArray(target) && isArrayIndexKey(key);

package/src/batch-transaction.ts

@@ -0,0 +1,183 @@
+import type { ChronicleCore } from './api.ts';
+import { clearLastUngrouped, ensureHistory, historyGet, nextGroupId } from './history.ts';
+import { undoGroups, undoSince } from './undo-redo.ts';
+
+
+const batchStack: WeakMap<object, BatchFrame[]> = new WeakMap();
+
+
+export type BatchDeps = Pick<ChronicleCore, 'chronicle' | 'getRoot'>;
+
+export interface BatchFrame { marker: number; id: string; }
+
+export interface BatchAPI {
+	getBatchFrames: (root: object) => BatchFrame[] | undefined;
+	beginBatch:     (obj: object) => void;
+	commitBatch:    (obj: object) => void;
+	rollbackBatch:  (obj: object) => void;
+	batch:          <T extends object, R>(object: T, action: (observed: T) => R) => R;
+	transaction: <T extends object, R>(object: T, action: (observed: T) => R) =>
+	{ result: R; marker: number; undo: () => void; };
+	transactionAsync: <T extends object, R>(object: T, action: (observed: T) => Promise<R>) =>
+	Promise<{ result: R; marker: number; undo: () => void; }>;
+}
+
+
+export const createBatchTransaction = (deps: BatchDeps): BatchAPI => {
+	const getBatchFrames: BatchAPI['getBatchFrames'] = (root) => batchStack.get(root);
+
+	const beginBatch: BatchAPI['beginBatch'] = (obj) => {
+		const root = deps.getRoot(obj);
+		const history = ensureHistory(root);
+		const frames = batchStack.get(root) ?? [];
+		const id = nextGroupId(root);
+		frames.push({ marker: history.length, id });
+		batchStack.set(root, frames);
+		clearLastUngrouped(root);
+	};
+
+	const commitBatch: BatchAPI['commitBatch'] = (obj) => {
+		const root = deps.getRoot(obj);
+		const frames = batchStack.get(root);
+		if (!frames || frames.length === 0)
+			return;
+
+		frames.pop();
+		if (frames.length === 0)
+			batchStack.delete(root);
+
+		clearLastUngrouped(root);
+	};
+
+	const rollbackBatch: BatchAPI['rollbackBatch'] = (obj) => {
+		const root = deps.getRoot(obj);
+		const frames = batchStack.get(root);
+		if (!frames || frames.length === 0)
+			return;
+
+		const frame = frames.pop()!;
+		undoSince(root, frame.marker);
+		if (frames.length === 0)
+			batchStack.delete(root);
+
+		clearLastUngrouped(root);
+	};
+
+	const batch: BatchAPI['batch'] = (object, action) => {
+		const root = deps.getRoot(object as unknown as object);
+		beginBatch(root);
+		const observed = deps.chronicle(object);
+		try {
+			const result = action(observed);
+			commitBatch(root);
+
+			return result;
+		}
+		catch (err) {
+			rollbackBatch(root);
+			throw err;
+		}
+	};
+
+	const transaction: BatchAPI['transaction'] = (object, action) => {
+		const root = deps.getRoot(object as unknown as object);
+		const marker = (historyGet(root) ?? []).length;
+
+		const framesBefore = (batchStack.get(root) ?? []).length;
+		const isTopLevel = framesBefore === 0;
+		if (isTopLevel)
+			beginBatch(root);
+
+		const observed = deps.chronicle(object);
+		let groupId: string | undefined;
+		try {
+			const result = action(observed);
+			const frames = (batchStack.get(root) ?? []);
+			groupId = frames.length > 0 ? frames[frames.length - 1]!.id : undefined;
+			if (isTopLevel)
+				commitBatch(root);
+
+			return {
+				result,
+				marker,
+				undo: () => {
+					const h = historyGet(root);
+					if (groupId && h && h.length > 0) {
+						const topGroup = h[h.length - 1]!.groupId ?? `__g#${ h.length - 1 }`;
+						if (topGroup === groupId) {
+							undoGroups(root, 1);
+
+							return;
+						}
+					}
+
+					undoSince(root, marker);
+				},
+			};
+		}
+		catch (err) {
+			if (isTopLevel)
+				rollbackBatch(root);
+			else
+				undoSince(root, marker);
+
+			throw err;
+		}
+	};
+
+	const transactionAsync: BatchAPI['transactionAsync'] = async (object, action) => {
+		const root = deps.getRoot(object as unknown as object);
+		const marker = (historyGet(root) ?? []).length;
+
+		const framesBefore = (batchStack.get(root) ?? []).length;
+		const isTopLevel = framesBefore === 0;
+		if (isTopLevel)
+			beginBatch(root);
+
+		const observed = deps.chronicle(object);
+		let groupId: string | undefined;
+		try {
+			const result = await action(observed);
+			const frames = (batchStack.get(root) ?? []);
+			groupId = frames.length > 0 ? frames[frames.length - 1]!.id : undefined;
+			if (isTopLevel)
+				commitBatch(root);
+
+			return {
+				result,
+				marker,
+				undo: () => {
+					const h = historyGet(root);
+					if (groupId && h && h.length > 0) {
+						const topGroup = h[h.length - 1]!.groupId ?? `__g#${ h.length - 1 }`;
+						if (topGroup === groupId) {
+							undoGroups(root, 1);
+
+							return;
+						}
+					}
+
+					undoSince(root, marker);
+				},
+			};
+		}
+		catch (err) {
+			if (isTopLevel)
+				rollbackBatch(root);
+			else
+				undoSince(root, marker);
+
+			throw err;
+		}
+	};
+
+	return {
+		getBatchFrames,
+		beginBatch,
+		commitBatch,
+		rollbackBatch,
+		batch,
+		transaction,
+		transactionAsync,
+	};
+};

package/src/chronicle.ts

@@ -0,0 +1,100 @@
+import { createChronicleCore } from './api.ts';
+import { createApiMethods } from './api-methods.ts';
+import { createBatchTransaction } from './batch-transaction.ts';
+import { type ConfigureOptions, configureRoot } from './config.ts';
+import type { ChangeListener, ChangeRecord, DiffRecord, ListenerOptions, PathMode, PathSelector } from './types.ts';
+
+
+interface Chronicle {
+	<T extends object>(object: T): T;
+
+	listen<T extends object>(
+		object: T,
+		selector: PathSelector<T>,
+		listener: ChangeListener,
+		modeOrOptions?: PathMode | ListenerOptions,
+		maybeOptions?: ListenerOptions
+	): () => void;
+	onAny(obj: object, listener: ChangeListener, options?: ListenerOptions): () => void;
+	pause(obj: object): void;
+	resume(obj: object): void;
+	flush(obj: object): void;
+	getHistory(obj: object): ChangeRecord[];
+	clearHistory(obj: object): void;
+	reset(obj: object): void;
+	markPristine(obj: object): void;
+	undo(obj: object, steps?: number): void;
+	undoSince(obj: object, historyLengthBefore: number): void;
+	diff(obj: object): DiffRecord[];
+	isPristine(obj: object): boolean;
+	mark(obj: object): number;
+	transaction<T extends object, R>(object: T, action: (observed: T) => R): TransactionResult<R>;
+	transactionAsync<T extends object, R>(object: T, action: (observed: T) => Promise<R>): Promise<TransactionResult<R>>;
+	beginBatch(obj: object): void;
+	commitBatch(obj: object): void;
+	rollbackBatch(obj: object): void;
+	batch<T extends object, R>(object: T, action: (observed: T) => R): R;
+	undoGroups(obj: object, groups?: number): void;
+	canUndo(obj: object): boolean;
+	canRedo(obj: object): boolean;
+	clearRedo(obj: object): void;
+	redo(obj: object, steps?: number): void;
+	redoGroups(obj: object, groups?: number): void;
+	configure(
+		obj: object,
+		options: ConfigureOptions,
+	): void;
+}
+
+interface TransactionResult<R> {
+	result: R;
+	marker: number;
+	undo:   () => void;
+}
+
+const core = createChronicleCore({ getBatchFrames: r => batchApi.getBatchFrames(r) });
+const chronicle = core.chronicle as Chronicle;
+
+const batchApi = createBatchTransaction(core);
+const api = createApiMethods({ getRoot: core.getRoot });
+
+chronicle.listen       = api.listen;
+chronicle.onAny        = api.onAny;
+chronicle.pause        = api.pause;
+chronicle.resume       = api.resume;
+chronicle.flush        = api.flush;
+chronicle.getHistory   = api.getHistory;
+chronicle.clearHistory = api.clearHistory;
+chronicle.reset        = api.reset;
+chronicle.markPristine = api.markPristine;
+chronicle.undo         = api.undo;
+chronicle.undoSince    = api.undoSince;
+chronicle.diff         = api.diff;
+chronicle.isPristine   = api.isPristine;
+chronicle.mark         = api.mark;
+chronicle.undoGroups   = api.undoGroups;
+chronicle.canUndo      = api.canUndo;
+chronicle.canRedo      = api.canRedo;
+chronicle.clearRedo    = api.clearRedo;
+chronicle.redo         = api.redo;
+chronicle.redoGroups   = api.redoGroups;
+
+
+chronicle.transaction = <T extends object, R>(object: T, action: (observed: T) => R) =>
+	batchApi.transaction(object, action);
+chronicle.transactionAsync = async <T extends object, R>(object: T, action: (observed: T) => Promise<R>) =>
+	batchApi.transactionAsync(object, action);
+chronicle.beginBatch = (obj) => batchApi.beginBatch(core.getRoot(obj));
+chronicle.commitBatch = (obj) => batchApi.commitBatch(core.getRoot(obj));
+chronicle.rollbackBatch = (obj) => batchApi.rollbackBatch(core.getRoot(obj));
+chronicle.batch = <T extends object, R>(object: T, action: (observed: T) => R) =>
+	batchApi.batch(object, action);
+
+
+chronicle.configure = (obj: object, options: ConfigureOptions) => {
+	const root = core.getRoot(obj);
+	configureRoot(root, options);
+};
+
+export { chronicle };
+export type { Chronicle };