patch-recorder 0.3.0 → 0.4.0

package/src/proxy.ts

@@ -1,4 +1,4 @@
-import type {PatchPath, RecorderState} from './types.js';
+import type {GetItemIdConfig, PatchPath, RecorderState} from './types.js';
 import {
 	generateSetPatch,
 	generateDeletePatch,
@@ -10,6 +10,100 @@ import {handleArrayGet} from './arrays.js';
 import {handleMapGet} from './maps.js';
 import {handleSetGet} from './sets.js';
 
+/**
+ * Find the array item context for getItemId extraction.
+ * Traverses the path and getItemId config in parallel to find the TRACKED array item,
+ * not just any array item. This ensures that nested arrays inside tracked items
+ * correctly return the tracked parent item.
+ *
+ * For path ['users', 0, 'posts', 0, 'title'] with config { users: (fn) => ... }:
+ * - Returns state.users[0] (the user), not state.users[0].posts[0] (the post)
+ * - pathIndex will be 2 (position after the user's numeric index)
+ *
+ * @param path - The full path to the property being modified
+ * @param state - The recorder state containing the root state object
+ * @returns Object with item and pathIndex, or undefined if not inside a tracked array item
+ */
+export function findArrayItemContext(
+	path: PatchPath,
+	state: RecorderState<any>,
+): {item: unknown; pathIndex: number} | undefined {
+	const getItemIdConfig = state.options.getItemId;
+	
+	// If no getItemId config, fall back to finding any numeric index from the end
+	// This maintains backward compatibility for cases without getItemId
+	if (!getItemIdConfig) {
+		return findDeepestArrayItem(path, state);
+	}
+	
+	// Traverse path and config in parallel
+	// Skip numeric indices in the path when traversing the config
+	let currentConfig: GetItemIdConfig | ((item: any) => any) | undefined = getItemIdConfig;
+	
+	for (let i = 0; i < path.length; i++) {
+		const pathKey = path[i];
+		
+		// If we find a numeric index, check if we've found a getItemId function
+		if (typeof pathKey === 'number') {
+			// Check if the previous config level was a function
+			// This means this numeric index is for a tracked array
+			if (typeof currentConfig === 'function') {
+				// Found the tracked item! Navigate to it from root
+				let item: any = state.state;
+				for (let j = 0; j <= i; j++) {
+					const key = path[j] as string | number;
+					item = item[key];
+					if (item === undefined || item === null) return undefined;
+				}
+				// pathIndex is i + 1 (position after the numeric index)
+				return {item, pathIndex: i + 1};
+			}
+			// Not a tracked array, continue to next path segment
+			continue;
+		}
+		
+		// String key - traverse the config
+		if (typeof pathKey === 'string' && currentConfig && typeof currentConfig === 'object') {
+			currentConfig = currentConfig[pathKey];
+		} else if (typeof pathKey === 'string') {
+			// No config at this level, but we still might have a numeric index ahead
+			// Continue without config
+			currentConfig = undefined;
+		}
+	}
+	
+	return undefined;
+}
+
+/**
+ * Fallback function that finds the deepest array item (original behavior).
+ * Used when no getItemId config is provided.
+ */
+function findDeepestArrayItem(
+	path: PatchPath,
+	state: RecorderState<any>,
+): {item: unknown; pathIndex: number} | undefined {
+	for (let i = path.length - 1; i >= 1; i--) {
+		if (typeof path[i] === 'number') {
+			// Found a numeric index - the array item is the object at this position
+			// Navigate from the root state to get the array item
+			let current: any = state.state;
+			for (let j = 0; j <= i; j++) {
+				const pathKey = path[j] as string | number;
+				current = current[pathKey];
+				if (current === undefined || current === null) break;
+			}
+			if (current !== undefined && current !== null) {
+				// pathIndex is i + 1 (the position after the numeric index)
+				// This represents the length of the item path
+				return {item: current, pathIndex: i + 1};
+			}
+			break;
+		}
+	}
+	return undefined;
+}
+
 export function createProxy<T extends object>(
 	target: T,
 	path: PatchPath,
@@ -101,9 +195,20 @@ export function createProxy<T extends object>(
 			// Mutate original immediately
 			(obj as any)[prop] = value;
 
+			// Find array item context for getItemId
+			const itemContext = findArrayItemContext(path, state);
+
 			// Generate patch - use pre-mutation property existence check
 			if (!hadProperty) {
-				generateAddPatch(state, propPath, value);
+				// Check if we're adding a field to an array item (should include id)
+				// vs adding a new item to an array (should NOT include id)
+				if (itemContext) {
+					// Adding a field to an existing array item - include the item id
+					generateAddPatch(state, propPath, value, itemContext.item, itemContext.pathIndex);
+				} else {
+					// Adding a new item to an array or a regular property - no id
+					generateAddPatch(state, propPath, value);
+				}
 			} else if (isArrayType && prop === 'length') {
 				if (state.options.arrayLengthAssignment === false) {
 					// When arrayLengthAssignment is false, generate individual remove patches
@@ -127,8 +232,25 @@ export function createProxy<T extends object>(
 					// Use generateReplacePatch for array length to include oldValue
 					generateReplacePatch(state, propPath, value, oldValue);
 				}
+			} else if (isArrayType && typeof propForPath === 'number') {
+				// Array element replacement - could be:
+				// 1. Top-level tracked array item (state.items[0] = newItem) → NO id
+				// 2. Nested array inside tracked item (state.items[0].tags[1] = 'new') → INCLUDE parent item id
+				if (itemContext) {
+					// Nested array inside a tracked item - include the parent item's id
+					generateSetPatch(state, propPath, value, itemContext.item, itemContext.pathIndex);
+				} else {
+					// Top-level tracked array item replacement - no id
+					generateSetPatch(state, propPath, value);
+				}
+			} else if (itemContext) {
+				// Modifying a field inside an array item (e.g., state.items[0].name = 'new')
+				// or deeply nested (e.g., state.items[0].data.nested.value = 'new')
+				// Pass the array item for id extraction and itemPathIndex
+				generateSetPatch(state, propPath, value, itemContext.item, itemContext.pathIndex);
 			} else {
-				generateSetPatch(state, propPath, oldValue, value);
+				// Regular property modification
+				generateSetPatch(state, propPath, value);
 			}
 
 			return true;
@@ -151,8 +273,17 @@ export function createProxy<T extends object>(
 			if (oldValue !== undefined || Object.prototype.hasOwnProperty.call(obj, prop)) {
 				delete (obj as any)[prop];
 
-				// Generate patch
-				generateDeletePatch(state, propPath, oldValue);
+				// Find array item context for getItemId
+				const itemContext = findArrayItemContext(path, state);
+
+				// Generate patch with item context if we're inside an array item
+				generateDeletePatch(
+					state,
+					propPath,
+					oldValue,
+					itemContext?.item,
+					itemContext?.pathIndex,
+				);
 			}
 
 			return true;

package/src/sets.ts

@@ -1,4 +1,5 @@
 import type {PatchPath, RecorderState} from './types.js';
+import {findArrayItemContext} from './proxy.js';
 import {generateAddPatch, generateDeletePatch} from './patches.js';
 import {cloneIfNeeded} from './utils.js';
 
@@ -28,7 +29,9 @@ export function handleSetGet(
 			// Generate patch only if value didn't exist
 			if (!existed) {
 				const itemPath = [...path, value as any];
-				generateAddPatch(state, itemPath, cloneIfNeeded(value));
+				// Find parent item context if this Set is inside a tracked array item
+				const itemContext = findArrayItemContext(path, state);
+				generateAddPatch(state, itemPath, cloneIfNeeded(value), itemContext?.item, itemContext?.pathIndex);
 			}
 
 			return result;
@@ -43,7 +46,9 @@ export function handleSetGet(
 			// Generate patch only if value existed
 			if (existed) {
 				const itemPath = [...path, value as any];
-				generateDeletePatch(state, itemPath, cloneIfNeeded(value));
+				// Find parent item context if this Set is inside a tracked array item
+				const itemContext = findArrayItemContext(path, state);
+				generateDeletePatch(state, itemPath, cloneIfNeeded(value), itemContext?.item, itemContext?.pathIndex);
 			}
 
 			return result;
@@ -55,10 +60,13 @@ export function handleSetGet(
 			const values = Array.from(obj.values());
 			obj.clear();
 
+			// Find parent item context if this Set is inside a tracked array item
+			const itemContext = findArrayItemContext(path, state);
+
 			// Generate remove patches for all items
 			values.forEach((value) => {
 				const itemPath = [...path, value as any];
-				generateDeletePatch(state, itemPath, cloneIfNeeded(value));
+				generateDeletePatch(state, itemPath, cloneIfNeeded(value), itemContext?.item, itemContext?.pathIndex);
 			});
 		};
 	}

package/src/types.ts

@@ -20,54 +20,109 @@ export type GetItemIdConfig = {
 
 export type PatchPath = (string | number | symbol | object)[];
 
-export type Patch = {
+/**
+ * Item identity information.
+ * Always includes both id and pathIndex together when present.
+ * Use `patch.path.slice(0, patch.pathIndex)` to get the path to the item.
+ */
+interface PatchWithItemId {
+	/**
+	 * ID of the item being modified.
+	 * Populated when getItemId option is configured and a field inside an array item is modified.
+	 */
+	id: string | number;
+	/**
+	 * Index indicating where in the path the item that `id` refers to ends.
+	 *
+	 * @example
+	 * // For path ['items', 0, 'data', 'nested', 'value'] with pathIndex 2
+	 * // The item path is ['items', 0]
+	 */
+	pathIndex: number;
+}
+
+/**
+ * Patch without item identity information.
+ */
+interface PatchWithoutItemId {
+	id?: undefined;
+	pathIndex?: undefined;
+}
+
+/**
+ * Base patch structure shared by all operations
+ */
+interface BasePatch {
 	path: PatchPath;
-	op: PatchOp;
-	value?: any;
+}
+
+/**
+ * Add operation - adding a new value.
+ * Includes item identity when adding a field TO an existing array item (the item is being modified).
+ * Does NOT include item identity when adding a new item to an array.
+ */
+export type AddPatch = BasePatch & {
+	op: typeof Operation.Add;
+	value: any;
+} & (PatchWithItemId | PatchWithoutItemId);
+
+/**
+ * Remove operation - removing a value.
+ * Includes item identity when removing a field FROM an array item (not when removing the item itself).
+ */
+export type RemovePatch = BasePatch & {
+	op: typeof Operation.Remove;
+} & (PatchWithItemId | PatchWithoutItemId);
+
+/**
+ * Replace operation - replacing a value.
+ * Includes oldValue for array length changes.
+ * Includes item identity when modifying a field inside an array item.
+ */
+export type ReplacePatch = BasePatch & {
+	op: typeof Operation.Replace;
+	value: any;
 	/**
-	 * Optional previous value for replace operations on array length.
+	 * Previous value for replace operations on array length.
 	 * Enables consumers to detect how many elements were removed without pre-snapshotting state.
 	 */
 	oldValue?: unknown;
-	/**
-	 * Optional ID of the item being removed or replaced.
-	 * Populated when getItemId option is configured for the item's parent path.
-	 */
-	id?: string | number;
-};
+} & (PatchWithItemId | PatchWithoutItemId);
+
+/**
+ * Union of all patch types.
+ * - AddPatch: Adding new values (no item identity)
+ * - RemovePatch: Removing values (has item identity when removing a field from an item)
+ * - ReplacePatch: Replacing values (has item identity when modifying a field inside an item)
+ */
+export type Patch = AddPatch | RemovePatch | ReplacePatch;
 
 export type Patches = Patch[];
 
 export type NonPrimitive = object | Array<unknown>;
 
 /**
- * Base options shared by all configurations
+ * Configuration options for recordPatches.
  */
-interface BaseRecordPatchesOptions {
+export interface RecordPatchesOptions {
 	/**
 	 * Compress patches by merging redundant operations (default: true)
 	 */
 	compressPatches?: boolean;
-}
-
-/**
- * Options when using getItemId - requires arrayLengthAssignment to be false
- * because length patches cannot include individual item IDs.
- */
-interface RecordPatchesOptionsWithItemId extends BaseRecordPatchesOptions {
 	/**
-	 * Must be false when using getItemId.
-	 * Length patches cannot include individual item IDs.
+	 * Include array length in patches (default: true)
 	 */
-	arrayLengthAssignment: false;
+	arrayLengthAssignment?: boolean;
 	/**
-	 * Configuration for extracting item IDs for remove/replace patches.
+	 * Configuration for extracting item IDs for replace patches on individual items.
 	 * Maps paths to functions that extract IDs from item values.
 	 *
+	 * Note: Item IDs are only included when an item itself is modified (replaced),
+	 * not when items are removed or the array length changes.
+	 *
 	 * @example
 	 * ```typescript
 	 * recordPatches(state, mutate, {
-	 *   arrayLengthAssignment: false,
 	 *   getItemId: {
 	 *     items: (item) => item.id,
 	 *     users: (user) => user.userId,
@@ -78,34 +133,9 @@ interface RecordPatchesOptionsWithItemId extends BaseRecordPatchesOptions {
 	 * });
 	 * ```
 	 */
-	getItemId: GetItemIdConfig;
+	getItemId?: GetItemIdConfig;
 }
 
-/**
- * Options when not using getItemId - arrayLengthAssignment can be any value
- */
-interface RecordPatchesOptionsWithoutItemId extends BaseRecordPatchesOptions {
-	/**
-	 * Include array length in patches (default: true)
-	 */
-	arrayLengthAssignment?: boolean;
-	/**
-	 * Not available unless arrayLengthAssignment is false
-	 */
-	getItemId?: undefined;
-}
-
-/**
- * Configuration options for recordPatches.
- *
- * Note: getItemId requires arrayLengthAssignment: false because length patches
- * (e.g., { op: 'replace', path: ['arr', 'length'], value: 2, oldValue: 3 })
- * cannot include the IDs of individual items that were removed.
- */
-export type RecordPatchesOptions =
-	| RecordPatchesOptionsWithItemId
-	| RecordPatchesOptionsWithoutItemId;
-
 export interface RecorderState<T extends NonPrimitive> {
 	state: T;
 	patches: Patches;

package/src/utils.ts

@@ -173,6 +173,13 @@ export function findGetItemIdFn(
 			continue;
 		}
 
+		// If we already found a function, return it immediately
+		// This handles nested paths like ['items', 0, 'data', 'nested', 'value']
+		// where the config is { items: (item) => item.id }
+		if (typeof current === 'function') {
+			return current as GetItemIdFunction;
+		}
+
 		if (current === undefined || typeof current !== 'object') {
 			return undefined;
 		}