patch-recorder 0.0.1 → 0.2.0

package/src/optimizer.ts

@@ -1,53 +1,283 @@
-import type {Patches} from './types.js';
+import type {Patch, Patches, PatchPath} from './types.js';
+import {pathToKey} from './utils.js';
+
+// ==================== Nested Map data structure ====================
 
 /**
- * Compress patches by merging redundant operations
- * This handles both consecutive and interleaved operations on the same path
+ * Node in the path tree for efficient path lookup
+ */
+interface PathNode {
+	patch?: Patch;
+	children?: Map<string | number | symbol | object, PathNode>;
+}
+
+/**
+ * Navigate to a node in the path tree, creating nodes along the way
+ */
+function getOrCreateNode(root: PathNode, path: PatchPath): PathNode {
+	let current = root;
+	for (const key of path) {
+		if (!current.children) {
+			current.children = new Map();
+		}
+		let child = current.children.get(key);
+		if (!child) {
+			child = {};
+			current.children.set(key, child);
+		}
+		current = child;
+	}
+	return current;
+}
+
+/**
+ * Collect all patches from the path tree
+ */
+function collectPatches(node: PathNode, patches: Patches = []): Patches {
+	if (node.patch) {
+		patches.push(node.patch);
+	}
+	if (node.children) {
+		for (const child of node.children.values()) {
+			collectPatches(child, patches);
+		}
+	}
+	return patches;
+}
+
+// ==================== V2: Nested Map optimizer (faster) ====================
+
+/**
+ * Compress patches by merging redundant operations using nested Maps
+ * This is faster than the string-key version because:
+ * - No string allocation for path keys
+ * - Preserves symbol and object identity
+ * - 2.5-5x faster in benchmarks
+ */
+export function compressPatchesWithNestedMaps(patches: Patches): Patches {
+	if (patches.length === 0) {
+		return patches;
+	}
+
+	// Use a nested Map tree to track the latest operation for each path
+	const root: PathNode = {};
+
+	for (const patch of patches) {
+		const node = getOrCreateNode(root, patch.path);
+		const existing = node.patch;
+
+		if (!existing) {
+			// First operation on this path
+			node.patch = patch;
+		} else {
+			// Merge with existing operation based on operation types
+			const merged = mergePatches(existing, patch);
+			// Check for undefined specifically (null means canceled, which is a valid result)
+			if (merged !== undefined) {
+				// Update with merged result (or null if they cancel out)
+				if (merged !== null) {
+					node.patch = merged;
+				} else {
+					// Operations canceled each other out
+					delete node.patch;
+				}
+			} else {
+				// Can't merge, keep the new operation
+				node.patch = patch;
+			}
+		}
+	}
+
+	// Collect all patches from tree
+	let finalPatches = collectPatches(root);
+
+	// Handle array push + pop cancellation
+	// Only cancel when push is at the last index and pop reduces length
+	finalPatches = cancelArrayPushPop(finalPatches);
+
+	// Cancel patches that are beyond array bounds after final length update
+	finalPatches = cancelOutOfBoundsPatches(finalPatches);
+
+	return finalPatches;
+}
+
+// ==================== V1: String key optimizer (original) ====================
+
+/**
+ * Compress patches by merging redundant operations using string keys
+ * This is the original implementation that uses pathToKey for path lookup.
  */
-export function compressPatches(patches: Patches<true>): Patches<true> {
+export function compressPatchesWithStringKeys(patches: Patches): Patches {
 	if (patches.length === 0) {
 		return patches;
 	}
 
 	// Use a Map to track the latest operation for each path
-	// Key: JSON stringified path, Value: the latest patch for that path
-	const pathMap = new Map<string, any>();
+	// Key: optimized path string (using pathToKey), Value: the latest patch for that path
+	const pathMap = new Map<string, Patch>();
 
 	for (const patch of patches) {
-		const pathKey = JSON.stringify(patch.path);
+		const pathKey = pathToKey(patch.path);
 		const existing = pathMap.get(pathKey);
 
 		if (!existing) {
 			// First operation on this path
 			pathMap.set(pathKey, patch);
+		} else {
+			// Merge with existing operation based on operation types
+			const merged = mergePatches(existing, patch);
+			// Check for undefined specifically (null means canceled, which is a valid result)
+			if (merged !== undefined) {
+				// Update with merged result (or null if they cancel out)
+				if (merged !== null) {
+					pathMap.set(pathKey, merged);
+				} else {
+					// Operations canceled each other out
+					pathMap.delete(pathKey);
+				}
+			} else {
+				// Can't merge, keep the new operation
+				pathMap.set(pathKey, patch);
+			}
+		}
+	}
+
+	// Convert Map to array for final processing
+	let finalPatches = Array.from(pathMap.values());
+
+	// Handle array push + pop cancellation
+	// Only cancel when push is at the last index and pop reduces length
+	finalPatches = cancelArrayPushPop(finalPatches);
+
+	// Cancel patches that are beyond array bounds after final length update
+	finalPatches = cancelOutOfBoundsPatches(finalPatches);
+
+	return finalPatches;
+}
+
+// ==================== Default export ====================
+
+/**
+ * Compress patches by merging redundant operations
+ * This handles both consecutive and interleaved operations on the same path
+ *
+ * Uses the nested Map implementation for better performance (2.5-5x faster)
+ */
+export const compressPatches = compressPatchesWithNestedMaps;
+
+// ==================== Post-processing functions (shared) ====================
+
+/**
+ * Cancel array push + pop operations
+ * Only cancels when push is at the last index and pop reduces length
+ *
+ * Note: Uses pathToKey for grouping since this works on already-compressed patches
+ * (smaller set) and the performance benefit of nested Maps is less significant here.
+ */
+function cancelArrayPushPop(patches: Patches): Patches {
+	// Group patches by parent array path
+	const arrayGroups = new Map<string, Patches>();
+
+	for (const patch of patches) {
+		if (!Array.isArray(patch.path) || patch.path.length < 2) {
 			continue;
 		}
 
-		// Merge with existing operation based on operation types
-		const merged = mergePatches(existing, patch);
-		if (merged) {
-			// Update with merged result (or null if they cancel out)
-			if (merged !== null) {
-				pathMap.set(pathKey, merged);
-			} else {
-				// Operations canceled each other out
-				pathMap.delete(pathKey);
+		const parentPath = patch.path.slice(0, -1);
+		const parentKey = pathToKey(parentPath);
+
+		if (!arrayGroups.has(parentKey)) {
+			arrayGroups.set(parentKey, []);
+		}
+		arrayGroups.get(parentKey)!.push(patch);
+	}
+
+	// Use WeakSet to track cancelable patches by reference (no string allocation)
+	const cancelablePatches = new WeakSet<Patch>();
+
+	for (const [, groupPatches] of arrayGroups.entries()) {
+		// Find push patches (add at highest indices)
+		const pushPatches = groupPatches
+			.filter((p) => p.op === 'add' && typeof p.path[p.path.length - 1] === 'number')
+			.sort(
+				(a, b) => (b.path[b.path.length - 1] as number) - (a.path[a.path.length - 1] as number),
+			);
+
+		// Find pop patches (length reduction)
+		const popPatches = groupPatches.filter(
+			(p) => p.op === 'replace' && p.path[p.path.length - 1] === 'length',
+		);
+
+		// Cancel pushes and pops that match (push at highest index, pop reduces length)
+		const cancelCount = Math.min(pushPatches.length, popPatches.length);
+		for (let i = 0; i < cancelCount; i++) {
+			const pushPatch = pushPatches[i];
+			const popPatch = popPatches[i];
+
+			// Check if the push index matches the pop target
+			const pushIndex = pushPatch.path[pushPatch.path.length - 1] as number;
+			const popLength = popPatch.value as number;
+
+			// If push added at index pushIndex and pop reduced to popLength, they cancel
+			// This is a heuristic: push adds at end, pop removes from end
+			if (pushIndex >= popLength) {
+				cancelablePatches.add(pushPatch);
+				cancelablePatches.add(popPatch);
 			}
-		} else {
-			// Can't merge, keep the new operation
-			pathMap.set(pathKey, patch);
 		}
 	}
 
-	// Convert Map back to array
-	return Array.from(pathMap.values()) as Patches<true>;
+	return patches.filter((patch) => !cancelablePatches.has(patch));
+}
+
+/**
+ * Cancel patches that are beyond array bounds after final length update
+ */
+function cancelOutOfBoundsPatches(patches: Patches): Patches {
+	// Find the final length for each array
+	const arrayLengths = new Map<string, number>();
+
+	for (const patch of patches) {
+		if (
+			Array.isArray(patch.path) &&
+			patch.path.length >= 2 &&
+			patch.path[patch.path.length - 1] === 'length'
+		) {
+			const parentPath = pathToKey(patch.path.slice(0, -1));
+			arrayLengths.set(parentPath, patch.value as number);
+		}
+	}
+
+	// Use WeakSet to track canceled patches by reference (no string allocation)
+	const canceledPatches = new WeakSet<Patch>();
+
+	// Cancel patches at indices >= final length
+	for (const patch of patches) {
+		if (!Array.isArray(patch.path) || patch.path.length < 2) {
+			continue;
+		}
+
+		const lastPath = patch.path[patch.path.length - 1];
+		const parentPath = pathToKey(patch.path.slice(0, -1));
+
+		if (typeof lastPath === 'number' && arrayLengths.has(parentPath)) {
+			const length = arrayLengths.get(parentPath)!;
+			if (lastPath >= length) {
+				canceledPatches.add(patch);
+			}
+		}
+	}
+
+	return patches.filter((patch) => !canceledPatches.has(patch));
 }
 
+// ==================== Patch merging logic (shared) ====================
+
 /**
  * Merge two patches on the same path
  * Returns the merged patch, or null if they cancel out, or undefined if they can't be merged
  */
-function mergePatches(patch1: any, patch2: any): any | null | undefined {
+function mergePatches(patch1: Patch, patch2: Patch): Patch | null | undefined {
 	const op1 = patch1.op;
 	const op2 = patch2.op;
 
@@ -55,19 +285,19 @@ function mergePatches(patch1: any, patch2: any): any | null | undefined {
 	if (op1 === op2) {
 		// For replace operations, keep the latest value
 		if (op1 === 'replace') {
-			// Skip if same value (no-op)
-			if (valuesEqual(patch1.value, patch2.value)) {
+			// Skip if same reference (no-op)
+			if (patch1.value === patch2.value) {
 				return patch1;
 			}
 			return patch2;
 		}
-		// For add operations, if adding the same value, it's a no-op
-		if (op1 === 'add' && valuesEqual(patch1.value, patch2.value)) {
+		// For add operations, if adding same reference, it's a no-op
+		if (op1 === 'add' && patch1.value === patch2.value) {
 			return patch1;
 		}
-		// For remove operations, keep the latest
+		// For remove operations, don't merge (sequential removes should never be merged)
 		if (op1 === 'remove') {
-			return patch2;
+			return undefined;
 		}
 	}
 
@@ -93,44 +323,14 @@ function mergePatches(patch1: any, patch2: any): any | null | undefined {
 	}
 
 	if (op1 === 'remove' && op2 === 'add') {
-		// Remove then add - keep the add
-		return patch2;
+		// Remove then add - this is a replace operation
+		return {
+			op: 'replace',
+			path: patch1.path,
+			value: patch2.value,
+		};
 	}
 
 	// Can't merge these operations
 	return undefined;
-}
-
-/**
- * Check if two values are equal (deep comparison)
- */
-function valuesEqual(val1: any, val2: any): boolean {
-	if (val1 === val2) return true;
-
-	// Handle null/undefined
-	if (val1 == null || val2 == null) return val1 === val2;
-
-	// Handle arrays
-	if (Array.isArray(val1) && Array.isArray(val2)) {
-		if (val1.length !== val2.length) return false;
-		for (let i = 0; i < val1.length; i++) {
-			if (!valuesEqual(val1[i], val2[i])) return false;
-		}
-		return true;
-	}
-
-	// Handle objects
-	if (typeof val1 === 'object' && typeof val2 === 'object') {
-		const keys1 = Object.keys(val1);
-		const keys2 = Object.keys(val2);
-
-		if (keys1.length !== keys2.length) return false;
-
-		for (const key of keys1) {
-			if (!valuesEqual(val1[key], val2[key])) return false;
-		}
-		return true;
-	}
-
-	return false;
-}
+}

package/src/patches.ts

@@ -1,22 +1,31 @@
-import type {RecorderState} from './types.js';
+import type {NonPrimitive, Patch, PatchPath, RecorderState} from './types.js';
 import {Operation} from './types.js';
-import {formatPath, cloneIfNeeded} from './utils.js';
+import {cloneIfNeeded, findGetItemIdFn} from './utils.js';
 
 /**
  * Generate a replace patch for property changes
  */
 export function generateSetPatch(
-	state: RecorderState<any>,
-	path: (string | number)[],
-	oldValue: any,
-	newValue: any,
+	state: RecorderState<NonPrimitive>,
+	path: PatchPath,
+	oldValue: unknown,
+	newValue: unknown,
 ) {
-	const patch = {
+	const patch: any = {
 		op: Operation.Replace,
-		path: formatPath(path, state.options),
+		path,
 		value: cloneIfNeeded(newValue),
 	};
 
+	// Add id if getItemId is configured for this path
+	const getItemIdFn = findGetItemIdFn(path, state.options.getItemId);
+	if (getItemIdFn && oldValue !== undefined) {
+		const id = getItemIdFn(oldValue);
+		if (id !== undefined && id !== null) {
+			patch.id = id;
+		}
+	}
+
 	state.patches.push(patch);
 }
 
@@ -24,28 +33,36 @@ export function generateSetPatch(
  * Generate a remove patch for property deletions
  */
 export function generateDeletePatch(
-	state: RecorderState<any>,
-	path: (string | number)[],
-	oldValue: any,
+	state: RecorderState<NonPrimitive>,
+	path: PatchPath,
+	oldValue: unknown,
 ) {
-	const patch = {
+	const patch: Patch = {
 		op: Operation.Remove,
-		path: formatPath(path, state.options),
+		path: path,
 	};
 
+	// Add id if getItemId is configured for this path
+	const getItemIdFn = findGetItemIdFn(path, state.options.getItemId);
+	if (getItemIdFn && oldValue !== undefined) {
+		const id = getItemIdFn(oldValue);
+		if (id !== undefined && id !== null) {
+			patch.id = id;
+		}
+	}
+
 	state.patches.push(patch);
 }
 
 /**
  * Generate an add patch for new properties
  */
-export function generateAddPatch(state: RecorderState<any>, path: (string | number)[], value: any) {
-	const patch = {
+export function generateAddPatch(state: RecorderState<any>, path: PatchPath, value: any) {
+	const patch: Patch = {
 		op: Operation.Add,
-		path: formatPath(path, state.options),
+		path,
 		value: cloneIfNeeded(value),
 	};
-
 	state.patches.push(patch);
 }
 
@@ -54,14 +71,24 @@ export function generateAddPatch(state: RecorderState<any>, path: (string | numb
  */
 export function generateReplacePatch(
 	state: RecorderState<any>,
-	path: (string | number)[],
-	value: any,
+	path: PatchPath,
+	value: unknown,
+	oldValue?: unknown,
 ) {
-	const patch = {
+	const patch: Patch = {
 		op: Operation.Replace,
-		path: formatPath(path, state.options),
+		path: path,
 		value: cloneIfNeeded(value),
 	};
 
+	// Add id if getItemId is configured for this path
+	const getItemIdFn = findGetItemIdFn(path, state.options.getItemId);
+	if (getItemIdFn && oldValue !== undefined) {
+		const id = getItemIdFn(oldValue);
+		if (id !== undefined && id !== null) {
+			patch.id = id;
+		}
+	}
+
 	state.patches.push(patch);
 }

package/src/proxy.ts

@@ -1,4 +1,4 @@
-import type {RecorderState} from './types.js';
+import type {PatchPath, RecorderState} from './types.js';
 import {generateSetPatch, generateDeletePatch, generateAddPatch} from './patches.js';
 import {isArray, isMap, isSet} from './utils.js';
 import {handleArrayGet} from './arrays.js';
@@ -7,9 +7,15 @@ import {handleSetGet} from './sets.js';
 
 export function createProxy<T extends object>(
 	target: T,
-	path: (string | number)[],
+	path: PatchPath,
 	state: RecorderState<any>,
 ): T {
+	// Check cache first
+	const cached = state.proxyCache.get(target);
+	if (cached) {
+		return cached;
+	}
+
 	const isArrayType = isArray(target);
 	const isMapType = isMap(target);
 	const isSetType = isSet(target);
@@ -39,12 +45,8 @@ export function createProxy<T extends object>(
 				return value;
 			}
 
-			// Create nested proxy for draftable values
-			// Only include string | number in path, skip symbols
-			if (typeof prop === 'string' || typeof prop === 'number') {
-				return createProxy(value, [...path, prop], state);
-			}
-			return value;
+			// Create nested proxy for all draftable values
+			return createProxy(value, [...path, prop], state);
 		},
 
 		set(obj, prop, value) {
@@ -55,50 +57,35 @@ export function createProxy<T extends object>(
 
 			const oldValue = (obj as any)[prop];
 
-			// Only create path for string | number props, skip symbols
-			if (typeof prop !== 'string' && typeof prop !== 'number') {
-				(obj as any)[prop] = value;
-				return true;
-			}
-
 			// Convert numeric string props to numbers for array indices
 			const propForPath = typeof prop === 'string' && !isNaN(Number(prop)) ? Number(prop) : prop;
 			const propPath = [...path, propForPath];
 
-			// Skip if no actual change (handle undefined as a valid value)
-			if (
-				oldValue === value &&
-				(value !== undefined || Object.prototype.hasOwnProperty.call(obj, prop))
-			) {
-				return true;
-			}
+			// Check if property actually exists (for no-op detection)
+			const actuallyHasProperty = Object.prototype.hasOwnProperty.call(obj, prop);
 
-			// Determine if this is an add or replace operation by checking the original state
-			let originalHasProperty = false;
-			let originalValue = undefined;
-
-			// Navigate to the original object at this path
-			let currentOriginal = state.original as any;
-			for (let i = 0; i < path.length; i++) {
-				currentOriginal = currentOriginal[path[i]];
-				if (currentOriginal === undefined || currentOriginal === null) {
-					break;
-				}
+			// For add vs replace distinction: check array bounds for arrays
+			// Index within bounds = replace, out of bounds = add
+			let hadProperty = actuallyHasProperty;
+			if (isArrayType && typeof propForPath === 'number') {
+				hadProperty = propForPath >= 0 && propForPath < (obj as any[]).length;
 			}
 
-			if (currentOriginal && currentOriginal !== undefined && currentOriginal !== null) {
-				originalHasProperty = Object.prototype.hasOwnProperty.call(currentOriginal, prop);
-				originalValue = currentOriginal[prop];
+			// Skip if no actual change (handle undefined as a valid value)
+			// Use Object.is to correctly handle NaN (NaN !== NaN, but Object.is(NaN, NaN) === true)
+			// Use actuallyHasProperty for no-op detection (sparse array hole is different from undefined)
+			if (Object.is(oldValue, value) && (value !== undefined || actuallyHasProperty)) {
+				return true;
 			}
 
 			// Mutate original immediately
 			(obj as any)[prop] = value;
 
-			// Generate patch
-			if (!originalHasProperty) {
+			// Generate patch - use pre-mutation property existence check
+			if (!hadProperty) {
 				generateAddPatch(state, propPath, value);
 			} else {
-				generateSetPatch(state, propPath, originalValue, value);
+				generateSetPatch(state, propPath, oldValue, value);
 			}
 
 			return true;
@@ -116,13 +103,6 @@ export function createProxy<T extends object>(
 			}
 
 			const oldValue = (obj as any)[prop];
-
-			// Only create path for string | number props, skip symbols
-			if (typeof prop !== 'string' && typeof prop !== 'number') {
-				delete (obj as any)[prop];
-				return true;
-			}
-
 			const propPath = [...path, prop];
 
 			if (oldValue !== undefined || Object.prototype.hasOwnProperty.call(obj, prop)) {
@@ -159,5 +139,10 @@ export function createProxy<T extends object>(
 		},
 	};
 
-	return new Proxy(target, handler);
+	const proxy = new Proxy(target, handler);
+
+	// Store in cache
+	state.proxyCache.set(target, proxy);
+
+	return proxy;
 }

package/src/sets.ts

@@ -1,29 +1,28 @@
-import type {RecorderState} from './types.js';
-import {createProxy} from './proxy.js';
-import {Operation} from './types.js';
+import type {PatchPath, RecorderState} from './types.js';
 import {generateAddPatch, generateDeletePatch} from './patches.js';
-import {cloneIfNeeded, isSet, isArray} from './utils.js';
+import {cloneIfNeeded} from './utils.js';
 
 /**
  * Handle property access on Set objects
  * Wraps mutating methods (add, delete, clear) to generate patches
  */
-export function handleSetGet<T = any>(
-	obj: Set<T>,
+export function handleSetGet(
+	obj: Set<any>,
 	prop: string | symbol,
-	path: (string | number)[],
+	path: PatchPath,
 	state: RecorderState<any>,
 ): any {
-	// Skip symbol properties
+	// Handle symbol properties - return the property value directly
+	// Symbol methods like Symbol.iterator should work normally
 	if (typeof prop === 'symbol') {
 		return (obj as any)[prop];
 	}
 
 	// Mutating methods
 	if (prop === 'add') {
-		return (value: T) => {
-			// Check if value existed BEFORE mutation
-			const existed = valueExistsInOriginal(state.original, path, value);
+		return (value: any) => {
+			// Check if value exists BEFORE mutation (current state, not original)
+			const existed = obj.has(value);
 			const result = obj.add(value);
 
 			// Generate patch only if value didn't exist
@@ -37,7 +36,7 @@ export function handleSetGet<T = any>(
 	}
 
 	if (prop === 'delete') {
-		return (value: T) => {
+		return (value: any) => {
 			const existed = obj.has(value);
 			const result = obj.delete(value);
 
@@ -80,21 +79,3 @@ export function handleSetGet<T = any>(
 	return (obj as any)[prop];
 }
 
-/**
- * Navigate to the original Set at the given path and check if a value exists
- * This is needed to check if a value existed before mutations
- */
-function valueExistsInOriginal(original: any, path: (string | number)[], value: any): boolean {
-	let current = original;
-	for (const part of path) {
-		if (current == null) return false;
-		current = current[part];
-	}
-
-	// If we reached a Set, check if the value exists
-	if (current instanceof Set) {
-		return current.has(value);
-	}
-
-	return false;
-}