@arcmantle/chronicle 0.0.4

package/src/nameof.ts

@@ -0,0 +1,42 @@
+import { normalizePropertyKey } from './symbol-id.ts';
+
+
+// nameof property path is stored here for retrieval.
+const propertyThatWasAccessed: string[] = [];
+
+
+// Proxy objects to store the property path.
+const proxy: any = new Proxy({} as any, {
+	get: <const C extends PropertyKey>(_: any, prop: C) => {
+		// Normalize to stable id so bracket keys with dots and Symbols become stable segments
+		propertyThatWasAccessed.push(normalizePropertyKey(prop));
+
+		return proxy;
+	},
+});
+
+
+export type Nameof<T> = (m: T extends object ? T : any) => any;
+
+
+/**
+ * Returns either the last part of a objects path  \
+ * or dotted path if the fullPath flag is set to true.
+ */
+export const nameof = <const T>(expression: (instance: T) => any): string => {
+	propertyThatWasAccessed.length = 0;
+	expression(proxy);
+
+	return propertyThatWasAccessed.join('.');
+};
+
+/**
+ * Returns a fresh array of path segments captured from the selector expression.
+ * The returned array is a new copy to avoid external mutations affecting internals.
+ */
+export const nameofSegments = <const T>(expression: (instance: T) => any): string[] => {
+	propertyThatWasAccessed.length = 0;
+	expression(proxy);
+
+	return propertyThatWasAccessed.slice();
+};

package/src/path-key.ts

@@ -0,0 +1,10 @@
+/**
+ * Generate a cache key from path segments.
+ *
+ * Uses ASCII Unit Separator (0x1F) as delimiter, which cannot appear in normal
+ * string keys, ensuring unambiguous path separation.
+ *
+ * @param segments - Path segments
+ * @returns Cache key string
+ */
+export const pathKeyOf = (segments: string[]): string => segments.join('\x1f');

package/src/path.ts

@@ -0,0 +1,69 @@
+import { normalizePropertyKey } from './symbol-id.ts';
+
+
+// Normalize property key to a stable string segment (symbols -> sym#id)
+export const normalizeKey = (prop: PropertyKey): string => normalizePropertyKey(prop);
+
+export const isArrayIndexKey = (k: string): boolean => /^(?:0|[1-9]\d*)$/.test(k);
+
+export const getParentAndKey = (root: any, path: string[]): [ any, string ] | null => {
+	if (path.length === 0)
+		return null;
+
+	let parent: any = root;
+	for (const seg of path.slice(0, -1)) {
+		if (parent == null)
+			return null;
+
+		parent = (parent as any)[seg as any];
+	}
+
+	const last = path[path.length - 1]!;
+
+	return [ parent, last ];
+};
+
+export const setAtPath = (root: any, path: string[], value: any): void => {
+	const res = getParentAndKey(root, path);
+	if (!res)
+		return;
+
+	const [ parent, key ] = res;
+	Reflect.set(parent, key, value);
+};
+
+export const deleteAtPath = (root: any, path: string[]): void => {
+	const res = getParentAndKey(root, path);
+	if (!res)
+		return;
+
+	const [ parent, key ] = res;
+	if (parent == null)
+		return;
+
+	// If deleting from an array, prefer splice to avoid holes and adjust length
+	if (Array.isArray(parent) && isArrayIndexKey(String(key))) {
+		const idx = Number(key);
+		if (Number.isInteger(idx))
+			parent.splice(idx, 1);
+
+		return;
+	}
+
+	Reflect.deleteProperty(parent, key as any);
+};
+
+export const ensureParents = (root: any, path: string[]): void => {
+	let node: any = root;
+	for (let i = 0; i < path.length - 1; i++) {
+		const seg = path[i]!;
+		let next = (node as any)[seg as any];
+		if (next == null) {
+			const following = path[i + 1]!;
+			next = /^(?:0|[1-9]\d*)$/.test(following) ? [] : {};
+			(node as any)[seg as any] = next;
+		}
+
+		node = next;
+	}
+};

package/src/proxy-cache.ts

@@ -0,0 +1,86 @@
+import { getOptions } from './history.ts';
+import { pathKeyOf } from './path-key.ts';
+
+
+/**
+ * Per-root proxy cache: Map<pathKey, proxy>
+ * Enables stable proxy identity when cacheProxies option is enabled.
+ */
+const proxyCache: WeakMap<object, Map<string, any>> = new WeakMap();
+
+
+/**
+ * Get a cached proxy for the given root and path.
+ *
+ * @param root - The root object
+ * @param pathKey - The path key (from pathKeyOf)
+ * @returns The cached proxy, or undefined if not cached
+ */
+export const getCached = (root: object, pathKey: string): any | undefined => {
+	const perRoot = proxyCache.get(root);
+
+	return perRoot?.get(pathKey);
+};
+
+
+/**
+ * Store a proxy in the cache for the given root and path.
+ *
+ * @param root - The root object
+ * @param pathKey - The path key (from pathKeyOf)
+ * @param proxy - The proxy to cache
+ */
+export const setCached = (root: object, pathKey: string, proxy: any): void => {
+	let perRoot = proxyCache.get(root);
+	if (!perRoot) {
+		perRoot = new Map<string, any>();
+		proxyCache.set(root, perRoot);
+	}
+
+	perRoot.set(pathKey, proxy);
+};
+
+
+/**
+ * Invalidate cached proxies at and below the given base path.
+ * Optionally also invalidates the parent path (for array shrinkage).
+ *
+ * @param root - The root object
+ * @param basePath - The base path to invalidate
+ * @param alsoParentArray - Whether to also invalidate the parent path
+ */
+export const invalidateAt = (root: object, basePath: string[], alsoParentArray?: boolean): void => {
+	const opts = getOptions(root);
+	if (!opts.cacheProxies)
+		return;
+
+	const perRoot = proxyCache.get(root);
+	if (!perRoot)
+		return;
+
+	const base = pathKeyOf(basePath);
+	for (const k of Array.from(perRoot.keys())) {
+		if (k === base || k.startsWith(base + '\x1f'))
+			perRoot.delete(k);
+	}
+
+	if (alsoParentArray) {
+		const parentKey = pathKeyOf(basePath.slice(0, -1));
+		for (const k of Array.from(perRoot.keys())) {
+			if (k === parentKey || k.startsWith(parentKey + '\x1f'))
+				perRoot.delete(k);
+		}
+	}
+};
+
+
+/**
+ * Clear all cached proxies for the given root.
+ *
+ * @param root - The root object
+ */
+export const clear = (root: object): void => {
+	const perRoot = proxyCache.get(root);
+	if (perRoot)
+		perRoot.clear();
+};

package/src/proxy-factory.ts

@@ -0,0 +1,168 @@
+import { captureShrinkRemovals, deleteIndex, isArrayIndexDeletion } from './array-mutations.ts';
+import { adaptMapMethod, adaptSetMethod } from './collection-adapters.ts';
+import { computeActiveGroupId } from './grouping.ts';
+import { getOptions } from './history.ts';
+import { recordArrayShrinkDeletes, recordDelete, recordSet } from './history-recorder.ts';
+import { computeAffectedListeners } from './listener-affinity.ts';
+import { getListenerBucket } from './listener-trie.ts';
+import { normalizeKey } from './path.ts';
+import { pathKeyOf } from './path-key.ts';
+import { clear as clearProxyCacheInternal, getCached, invalidateAt, setCached } from './proxy-cache.ts';
+import { notifyListeners } from './schedule-queue.ts';
+import type { ChangeMeta } from './types.ts';
+
+
+export interface ProxyFactoryDeps {
+	getBatchFrames: (root: object) => { marker: number; id: string; }[] | undefined;
+	setProxyRoot:   (proxy: object, root: object) => void;
+}
+
+export interface ProxyFactory {
+	createProxy:       <O extends object>(targetObject: O, path: string[] | undefined, rootObject: object) => O;
+	invalidateCacheAt: (root: object, basePath: string[], alsoParentArray?: boolean) => void;
+	clearProxyCache:   (root: object) => void;
+}
+
+
+export const invalidateCacheAt: typeof invalidateAt = invalidateAt;
+export const clearProxyCache: typeof clearProxyCacheInternal = clearProxyCacheInternal;
+
+
+export const createProxyFactory = (deps: ProxyFactoryDeps): ProxyFactory => {
+	const createProxy: ProxyFactory['createProxy'] = (targetObject, path = [], rootObject) => {
+		const opts = getOptions(rootObject);
+		if (opts.cacheProxies) {
+			const pathKey = pathKeyOf(path);
+			const cached = getCached(rootObject, pathKey);
+			if (cached)
+				return cached;
+		}
+
+		const proxy = new Proxy(targetObject, {
+			get(target, prop) {
+				const result = Reflect.get(target, prop);
+
+				// Map/Set adapters: wrap mutating methods and bind non-mutators to raw target for brand checks
+				const isMap = target instanceof Map;
+				const isSet = target instanceof Set;
+				if ((isMap || isSet) && typeof result === 'function') {
+					const method = String(prop);
+					const currentPath = path.slice(); // collection lives at this path
+
+					if (isMap) {
+						const adapted = adaptMapMethod(target as Map<any, any>, currentPath, rootObject, deps, method);
+						if (adapted)
+							return adapted;
+					}
+
+					if (isSet) {
+						const adapted = adaptSetMethod(target as Set<any>, currentPath, rootObject, deps, method);
+						if (adapted)
+							return adapted;
+					}
+
+					// For other methods, bind to raw target to satisfy brand checks
+					return (result as (...args: any[]) => any).bind(target);
+				}
+				if (!result || typeof result !== 'object')
+					return result;
+
+				const currentPath = [ ...path, normalizeKey(prop) ];
+
+				return createProxy(result, currentPath, rootObject);
+			},
+			set(target, prop, value) {
+				const currentPath = [ ...path, normalizeKey(prop) ];
+				const hadBefore = Reflect.has(target, prop);
+				const oldValue = Reflect.get(target, prop);
+
+				// Capture elements that will be removed if shrinking array length
+				let removedForLengthShrink: { index: number; value: any; }[] | null = null;
+				if (
+					Array.isArray(target)
+					&& normalizeKey(prop) === 'length'
+					&& typeof oldValue === 'number'
+					&& typeof value === 'number'
+					&& value < oldValue
+				)
+					removedForLengthShrink = captureShrinkRemovals(target, oldValue, value);
+
+
+				const result = Reflect.set(target, prop, value);
+				const bucket = getListenerBucket(rootObject);
+				const activeGroupId = computeActiveGroupId(rootObject, deps.getBatchFrames);
+
+				// Record change in history
+				recordSet(rootObject, currentPath, oldValue, value, hadBefore, activeGroupId);
+
+				// If we shrank array length, synthesize delete records for removed indices
+				if (removedForLengthShrink && removedForLengthShrink.length > 0)
+					recordArrayShrinkDeletes(rootObject, path, removedForLengthShrink, activeGroupId);
+
+				// Invalidate proxy cache for this path; if shrinking array length, also invalidate the array base
+				const shrinkingArray = Array.isArray(target)
+					&& normalizeKey(prop) === 'length'
+					&& typeof oldValue === 'number'
+					&& typeof value === 'number'
+					&& value < oldValue;
+
+				invalidateAt(rootObject, currentPath, shrinkingArray);
+
+				if (bucket) {
+					const affectedListeners = computeAffectedListeners(rootObject, currentPath);
+					const meta: ChangeMeta = { type: 'set', existedBefore: hadBefore, groupId: activeGroupId };
+					notifyListeners(rootObject, affectedListeners, [ currentPath, value, oldValue, meta ]);
+				}
+
+				return result;
+			},
+			deleteProperty(target, prop) {
+				const key = normalizeKey(prop);
+				const currentPath = [ ...path, key ];
+				const oldValue = Reflect.get(target, prop);
+				const hadBefore = Reflect.has(target, prop);
+				let result: boolean;
+
+				// If deleting from an array by numeric index, use splice to avoid holes (parity with undo behavior)
+				if (isArrayIndexDeletion(target, key)) {
+					const idx = Number(key);
+					result = deleteIndex(rootObject, target as any[], idx);
+				}
+				else {
+					result = Reflect.deleteProperty(target, prop);
+				}
+
+				const bucket = getListenerBucket(rootObject);
+				const activeGroupId = computeActiveGroupId(rootObject, deps.getBatchFrames);
+
+				// Record change in history
+				recordDelete(rootObject, currentPath, oldValue, activeGroupId);
+
+				// Invalidate proxy cache for this path and, for array index splice case, also for the array base
+				const isArrayIndex = isArrayIndexDeletion(target, key);
+				invalidateAt(rootObject, currentPath, isArrayIndex);
+
+				// Notify listeners (deletes affect exact path only and descendants no longer exist)
+				if (bucket) {
+					const affectedListeners = computeAffectedListeners(rootObject, currentPath);
+					const meta: ChangeMeta = { type: 'delete', existedBefore: hadBefore, groupId: activeGroupId };
+					notifyListeners(rootObject, affectedListeners, [ currentPath, undefined, oldValue, meta ]);
+				}
+
+				return result;
+			},
+		});
+
+		deps.setProxyRoot(proxy, rootObject);
+
+		// Store in cache if enabled
+		if (opts.cacheProxies) {
+			const pathKey = pathKeyOf(path);
+			setCached(rootObject, pathKey, proxy);
+		}
+
+		return proxy;
+	};
+
+	return { createProxy, invalidateCacheAt, clearProxyCache };
+};

package/src/schedule-queue.ts

@@ -0,0 +1,144 @@
+import type { ChangeListener, ChangeMeta, ListenerOptions, QueuedCall } from './types.ts';
+
+// Per-root pause state and queued notifications
+const pauseState: WeakMap<object, { paused: boolean; queue: QueuedCall[]; }> = new WeakMap();
+
+const isPaused = (root: object): boolean => (pauseState.get(root)?.paused === true);
+
+const enqueue = (root: object, call: QueuedCall) => {
+	let st = pauseState.get(root);
+	if (!st) {
+		st = { paused: true, queue: [] };
+		pauseState.set(root, st);
+	}
+
+	st.queue.push(call);
+};
+
+export const notifyListeners = (
+	root: object,
+	listeners: Set<ChangeListener>,
+	args: [ string[], any, any, ChangeMeta | undefined ],
+): void => {
+	if (listeners.size === 0)
+		return;
+
+	if (isPaused(root)) {
+		listeners.forEach(listener => enqueue(root, { listener, args }));
+
+		return;
+	}
+
+	listeners.forEach(listener => listener(...args));
+};
+
+export const pause = (obj: object): void => {
+	const st = pauseState.get(obj);
+	if (st)
+		st.paused = true;
+	else
+		pauseState.set(obj, { paused: true, queue: [] });
+};
+
+export const resume = (obj: object): void => {
+	const st = pauseState.get(obj);
+	if (!st)
+		return;
+
+	// Deliver queued notifications in FIFO order
+	const q = st.queue.splice(0, st.queue.length);
+	st.paused = false;
+	for (const { listener, args } of q)
+		listener(...args);
+};
+
+export const flush = (obj: object): void => {
+	const st = pauseState.get(obj);
+	if (!st || st.queue.length === 0)
+		return;
+
+	const q = st.queue.splice(0, st.queue.length);
+	for (const { listener, args } of q)
+		listener(...args);
+};
+
+// Wrap a listener with QoL options: once, debounce, throttle, schedule=microtask
+export const buildEffectiveListener = (
+	listener: ChangeListener,
+	options?: ListenerOptions,
+): { effective: ChangeListener; setUnsubscribe: (fn: () => void) => void; } => {
+	const opts = options ?? {};
+	let unsubscribe: (() => void) | undefined;
+	const setUnsubscribe = (fn: () => void) => { unsubscribe = fn; };
+
+	const scheduleInvoke = (fn: () => void) => {
+		if (opts.schedule === 'microtask')
+			queueMicrotask(fn);
+		else
+			fn();
+	};
+
+	let calledOnce = false;
+	let debounceTimer: any = null;
+	let throttleTimer: any = null;
+	let nextAllowed = 0;
+	let pendingArgs: [string[], any, any, ChangeMeta | undefined] | null = null;
+
+	const invoke = (args: [string[], any, any, ChangeMeta | undefined]) => {
+		if (opts.once && calledOnce)
+			return;
+
+		scheduleInvoke(() => {
+			listener(...args);
+			if (opts.once) {
+				calledOnce = true;
+				if (unsubscribe)
+					unsubscribe();
+			}
+		});
+	};
+
+	const effective: ChangeListener = (path, newValue, oldValue, meta) => {
+		const args: [string[], any, any, ChangeMeta | undefined] = [ path, newValue, oldValue, meta ];
+		if (opts.debounceMs != null && opts.debounceMs >= 0) {
+			pendingArgs = args;
+			if (debounceTimer)
+				clearTimeout(debounceTimer);
+
+			debounceTimer = setTimeout(() => {
+				const a = pendingArgs!;
+				pendingArgs = null;
+				invoke(a);
+			}, opts.debounceMs);
+
+			return;
+		}
+
+		if (opts.throttleMs != null && opts.throttleMs > 0) {
+			const now = Date.now();
+			if (now >= nextAllowed) {
+				nextAllowed = now + opts.throttleMs;
+				invoke(args);
+			}
+			else {
+				pendingArgs = args;
+				if (!throttleTimer) {
+					throttleTimer = setTimeout(() => {
+						throttleTimer = null;
+						const a = pendingArgs!;
+						pendingArgs = null;
+						nextAllowed = Date.now() + (opts.throttleMs ?? 0);
+						invoke(a);
+					}, Math.max(0, nextAllowed - now));
+				}
+			}
+
+			return;
+		}
+
+		// default immediate
+		invoke(args);
+	};
+
+	return { effective, setUnsubscribe };
+};

package/src/snapshot-diff.ts

@@ -0,0 +1,90 @@
+import { getOptions } from './history.ts';
+import { normalizeKey } from './path.ts';
+import type { DiffRecord } from './types.ts';
+
+// Original snapshot for diff/isPristine
+export const originalSnapshotCache: WeakMap<object, any> = new WeakMap();
+
+// Deep clone utility honoring options.clone and falling back to structuredClone
+export const deepClone = <T>(v: T): T => {
+	try {
+		return structuredClone(v) as T;
+	}
+	catch {
+		return v;
+	}
+};
+
+export const cloneWithOptions = <T>(root: object, v: T): T => {
+	const opts = getOptions(root);
+	if (opts.clone) {
+		try {
+			return opts.clone(v);
+		}
+		catch { /* fall through */ }
+	}
+
+	return deepClone(v);
+};
+
+const isObject = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null;
+
+export const diffValues = (
+	a: any,
+	b: any,
+	path: string[],
+	out: DiffRecord[],
+	root: object,
+	seenParam?: WeakMap<object, object>,
+): void => {
+	const opts = getOptions(root);
+	const equal = opts.compare ?? ((x: any, y: any) => Object.is(x, y));
+	const filter = opts.diffFilter;
+	const seen = seenParam ?? new WeakMap<object, object>();
+
+	const f = filter ? filter(path) : true;
+	if (f === false)
+		return; // skip subtree
+	if (f === 'shallow') {
+		if (!equal(a, b, path))
+			out.push({ path: path.slice(), kind: 'changed', oldValue: a, newValue: b });
+
+		return;
+	}
+
+	if (equal(a, b, path))
+		return;
+
+	if (isObject(a) && isObject(b)) {
+		if (seen.get(a as object) === (b as object))
+			return;
+
+		seen.set(a as object, b as object);
+
+		const aKeyMap: Map<string, PropertyKey> = new Map();
+		for (const k of Reflect.ownKeys(a))
+			aKeyMap.set(normalizeKey(k), k);
+		const bKeyMap: Map<string, PropertyKey> = new Map();
+		for (const k of Reflect.ownKeys(b))
+			bKeyMap.set(normalizeKey(k), k);
+
+		const aKeys = new Set(aKeyMap.keys());
+		const bKeys = new Set(bKeyMap.keys());
+
+		for (const nk of aKeys) {
+			const nextPath = [ ...path, nk ];
+			if (!bKeys.has(nk))
+				out.push({ path: nextPath, kind: 'removed', oldValue: (a as any)[aKeyMap.get(nk)!] });
+			else
+				diffValues((a as any)[aKeyMap.get(nk)!], (b as any)[bKeyMap.get(nk)!], nextPath, out, root, seen);
+		}
+		for (const nk of bKeys) {
+			if (!aKeys.has(nk))
+				out.push({ path: [ ...path, nk ], kind: 'added', newValue: (b as any)[bKeyMap.get(nk)!] });
+		}
+
+		return;
+	}
+
+	out.push({ path: path.slice(), kind: 'changed', oldValue: a, newValue: b });
+};

package/src/symbol-id.ts

@@ -0,0 +1,20 @@
+/*
+ * Stable per-process symbol identity mapping used for path normalization.
+ * Distinct symbols map to unique ids (sym#N), avoiding description-based collisions.
+ */
+
+const symbolIds: WeakMap<symbol, string> = new WeakMap();
+let symbolCounter = 0;
+
+export const getSymbolId = (s: symbol): string => {
+	let id = symbolIds.get(s);
+	if (!id) {
+		id = `sym#${ ++symbolCounter }`;
+		symbolIds.set(s, id);
+	}
+
+	return id;
+};
+
+export const normalizePropertyKey = (prop: PropertyKey): string =>
+	typeof prop === 'symbol' ? getSymbolId(prop) : String(prop);

package/src/tsconfig.json

@@ -0,0 +1,3 @@
+{
+	"extends": "@arcmantle/tsconfig",
+}

package/src/types.ts

@@ -0,0 +1,59 @@
+// Shared types for observe subsystem (no runtime code)
+
+export interface ChangeMeta {
+	type:           'set' | 'delete';
+	existedBefore?: boolean;
+	groupId?:       string;
+	// Collection metadata (for Map/Set)
+	collection?:    'map' | 'set';
+	key?:           any;
+}
+export type ChangeListener = (path: string[], newValue: any, oldValue: any, meta?: ChangeMeta) => void;
+
+export type PathSelector<T> = (object: T) => any;
+
+export type PathMode = 'exact' | 'up' | 'down';
+
+export interface PathTrieNode {
+	children: Map<string, PathTrieNode>;
+	modes:    Map<PathMode, Set<ChangeListener>>;
+}
+
+export interface ListenerBucket {
+	global: Set<ChangeListener>;
+	trie:   PathTrieNode;
+}
+
+export interface ListenerOptions {
+	once?:       boolean;
+	debounceMs?: number;
+	throttleMs?: number;
+	schedule?:   'sync' | 'microtask';
+}
+
+// --- Change history (for undo/diff) ---
+export type ChangeType = 'set' | 'delete';
+export interface ChangeRecord {
+	path:           string[];
+	type:           ChangeType;
+	oldValue:       any;
+	newValue:       any;
+	timestamp:      number;
+	existedBefore?: boolean;
+	groupId?:       string;
+	// Collection metadata (for Map/Set adapters)
+	collection?:    'map' | 'set';
+	key?:           any; // Map key (or Set entry when needed)
+}
+
+// --- Diff ---
+export type DiffKind = 'added' | 'removed' | 'changed';
+export interface DiffRecord {
+	path:      string[];
+	kind:      DiffKind;
+	oldValue?: any;
+	newValue?: any;
+}
+
+// Internal helper for pause queue
+export interface QueuedCall { listener: ChangeListener; args: [ string[], any, any, ChangeMeta | undefined ]; }