patch-recorder 0.1.0 → 0.2.0

package/src/optimizer.ts

@@ -1,20 +1,123 @@
-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
  */
-export function compressPatches(patches: Patches<true>): Patches<true> {
+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 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) {
@@ -49,16 +152,31 @@ export function compressPatches(patches: Patches<true>): Patches<true> {
 	// Cancel patches that are beyond array bounds after final length update
 	finalPatches = cancelOutOfBoundsPatches(finalPatches);
 
-	return finalPatches as Patches<true>;
+	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<true>): Patches<true> {
+function cancelArrayPushPop(patches: Patches): Patches {
 	// Group patches by parent array path
-	const arrayGroups = new Map<string, Patches<true>>();
+	const arrayGroups = new Map<string, Patches>();
 
 	for (const patch of patches) {
 		if (!Array.isArray(patch.path) || patch.path.length < 2) {
@@ -66,7 +184,7 @@ function cancelArrayPushPop(patches: Patches<true>): Patches<true> {
 		}
 
 		const parentPath = patch.path.slice(0, -1);
-		const parentKey = JSON.stringify(parentPath);
+		const parentKey = pathToKey(parentPath);
 
 		if (!arrayGroups.has(parentKey)) {
 			arrayGroups.set(parentKey, []);
@@ -74,15 +192,15 @@ function cancelArrayPushPop(patches: Patches<true>): Patches<true> {
 		arrayGroups.get(parentKey)!.push(patch);
 	}
 
-	const cancelablePatches = new Set<string>();
+	// 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),
+				(a, b) => (b.path[b.path.length - 1] as number) - (a.path[a.path.length - 1] as number),
 			);
 
 		// Find pop patches (length reduction)
@@ -103,24 +221,21 @@ function cancelArrayPushPop(patches: Patches<true>): Patches<true> {
 			// 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(JSON.stringify(pushPatch.path));
-				cancelablePatches.add(JSON.stringify(popPatch.path));
+				cancelablePatches.add(pushPatch);
+				cancelablePatches.add(popPatch);
 			}
 		}
 	}
 
-	return patches.filter(
-		(patch) => !cancelablePatches.has(JSON.stringify(patch.path)),
-	) 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<true>): Patches<true> {
+function cancelOutOfBoundsPatches(patches: Patches): Patches {
 	// Find the final length for each array
 	const arrayLengths = new Map<string, number>();
-	const canceledPatches = new Set<string>();
 
 	for (const patch of patches) {
 		if (
@@ -128,11 +243,14 @@ function cancelOutOfBoundsPatches(patches: Patches<true>): Patches<true> {
 			patch.path.length >= 2 &&
 			patch.path[patch.path.length - 1] === 'length'
 		) {
-			const parentPath = JSON.stringify(patch.path.slice(0, -1));
+			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) {
@@ -140,26 +258,26 @@ function cancelOutOfBoundsPatches(patches: Patches<true>): Patches<true> {
 		}
 
 		const lastPath = patch.path[patch.path.length - 1];
-		const parentPath = JSON.stringify(patch.path.slice(0, -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(JSON.stringify(patch.path));
+				canceledPatches.add(patch);
 			}
 		}
 	}
 
-	return patches.filter(
-		(patch) => !canceledPatches.has(JSON.stringify(patch.path)),
-	) as Patches<true>;
+	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;
 

package/src/patches.ts

@@ -1,19 +1,19 @@
-import type {RecorderState} from './types.js';
+import type {NonPrimitive, Patch, PatchPath, RecorderState} from './types.js';
 import {Operation} from './types.js';
-import {formatPath, cloneIfNeeded, findGetItemIdFn} 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: any = {
 		op: Operation.Replace,
-		path: formatPath(path, state.options),
+		path,
 		value: cloneIfNeeded(newValue),
 	};
 
@@ -33,13 +33,13 @@ 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: any = {
+	const patch: Patch = {
 		op: Operation.Remove,
-		path: formatPath(path, state.options),
+		path: path,
 	};
 
 	// Add id if getItemId is configured for this path
@@ -57,13 +57,12 @@ export function generateDeletePatch(
 /**
  * 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);
 }
 
@@ -72,13 +71,13 @@ export function generateAddPatch(state: RecorderState<any>, path: (string | numb
  */
 export function generateReplacePatch(
 	state: RecorderState<any>,
-	path: (string | number)[],
-	value: any,
-	oldValue?: any,
+	path: PatchPath,
+	value: unknown,
+	oldValue?: unknown,
 ) {
-	const patch: any = {
+	const patch: Patch = {
 		op: Operation.Replace,
-		path: formatPath(path, state.options),
+		path: path,
 		value: cloneIfNeeded(value),
 	};
 

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,64 +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)
-			// Use Object.is to correctly handle NaN (NaN !== NaN, but Object.is(NaN, NaN) === true)
-			if (
-				Object.is(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) {
-				// For arrays, check if the index is within the array length (handles sparse arrays correctly)
-				if (Array.isArray(currentOriginal)) {
-					// Convert prop to number if it's a numeric string
-					const index = typeof prop === 'string' && !isNaN(Number(prop)) ? Number(prop) : prop;
-					if (typeof index === 'number') {
-						originalHasProperty = index >= 0 && index < currentOriginal.length;
-						originalValue = (currentOriginal as any)[index];
-					} else {
-						originalHasProperty = Object.prototype.hasOwnProperty.call(currentOriginal, prop);
-						originalValue = (currentOriginal as any)[prop];
-					}
-				} else {
-					originalHasProperty = Object.prototype.hasOwnProperty.call(currentOriginal, prop);
-					originalValue = (currentOriginal as any)[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;
@@ -130,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)) {
@@ -173,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;
-}

package/src/types.ts

@@ -6,19 +6,6 @@ export const Operation = {
 
 export type PatchOp = (typeof Operation)[keyof typeof Operation];
 
-export type PatchesOptions =
-	| boolean
-	| {
-			/**
-			 * The default value is `true`. If it's `true`, the path will be an array, otherwise it is a string.
-			 */
-			pathAsArray?: boolean;
-			/**
-			 * The default value is `true`. If it's `true`, the array length will be included in the patches, otherwise no include array length.
-			 */
-			arrayLengthAssignment?: boolean;
-	  };
-
 /**
  * Function that extracts an ID from an item value
  */
@@ -31,7 +18,10 @@ export type GetItemIdConfig = {
 	[key: string]: GetItemIdFunction | GetItemIdConfig;
 };
 
-export interface IPatch {
+export type PatchPath = (string | number | symbol | object)[];
+
+export type Patch = {
+	path: PatchPath;
 	op: PatchOp;
 	value?: any;
 	/**
@@ -39,31 +29,13 @@ export interface IPatch {
 	 * Populated when getItemId option is configured for the item's parent path.
 	 */
 	id?: string | number;
-}
-
-export type Patch<P extends PatchesOptions = true> = P extends {
-	pathAsArray: false;
-}
-	? IPatch & {
-			path: string;
-		}
-	: P extends true | object
-		? IPatch & {
-				path: (string | number)[];
-			}
-		: IPatch & {
-				path: string | (string | number)[];
-			};
+};
 
-export type Patches<P extends PatchesOptions = true> = Patch<P>[];
+export type Patches = Patch[];
 
 export type NonPrimitive = object | Array<unknown>;
 
 export interface RecordPatchesOptions {
-	/**
-	 * Return paths as arrays (default: true) or strings
-	 */
-	pathAsArray?: boolean;
 	/**
 	 * Include array length in patches (default: true)
 	 */
@@ -92,11 +64,15 @@ export interface RecordPatchesOptions {
 	getItemId?: GetItemIdConfig;
 }
 
-export type Draft<T> = T;
+export type Draft<T extends NonPrimitive> = T;
 
-export interface RecorderState<T> {
-	original: T;
-	patches: Patches<any>;
-	basePath: (string | number)[];
-	options: RecordPatchesOptions & {internalPatchesOptions: PatchesOptions};
+export interface RecorderState<T extends NonPrimitive> {
+	state: T;
+	patches: Patches;
+	basePath: PatchPath;
+	options: RecordPatchesOptions;
+	/**
+	 * Cache for proxies to avoid creating new ones on repeated property access
+	 */
+	proxyCache: WeakMap<object, any>;
 }