patch-recorder 0.0.1 → 0.2.0

package/src/types.ts

@@ -6,47 +6,36 @@ 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
+ */
+export type GetItemIdFunction = (value: any) => string | number | undefined | null;
 
-export interface IPatch {
+/**
+ * Recursive configuration for getItemId - can be a function or nested object
+ */
+export type GetItemIdConfig = {
+	[key: string]: GetItemIdFunction | GetItemIdConfig;
+};
+
+export type PatchPath = (string | number | symbol | object)[];
+
+export type Patch = {
+	path: PatchPath;
 	op: PatchOp;
 	value?: any;
-}
-
-export type Patch<P extends PatchesOptions = any> = P extends {
-	pathAsArray: false;
-}
-	? IPatch & {
-			path: string;
-		}
-	: P extends true | object
-		? IPatch & {
-				path: (string | number)[];
-			}
-		: IPatch & {
-				path: string | (string | number)[];
-			};
+	/**
+	 * 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 Patches<P extends PatchesOptions = any> = 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)
 	 */
@@ -55,13 +44,35 @@ 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;
+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>;
 }

package/src/utils.ts

@@ -1,4 +1,4 @@
-import type {PatchesOptions} from './types.js';
+import type {GetItemIdConfig, GetItemIdFunction, PatchPath} from './types.js';
 
 /**
  * Type guard to check if a value is a plain object (not null, not array, not Map/Set)
@@ -37,27 +37,12 @@ export function isSet(value: unknown): value is Set<unknown> {
 /**
  * Format a path array to either array format or JSON Pointer string format
  */
-export function formatPath(
-	path: (string | number)[],
-	options: {internalPatchesOptions: PatchesOptions},
-): string | (string | number)[] {
-	if (
-		options.internalPatchesOptions &&
-		typeof options.internalPatchesOptions === 'object' &&
-		options.internalPatchesOptions.pathAsArray === false
-	) {
-		// Convert to JSON Pointer string format
-		return path
-			.map((part) => {
-				if (typeof part === 'number') {
-					return String(part);
-				}
-				return '/' + String(part).replace(/~/g, '~0').replace(/\//g, '~1');
-			})
-			.join('');
-	}
-
-	return path;
+export function formatPath(path: PatchPath): string {
+	// Convert to JSON Pointer string format (RFC 6901)
+	if (path.length === 0) {
+		return '';
+	}
+	return '/' + path.map((part) => String(part).replace(/~/g, '~0').replace(/\//g, '~1')).join('/');
 }
 
 /**
@@ -148,3 +133,123 @@ export function cloneIfNeeded<T>(value: T): T {
 	}
 	return cloned;
 }
+
+/**
+ * Find a getItemId function for a given path.
+ * The function is looked up by traversing the getItemId config object
+ * using the parent path (all elements except the last one).
+ *
+ * @example
+ * // For path ['items', 3] with config { items: (item) => item.id }
+ * // Returns the function (item) => item.id
+ */
+export function findGetItemIdFn(
+	path: PatchPath,
+	getItemIdConfig: GetItemIdConfig | undefined,
+): GetItemIdFunction | undefined {
+	if (!getItemIdConfig || path.length === 0) {
+		return undefined;
+	}
+
+	// We want to match the parent path (all elements except the last one)
+	// For path ['items', 3], we want to find config at 'items'
+	// For path ['user', 'settings', 'darkMode'], we want to find config at ['user', 'settings']
+	const parentPath = path.slice(0, -1);
+
+	if (parentPath.length === 0) {
+		// The path is directly under root (e.g., ['items'])
+		// In this case, there's no parent to match against
+		return undefined;
+	}
+
+	// Navigate the config object using the parent path
+	let current: GetItemIdConfig | GetItemIdFunction | undefined = getItemIdConfig;
+
+	for (let i = 0; i < parentPath.length; i++) {
+		const key = parentPath[i];
+
+		// Skip numeric indices (array positions) in the path
+		if (typeof key === 'number') {
+			continue;
+		}
+
+		if (current === undefined || typeof current !== 'object') {
+			return undefined;
+		}
+
+		if (typeof key === 'object' || typeof key === 'symbol') {
+			// there is no way to match an object or symbol key in the config
+			return undefined;
+		}
+
+		current = (current as GetItemIdConfig)[key];
+	}
+
+	// current should now be a function or undefined
+	if (typeof current === 'function') {
+		return current as GetItemIdFunction;
+	}
+
+	return undefined;
+}
+
+/**
+ * Convert a path array or string to a string key for optimized lookup.
+ * Uses null character (\x00) as delimiter since it's unlikely in property names.
+ * This is significantly faster than JSON.stringify for the common case.
+ *
+ * @param path - The path array or string to convert
+ * @returns A string key representation of the path
+ */
+export function pathToKey(path: PatchPath): string {
+	// If path is already a string, use it directly
+	if (typeof path === 'string') {
+		return path;
+	}
+	// Otherwise convert array to string
+	if (path.length === 0) {
+		return '';
+	}
+	if (path.length === 1) {
+		const elem = path[0];
+		if (typeof elem === 'symbol') {
+			return elem.toString();
+		}
+		if (typeof elem === 'object') {
+			return JSON.stringify(elem);
+		}
+		return String(elem);
+	}
+	return path.map((elem) => {
+		if (typeof elem === 'symbol') {
+			return elem.toString();
+		}
+		if (typeof elem === 'object') {
+			return JSON.stringify(elem);
+		}
+		return String(elem);
+	}).join('\x00');
+}
+
+/**
+ * Convert a string key back to a path array.
+ * This is the inverse of pathToKey.
+ *
+ * @param key - The string key to convert
+ * @returns The path array
+ */
+export function keyToPath(key: string): (string | number)[] {
+	if (key === '') {
+		return [];
+	}
+	if (key.indexOf('\x00') === -1) {
+		// No delimiter, single element
+		// Try to parse as number for consistency
+		const num = Number(key);
+		return isNaN(num) ? [key] : [num];
+	}
+	return key.split('\x00').map((part) => {
+		const num = Number(part);
+		return isNaN(num) ? part : num;
+	});
+}