patch-recorder 0.0.0

package/dist/utils.d.ts

@@ -0,0 +1,33 @@
+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 declare function isObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Type guard to check if a value is an array
+ */
+export declare function isArray(value: unknown): value is unknown[];
+/**
+ * Type guard to check if a value is a Map
+ */
+export declare function isMap(value: unknown): value is Map<unknown, unknown>;
+/**
+ * Type guard to check if a value is a Set
+ */
+export declare function isSet(value: unknown): value is Set<unknown>;
+/**
+ * Format a path array to either array format or JSON Pointer string format
+ */
+export declare function formatPath(path: (string | number)[], options: {
+    internalPatchesOptions: PatchesOptions;
+}): string | (string | number)[];
+/**
+ * Check if two values are deeply equal
+ */
+export declare function isEqual(a: unknown, b: unknown): boolean;
+/**
+ * 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 declare function cloneIfNeeded<T>(value: T): T;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,YAAY,CAAC;AAE/C;;GAEG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzE;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,EAAE,CAE1D;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAEpE;AAED;;GAEG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,GAAG,CAAC,OAAO,CAAC,CAE3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CACzB,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACzB,OAAO,EAAE;IAAC,sBAAsB,EAAE,cAAc,CAAA;CAAC,GAC/C,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAkB9B;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CA2CvD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAmC5C"}

package/dist/utils.js

@@ -0,0 +1,132 @@
+/**
+ * Type guard to check if a value is a plain object (not null, not array, not Map/Set)
+ */
+export function isObject(value) {
+    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) {
+    return Array.isArray(value);
+}
+/**
+ * Type guard to check if a value is a Map
+ */
+export function isMap(value) {
+    return value instanceof Map;
+}
+/**
+ * Type guard to check if a value is a Set
+ */
+export function isSet(value) {
+    return value instanceof Set;
+}
+/**
+ * Format a path array to either array format or JSON Pointer string format
+ */
+export function formatPath(path, options) {
+    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, b) {
+    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[key], b[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(value) {
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => cloneIfNeeded(item));
+    }
+    if (value instanceof Map) {
+        const clonedMap = new Map();
+        for (const [key, val] of value) {
+            clonedMap.set(cloneIfNeeded(key), cloneIfNeeded(val));
+        }
+        return clonedMap;
+    }
+    if (value instanceof Set) {
+        const clonedSet = new Set();
+        for (const item of value) {
+            clonedSet.add(cloneIfNeeded(item));
+        }
+        return clonedSet;
+    }
+    // Plain object
+    const cloned = {};
+    for (const key in value) {
+        if (Object.prototype.hasOwnProperty.call(value, key)) {
+            cloned[key] = cloneIfNeeded(value[key]);
+        }
+    }
+    return cloned;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "patch-recorder",
+	"version": "0.0.0",
+	"description": "Record JSON patches (RFC 6902) from mutations applied to objects, arrays, Maps, and Sets via a proxy interface. Mutates the original object in place while recording changes, preserving object references and avoiding memory and computational overhead from copying.",
+	"keywords": [
+		"patch",
+		"mutable",
+		"record",
+		"typescript",
+		"type-safe",
+		"lightweight",
+		"minimal"
+	],
+	"author": "Ronan Sandford",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/wighawag/patch-recorder.git"
+	},
+	"homepage": "https://github.com/wighawag/patch-recorder#readme",
+	"bugs": {
+		"url": "https://github.com/wighawag/patch-recorder/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"sideEffects": false,
+	"devDependencies": {
+		"@types/node": "^25.0.10",
+		"as-soon": "^0.1.5",
+		"mutative": "^1.3.0",
+		"prettier": "^3.8.0",
+		"tsx": "^4.21.0",
+		"typescript": "^5.3.3",
+		"vitest": "^2.1.8"
+	},
+	"scripts": {
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"build": "tsc",
+		"dev": "as-soon -w src pnpm build",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"benchmark": "tsx benchmark/index.ts"
+	}
+}

package/src/arrays.ts

@@ -0,0 +1,191 @@
+import type {RecorderState} from './types.js';
+import {Operation} from './types.js';
+import {generateAddPatch, generateDeletePatch, generateReplacePatch} from './patches.js';
+import {createProxy} from './proxy.js';
+
+/**
+ * Handle array method calls and property access
+ */
+export function handleArrayGet(
+	obj: any[],
+	prop: string,
+	path: (string | number)[],
+	state: RecorderState<any>,
+): any {
+	// Mutating methods
+	const mutatingMethods = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'];
+
+	if (mutatingMethods.includes(prop)) {
+		return (...args: any[]) => {
+			const oldValue = [...obj]; // Snapshot before mutation
+			const result = (Array.prototype as any)[prop].apply(obj, args);
+
+			// Generate patches based on the method
+			generateArrayPatches(state, obj, prop, args, result, path, oldValue);
+
+			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)) {
+		return (Array.prototype as any)[prop].bind(obj);
+	}
+
+	// Property access
+	if (prop === 'length') {
+		return obj.length;
+	}
+
+	const value = obj[prop as any];
+
+	// For numeric properties (array indices), check if the value is an object/array
+	// If so, return a proxy to enable nested mutation tracking
+	if (!isNaN(Number(prop)) && typeof value === 'object' && value !== null) {
+		const index = Number(prop);
+		return createProxy(value, [...path, index], state);
+	}
+
+	// For numeric properties (array indices), return the value
+	// The main proxy handler's get will handle creating proxies for nested objects
+	return value;
+}
+
+/**
+ * Generate patches for array mutations
+ */
+function generateArrayPatches(
+	state: RecorderState<any>,
+	obj: any[],
+	method: string,
+	args: any[],
+	result: any,
+	path: (string | number)[],
+	oldValue: any[],
+) {
+	switch (method) {
+		case 'push': {
+			// Generate add patches for each new element
+			const startIndex = oldValue.length;
+			args.forEach((value, i) => {
+				const index = startIndex + i;
+				generateAddPatch(state, [...path, index], value);
+			});
+
+			// Generate length patch if option is enabled
+			if (state.options.arrayLengthAssignment !== false) {
+				generateReplacePatch(state, [...path, 'length'], obj.length);
+			}
+			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);
+			}
+			break;
+		}
+
+		case 'shift': {
+			// Generate remove patch for 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
+			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]);
+			}
+
+			// 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],
+				);
+			}
+
+			// Generate length patch if option is enabled
+			if (state.options.arrayLengthAssignment !== false) {
+				generateReplacePatch(state, [...path, 'length'], obj.length);
+			}
+
+			break;
+		}
+
+		case 'sort':
+		case 'reverse': {
+			// These reorder the entire array - generate full replace
+			generateReplacePatch(state, path, [...obj]);
+			break;
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,71 @@
+import {createProxy} from './proxy.js';
+import {compressPatches} from './optimizer.js';
+import type {
+	NonPrimitive,
+	Draft,
+	RecordPatchesOptions,
+	Patches,
+	Patch,
+	Operation,
+} from './types.js';
+
+/**
+ * Record JSON patches from mutations applied to an object, array, Map, or Set.
+ * Unlike mutative or immer, this mutates the original object in place while recording changes.
+ *
+ * @param state - The state to record patches from
+ * @param mutate - A function that receives a draft of the state and applies mutations
+ * @param options - Configuration options
+ * @returns Array of JSON patches (RFC 6902 compliant)
+ *
+ * @example
+ * const state = { user: { name: 'John' } };
+ * const patches = recordPatches(state, (draft) => {
+ *   draft.user.name = 'Jane';
+ * });
+ * console.log(state.user.name); // 'Jane' (mutated in place!)
+ * console.log(patches); // [{ op: 'replace', path: ['user', 'name'], value: 'Jane' }]
+ */
+export function recordPatches<T extends NonPrimitive>(
+	state: T,
+	mutate: (state: Draft<T>) => void,
+	options: RecordPatchesOptions = {},
+): Patches<true> {
+	const internalPatchesOptions = {
+		pathAsArray: options.pathAsArray ?? true,
+		arrayLengthAssignment: options.arrayLengthAssignment ?? true,
+	};
+
+	const recorderState = {
+		original: state,
+		patches: [],
+		basePath: [],
+		options: {
+			...options,
+			internalPatchesOptions,
+		},
+	};
+
+	// Create proxy
+	const proxy = createProxy(state, [], recorderState) as Draft<T>;
+
+	// Apply mutations
+	mutate(proxy);
+
+	// Return patches (optionally optimized)
+	if (options.optimize) {
+		return compressPatches(recorderState.patches);
+	}
+
+	return recorderState.patches as Patches<true>;
+}
+
+// Re-export types
+export type {
+	NonPrimitive,
+	Draft,
+	RecordPatchesOptions,
+	Patches,
+	Patch,
+	Operation,
+} from './types.js';

package/src/maps.ts

@@ -0,0 +1,120 @@
+import type {RecorderState} from './types.js';
+import {createProxy} from './proxy.js';
+import {Operation} from './types.js';
+import {generateAddPatch, generateDeletePatch, generateReplacePatch} from './patches.js';
+import {cloneIfNeeded, isMap, isArray} from './utils.js';
+
+/**
+ * Handle property access on Map objects
+ * Wraps mutating methods (set, delete, clear) to generate patches
+ */
+export function handleMapGet<K = any, V = any>(
+	obj: Map<K, V>,
+	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 === 'set') {
+		return (key: K, value: V) => {
+			// Check if key existed BEFORE mutation
+			const existed = keyExistsInOriginal(state.original, path, key);
+			const oldValue = obj.get(key);
+			const result = obj.set(key, value);
+
+			// Generate patch
+			const itemPath = [...path, key as any];
+
+			if (existed) {
+				// Key exists - replace
+				generateReplacePatch(state, itemPath, cloneIfNeeded(value));
+			} else {
+				// Key doesn't exist - add
+				generateAddPatch(state, itemPath, cloneIfNeeded(value));
+			}
+
+			return result;
+		};
+	}
+
+	if (prop === 'delete') {
+		return (key: K) => {
+			const oldValue = obj.get(key);
+			const result = obj.delete(key);
+
+			if (result) {
+				const itemPath = [...path, key as any];
+				generateDeletePatch(state, itemPath, cloneIfNeeded(oldValue));
+			}
+
+			return result;
+		};
+	}
+
+	if (prop === 'clear') {
+		return () => {
+			const entries = Array.from(obj.entries());
+			obj.clear();
+
+			// Generate remove patches for all items
+			entries.forEach(([key, value]) => {
+				const itemPath = [...path, key as any];
+				generateDeletePatch(state, itemPath, cloneIfNeeded(value));
+			});
+		};
+	}
+
+	// Non-mutating methods
+	if (prop === 'get') {
+		return (key: K) => {
+			const value = obj.get(key);
+
+			// If the value is a Map, Array, or object, return a proxy
+			if (value != null && typeof value === 'object') {
+				if (isMap(value) || isArray(value)) {
+					return createProxy(value, [...path, key as any], state);
+				}
+			}
+
+			return value;
+		};
+	}
+
+	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 Map at the given path and check if a key exists
+ * This is needed to check if a key existed before mutations
+ */
+function keyExistsInOriginal(original: any, path: (string | number)[], key: any): boolean {
+	let current = original;
+	for (const part of path) {
+		if (current == null) return false;
+		current = current[part];
+	}
+
+	// If we reached a Map, check if the key exists
+	if (current instanceof Map) {
+		return current.has(key);
+	}
+
+	return false;
+}