patch-recorder 0.0.0 → 0.0.1

package/README.md

@@ -9,7 +9,7 @@
 - ✅ **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
+- ✅ **Optimization enabled by default** - Automatically compresses/merges redundant patches
 - ✅ **Full collection support** - Works with objects, arrays, Maps, and Sets
 
 ## Installation
@@ -55,9 +55,9 @@ Unlike mutative or immer, **patch-recorder mutates the original object in place*
 - 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
+- Substantially faster than mutative (2x to 1,000x depending on operation)
+- Especially dramatic speedups for array index and Map operations
+- Consistent performance improvements across all data types
 
 ```typescript
 // With patch-recorder
@@ -76,7 +76,15 @@ const patches = recordPatches(state, (draft) => {
 
 Records JSON patches from mutations applied to the state.
 
-#### Parameters
+### `create(state, mutate, options?)`
+
+Mutative-compatible API for easy switching between mutative and patch-recorder. Returns `[state, patches]` tuple like mutative does.
+
+**Key difference from mutative:** Unlike mutative which creates a new state copy, this mutates the original object in place. The returned `state` is the same reference as the input state.
+
+**Note:** The `enablePatches` option is forced to `true` by default for full mutative compatibility (patches are always returned).
+
+#### Parameters (both functions)
 
 - **`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
@@ -84,32 +92,25 @@ Records JSON patches from mutations applied to the state.
 
 #### 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;
-}
-```
+For `recordPatches`:
+
+- **`pathAsArray`** (boolean, default: `true`) - Return paths as arrays or strings
+- **`arrayLengthAssignment`** (boolean, default: `true`) - Include array length in patches
+- **`compressPatches`** (boolean, default: `true`) - Compress patches by merging redundant operations
+
+For `create` (additional options for mutative compatibility):
+- **`enablePatches`** (boolean, default: `true`) - Always true, patches are always returned
 
 #### Returns
 
-`Patches<true>` - Array of JSON patches
+- **`recordPatches`**: Returns `Patches<true>` - Array of JSON patches
+- **`create`**: Returns `[T, Patches<true>]` - Tuple of mutated state and patches
 
 ## Usage Examples
 
-### Basic Object Mutations
+### Using `recordPatches`
+
+#### Basic Object Mutations
 
 ```typescript
 const state = { count: 0, name: 'test' };
@@ -208,26 +209,70 @@ console.log(patches);
 // ]
 ```
 
+### Using `create` (Mutative-compatible API)
+
+The `create` function provides the same API as mutative for easy switching:
+
+```typescript
+import {create} from 'patch-recorder';
+
+const state = { user: { name: 'John' } };
+
+const [nextState, patches] = create(state, (draft) => {
+  draft.user.name = 'Jane';
+});
+
+console.log(nextState.user.name); // 'Jane' (mutated in place!)
+console.log(nextState === state); // true (same reference - unlike mutative)
+console.log(patches);
+// [{ op: 'replace', path: ['user', 'name'], value: 'Jane' }]
+```
+
+#### Easy Migration from Mutative
+
+```typescript
+// Before (with mutative)
+import {create} from 'mutative';
+const [newState, patches] = create(state, mutate, {enablePatches: true});
+// newState !== state (mutative creates a copy)
+
+// After (with patch-recorder) - EXACT SAME CODE!
+import {create} from 'patch-recorder';
+const [nextState, patches] = create(state, mutate, {enablePatches: true});
+// nextState === state (patch-recorder mutates in place)
+```
+
+**No code changes needed** - just change the import! The `enablePatches` option is forced to `true` by default, so it's always enabled.
+
 ### Using Options
 
+For `recordPatches`:
+
 ```typescript
 const state = { value: 1 };
 
 // Use string paths instead of arrays
-const patches2 = recordPatches(state, (draft) => {
+const patches = recordPatches(state, (draft) => {
   draft.value = 3;
 }, { pathAsArray: false });
-console.log(patches2);
+console.log(patches);
 // [{ op: 'replace', path: '/value', value: 3 }]
 
-// Optimize patches (merge redundant operations)
-const patches3 = recordPatches(state, (draft) => {
+// Compress patches (merge redundant operations) - enabled by default
+const patches = recordPatches(state, (draft) => {
   draft.value = 4;
   draft.value = 5;
   draft.value = 5; // no-op
-}, { optimize: true });
-console.log(patches3);
+});
+// To disable compression:
+// const patches = recordPatches(state, (draft) => { ... }, { compressPatches: false });
+console.log(patches);
 // [{ op: 'replace', path: ['value'], value: 5 }]
+
+// For create function, you also have to pass enablePatches (it's always true)
+const [nextState, patches] = create(state, (draft) => {
+  draft.value = 5;
+}, { enablePatches: true, pathAsArray: false, compressPatches: true });
 ```
 
 ## Comparison with Mutative
@@ -238,8 +283,27 @@ console.log(patches3);
 | Memory overhead | ❌ Yes (copies) | ✅ No |
 | Patch accuracy | ✅ Excellent | ✅ Excellent |
 | Type safety | ✅ Excellent | ✅ Excellent |
-| API similarity | ✅ Similar | ✅ Similar |
+| API compatibility | - | ✅ `create()` function provides same API |
 | Use case | Immutable state | Mutable with tracking |
+| Performance | Fast | 2-1000x faster |
+
+### Easy Migration
+
+```typescript
+// Switching from mutative to patch-recorder is simple:
+// Just change the import - no other changes needed!
+
+// Before
+import {create} from 'mutative';
+const [nextState, patches] = create(state, mutate, {enablePatches: true});
+
+// After - EXACT SAME CODE!
+import {create} from 'patch-recorder';
+const [nextState, patches] = create(state, mutate, {enablePatches: true});
+
+// Note: patch-recorder mutates in place, so nextState === state
+// If you rely on immutability, you may need to clone before mutation
+```
 
 ### When to Use patch-recorder
 
@@ -326,7 +390,7 @@ npm run benchmark
 ### Optimization Tips
 
 1. **Lazy proxy creation**: Only creates proxies for accessed properties
-2. **Patch compression**: Reduces redundant patches via `optimize` option
+2. **Patch compression**: Reduces redundant patches via `compressPatches` option
 
 ## License
 

package/dist/index.d.ts

@@ -17,5 +17,28 @@ import type { NonPrimitive, Draft, RecordPatchesOptions, Patches } from './types
  * 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>;
+/**
+ * Mutative-compatible API for easy switching between mutative and patch-recorder.
+ * Returns [state, patches] tuple like mutative does.
+ *
+ * Unlike mutative, this mutates the original object in place (state === originalState).
+ * The returned state is the same reference as the input state for API compatibility.
+ *
+ * @param state - The state to mutate and record patches from
+ * @param mutate - A function that receives a draft of the state and applies mutations
+ * @param options - Configuration options (enablePatches is forced but ignored - patches are always returned)
+ * @returns Tuple [state, patches] where state is the mutated state (same reference as input)
+ *
+ * @example
+ * const state = { user: { name: 'John' } };
+ * const [nextState, patches] = create(state, (draft) => {
+ *   draft.user.name = 'Jane';
+ * }, {enabledPatches: true});
+ * console.log(nextState === state); // true (mutated in place!)
+ * console.log(patches); // [{ op: 'replace', path: ['user', 'name'], value: 'Jane' }]
+ */
+export declare function create<T extends NonPrimitive>(state: T, mutate: (state: Draft<T>) => void, options?: RecordPatchesOptions & {
+    enablePatches: true;
+}): [T, Patches<true>];
 export type { NonPrimitive, Draft, RecordPatchesOptions, Patches, Patch, Operation, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +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"}
+{"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;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,MAAM,CAAC,CAAC,SAAS,YAAY,EAC5C,KAAK,EAAE,CAAC,EACR,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,EACjC,OAAO,GAAE,oBAAoB,GAAG;IAAC,aAAa,EAAE,IAAI,CAAA;CAAyB,GAC3E,CAAC,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAKpB;AAGD,YAAY,EACX,YAAY,EACZ,KAAK,EACL,oBAAoB,EACpB,OAAO,EACP,KAAK,EACL,SAAS,GACT,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -35,10 +35,36 @@ export function recordPatches(state, mutate, options = {}) {
     const proxy = createProxy(state, [], recorderState);
     // Apply mutations
     mutate(proxy);
-    // Return patches (optionally optimized)
-    if (options.optimize) {
+    // Return patches (optionally compressed)
+    if (options.compressPatches !== false) {
         return compressPatches(recorderState.patches);
     }
     return recorderState.patches;
 }
+/**
+ * Mutative-compatible API for easy switching between mutative and patch-recorder.
+ * Returns [state, patches] tuple like mutative does.
+ *
+ * Unlike mutative, this mutates the original object in place (state === originalState).
+ * The returned state is the same reference as the input state for API compatibility.
+ *
+ * @param state - The state to mutate and record patches from
+ * @param mutate - A function that receives a draft of the state and applies mutations
+ * @param options - Configuration options (enablePatches is forced but ignored - patches are always returned)
+ * @returns Tuple [state, patches] where state is the mutated state (same reference as input)
+ *
+ * @example
+ * const state = { user: { name: 'John' } };
+ * const [nextState, patches] = create(state, (draft) => {
+ *   draft.user.name = 'Jane';
+ * }, {enabledPatches: true});
+ * console.log(nextState === state); // true (mutated in place!)
+ * console.log(patches); // [{ op: 'replace', path: ['user', 'name'], value: 'Jane' }]
+ */
+export function create(state, mutate, options = { enablePatches: true }) {
+    // Extract enablePatches but ignore it (patches are always returned)
+    const { enablePatches, ...recordPatchesOptions } = options;
+    const patches = recordPatches(state, mutate, recordPatchesOptions);
+    return [state, patches];
+}
 //# sourceMappingURL=index.js.map

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;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"}
+{"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,yCAAyC;IACzC,IAAI,OAAO,CAAC,eAAe,KAAK,KAAK,EAAE,CAAC;QACvC,OAAO,eAAe,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,aAAa,CAAC,OAAwB,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,MAAM,CACrB,KAAQ,EACR,MAAiC,EACjC,UAAwD,EAAC,aAAa,EAAE,IAAI,EAAC;IAE7E,oEAAoE;IACpE,MAAM,EAAC,aAAa,EAAE,GAAG,oBAAoB,EAAC,GAAG,OAAO,CAAC;IACzD,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACnE,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;AACzB,CAAC"}

package/dist/types.d.ts

@@ -39,9 +39,9 @@ export interface RecordPatchesOptions {
      */
     arrayLengthAssignment?: boolean;
     /**
-     * Optimize patches by merging redundant operations (default: false)
+     * Compress patches by merging redundant operations (default: true)
      */
-    optimize?: boolean;
+    compressPatches?: boolean;
 }
 export type Draft<T> = T;
 export interface RecorderState<T> {

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,MAAM,MAAM,cAAc,GACvB,OAAO,GACP;IACA;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEL,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,GAAG,CAAC;CACZ;AAED,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,IAAI,CAAC,SAAS;IAC7D,WAAW,EAAE,KAAK,CAAC;CACnB,GACE,MAAM,GAAG;IACT,IAAI,EAAE,MAAM,CAAC;CACb,GACA,CAAC,SAAS,IAAI,GAAG,MAAM,GACtB,MAAM,GAAG;IACT,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC1B,GACA,MAAM,GAAG;IACT,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CACnC,CAAC;AAEL,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAEjE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;AAEzB,MAAM,WAAW,aAAa,CAAC,CAAC;IAC/B,QAAQ,EAAE,CAAC,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,QAAQ,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC9B,OAAO,EAAE,oBAAoB,GAAG;QAAC,sBAAsB,EAAE,cAAc,CAAA;KAAC,CAAC;CACzE"}
+{"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,MAAM,MAAM,cAAc,GACvB,OAAO,GACP;IACA;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AAEL,MAAM,WAAW,MAAM;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,CAAC,EAAE,GAAG,CAAC;CACZ;AAED,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,IAAI,CAAC,SAAS;IAC7D,WAAW,EAAE,KAAK,CAAC;CACnB,GACE,MAAM,GAAG;IACT,IAAI,EAAE,MAAM,CAAC;CACb,GACA,CAAC,SAAS,IAAI,GAAG,MAAM,GACtB,MAAM,GAAG;IACT,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CAC1B,GACA,MAAM,GAAG;IACT,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;CACnC,CAAC;AAEL,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,cAAc,GAAG,GAAG,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;AAEjE,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;AAEnD,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;OAEG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;OAEG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC;AAEzB,MAAM,WAAW,aAAa,CAAC,CAAC;IAC/B,QAAQ,EAAE,CAAC,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,QAAQ,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC9B,OAAO,EAAE,oBAAoB,GAAG;QAAC,sBAAsB,EAAE,cAAc,CAAA;KAAC,CAAC;CACzE"}

package/package.json

@@ -1,7 +1,7 @@
 {
 	"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.",
+	"version": "0.0.1",
+	"description": "Record JSON patches (RFC 6902) from mutations applied to objects, arrays, Maps, and Sets via a proxy interface.",
 	"keywords": [
 		"patch",
 		"mutable",

package/src/index.ts

@@ -52,14 +52,45 @@ export function recordPatches<T extends NonPrimitive>(
 	// Apply mutations
 	mutate(proxy);
 
-	// Return patches (optionally optimized)
-	if (options.optimize) {
+	// Return patches (optionally compressed)
+	if (options.compressPatches !== false) {
 		return compressPatches(recorderState.patches);
 	}
 
 	return recorderState.patches as Patches<true>;
 }
 
+/**
+ * Mutative-compatible API for easy switching between mutative and patch-recorder.
+ * Returns [state, patches] tuple like mutative does.
+ *
+ * Unlike mutative, this mutates the original object in place (state === originalState).
+ * The returned state is the same reference as the input state for API compatibility.
+ *
+ * @param state - The state to mutate and record patches from
+ * @param mutate - A function that receives a draft of the state and applies mutations
+ * @param options - Configuration options (enablePatches is forced but ignored - patches are always returned)
+ * @returns Tuple [state, patches] where state is the mutated state (same reference as input)
+ *
+ * @example
+ * const state = { user: { name: 'John' } };
+ * const [nextState, patches] = create(state, (draft) => {
+ *   draft.user.name = 'Jane';
+ * }, {enabledPatches: true});
+ * console.log(nextState === state); // true (mutated in place!)
+ * console.log(patches); // [{ op: 'replace', path: ['user', 'name'], value: 'Jane' }]
+ */
+export function create<T extends NonPrimitive>(
+	state: T,
+	mutate: (state: Draft<T>) => void,
+	options: RecordPatchesOptions & {enablePatches: true} = {enablePatches: true},
+): [T, Patches<true>] {
+	// Extract enablePatches but ignore it (patches are always returned)
+	const {enablePatches, ...recordPatchesOptions} = options;
+	const patches = recordPatches(state, mutate, recordPatchesOptions);
+	return [state, patches];
+}
+
 // Re-export types
 export type {
 	NonPrimitive,

package/src/types.ts

@@ -52,9 +52,9 @@ export interface RecordPatchesOptions {
 	 */
 	arrayLengthAssignment?: boolean;
 	/**
-	 * Optimize patches by merging redundant operations (default: false)
+	 * Compress patches by merging redundant operations (default: true)
 	 */
-	optimize?: boolean;
+	compressPatches?: boolean;
 }
 
 export type Draft<T> = T;