@arcmantle/chronicle 1.0.2 → 1.0.4

package/src/api-methods.ts

@@ -1,10 +1,12 @@
+import { type ConfigureOptions, configureRoot } from './config.ts';
 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 { threeWayMerge } from './three-way-merge.ts';
+import type { ChangeListener, ChangeRecord, ConflictResolutions, DiffRecord, ListenerOptions, MergeResult, 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';
 
 
@@ -17,13 +19,13 @@ const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'obj
 
 
 export interface ChronicleApiMethods {
-	listen: <T extends object>(
-		object: T,
-		selector: PathSelector<T>,
-		listener: ChangeListener,
-		modeOrOptions?: PathMode | ListenerOptions,
-		maybeOptions?: ListenerOptions,
-	) => () => void;
+	listen<T extends object>(object: T, selector: PathSelector<T>, listener: ChangeListener): () => void;
+	// eslint-disable-next-line @typescript-eslint/unified-signatures
+	listen<T extends object>(object: T, selector: PathSelector<T>, listener: ChangeListener, options: ListenerOptions): () => void;
+	// eslint-disable-next-line @typescript-eslint/unified-signatures
+	listen<T extends object>(object: T, selector: PathSelector<T>, listener: ChangeListener, mode: PathMode): () => void;
+	// eslint-disable-next-line @stylistic/max-len, @typescript-eslint/unified-signatures
+	listen<T extends object>(object: T, selector: PathSelector<T>, listener: ChangeListener, mode: PathMode, options: ListenerOptions): () => void;
 	onAny:        (obj: object, listener: ChangeListener, options?: ListenerOptions) => () => void;
 	pause:        (obj: object) => void;
 	resume:       (obj: object) => void;
@@ -34,6 +36,9 @@ export interface ChronicleApiMethods {
 	markPristine: (obj: object) => void;
 	diff:         (obj: object) => DiffRecord[];
 	isPristine:   (obj: object) => boolean;
+	snapshot:     <T extends object>(obj: T) => T;
+	unwrap:       <T extends object>(obj: T) => T;
+	merge:        (obj: object, incomingObject: object, resolutions?: ConflictResolutions) => MergeResult;
 	mark:         (obj: object) => number;
 	undo:         (obj: object, steps?: number) => void;
 	undoSince:    (obj: object, historyLengthBefore: number) => void;
@@ -43,19 +48,20 @@ export interface ChronicleApiMethods {
 	clearRedo:    (obj: object) => void;
 	redo:         (obj: object, steps?: number) => void;
 	redoGroups:   (obj: object, groups?: number) => void;
+	configure:    (obj: object, options: ConfigureOptions) => void;
 }
 
 export const createApiMethods = (deps: ApiDeps): ChronicleApiMethods => {
 	// listen/onAny --------------------------------------------------------------
-	const listen = <T extends object>(
-		object: T,
-		selector: PathSelector<T>,
-		listener: ChangeListener,
+	const listen: ChronicleApiMethods['listen'] = (
+		object,
+		selector,
+		listener,
 		modeOrOptions?: PathMode | ListenerOptions,
 		maybeOptions?: ListenerOptions,
 	) => {
 		const segs = nameofSegments(selector);
-		const root = deps.getRoot(object as object);
+		const root = deps.getRoot(object);
 		const bucket = ensureListenerBucket(root);
 
 		let mode: PathMode = 'down';
@@ -96,34 +102,34 @@ export const createApiMethods = (deps: ApiDeps): ChronicleApiMethods => {
 		return unsubscribe;
 	};
 
-	const onAny = (obj: object, listener: ChangeListener, options?: ListenerOptions): () => void => {
-		return listen(obj as any, s => s as any, listener, options);
+	const onAny: ChronicleApiMethods['onAny'] = (obj, listener, options) => {
+		return listen(obj, s => s, listener, options!);
 	};
 
 	// pause/resume/flush --------------------------------------------------------
-	const pause = (obj: object): void => {
+	const pause: ChronicleApiMethods['pause'] = (obj) => {
 		const root = deps.getRoot(obj);
 		schedulePause(root);
 	};
 
-	const resume = (obj: object): void => {
+	const resume: ChronicleApiMethods['resume'] = (obj) => {
 		const root = deps.getRoot(obj);
 		scheduleResume(root);
 	};
 
-	const flush = (obj: object): void => {
+	const flush: ChronicleApiMethods['flush'] = (obj) => {
 		const root = deps.getRoot(obj);
 		scheduleFlush(root);
 	};
 
 	// history ------------------------------------------------------------------
-	const getHistory = (obj: object): ChangeRecord[] => {
+	const getHistory: ChronicleApiMethods['getHistory'] = (obj) => {
 		const root = deps.getRoot(obj);
 
 		return (historyGet(root) ?? []).slice();
 	};
 
-	const clearHistory = (obj: object): void => {
+	const clearHistory: ChronicleApiMethods['clearHistory'] = (obj) => {
 		const root = deps.getRoot(obj);
 		historyDelete(root);
 		clearLastUngrouped(root);
@@ -131,7 +137,7 @@ export const createApiMethods = (deps: ApiDeps): ChronicleApiMethods => {
 	};
 
 	// reset/markPristine/diff/pristine ----------------------------------------
-	const markPristine = (obj: object): void => {
+	const markPristine: ChronicleApiMethods['markPristine'] = (obj) => {
 		const root = deps.getRoot(obj);
 		originalSnapshotCache.set(root, cloneWithOptions(root, root));
 		historyDelete(root);
@@ -140,7 +146,7 @@ export const createApiMethods = (deps: ApiDeps): ChronicleApiMethods => {
 		pfClearProxyCache(root);
 	};
 
-	const reset = (obj: object): void => {
+	const reset: ChronicleApiMethods['reset'] = (obj) => {
 		const root = deps.getRoot(obj);
 		const snapshot = originalSnapshotCache.get(root);
 		if (!snapshot) {
@@ -198,7 +204,7 @@ export const createApiMethods = (deps: ApiDeps): ChronicleApiMethods => {
 		clearRedoCache(root);
 	};
 
-	const diff = (obj: object): DiffRecord[] => {
+	const diff: ChronicleApiMethods['diff'] = (obj) => {
 		const root = deps.getRoot(obj);
 		const original = originalSnapshotCache.get(root) ?? cloneWithOptions(root, root as any);
 		const out: DiffRecord[] = [];
@@ -207,86 +213,113 @@ export const createApiMethods = (deps: ApiDeps): ChronicleApiMethods => {
 		return out;
 	};
 
-	const isPristine = (obj: object): boolean => {
+	const isPristine: ChronicleApiMethods['isPristine'] = (obj) => {
 		const diffs = diff(obj);
 
 		return diffs.length === 0;
 	};
 
+	const snapshot: ChronicleApiMethods['snapshot'] = (obj) => {
+		const root = deps.getRoot(obj);
+
+		return cloneWithOptions(root, root) as any;
+	};
+
+	const unwrap: ChronicleApiMethods['unwrap'] = (obj) => {
+		const root = deps.getRoot(obj);
+
+		return root as any;
+	};
+
+	const merge: ChronicleApiMethods['merge'] = (obj, incomingObject, resolutions?) => {
+		const root = deps.getRoot(obj);
+
+		return threeWayMerge(root, obj, incomingObject, resolutions);
+	};
+
 	// marks/undo/redo -----------------------------------------------------------
-	const mark = (obj: object): number => {
+	const mark: ChronicleApiMethods['mark'] = (obj) => {
 		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 undo: ChronicleApiMethods['undo'] = (obj, steps = Number.POSITIVE_INFINITY) => {
 		const root = deps.getRoot(obj);
 		coreUndo(root, steps);
 	};
 
-	const undoSince = (obj: object, historyLengthBefore: number): void => {
+	const undoSince: ChronicleApiMethods['undoSince'] = (obj, historyLengthBefore) => {
 		const root = deps.getRoot(obj);
 		coreUndoSince(root, historyLengthBefore);
 		clearLastUngrouped(root);
 	};
 
-	const undoGroups = (obj: object, groups: number = 1): void => {
+	const undoGroups: ChronicleApiMethods['undoGroups'] = (obj, groups = 1) => {
 		const root = deps.getRoot(obj);
 		coreUndoGroups(root, groups);
 		clearLastUngrouped(root);
 	};
 
-	const canUndo = (obj: object): boolean => {
+	const canUndo: ChronicleApiMethods['canUndo'] = (obj) => {
 		const root = deps.getRoot(obj);
 
 		return coreCanUndo(root);
 	};
 
-	const canRedo = (obj: object): boolean => {
+	const canRedo: ChronicleApiMethods['canRedo'] = (obj) => {
 		const root = deps.getRoot(obj);
 
 		return coreCanRedo(root);
 	};
 
-	const clearRedo = (obj: object): void => {
+	const clearRedo: ChronicleApiMethods['clearRedo'] = (obj) => {
 		const root = deps.getRoot(obj);
 		clearRedoCache(root);
 	};
 
-	const redo = (obj: object, steps: number = Number.POSITIVE_INFINITY): void => {
+	const redo: ChronicleApiMethods['redo'] = (obj, steps = Number.POSITIVE_INFINITY) => {
 		const root = deps.getRoot(obj);
 		coreRedo(root, steps);
 		clearLastUngrouped(root);
 	};
 
-	const redoGroups = (obj: object, groups: number = 1): void => {
+	const redoGroups: ChronicleApiMethods['redoGroups'] = (obj, groups = 1) => {
 		const root = deps.getRoot(obj);
 		coreRedoGroups(root, groups);
 		clearLastUngrouped(root);
 	};
 
+	const configure: ChronicleApiMethods['configure'] = (obj, options) => {
+		const root = deps.getRoot(obj);
+		configureRoot(root, options);
+	};
+
 	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,
+		listen,
+		onAny,
+		pause,
+		resume,
+		flush,
+		getHistory,
+		clearHistory,
+		reset,
+		markPristine,
+		diff,
+		isPristine,
+		snapshot,
+		unwrap,
+		merge,
+		mark,
+		undo,
+		undoSince,
+		undoGroups,
+		canUndo,
+		canRedo,
+		clearRedo,
+		redo,
+		redoGroups,
+		configure,
 	};
 };

package/src/batch-transaction.ts

@@ -8,6 +8,8 @@ const batchStack: WeakMap<object, BatchFrame[]> = new WeakMap();
 
 export type BatchDeps = Pick<ChronicleCore, 'chronicle' | 'getRoot'>;
 
+export interface TransactionResult<R> { result: R; marker: number; undo: () => void; }
+
 export interface BatchFrame { marker: number; id: string; }
 
 export interface BatchAPI {
@@ -16,10 +18,11 @@ export interface BatchAPI {
 	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; }>;
+	transaction<T extends object, R>(
+		object: T, action: (observed: T) => R,
+	): R extends Promise<infer U>
+		? Promise<TransactionResult<U>>
+		: TransactionResult<R>;
 }
 
 
@@ -80,7 +83,7 @@ export const createBatchTransaction = (deps: BatchDeps): BatchAPI => {
 	};
 
 	const transaction: BatchAPI['transaction'] = (object, action) => {
-		const root = deps.getRoot(object as unknown as object);
+		const root = deps.getRoot(object);
 		const marker = (historyGet(root) ?? []).length;
 
 		const framesBefore = (batchStack.get(root) ?? []).length;
@@ -90,63 +93,62 @@ export const createBatchTransaction = (deps: BatchDeps): BatchAPI => {
 
 		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 actionResult = action(observed);
+			const isObject = typeof actionResult === 'object' && actionResult !== null;
+			const isPromise = isObject && 'then' in actionResult && typeof actionResult.then === 'function';
+
+			// Check if result is a Promise
+			if (isPromise) {
+				const typedActionResult = actionResult as any as Promise<ReturnType<typeof action>>;
+
+				return typedActionResult.then(
+					resolvedResult => {
+						const frames = (batchStack.get(root) ?? []);
+						groupId = frames.length > 0 ? frames[frames.length - 1]!.id : undefined;
+						if (isTopLevel)
+							commitBatch(root);
+
+						return {
+							result: resolvedResult,
+							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);
+							},
+						} satisfies TransactionResult<typeof resolvedResult> as any;
+					},
+					err => {
+						if (isTopLevel)
+							rollbackBatch(root);
+						else
+							undoSince(root, marker);
+
+						throw err;
+					},
+				);
+			}
+
+			// Synchronous result
 			const frames = (batchStack.get(root) ?? []);
 			groupId = frames.length > 0 ? frames[frames.length - 1]!.id : undefined;
 			if (isTopLevel)
 				commitBatch(root);
 
 			return {
-				result,
+				result: actionResult,
 				marker,
-				undo: () => {
+				undo:   () => {
 					const h = historyGet(root);
 					if (groupId && h && h.length > 0) {
 						const topGroup = h[h.length - 1]!.groupId ?? `__g#${ h.length - 1 }`;
@@ -159,7 +161,7 @@ export const createBatchTransaction = (deps: BatchDeps): BatchAPI => {
 
 					undoSince(root, marker);
 				},
-			};
+			} satisfies TransactionResult<typeof actionResult> as any;
 		}
 		catch (err) {
 			if (isTopLevel)
@@ -178,6 +180,5 @@ export const createBatchTransaction = (deps: BatchDeps): BatchAPI => {
 		rollbackBatch,
 		batch,
 		transaction,
-		transactionAsync,
 	};
 };

package/src/chronicle.ts

@@ -1,55 +1,10 @@
 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';
+import { type ChronicleApiMethods, createApiMethods } from './api-methods.ts';
+import { type BatchAPI, createBatchTransaction } from './batch-transaction.ts';
 
 
-interface Chronicle {
+interface Chronicle extends Omit<BatchAPI, 'getBatchFrames'>, ChronicleApiMethods {
 	<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) });
@@ -58,43 +13,35 @@ 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.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.snapshot      = api.snapshot;
+chronicle.unwrap        = api.unwrap;
+chronicle.merge         = api.merge;
+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.configure     = api.configure;
+chronicle.transaction   = batchApi.transaction;
+chronicle.batch         = batchApi.batch;
+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 };

package/src/history-recorder.ts

@@ -1,4 +1,5 @@
 import { ensureHistory, getOptions, trimHistoryByGroups } from './history.ts';
+import { cloneWithOptions } from './snapshot-diff.ts';
 import type { ChangeRecord } from './types.ts';
 import { clearRedoCache, isSuspended } from './undo-redo.ts';
 
@@ -34,8 +35,8 @@ export const recordSet = (
 	const rec: ChangeRecord = {
 		path:      path.slice(),
 		type:      'set',
-		oldValue,
-		newValue,
+		oldValue:  cloneWithOptions(root, oldValue),
+		newValue:  cloneWithOptions(root, newValue),
 		timestamp: Date.now(),
 		existedBefore,
 		groupId,
@@ -92,7 +93,7 @@ export const recordDelete = (
 	const rec: ChangeRecord = {
 		path:      path.slice(),
 		type:      'delete',
-		oldValue,
+		oldValue:  cloneWithOptions(root, oldValue),
 		newValue:  undefined,
 		timestamp: Date.now(),
 		groupId,
@@ -133,7 +134,7 @@ export const recordArrayShrinkDeletes = (
 		const rec: ChangeRecord = {
 			path:      [ ...basePath, String(index) ],
 			type:      'delete',
-			oldValue:  oldVal,
+			oldValue:  cloneWithOptions(root, oldVal),
 			newValue:  undefined,
 			timestamp: Date.now(),
 			groupId,