patch-recorder 0.0.0

package/src/optimizer.ts

@@ -0,0 +1,136 @@
+import type {Patches} from './types.js';
+
+/**
+ * Compress patches by merging redundant operations
+ * This handles both consecutive and interleaved operations on the same path
+ */
+export function compressPatches(patches: Patches<true>): Patches<true> {
+	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>();
+
+	for (const patch of patches) {
+		const pathKey = JSON.stringify(patch.path);
+		const existing = pathMap.get(pathKey);
+
+		if (!existing) {
+			// First operation on this path
+			pathMap.set(pathKey, patch);
+			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);
+			}
+		} 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>;
+}
+
+/**
+ * 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 {
+	const op1 = patch1.op;
+	const op2 = patch2.op;
+
+	// Same operations - keep the latest one
+	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)) {
+				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)) {
+			return patch1;
+		}
+		// For remove operations, keep the latest
+		if (op1 === 'remove') {
+			return patch2;
+		}
+	}
+
+	// Different operations
+	if (op1 === 'add' && op2 === 'replace') {
+		// Add then replace - just keep the replace
+		return patch2;
+	}
+
+	if (op1 === 'replace' && op2 === 'replace') {
+		// Replace then replace - keep the latest
+		return patch2;
+	}
+
+	if (op1 === 'replace' && op2 === 'remove') {
+		// Replace then delete - just keep the delete
+		return patch2;
+	}
+
+	if (op1 === 'add' && op2 === 'remove') {
+		// Add then remove - they cancel out
+		return null;
+	}
+
+	if (op1 === 'remove' && op2 === 'add') {
+		// Remove then add - keep the add
+		return patch2;
+	}
+
+	// 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

@@ -0,0 +1,67 @@
+import type {RecorderState} from './types.js';
+import {Operation} from './types.js';
+import {formatPath, cloneIfNeeded} from './utils.js';
+
+/**
+ * Generate a replace patch for property changes
+ */
+export function generateSetPatch(
+	state: RecorderState<any>,
+	path: (string | number)[],
+	oldValue: any,
+	newValue: any,
+) {
+	const patch = {
+		op: Operation.Replace,
+		path: formatPath(path, state.options),
+		value: cloneIfNeeded(newValue),
+	};
+
+	state.patches.push(patch);
+}
+
+/**
+ * Generate a remove patch for property deletions
+ */
+export function generateDeletePatch(
+	state: RecorderState<any>,
+	path: (string | number)[],
+	oldValue: any,
+) {
+	const patch = {
+		op: Operation.Remove,
+		path: formatPath(path, state.options),
+	};
+
+	state.patches.push(patch);
+}
+
+/**
+ * Generate an add patch for new properties
+ */
+export function generateAddPatch(state: RecorderState<any>, path: (string | number)[], value: any) {
+	const patch = {
+		op: Operation.Add,
+		path: formatPath(path, state.options),
+		value: cloneIfNeeded(value),
+	};
+
+	state.patches.push(patch);
+}
+
+/**
+ * Generate a replace patch for full object/array replacement
+ */
+export function generateReplacePatch(
+	state: RecorderState<any>,
+	path: (string | number)[],
+	value: any,
+) {
+	const patch = {
+		op: Operation.Replace,
+		path: formatPath(path, state.options),
+		value: cloneIfNeeded(value),
+	};
+
+	state.patches.push(patch);
+}

package/src/proxy.ts

@@ -0,0 +1,163 @@
+import type {RecorderState} from './types.js';
+import {generateSetPatch, generateDeletePatch, generateAddPatch} from './patches.js';
+import {isArray, isMap, isSet} from './utils.js';
+import {handleArrayGet} from './arrays.js';
+import {handleMapGet} from './maps.js';
+import {handleSetGet} from './sets.js';
+
+export function createProxy<T extends object>(
+	target: T,
+	path: (string | number)[],
+	state: RecorderState<any>,
+): T {
+	const isArrayType = isArray(target);
+	const isMapType = isMap(target);
+	const isSetType = isSet(target);
+
+	const handler: ProxyHandler<T> = {
+		get(obj, prop) {
+			// Handle array methods
+			if (isArrayType && typeof prop === 'string') {
+				return handleArrayGet(obj as any[], prop, path, state);
+			}
+
+			// Handle Map methods
+			if (isMapType) {
+				return handleMapGet(obj as Map<any, any>, prop, path, state);
+			}
+
+			// Handle Set methods
+			if (isSetType) {
+				return handleSetGet(obj as Set<any>, prop, path, state);
+			}
+
+			// Handle property access
+			const value = (obj as any)[prop];
+
+			// Skip creating proxies for primitive values and special cases
+			if (typeof value !== 'object' || value === null) {
+				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;
+		},
+
+		set(obj, prop, value) {
+			// Map and Set don't support direct property assignment
+			if (isMapType || isSetType) {
+				throw new Error('Map/Set draft does not support any property assignment.');
+			}
+
+			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;
+			}
+
+			// 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;
+				}
+			}
+
+			if (currentOriginal && currentOriginal !== undefined && currentOriginal !== null) {
+				originalHasProperty = Object.prototype.hasOwnProperty.call(currentOriginal, prop);
+				originalValue = currentOriginal[prop];
+			}
+
+			// Mutate original immediately
+			(obj as any)[prop] = value;
+
+			// Generate patch
+			if (!originalHasProperty) {
+				generateAddPatch(state, propPath, value);
+			} else {
+				generateSetPatch(state, propPath, originalValue, value);
+			}
+
+			return true;
+		},
+
+		deleteProperty(obj, prop) {
+			if (isArrayType) {
+				// For arrays, delete is equivalent to setting to undefined
+				return handler.set!(obj, prop, undefined, obj);
+			}
+
+			// Map and Set don't support deleteProperty
+			if (isMapType || isSetType) {
+				throw new Error('Map/Set draft does not support deleteProperty.');
+			}
+
+			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)) {
+				delete (obj as any)[prop];
+
+				// Generate patch
+				generateDeletePatch(state, propPath, oldValue);
+			}
+
+			return true;
+		},
+
+		has(obj, prop) {
+			return prop in obj;
+		},
+
+		ownKeys(obj) {
+			return Reflect.ownKeys(obj);
+		},
+
+		getOwnPropertyDescriptor(obj, prop) {
+			const descriptor = Reflect.getOwnPropertyDescriptor(obj, prop);
+			if (!descriptor) return descriptor;
+
+			return {
+				...descriptor,
+				writable: true,
+				configurable: true,
+			};
+		},
+
+		getPrototypeOf(obj) {
+			return Reflect.getPrototypeOf(obj);
+		},
+	};
+
+	return new Proxy(target, handler);
+}

package/src/sets.ts

@@ -0,0 +1,100 @@
+import type {RecorderState} from './types.js';
+import {createProxy} from './proxy.js';
+import {Operation} from './types.js';
+import {generateAddPatch, generateDeletePatch} from './patches.js';
+import {cloneIfNeeded, isSet, isArray} 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>,
+	prop: string | symbol,
+	path: (string | number)[],
+	state: RecorderState<any>,
+): any {
+	// Skip symbol properties
+	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);
+			const result = obj.add(value);
+
+			// Generate patch only if value didn't exist
+			if (!existed) {
+				const itemPath = [...path, value as any];
+				generateAddPatch(state, itemPath, cloneIfNeeded(value));
+			}
+
+			return result;
+		};
+	}
+
+	if (prop === 'delete') {
+		return (value: T) => {
+			const existed = obj.has(value);
+			const result = obj.delete(value);
+
+			// Generate patch only if value existed
+			if (existed) {
+				const itemPath = [...path, value as any];
+				generateDeletePatch(state, itemPath, cloneIfNeeded(value));
+			}
+
+			return result;
+		};
+	}
+
+	if (prop === 'clear') {
+		return () => {
+			const values = Array.from(obj.values());
+			obj.clear();
+
+			// Generate remove patches for all items
+			values.forEach((value) => {
+				const itemPath = [...path, value as any];
+				generateDeletePatch(state, itemPath, cloneIfNeeded(value));
+			});
+		};
+	}
+
+	// Non-mutating methods
+	const nonMutatingMethods = ['has', 'keys', 'values', 'entries', 'forEach'];
+
+	if (nonMutatingMethods.includes(prop)) {
+		return (obj as any)[prop].bind(obj);
+	}
+
+	// Size property
+	if (prop === 'size') {
+		return obj.size;
+	}
+
+	// Return any other property
+	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

@@ -0,0 +1,67 @@
+export const Operation = {
+	Remove: 'remove',
+	Replace: 'replace',
+	Add: 'add',
+} as const;
+
+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;
+	  };
+
+export interface IPatch {
+	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)[];
+			};
+
+export type Patches<P extends PatchesOptions = any> = Patch<P>[];
+
+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)
+	 */
+	arrayLengthAssignment?: boolean;
+	/**
+	 * Optimize patches by merging redundant operations (default: false)
+	 */
+	optimize?: boolean;
+}
+
+export type Draft<T> = T;
+
+export interface RecorderState<T> {
+	original: T;
+	patches: Patches<any>;
+	basePath: (string | number)[];
+	options: RecordPatchesOptions & {internalPatchesOptions: PatchesOptions};
+}

package/src/utils.ts

@@ -0,0 +1,150 @@
+import type {PatchesOptions} from './types.js';
+
+/**
+ * Type guard to check if a value is a plain object (not null, not array, not Map/Set)
+ */
+export function isObject(value: unknown): value is Record<string, unknown> {
+	return (
+		typeof value === 'object' &&
+		value !== null &&
+		!Array.isArray(value) &&
+		!(value instanceof Map) &&
+		!(value instanceof Set)
+	);
+}
+
+/**
+ * Type guard to check if a value is an array
+ */
+export function isArray(value: unknown): value is unknown[] {
+	return Array.isArray(value);
+}
+
+/**
+ * Type guard to check if a value is a Map
+ */
+export function isMap(value: unknown): value is Map<unknown, unknown> {
+	return value instanceof Map;
+}
+
+/**
+ * Type guard to check if a value is a Set
+ */
+export function isSet(value: unknown): value is Set<unknown> {
+	return value instanceof Set;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Check if two values are deeply equal
+ */
+export function isEqual(a: unknown, b: unknown): boolean {
+	if (a === b) return true;
+	if (a == null || b == null) return a === b;
+	if (typeof a !== typeof b) return false;
+
+	if (typeof a === 'object') {
+		if (Array.isArray(a) && Array.isArray(b)) {
+			if (a.length !== b.length) return false;
+			for (let i = 0; i < a.length; i++) {
+				if (!isEqual(a[i], b[i])) return false;
+			}
+			return true;
+		}
+
+		if (a instanceof Map && b instanceof Map) {
+			if (a.size !== b.size) return false;
+			for (const [key, value] of a) {
+				if (!b.has(key) || !isEqual(value, b.get(key))) return false;
+			}
+			return true;
+		}
+
+		if (a instanceof Set && b instanceof Set) {
+			if (a.size !== b.size) return false;
+			for (const value of a) {
+				if (!b.has(value)) return false;
+			}
+			return true;
+		}
+
+		if (Object.keys(a).length !== Object.keys(b).length) return false;
+		for (const key in a) {
+			if (
+				!Object.prototype.hasOwnProperty.call(b, key) ||
+				!isEqual((a as Record<string, unknown>)[key], (b as Record<string, unknown>)[key])
+			) {
+				return false;
+			}
+		}
+		return true;
+	}
+
+	return false;
+}
+
+/**
+ * Deep clone a value if it's an object/array, otherwise return as-is
+ * This is needed for patch values to avoid reference issues
+ */
+export function cloneIfNeeded<T>(value: T): T {
+	if (value === null || typeof value !== 'object') {
+		return value;
+	}
+
+	if (Array.isArray(value)) {
+		return value.map((item) => cloneIfNeeded(item)) as T;
+	}
+
+	if (value instanceof Map) {
+		const clonedMap = new Map();
+		for (const [key, val] of value) {
+			clonedMap.set(cloneIfNeeded(key), cloneIfNeeded(val));
+		}
+		return clonedMap as T;
+	}
+
+	if (value instanceof Set) {
+		const clonedSet = new Set();
+		for (const item of value) {
+			clonedSet.add(cloneIfNeeded(item));
+		}
+		return clonedSet as T;
+	}
+
+	// Plain object
+	const cloned = {} as T;
+	for (const key in value) {
+		if (Object.prototype.hasOwnProperty.call(value, key)) {
+			(cloned as Record<string, unknown>)[key] = cloneIfNeeded(
+				(value as Record<string, unknown>)[key],
+			);
+		}
+	}
+	return cloned;
+}