feat: add in-place deserialize (#320)

* feat: add in-place deserialize

* add issue reference

* update ci

* recommend inplace deserialize

* add more explicit inPlace documentation (#323)

---------

Co-authored-by: Brandon Bayer <b@bayer.ws>

Author: Skn0tt

.github/workflows/main.yml

@@ -6,7 +6,7 @@ jobs:
 
     strategy:
       matrix:
-        node: [20.x, 18.x, 16.x]
+        node: [24.x, 22.x, 20.x, 18.x]
 
     env:
       CI: true
@@ -21,14 +21,6 @@ jobs:
         with:
           node-version: ${{ matrix.node }}
 
-      - name: Use cached node_modules
-        uses: actions/cache@v2
-        with:
-          path: node_modules
-          key: nodeModules-${{ hashFiles('**/yarn.lock') }}
-          restore-keys: |
-            nodeModules-
-
       - name: Install dependencies
         run: yarn install --frozen-lockfile
 

README.md

@@ -198,9 +198,16 @@ Deserializes the output of Superjson back into your original value.
 ```js
 const { json, meta } = serialize(object);
 
-deserialize({ json, meta });
+deserialize({ json, meta }, { inPlace: true });
 ```
 
+Options
+
+- `inPlace: boolean`
+  - Default: `false`
+  - Mutate the input json object in place instead of returning a deep copy
+  - `inPlace: true` will be much more performant on large objects if it's safe to mutate it
+
 Returns **`your original value`**.
 
 ### stringify

src/index.test.ts

@@ -1271,6 +1271,16 @@ test('doesnt iterate to keys that dont exist', () => {
   expect(() => SuperJSON.deserialize(res)).toThrowError('index out of bounds');
 });
 
+// https://github.com/flightcontrolhq/superjson/issues/319
+test('deserialize in place', () => {
+  const serialized = SuperJSON.serialize({ a: new Date() });
+  const deserializedCopy = SuperJSON.deserialize(serialized);
+  const deserializedInPlace = SuperJSON.deserialize(serialized, { inPlace: true });
+  expect(deserializedInPlace).toBe(serialized.json);
+  expect(deserializedCopy).not.toBe(serialized.json);
+  expect(deserializedCopy).toEqual(deserializedInPlace);
+});
+
 test('#310 fixes backwards compat', () => {
   expect(
     SuperJSON.deserialize({

src/index.ts

@@ -60,10 +60,10 @@ export default class SuperJSON {
     return res;
   }
 
-  deserialize<T = unknown>(payload: SuperJSONResult): T {
+  deserialize<T = unknown>(payload: SuperJSONResult, options?: { inPlace?: boolean }): T {
     const { json, meta } = payload;
 
-    let result: T = copy(json) as any;
+    let result: T = options?.inPlace ? json : copy(json) as any;
 
     if (meta?.values) {
       result = applyValueAnnotations(result, meta.values, meta.v ?? 0, this);
@@ -85,7 +85,7 @@ export default class SuperJSON {
   }
 
   parse<T = unknown>(string: string): T {
-    return this.deserialize(JSON.parse(string));
+    return this.deserialize(JSON.parse(string), { inPlace: true });
   }
 
   readonly classRegistry = new ClassRegistry();