patch-recorder 0.2.2 → 0.3.0

package/README.md

@@ -90,9 +90,9 @@ Records JSON patches from mutations applied to the state.
 #### Options
 
 
-- **`arrayLengthAssignment`** (boolean, default: `true`) - When `true`, includes length patches when array shrinks (pop, shift, splice delete). When `false`, omits length patches entirely. Aligned with mutative's behavior.
+- **`arrayLengthAssignment`** (boolean, default: `true`) - When `true`, includes length patches when array shrinks (pop, shift, splice delete). When `false`, omits length patches entirely. Must be `false` when using `getItemId`. Aligned with mutative's behavior.
 - **`compressPatches`** (boolean, default: `true`) - Compress patches by merging redundant operations
-- **`getItemId`** (object, optional) - Configuration for extracting item IDs (see [Item ID Tracking](#item-id-tracking))
+- **`getItemId`** (object, optional) - Configuration for extracting item IDs. **Requires `arrayLengthAssignment: false`**. (see [Item ID Tracking](#item-id-tracking))
 
 
 #### Returns
@@ -227,6 +227,10 @@ console.log(patches);
 
 When working with arrays, the patch path only tells you the index, not which item was affected. The `getItemId` option allows you to include item IDs in `remove` and `replace` patches, making it easier to track which items changed.
 
+**Important:** `getItemId` requires `arrayLengthAssignment: false` because length patches (e.g., `{ op: 'replace', path: ['arr', 'length'], value: 2 }`) cannot include individual item IDs. This is enforced at both compile time and runtime.
+
+**Note:** When `arrayLengthAssignment: false`, direct array length assignment (`arr.length = N`) generates individual remove/add patches instead of a length patch, allowing proper item ID tracking.
+
 ```typescript
 const state = {
   users: [
@@ -239,6 +243,7 @@ const state = {
 const patches = recordPatches(state, (state) => {
   state.users.splice(1, 1); // Remove Bob
 }, {
+  arrayLengthAssignment: false,  // Required when using getItemId
   getItemId: {
     users: (user) => user.id  // Extract ID from each user
   }
@@ -255,6 +260,7 @@ The `getItemId` option is an object that mirrors your data structure:
 
 ```typescript
 recordPatches(state, mutate, {
+  arrayLengthAssignment: false,  // Required when using getItemId
   getItemId: {
     // Top-level arrays
     items: (item) => item.id,
@@ -288,6 +294,7 @@ const state = {
 const patches = recordPatches(state, (state) => {
   state.entityMap.delete('key1');
 }, {
+  arrayLengthAssignment: false,  // Required when using getItemId
   getItemId: {
     entityMap: (entity) => entity.internalId
   }

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,YAAY,EAAE,oBAAoB,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC5B,CAAC,SAAS,YAAY,EACtB,aAAa,SAAS,oBAAoB,GAAG,EAAE,EAC9C,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAuBxE;AAGD,YAAY,EAAC,YAAY,EAAE,oBAAoB,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,YAAY,EAAE,oBAAoB,EAAE,OAAO,EAAC,MAAM,YAAY,CAAC;AAE5E;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAC5B,CAAC,SAAS,YAAY,EACtB,aAAa,SAAS,oBAAoB,GAAG,EAAE,EAC9C,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CA6BxE;AAGD,YAAY,EAAC,YAAY,EAAE,oBAAoB,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAC,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -18,13 +18,16 @@ import { compressPatches } from './optimizer.js';
  * console.log(patches); // [{ op: 'replace', path: ['user', 'name'], value: 'Jane' }]
  */
 export function recordPatches(state, mutate, options) {
+    // Runtime validation: getItemId requires arrayLengthAssignment: false
+    if (options?.getItemId && options?.arrayLengthAssignment !== false) {
+        throw new Error('getItemId requires arrayLengthAssignment: false. ' +
+            'Length patches cannot include individual item IDs.');
+    }
     const recorderState = {
         state,
         patches: [],
         basePath: [],
-        options: {
-            ...options,
-        },
+        options: options ?? {},
         proxyCache: new WeakMap(),
     };
     // Create proxy

package/dist/index.js.map

@@ -1 +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;AAG/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAG3B,KAAQ,EAAE,MAA0B,EAAE,OAAuB;IAC9D,MAAM,aAAa,GAAG;QACrB,KAAK;QACL,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE;YACR,GAAG,OAAO;SACV;QACD,UAAU,EAAE,IAAI,OAAO,EAAE;KACzB,CAAC;IAEF,eAAe;IACf,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,aAAa,CAAM,CAAC;IAEzD,kBAAkB;IAClB,MAAM,CAAC,KAAK,CAAC,CAAC;IAEd,yCAAyC;IACzC,IAAI,OAAO,EAAE,eAAe,KAAK,KAAK,EAAE,CAAC;QACxC,OAAO,eAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,aAAa,CAAC,OAAkB,CAAC;AACzC,CAAC"}
+{"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;AAG/C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,aAAa,CAG3B,KAAQ,EAAE,MAA0B,EAAE,OAAuB;IAC9D,sEAAsE;IACtE,IAAI,OAAO,EAAE,SAAS,IAAI,OAAO,EAAE,qBAAqB,KAAK,KAAK,EAAE,CAAC;QACpE,MAAM,IAAI,KAAK,CACd,mDAAmD;YAClD,oDAAoD,CACrD,CAAC;IACH,CAAC;IAED,MAAM,aAAa,GAAG;QACrB,KAAK;QACL,OAAO,EAAE,EAAE;QACX,QAAQ,EAAE,EAAE;QACZ,OAAO,EAAE,OAAO,IAAI,EAAE;QACtB,UAAU,EAAE,IAAI,OAAO,EAAE;KACzB,CAAC;IAEF,eAAe;IACf,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,EAAE,EAAE,EAAE,aAAa,CAAM,CAAC;IAEzD,kBAAkB;IAClB,MAAM,CAAC,KAAK,CAAC,CAAC;IAEd,yCAAyC;IACzC,IAAI,OAAO,EAAE,eAAe,KAAK,KAAK,EAAE,CAAC;QACxC,OAAO,eAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,aAAa,CAAC,OAAkB,CAAC;AACzC,CAAC"}

package/dist/proxy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,YAAY,CAAC;AAOzD,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC3C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,GACvB,CAAC,CA2IH"}
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAE,aAAa,EAAC,MAAM,YAAY,CAAC;AAYzD,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,EAC3C,MAAM,EAAE,CAAC,EACT,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,GACvB,CAAC,CA8KH"}

package/dist/proxy.js

@@ -1,4 +1,4 @@
-import { generateSetPatch, generateDeletePatch, generateAddPatch, generateReplacePatch } from './patches.js';
+import { generateSetPatch, generateDeletePatch, generateAddPatch, generateReplacePatch, } from './patches.js';
 import { isArray, isMap, isSet } from './utils.js';
 import { handleArrayGet } from './arrays.js';
 import { handleMapGet } from './maps.js';
@@ -58,6 +58,20 @@ export function createProxy(target, path, state) {
             if (Object.is(oldValue, value) && (value !== undefined || actuallyHasProperty)) {
                 return true;
             }
+            // Special handling for array length with arrayLengthAssignment: false
+            // Must capture removed items BEFORE mutation
+            let removedItems = null;
+            if (isArrayType && prop === 'length' && state.options.arrayLengthAssignment === false) {
+                const arr = obj;
+                const newLength = value;
+                if (newLength < oldValue) {
+                    // Capture items that will be removed before mutation
+                    removedItems = [];
+                    for (let i = newLength; i < oldValue; i++) {
+                        removedItems.push(arr[i]);
+                    }
+                }
+            }
             // Mutate original immediately
             obj[prop] = value;
             // Generate patch - use pre-mutation property existence check
@@ -65,8 +79,29 @@ export function createProxy(target, path, state) {
                 generateAddPatch(state, propPath, value);
             }
             else if (isArrayType && prop === 'length') {
-                // Use generateReplacePatch for array length to include oldValue
-                generateReplacePatch(state, propPath, value, oldValue);
+                if (state.options.arrayLengthAssignment === false) {
+                    // When arrayLengthAssignment is false, generate individual remove patches
+                    // for each removed item (in reverse order)
+                    const newLength = value;
+                    if (removedItems) {
+                        // Array was shrinking - generate remove patches for removed items
+                        // Iterate in reverse to generate patches from end to start
+                        for (let i = removedItems.length - 1; i >= 0; i--) {
+                            const index = newLength + i;
+                            generateDeletePatch(state, [...path, index], removedItems[i]);
+                        }
+                    }
+                    else if (newLength > oldValue) {
+                        // Array is growing - generate add patches for new undefined slots
+                        for (let i = oldValue; i < newLength; i++) {
+                            generateAddPatch(state, [...path, i], undefined);
+                        }
+                    }
+                }
+                else {
+                    // Use generateReplacePatch for array length to include oldValue
+                    generateReplacePatch(state, propPath, value, oldValue);
+                }
             }
             else {
                 generateSetPatch(state, propPath, oldValue, value);

package/dist/proxy.js.map

@@ -1 +1 @@
-{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AACA,OAAO,EACN,gBAAgB,EAChB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAC,OAAO,EAAE,KAAK,EAAE,KAAK,EAAC,MAAM,YAAY,CAAC;AACjD,OAAO,EAAC,cAAc,EAAC,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAC,YAAY,EAAC,MAAM,WAAW,CAAC;AACvC,OAAO,EAAC,YAAY,EAAC,MAAM,WAAW,CAAC;AAEvC,MAAM,UAAU,WAAW,CAC1B,MAAS,EACT,IAAe,EACf,KAAyB;IAEzB,oBAAoB;IACpB,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,MAAM,EAAE,CAAC;QACZ,OAAO,MAAM,CAAC;IACf,CAAC;IAED,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAChC,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;IAEhC,MAAM,OAAO,GAAoB;QAChC,GAAG,CAAC,GAAG,EAAE,IAAI;YACZ,uBAAuB;YACvB,IAAI,WAAW,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7C,OAAO,cAAc,CAAC,GAAY,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACxD,CAAC;YAED,qBAAqB;YACrB,IAAI,SAAS,EAAE,CAAC;gBACf,OAAO,YAAY,CAAC,GAAoB,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YAC9D,CAAC;YAED,qBAAqB;YACrB,IAAI,SAAS,EAAE,CAAC;gBACf,OAAO,YAAY,CAAC,GAAe,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YACzD,CAAC;YAED,yBAAyB;YACzB,MAAM,KAAK,GAAI,GAAW,CAAC,IAAI,CAAC,CAAC;YAEjC,+DAA+D;YAC/D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACjD,OAAO,KAAK,CAAC;YACd,CAAC;YAED,+CAA+C;YAC/C,OAAO,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;QACnD,CAAC;QAED,GAAG,CAAC,GAAG,EAAE,IAAI,EAAE,KAAK;YACnB,uDAAuD;YACvD,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;YAC5E,CAAC;YAED,MAAM,QAAQ,GAAI,GAAW,CAAC,IAAI,CAAC,CAAC;YAEpC,4DAA4D;YAC5D,MAAM,WAAW,GAAG,OAAO,IAAI,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YAC3F,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,WAAW,CAAC,CAAC;YAExC,0DAA0D;YAC1D,MAAM,mBAAmB,GAAG,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAE5E,gEAAgE;YAChE,qDAAqD;YACrD,IAAI,WAAW,GAAG,mBAAmB,CAAC;YACtC,IAAI,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ,EAAE,CAAC;gBACpD,WAAW,GAAG,WAAW,IAAI,CAAC,IAAI,WAAW,GAAI,GAAa,CAAC,MAAM,CAAC;YACvE,CAAC;YAED,+DAA+D;YAC/D,wFAAwF;YACxF,8FAA8F;YAC9F,IAAI,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,mBAAmB,CAAC,EAAE,CAAC;gBAChF,OAAO,IAAI,CAAC;YACb,CAAC;YAED,sEAAsE;YACtE,6CAA6C;YAC7C,IAAI,YAAY,GAAiB,IAAI,CAAC;YACtC,IAAI,WAAW,IAAI,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;gBACvF,MAAM,GAAG,GAAG,GAAY,CAAC;gBACzB,MAAM,SAAS,GAAG,KAAe,CAAC;gBAClC,IAAI,SAAS,GAAG,QAAQ,EAAE,CAAC;oBAC1B,qDAAqD;oBACrD,YAAY,GAAG,EAAE,CAAC;oBAClB,KAAK,IAAI,CAAC,GAAG,SAAS,EAAE,CAAC,GAAG,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;wBAC3C,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;oBAC3B,CAAC;gBACF,CAAC;YACF,CAAC;YAED,8BAA8B;YAC7B,GAAW,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;YAE3B,6DAA6D;YAC7D,IAAI,CAAC,WAAW,EAAE,CAAC;gBAClB,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC1C,CAAC;iBAAM,IAAI,WAAW,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7C,IAAI,KAAK,CAAC,OAAO,CAAC,qBAAqB,KAAK,KAAK,EAAE,CAAC;oBACnD,0EAA0E;oBAC1E,2CAA2C;oBAC3C,MAAM,SAAS,GAAG,KAAe,CAAC;oBAElC,IAAI,YAAY,EAAE,CAAC;wBAClB,kEAAkE;wBAClE,2DAA2D;wBAC3D,KAAK,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;4BACnD,MAAM,KAAK,GAAG,SAAS,GAAG,CAAC,CAAC;4BAC5B,mBAAmB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC/D,CAAC;oBACF,CAAC;yBAAM,IAAI,SAAS,GAAG,QAAQ,EAAE,CAAC;wBACjC,kEAAkE;wBAClE,KAAK,IAAI,CAAC,GAAG,QAAQ,EAAE,CAAC,GAAG,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;4BAC3C,gBAAgB,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;wBAClD,CAAC;oBACF,CAAC;gBACF,CAAC;qBAAM,CAAC;oBACP,gEAAgE;oBAChE,oBAAoB,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;gBACxD,CAAC;YACF,CAAC;iBAAM,CAAC;gBACP,gBAAgB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;YACpD,CAAC;YAED,OAAO,IAAI,CAAC;QACb,CAAC;QAED,cAAc,CAAC,GAAG,EAAE,IAAI;YACvB,IAAI,WAAW,EAAE,CAAC;gBACjB,2DAA2D;gBAC3D,OAAO,OAAO,CAAC,GAAI,CAAC,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;YAChD,CAAC;YAED,2CAA2C;YAC3C,IAAI,SAAS,IAAI,SAAS,EAAE,CAAC;gBAC5B,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;YACnE,CAAC;YAED,MAAM,QAAQ,GAAI,GAAW,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,EAAE,IAAI,CAAC,CAAC;YAEjC,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC;gBAC/E,OAAQ,GAAW,CAAC,IAAI,CAAC,CAAC;gBAE1B,iBAAiB;gBACjB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;YAChD,CAAC;YAED,OAAO,IAAI,CAAC;QACb,CAAC;QAED,GAAG,CAAC,GAAG,EAAE,IAAI;YACZ,OAAO,IAAI,IAAI,GAAG,CAAC;QACpB,CAAC;QAED,OAAO,CAAC,GAAG;YACV,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QAED,wBAAwB,CAAC,GAAG,EAAE,IAAI;YACjC,MAAM,UAAU,GAAG,OAAO,CAAC,wBAAwB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC/D,IAAI,CAAC,UAAU;gBAAE,OAAO,UAAU,CAAC;YAEnC,OAAO;gBACN,GAAG,UAAU;gBACb,QAAQ,EAAE,IAAI;gBACd,YAAY,EAAE,IAAI;aAClB,CAAC;QACH,CAAC;QAED,cAAc,CAAC,GAAG;YACjB,OAAO,OAAO,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;KACD,CAAC;IAEF,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEzC,iBAAiB;IACjB,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAEpC,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/types.d.ts

@@ -32,15 +32,25 @@ export type Patch = {
 };
 export type Patches = Patch[];
 export type NonPrimitive = object | Array<unknown>;
-export interface RecordPatchesOptions {
-    /**
-     * Include array length in patches (default: true)
-     */
-    arrayLengthAssignment?: boolean;
+/**
+ * Base options shared by all configurations
+ */
+interface BaseRecordPatchesOptions {
     /**
      * 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.
+     */
+    arrayLengthAssignment: false;
     /**
      * Configuration for extracting item IDs for remove/replace patches.
      * Maps paths to functions that extract IDs from item values.
@@ -48,6 +58,7 @@ export interface RecordPatchesOptions {
      * @example
      * ```typescript
      * recordPatches(state, mutate, {
+     *   arrayLengthAssignment: false,
      *   getItemId: {
      *     items: (item) => item.id,
      *     users: (user) => user.userId,
@@ -58,8 +69,29 @@ export interface RecordPatchesOptions {
      * });
      * ```
      */
-    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;
@@ -70,4 +102,5 @@ export interface RecorderState<T extends NonPrimitive> {
      */
     proxyCache: WeakMap<object, any>;
 }
+export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;CAIZ,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,eAAe,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAE9D,MAAM,MAAM,KAAK,GAAG;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC;AAE9B,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC5B;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,YAAY;IACpD,KAAK,EAAE,CAAC,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,SAAS;;;;CAIZ,CAAC;AAEX,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,OAAO,SAAS,CAAC,CAAC;AAEjE;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnF;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,iBAAiB,GAAG,eAAe,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAE9D,MAAM,MAAM,KAAK,GAAG;IACnB,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,KAAK,EAAE,CAAC;AAE9B,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;AAEnD;;GAEG;AACH,UAAU,wBAAwB;IACjC;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;GAGG;AACH,UAAU,8BAA+B,SAAQ,wBAAwB;IACxE;;;OAGG;IACH,qBAAqB,EAAE,KAAK,CAAC;IAC7B;;;;;;;;;;;;;;;;;OAiBG;IACH,SAAS,EAAE,eAAe,CAAC;CAC3B;AAED;;GAEG;AACH,UAAU,iCAAkC,SAAQ,wBAAwB;IAC3E;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,oBAAoB,GAC7B,8BAA8B,GAC9B,iCAAiC,CAAC;AAErC,MAAM,WAAW,aAAa,CAAC,CAAC,SAAS,YAAY;IACpD,KAAK,EAAE,CAAC,CAAC;IACT,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,SAAS,CAAC;IACpB,OAAO,EAAE,oBAAoB,CAAC;IAC9B;;OAEG;IACH,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "patch-recorder",
-	"version": "0.2.2",
+	"version": "0.3.0",
 	"description": "Record JSON patches (RFC 6902) from mutations applied to objects, arrays, Maps, and Sets via a proxy interface.",
 	"keywords": [
 		"patch",

package/src/index.ts

@@ -23,13 +23,19 @@ export function recordPatches<
 	T extends NonPrimitive,
 	PatchesOption extends RecordPatchesOptions = {},
 >(state: T, mutate: (state: T) => void, options?: PatchesOption): Patches {
+	// Runtime validation: getItemId requires arrayLengthAssignment: false
+	if (options?.getItemId && options?.arrayLengthAssignment !== false) {
+		throw new Error(
+			'getItemId requires arrayLengthAssignment: false. ' +
+				'Length patches cannot include individual item IDs.',
+		);
+	}
+
 	const recorderState = {
 		state,
 		patches: [],
 		basePath: [],
-		options: {
-			...options,
-		},
+		options: options ?? {},
 		proxyCache: new WeakMap(),
 	};
 

package/src/proxy.ts

@@ -1,5 +1,10 @@
 import type {PatchPath, RecorderState} from './types.js';
-import {generateSetPatch, generateDeletePatch, generateAddPatch, generateReplacePatch} from './patches.js';
+import {
+	generateSetPatch,
+	generateDeletePatch,
+	generateAddPatch,
+	generateReplacePatch,
+} from './patches.js';
 import {isArray, isMap, isSet} from './utils.js';
 import {handleArrayGet} from './arrays.js';
 import {handleMapGet} from './maps.js';
@@ -78,6 +83,21 @@ export function createProxy<T extends object>(
 				return true;
 			}
 
+			// Special handling for array length with arrayLengthAssignment: false
+			// Must capture removed items BEFORE mutation
+			let removedItems: any[] | null = null;
+			if (isArrayType && prop === 'length' && state.options.arrayLengthAssignment === false) {
+				const arr = obj as any[];
+				const newLength = value as number;
+				if (newLength < oldValue) {
+					// Capture items that will be removed before mutation
+					removedItems = [];
+					for (let i = newLength; i < oldValue; i++) {
+						removedItems.push(arr[i]);
+					}
+				}
+			}
+
 			// Mutate original immediately
 			(obj as any)[prop] = value;
 
@@ -85,8 +105,28 @@ export function createProxy<T extends object>(
 			if (!hadProperty) {
 				generateAddPatch(state, propPath, value);
 			} else if (isArrayType && prop === 'length') {
-				// Use generateReplacePatch for array length to include oldValue
-				generateReplacePatch(state, propPath, value, oldValue);
+				if (state.options.arrayLengthAssignment === false) {
+					// When arrayLengthAssignment is false, generate individual remove patches
+					// for each removed item (in reverse order)
+					const newLength = value as number;
+
+					if (removedItems) {
+						// Array was shrinking - generate remove patches for removed items
+						// Iterate in reverse to generate patches from end to start
+						for (let i = removedItems.length - 1; i >= 0; i--) {
+							const index = newLength + i;
+							generateDeletePatch(state, [...path, index], removedItems[i]);
+						}
+					} else if (newLength > oldValue) {
+						// Array is growing - generate add patches for new undefined slots
+						for (let i = oldValue; i < newLength; i++) {
+							generateAddPatch(state, [...path, i], undefined);
+						}
+					}
+				} else {
+					// Use generateReplacePatch for array length to include oldValue
+					generateReplacePatch(state, propPath, value, oldValue);
+				}
 			} else {
 				generateSetPatch(state, propPath, oldValue, value);
 			}

package/src/types.ts

@@ -40,15 +40,26 @@ export type Patches = Patch[];
 
 export type NonPrimitive = object | Array<unknown>;
 
-export interface RecordPatchesOptions {
-	/**
-	 * Include array length in patches (default: true)
-	 */
-	arrayLengthAssignment?: boolean;
+/**
+ * Base options shared by all configurations
+ */
+interface BaseRecordPatchesOptions {
 	/**
 	 * 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.
+	 */
+	arrayLengthAssignment: false;
 	/**
 	 * Configuration for extracting item IDs for remove/replace patches.
 	 * Maps paths to functions that extract IDs from item values.
@@ -56,6 +67,7 @@ export interface RecordPatchesOptions {
 	 * @example
 	 * ```typescript
 	 * recordPatches(state, mutate, {
+	 *   arrayLengthAssignment: false,
 	 *   getItemId: {
 	 *     items: (item) => item.id,
 	 *     users: (user) => user.userId,
@@ -66,9 +78,34 @@ export interface RecordPatchesOptions {
 	 * });
 	 * ```
 	 */
-	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;