patch-recorder 0.0.1 → 0.1.0

package/src/arrays.ts

@@ -1,8 +1,39 @@
 import type {RecorderState} from './types.js';
-import {Operation} from './types.js';
 import {generateAddPatch, generateDeletePatch, generateReplacePatch} from './patches.js';
 import {createProxy} from './proxy.js';
 
+// Module-level Sets for O(1) lookup instead of O(n) array includes
+const MUTATING_METHODS = new Set([
+	'push',
+	'pop',
+	'shift',
+	'unshift',
+	'splice',
+	'sort',
+	'reverse',
+]);
+
+const NON_MUTATING_METHODS = new Set([
+	'map',
+	'filter',
+	'reduce',
+	'reduceRight',
+	'forEach',
+	'find',
+	'findIndex',
+	'some',
+	'every',
+	'includes',
+	'indexOf',
+	'lastIndexOf',
+	'slice',
+	'concat',
+	'join',
+	'flat',
+	'flatMap',
+	'at',
+]);
+
 /**
  * Handle array method calls and property access
  */
@@ -13,43 +44,28 @@ export function handleArrayGet(
 	state: RecorderState<any>,
 ): any {
 	// Mutating methods
-	const mutatingMethods = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'];
-
-	if (mutatingMethods.includes(prop)) {
+	if (MUTATING_METHODS.has(prop)) {
 		return (...args: any[]) => {
-			const oldValue = [...obj]; // Snapshot before mutation
+			// Optimized: only copy what's needed for each method
+			const oldLength = obj.length;
+			let oldValue: any[] | null = null;
+
+			// Only create full copy for sort/reverse which need the entire old array
+			if (prop === 'sort' || prop === 'reverse') {
+				oldValue = [...obj];
+			}
+
 			const result = (Array.prototype as any)[prop].apply(obj, args);
 
 			// Generate patches based on the method
-			generateArrayPatches(state, obj, prop, args, result, path, oldValue);
+			generateArrayPatches(state, obj, prop, args, result, path, oldValue, oldLength);
 
 			return result;
 		};
 	}
 
 	// Non-mutating methods - just return them bound to the array
-	const nonMutatingMethods = [
-		'map',
-		'filter',
-		'reduce',
-		'reduceRight',
-		'forEach',
-		'find',
-		'findIndex',
-		'some',
-		'every',
-		'includes',
-		'indexOf',
-		'lastIndexOf',
-		'slice',
-		'concat',
-		'join',
-		'flat',
-		'flatMap',
-		'at',
-	];
-
-	if (nonMutatingMethods.includes(prop)) {
+	if (NON_MUTATING_METHODS.has(prop)) {
 		return (Array.prototype as any)[prop].bind(obj);
 	}
 
@@ -82,100 +98,71 @@ function generateArrayPatches(
 	args: any[],
 	result: any,
 	path: (string | number)[],
-	oldValue: any[],
+	oldValue: any[] | null,
+	oldLength: number,
 ) {
 	switch (method) {
 		case 'push': {
 			// Generate add patches for each new element
-			const startIndex = oldValue.length;
+			// oldLength is the starting index before push
 			args.forEach((value, i) => {
-				const index = startIndex + i;
+				const index = oldLength + i;
 				generateAddPatch(state, [...path, index], value);
 			});
-
-			// Generate length patch if option is enabled
-			if (state.options.arrayLengthAssignment !== false) {
-				generateReplacePatch(state, [...path, 'length'], obj.length);
-			}
+			// No length patch when array grows (aligned with mutative)
 			break;
 		}
 
 		case 'pop': {
-			// Generate remove patch for the removed element
-			const removedIndex = oldValue.length - 1;
-			generateDeletePatch(state, [...path, removedIndex], result);
-
-			// Generate length patch if option is enabled
 			if (state.options.arrayLengthAssignment !== false) {
-				generateReplacePatch(state, [...path, 'length'], obj.length);
+				// Generate length replace patch (mutative uses this instead of remove)
+				generateReplacePatch(state, [...path, 'length'], obj.length, oldLength);
+			} else {
+				// When arrayLengthAssignment is false, generate remove patch for last element
+				generateDeletePatch(state, [...path, oldLength - 1], result);
 			}
 			break;
 		}
 
 		case 'shift': {
-			// Generate remove patch for the removed element
+			// Remove first element (shifted elements are handled automatically by JSON Patch spec)
+			// We don't have oldValue here, but the result of shift() is the removed element
 			generateDeletePatch(state, [...path, 0], result);
-
-			// Shift is complex - we need to update all remaining elements
-			// Update all shifted elements (after the shift, each element moves to index - 1)
-			for (let i = 0; i < obj.length; i++) {
-				generateReplacePatch(state, [...path, i], oldValue[i + 1]);
-			}
-
-			// Generate length patch if option is enabled
-			if (state.options.arrayLengthAssignment !== false) {
-				generateReplacePatch(state, [...path, 'length'], obj.length);
-			}
 			break;
 		}
 
 		case 'unshift': {
-			// Add new elements at the beginning
+			// Add new elements at the beginning (shifted elements are handled automatically by JSON Patch spec)
 			args.forEach((value, i) => {
 				generateAddPatch(state, [...path, i], value);
 			});
-
-			// Update all existing elements
-
-			for (let i = 0; i < oldValue.length; i++) {
-				generateReplacePatch(state, [...path, i + args.length], oldValue[i]);
-			}
-
-			// Generate length patch if option is enabled
-			if (state.options.arrayLengthAssignment !== false) {
-				generateReplacePatch(state, [...path, 'length'], obj.length);
-			}
-
 			break;
 		}
 
 		case 'splice': {
-			const [start, deleteCount, ...addItems] = args;
-
-			// Generate remove patches for deleted items
-			for (let i = 0; i < deleteCount; i++) {
-				generateDeletePatch(state, [...path, start], oldValue[start]);
+			const [start, deleteCount = 0, ...addItems] = args;
+			const actualStart = start < 0 ? Math.max(oldLength + start, 0) : Math.min(start, oldLength);
+			const actualDeleteCount = Math.min(deleteCount, oldLength - actualStart);
+			const minCount = Math.min(actualDeleteCount, addItems.length);
+
+			// For splice, we need the old values for delete operations
+			// Since we don't have oldValue, we need to track what was deleted
+			// The result of splice() is the array of deleted elements
+			const deletedElements = result as any[];
+
+			// First minCount elements: replace (overlap between add and delete)
+			for (let i = 0; i < minCount; i++) {
+				generateReplacePatch(state, [...path, actualStart + i], addItems[i], deletedElements[i]);
 			}
 
-			// Generate add patches for new items
-			addItems.forEach((item, i) => {
-				generateAddPatch(state, [...path, start + i], item);
-			});
-
-			// If there are both deletions and additions, update the shifted elements
-
-			const itemsToShift = oldValue.length - start - deleteCount;
-			for (let i = 0; i < itemsToShift; i++) {
-				generateReplacePatch(
-					state,
-					[...path, start + addItems.length + i],
-					oldValue[start + deleteCount + i],
-				);
+			// Remaining add items: add
+			for (let i = minCount; i < addItems.length; i++) {
+				generateAddPatch(state, [...path, actualStart + i], addItems[i]);
 			}
 
-			// Generate length patch if option is enabled
-			if (state.options.arrayLengthAssignment !== false) {
-				generateReplacePatch(state, [...path, 'length'], obj.length);
+			// Remaining delete items: remove (generate in reverse order)
+			for (let i = actualDeleteCount - 1; i >= minCount; i--) {
+				generateDeletePatch(state, [...path, actualStart + i], deletedElements[i]);
 			}
 
 			break;
@@ -184,7 +171,8 @@ function generateArrayPatches(
 		case 'sort':
 		case 'reverse': {
 			// These reorder the entire array - generate full replace
-			generateReplacePatch(state, path, [...obj]);
+			// oldValue contains the array before the mutation
+			generateReplacePatch(state, path, [...obj], oldValue);
 			break;
 		}
 	}

package/src/index.ts

@@ -60,6 +60,7 @@ export function recordPatches<T extends NonPrimitive>(
 	return recorderState.patches as Patches<true>;
 }
 
+
 /**
  * Mutative-compatible API for easy switching between mutative and patch-recorder.
  * Returns [state, patches] tuple like mutative does.

package/src/maps.ts

@@ -31,8 +31,8 @@ export function handleMapGet<K = any, V = any>(
 			const itemPath = [...path, key as any];
 
 			if (existed) {
-				// Key exists - replace
-				generateReplacePatch(state, itemPath, cloneIfNeeded(value));
+				// Key exists - replace (pass oldValue for getItemId)
+				generateReplacePatch(state, itemPath, cloneIfNeeded(value), oldValue);
 			} else {
 				// Key doesn't exist - add
 				generateAddPatch(state, itemPath, cloneIfNeeded(value));
@@ -74,11 +74,9 @@ export function handleMapGet<K = any, V = any>(
 		return (key: K) => {
 			const value = obj.get(key);
 
-			// If the value is a Map, Array, or object, return a proxy
+			// If the value is an object, return a proxy for nested mutation tracking
 			if (value != null && typeof value === 'object') {
-				if (isMap(value) || isArray(value)) {
-					return createProxy(value, [...path, key as any], state);
-				}
+				return createProxy(value, [...path, key as any], state);
 			}
 
 			return value;

package/src/optimizer.ts

@@ -20,27 +20,139 @@ export function compressPatches(patches: Patches<true>): Patches<true> {
 		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 as Patches<true>;
+}
+
+/**
+ * Cancel array push + pop operations
+ * Only cancels when push is at the last index and pop reduces length
+ */
+function cancelArrayPushPop(patches: Patches<true>): Patches<true> {
+	// Group patches by parent array path
+	const arrayGroups = new Map<string, Patches<true>>();
+
+	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 = JSON.stringify(parentPath);
+
+		if (!arrayGroups.has(parentKey)) {
+			arrayGroups.set(parentKey, []);
+		}
+		arrayGroups.get(parentKey)!.push(patch);
+	}
+
+	const cancelablePatches = new Set<string>();
+
+	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(JSON.stringify(pushPatch.path));
+				cancelablePatches.add(JSON.stringify(popPatch.path));
 			}
-		} 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(JSON.stringify(patch.path)),
+	) as Patches<true>;
+}
+
+/**
+ * Cancel patches that are beyond array bounds after final length update
+ */
+function cancelOutOfBoundsPatches(patches: Patches<true>): Patches<true> {
+	// Find the final length for each array
+	const arrayLengths = new Map<string, number>();
+	const canceledPatches = new Set<string>();
+
+	for (const patch of patches) {
+		if (
+			Array.isArray(patch.path) &&
+			patch.path.length >= 2 &&
+			patch.path[patch.path.length - 1] === 'length'
+		) {
+			const parentPath = JSON.stringify(patch.path.slice(0, -1));
+			arrayLengths.set(parentPath, patch.value as number);
+		}
+	}
+
+	// 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 = JSON.stringify(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));
+			}
+		}
+	}
+
+	return patches.filter(
+		(patch) => !canceledPatches.has(JSON.stringify(patch.path)),
+	) as Patches<true>;
 }
 
 /**
@@ -55,19 +167,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 +205,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,6 +1,6 @@
 import type {RecorderState} from './types.js';
 import {Operation} from './types.js';
-import {formatPath, cloneIfNeeded} from './utils.js';
+import {formatPath, cloneIfNeeded, findGetItemIdFn} from './utils.js';
 
 /**
  * Generate a replace patch for property changes
@@ -11,12 +11,21 @@ export function generateSetPatch(
 	oldValue: any,
 	newValue: any,
 ) {
-	const patch = {
+	const patch: any = {
 		op: Operation.Replace,
 		path: formatPath(path, state.options),
 		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);
 }
 
@@ -28,11 +37,20 @@ export function generateDeletePatch(
 	path: (string | number)[],
 	oldValue: any,
 ) {
-	const patch = {
+	const patch: any = {
 		op: Operation.Remove,
 		path: formatPath(path, state.options),
 	};
 
+	// 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);
 }
 
@@ -56,12 +74,22 @@ export function generateReplacePatch(
 	state: RecorderState<any>,
 	path: (string | number)[],
 	value: any,
+	oldValue?: any,
 ) {
-	const patch = {
+	const patch: any = {
 		op: Operation.Replace,
 		path: formatPath(path, state.options),
 		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

@@ -66,8 +66,9 @@ export function createProxy<T extends object>(
 			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 (
-				oldValue === value &&
+				Object.is(oldValue, value) &&
 				(value !== undefined || Object.prototype.hasOwnProperty.call(obj, prop))
 			) {
 				return true;
@@ -87,8 +88,21 @@ export function createProxy<T extends object>(
 			}
 
 			if (currentOriginal && currentOriginal !== undefined && currentOriginal !== null) {
-				originalHasProperty = Object.prototype.hasOwnProperty.call(currentOriginal, prop);
-				originalValue = currentOriginal[prop];
+				// 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];
+				}
 			}
 
 			// Mutate original immediately

package/src/types.ts

@@ -19,12 +19,29 @@ export type PatchesOptions =
 			arrayLengthAssignment?: boolean;
 	  };
 
+/**
+ * Function that extracts an ID from an item value
+ */
+export type GetItemIdFunction = (value: any) => string | number | undefined | null;
+
+/**
+ * Recursive configuration for getItemId - can be a function or nested object
+ */
+export type GetItemIdConfig = {
+	[key: string]: GetItemIdFunction | GetItemIdConfig;
+};
+
 export interface IPatch {
 	op: PatchOp;
 	value?: any;
+	/**
+	 * Optional ID of the item being removed or replaced.
+	 * Populated when getItemId option is configured for the item's parent path.
+	 */
+	id?: string | number;
 }
 
-export type Patch<P extends PatchesOptions = any> = P extends {
+export type Patch<P extends PatchesOptions = true> = P extends {
 	pathAsArray: false;
 }
 	? IPatch & {
@@ -38,7 +55,7 @@ export type Patch<P extends PatchesOptions = any> = P extends {
 				path: string | (string | number)[];
 			};
 
-export type Patches<P extends PatchesOptions = any> = Patch<P>[];
+export type Patches<P extends PatchesOptions = true> = Patch<P>[];
 
 export type NonPrimitive = object | Array<unknown>;
 
@@ -55,6 +72,24 @@ export interface RecordPatchesOptions {
 	 * Compress patches by merging redundant operations (default: true)
 	 */
 	compressPatches?: boolean;
+	/**
+	 * Configuration for extracting item IDs for remove/replace patches.
+	 * Maps paths to functions that extract IDs from item values.
+	 *
+	 * @example
+	 * ```typescript
+	 * recordPatches(state, mutate, {
+	 *   getItemId: {
+	 *     items: (item) => item.id,
+	 *     users: (user) => user.userId,
+	 *     nested: {
+	 *       array: (item) => item._id
+	 *     }
+	 *   }
+	 * });
+	 * ```
+	 */
+	getItemId?: GetItemIdConfig;
 }
 
 export type Draft<T> = T;