patch-recorder 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Ronan Sandford
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# patch-recorder
+
+> Record JSON patches (RFC 6902) from mutations applied to objects, arrays, Maps, and Sets via a proxy interface.
+
+## Features
+
+- ✅ **Reference integrity** - Original object reference maintained (mutates in place)
+- ✅ **Zero memory overhead** - No copying of large arrays/objects
+- ✅ **Accurate patches** - JSON Patch (RFC 6902) compliant
+- ✅ **Type safety** - Full TypeScript support
+- ✅ **Immediate patch generation** - Patches generated as mutations occur
+- ✅ **Optional optimization** - Can compress/merge redundant patches
+- ✅ **Full collection support** - Works with objects, arrays, Maps, and Sets
+
+## Installation
+
+```bash
+npm install patch-recorder
+# or
+pnpm add patch-recorder
+# or
+yarn add patch-recorder
+```
+
+## Quick Start
+
+```typescript
+import {recordPatches} from 'patch-recorder';
+
+const state = {
+  user: { name: 'John', age: 30 },
+  items: [1, 2, 3]
+};
+
+const patches = recordPatches(state, (draft) => {
+  draft.user.name = 'Jane';
+  draft.items.push(4);
+});
+
+console.log(state.user.name); // 'Jane' (mutated in place!)
+console.log(patches);
+// [
+//   { op: 'replace', path: ['user', 'name'], value: 'Jane' },
+//   { op: 'add', path: ['items', 3], value: 4 }
+// ]
+```
+
+## Core Difference from Mutative/Immer
+
+Unlike mutative or immer, **patch-recorder mutates the original object in place** while recording changes. This is its primary advantage:
+
+**Reference Integrity:**
+- **Zero memory overhead** from copying objects
+- **Original object references are preserved** throughout the operation
+- Perfect for scenarios where you need both mutation tracking AND direct object manipulation
+
+**Performance:**
+- Similar performance to mutative for most operations
+- Slightly faster for object and Map operations
+- Comparable performance for large array operations
+
+```typescript
+// With patch-recorder
+const state = { user: { name: 'John' } };
+const patches = recordPatches(state, (draft) => {
+  draft.user.name = 'Jane';
+});
+
+// state === originalState (same reference)
+// state.user.name === 'Jane'
+```
+
+## API
+
+### `recordPatches(state, mutate, options?)`
+
+Records JSON patches from mutations applied to the state.
+
+#### Parameters
+
+- **`state`** (`T extends NonPrimitive`): The state object to mutate and record patches from
+- **`mutate`** `(state: Draft<T>) => void`: Callback function that performs mutations on the draft
+- **`options`** (`RecordPatchesOptions`, optional): Configuration options
+
+#### Options
+
+```typescript
+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;
+}
+```
+
+#### Returns
+
+`Patches<true>` - Array of JSON patches
+
+## Usage Examples
+
+### Basic Object Mutations
+
+```typescript
+const state = { count: 0, name: 'test' };
+
+const patches = recordPatches(state, (draft) => {
+  draft.count = 5;
+  draft.name = 'updated';
+});
+
+console.log(patches);
+// [
+//   { op: 'replace', path: ['count'], value: 5 },
+//   { op: 'replace', path: ['name'], value: 'updated' }
+// ]
+```
+
+### Nested Object Mutations
+
+```typescript
+const state = {
+  user: {
+    profile: {
+      name: 'John',
+      age: 30
+    }
+  }
+};
+
+const patches = recordPatches(state, (draft) => {
+  draft.user.profile.name = 'Jane';
+  draft.user.profile.age = 31;
+});
+
+console.log(patches);
+// [
+//   { op: 'replace', path: ['user', 'profile', 'name'], value: 'Jane' },
+//   { op: 'replace', path: ['user', 'profile', 'age'], value: 31 }
+// ]
+```
+
+### Array Operations
+
+```typescript
+const state = { items: [1, 2, 3] };
+
+const patches = recordPatches(state, (draft) => {
+  draft.items.push(4);           // add
+  draft.items[1] = 10;           // replace
+  draft.items.shift();           // remove
+});
+
+console.log(patches);
+// [
+//   { op: 'add', path: ['items', 3], value: 4 },
+//   { op: 'replace', path: ['items', 1], value: 10 },
+//   { op: 'remove', path: ['items', 0] },
+//   { op: 'replace', path: ['items', 0], value: 2 },
+//   { op: 'replace', path: ['items', 1], value: 3 },
+//   { op: 'replace', path: ['items', 'length'], value: 3 }
+// ]
+```
+
+### Map Operations
+
+```typescript
+const state = { map: new Map([['a', 1]]) };
+
+const patches = recordPatches(state, (draft) => {
+  draft.map.set('b', 2);         // add
+  draft.map.set('a', 10);        // replace
+  draft.map.delete('b');         // remove
+});
+
+console.log(patches);
+// [
+//   { op: 'add', path: ['map', 'b'], value: 2 },
+//   { op: 'replace', path: ['map', 'a'], value: 10 },
+//   { op: 'remove', path: ['map', 'b'] }
+// ]
+```
+
+### Set Operations
+
+```typescript
+const state = { set: new Set([1, 2]) };
+
+const patches = recordPatches(state, (draft) => {
+  draft.set.add(3);              // add
+  draft.set.delete(2);           // remove
+});
+
+console.log(patches);
+// [
+//   { op: 'add', path: ['set', 3], value: 3 },
+//   { op: 'remove', path: ['set', 2] }
+// ]
+```
+
+### Using Options
+
+```typescript
+const state = { value: 1 };
+
+// Use string paths instead of arrays
+const patches2 = recordPatches(state, (draft) => {
+  draft.value = 3;
+}, { pathAsArray: false });
+console.log(patches2);
+// [{ op: 'replace', path: '/value', value: 3 }]
+
+// Optimize patches (merge redundant operations)
+const patches3 = recordPatches(state, (draft) => {
+  draft.value = 4;
+  draft.value = 5;
+  draft.value = 5; // no-op
+}, { optimize: true });
+console.log(patches3);
+// [{ op: 'replace', path: ['value'], value: 5 }]
+```
+
+## Comparison with Mutative
+
+| Feature | Mutative | patch-recorder |
+|---------|----------|----------------|
+| Reference preservation | ❌ No (creates copy) | ✅ Yes (mutates in place) |
+| Memory overhead | ❌ Yes (copies) | ✅ No |
+| Patch accuracy | ✅ Excellent | ✅ Excellent |
+| Type safety | ✅ Excellent | ✅ Excellent |
+| API similarity | ✅ Similar | ✅ Similar |
+| Use case | Immutable state | Mutable with tracking |
+
+### When to Use patch-recorder
+
+Use **patch-recorder** when you need:
+- To mutate state in place while tracking changes
+- Zero memory overhead from copying
+- To preserve object references
+- To integrate with systems that require direct mutation
+
+Use **mutative** when you need:
+- Immutable state management
+- To create new state versions
+- Functional programming patterns
+
+## Performance
+
+patch-recorder provides substantial performance improvements over mutative while maintaining **reference integrity** as its key differentiator. When properly benchmarking just the mutation operations (excluding state creation), patch-recorder shows dramatic speedups:
+
+### Benchmark Results
+
+| Operation | Mutative | patch-recorder | Speedup |
+|-----------|----------|----------------|---------|
+| Simple object mutation | 0.0272ms | 0.0110ms | **2.48x** |
+| Medium nested object | 0.0268ms | 0.0114ms | **2.35x** |
+| Large nested object | 0.0094ms | 0.0040ms | **2.38x** |
+| Array push (100k elements) | 3.277ms | 1.155ms | **2.84x** |
+| Array index (100k elements) | 2.966ms | 0.004ms | **826x** |
+| Map operations (100k entries) | 11.384ms | 0.011ms | **1,067x** |
+
+**Memory Usage:**
+- **Mutative**: Creates copies (memory overhead proportional to state size)
+- **patch-recorder**: 0 MB overhead (mutates in place, no copying)
+
+### Performance Analysis
+
+The benchmark results reveal patch-recorder's massive advantage for operations that would require copying large data structures:
+
+- **Object mutations** (2.35-2.48x faster) - Consistent speedups due to simpler proxy overhead
+- **Array push** (2.84x faster) - Avoids copying entire arrays on mutation
+- **Array index assignment** (826x faster) - **Massive speedup** by not copying 100k-element arrays
+- **Map operations** (1,067x faster) - **Incredible speedup** by not copying 100k-entry Maps
+
+**Why the dramatic differences?**
+- patch-recorder mutates in place, so array index assignment and Map operations don't require copying
+- mutative's copy-on-write approach is elegant but incurs significant overhead for large collections
+- The advantage scales with data size - the larger the collection, the bigger the speedup
+
+**Note on mutative's performance:** Mutative is impressively fast for object mutations and offers excellent immutability guarantees. Its speedups of 2-3x for objects are reasonable trade-offs for immutable state management.
+
+### Run Benchmarks
+
+You can run the benchmarks locally:
+
+```bash
+npm run benchmark
+```
+
+### Memory Usage
+
+- **No copying**: Original object mutated in place
+- **Patch storage**: Only patches array stored (minimal overhead)
+- **Proxy creation**: One proxy per object accessed during mutation
+
+### Time Complexity
+
+- **Property access**: O(1) for direct access, O(1) for proxy
+- **Property mutation**: O(1) + patch generation
+- **Array operations**: O(n) for some operations (same as native)
+- **Nested mutations**: O(depth) for proxy creation
+
+### When to Choose patch-recorder
+
+**Choose patch-recorder if you need:**
+- **Reference integrity** - Objects and arrays maintain their identity
+- **Zero memory overhead** - No copying of state
+- **Direct mutation** - Mutate in place while tracking changes
+- **Integration with mutable systems** - Systems that require direct object manipulation
+
+**Choose mutative if you need:**
+- **Immutable state** - Create new state versions
+- **Functional programming patterns** - Prefer immutability
+- **State versioning** - Need to track multiple state versions
+
+### Optimization Tips
+
+1. **Lazy proxy creation**: Only creates proxies for accessed properties
+2. **Patch compression**: Reduces redundant patches via `optimize` option
+
+## License
+
+MIT © [Ronan Sandford](https://github.com/wighawag)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/dist/arrays.d.ts

@@ -0,0 +1,6 @@
+import type { RecorderState } from './types.js';
+/**
+ * Handle array method calls and property access
+ */
+export declare function handleArrayGet(obj: any[], prop: string, path: (string | number)[], state: RecorderState<any>): any;
+//# sourceMappingURL=arrays.d.ts.map

package/dist/arrays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.d.ts","sourceRoot":"","sources":["../src/arrays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAK9C;;GAEG;AACH,wBAAgB,cAAc,CAC7B,GAAG,EAAE,GAAG,EAAE,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACzB,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,GACvB,GAAG,CA2DL"}

package/dist/arrays.js

@@ -0,0 +1,143 @@
+import { generateAddPatch, generateDeletePatch, generateReplacePatch } from './patches.js';
+import { createProxy } from './proxy.js';
+/**
+ * Handle array method calls and property access
+ */
+export function handleArrayGet(obj, prop, path, state) {
+    // Mutating methods
+    const mutatingMethods = ['push', 'pop', 'shift', 'unshift', 'splice', 'sort', 'reverse'];
+    if (mutatingMethods.includes(prop)) {
+        return (...args) => {
+            const oldValue = [...obj]; // Snapshot before mutation
+            const result = Array.prototype[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[prop].bind(obj);
+    }
+    // Property access
+    if (prop === 'length') {
+        return obj.length;
+    }
+    const value = obj[prop];
+    // 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, obj, method, args, result, path, oldValue) {
+    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;
+        }
+    }
+}
+//# sourceMappingURL=arrays.js.map

package/dist/arrays.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrays.js","sourceRoot":"","sources":["../src/arrays.ts"],"names":[],"mappings":"AAEA,OAAO,EAAC,gBAAgB,EAAE,mBAAmB,EAAE,oBAAoB,EAAC,MAAM,cAAc,CAAC;AACzF,OAAO,EAAC,WAAW,EAAC,MAAM,YAAY,CAAC;AAEvC;;GAEG;AACH,MAAM,UAAU,cAAc,CAC7B,GAAU,EACV,IAAY,EACZ,IAAyB,EACzB,KAAyB;IAEzB,mBAAmB;IACnB,MAAM,eAAe,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;IAEzF,IAAI,eAAe,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,GAAG,IAAW,EAAE,EAAE;YACzB,MAAM,QAAQ,GAAG,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,2BAA2B;YACtD,MAAM,MAAM,GAAI,KAAK,CAAC,SAAiB,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAE/D,uCAAuC;YACvC,oBAAoB,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;YAErE,OAAO,MAAM,CAAC;QACf,CAAC,CAAC;IACH,CAAC;IAED,6DAA6D;IAC7D,MAAM,kBAAkB,GAAG;QAC1B,KAAK;QACL,QAAQ;QACR,QAAQ;QACR,aAAa;QACb,SAAS;QACT,MAAM;QACN,WAAW;QACX,MAAM;QACN,OAAO;QACP,UAAU;QACV,SAAS;QACT,aAAa;QACb,OAAO;QACP,QAAQ;QACR,MAAM;QACN,MAAM;QACN,SAAS;QACT,IAAI;KACJ,CAAC;IAEF,IAAI,kBAAkB,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACvC,OAAQ,KAAK,CAAC,SAAiB,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjD,CAAC;IAED,kBAAkB;IAClB,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACvB,OAAO,GAAG,CAAC,MAAM,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,GAAG,CAAC,IAAW,CAAC,CAAC;IAE/B,gFAAgF;IAChF,2DAA2D;IAC3D,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACzE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;IACpD,CAAC;IAED,2DAA2D;IAC3D,+EAA+E;IAC/E,OAAO,KAAK,CAAC;AACd,CAAC;AAED;;GAEG;AACH,SAAS,oBAAoB,CAC5B,KAAyB,EACzB,GAAU,EACV,MAAc,EACd,IAAW,EACX,MAAW,EACX,IAAyB,EACzB,QAAe;IAEf,QAAQ,MAAM,EAAE,CAAC;QAChB,KAAK,MAAM,CAAC,CAAC,CAAC;YACb,4CAA4C;YAC5C,MAAM,UAAU,GAAG,QAAQ,CAAC,MAAM,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;gBACzB,MAAM,KAAK,GAAG,UAAU,GAAG,CAAC,CAAC;gBAC7B,gBAAgB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,KAAK,CAAC,CAAC;YAClD,CAAC,CAAC,CAAC;YAEH,6CAA6C;YAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;gBACnD,oBAAoB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM;QACP,CAAC;QAED,KAAK,KAAK,CAAC,CAAC,CAAC;YACZ,gDAAgD;YAChD,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;YACzC,mBAAmB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;YAE5D,6CAA6C;YAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;gBACnD,oBAAoB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM;QACP,CAAC;QAED,KAAK,OAAO,CAAC,CAAC,CAAC;YACd,gDAAgD;YAChD,mBAAmB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;YAEjD,8DAA8D;YAC9D,iFAAiF;YACjF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACrC,oBAAoB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC5D,CAAC;YAED,6CAA6C;YAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;gBACnD,oBAAoB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC9D,CAAC;YACD,MAAM;QACP,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YAChB,oCAAoC;YACpC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE;gBACzB,gBAAgB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;YAC9C,CAAC,CAAC,CAAC;YAEH,+BAA+B;YAE/B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC1C,oBAAoB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACtE,CAAC;YAED,6CAA6C;YAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;gBACnD,oBAAoB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC9D,CAAC;YAED,MAAM;QACP,CAAC;QAED,KAAK,QAAQ,CAAC,CAAC,CAAC;YACf,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,QAAQ,CAAC,GAAG,IAAI,CAAC;YAE/C,4CAA4C;YAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,mBAAmB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;YAC/D,CAAC;YAED,qCAAqC;YACrC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;gBAC5B,gBAAgB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;YACrD,CAAC,CAAC,CAAC;YAEH,yEAAyE;YAEzE,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,GAAG,KAAK,GAAG,WAAW,CAAC;YAC3D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,YAAY,EAAE,CAAC,EAAE,EAAE,CAAC;gBACvC,oBAAoB,CACnB,KAAK,EACL,CAAC,GAAG,IAAI,EAAE,KAAK,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,EACtC,QAAQ,CAAC,KAAK,GAAG,WAAW,GAAG,CAAC,CAAC,CACjC,CAAC;YACH,CAAC;YAED,6CAA6C;YAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;gBACnD,oBAAoB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAC9D,CAAC;YAED,MAAM;QACP,CAAC;QAED,KAAK,MAAM,CAAC;QACZ,KAAK,SAAS,CAAC,CAAC,CAAC;YAChB,yDAAyD;YACzD,oBAAoB,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;YAC5C,MAAM;QACP,CAAC;IACF,CAAC;AACF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { NonPrimitive, Draft, RecordPatchesOptions, Patches } 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 declare function recordPatches<T extends NonPrimitive>(state: T, mutate: (state: Draft<T>) => void, options?: RecordPatchesOptions): Patches<true>;
+export type { NonPrimitive, Draft, RecordPatchesOptions, Patches, Patch, Operation, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,YAAY,EACZ,KAAK,EACL,oBAAoB,EACpB,OAAO,EAGP,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,YAAY,EACnD,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,EACjC,OAAO,GAAE,oBAAyB,GAChC,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAGD,YAAY,EACX,YAAY,EACZ,KAAK,EACL,oBAAoB,EACpB,OAAO,EACP,KAAK,EACL,SAAS,GACT,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,44 @@
+import { createProxy } from './proxy.js';
+import { compressPatches } from './optimizer.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(state, mutate, options = {}) {
+    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);
+    // Apply mutations
+    mutate(proxy);
+    // Return patches (optionally optimized)
+    if (options.optimize) {
+        return compressPatches(recorderState.patches);
+    }
+    return recorderState.patches;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,WAAW,EAAC,MAAM,YAAY,CAAC;AACvC,OAAO,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAU/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAC5B,KAAQ,EACR,MAAiC,EACjC,UAAgC,EAAE;IAElC,MAAM,sBAAsB,GAAG;QAC9B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,qBAAqB,EAAE,OAAO,CAAC,qBAAqB,IAAI,IAAI;KAC5D,CAAC;IAEF,MAAM,aAAa,GAAG;QACrB,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE;YACR,GAAG,OAAO;YACV,sBAAsB;SACtB;KACD,CAAC;IAEF,eAAe;IACf,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,aAAa,CAAa,CAAC;IAEhE,kBAAkB;IAClB,MAAM,CAAC,KAAK,CAAC,CAAC;IAEd,wCAAwC;IACxC,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtB,OAAO,eAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,aAAa,CAAC,OAAwB,CAAC;AAC/C,CAAC"}

package/dist/maps.d.ts

@@ -0,0 +1,7 @@
+import type { RecorderState } from './types.js';
+/**
+ * Handle property access on Map objects
+ * Wraps mutating methods (set, delete, clear) to generate patches
+ */
+export declare function handleMapGet<K = any, V = any>(obj: Map<K, V>, prop: string | symbol, path: (string | number)[], state: RecorderState<any>): any;
+//# sourceMappingURL=maps.d.ts.map

package/dist/maps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"maps.d.ts","sourceRoot":"","sources":["../src/maps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,YAAY,CAAC;AAM9C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,EAC5C,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EACd,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACzB,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,GACvB,GAAG,CAqFL"}