fix(commons): prevent deepMerge from mutating source objects

deepMerge mutated source objects when merging arrays because inner
objects/arrays were shared by reference rather than cloned.

Changes:
- handleArrayMerge: replace shallow spread with recursive clone via
  mergeArrayItemsByIndex into a fresh array
- mergeArrayItemsByIndex: clone plain objects via mergeRecursive into
  fresh {}, clone arrays into fresh [], and merge array-to-array by
  index instead of replacing
- Add source immutability unit tests
- Add property-based tests using fast-check

Closes #5196

Author: svozza

package-lock.json

@@ -44,7 +44,8 @@
     "@aws/lambda-invoke-store": "0.2.4"
   },
   "devDependencies": {
-    "@aws-lambda-powertools/testing-utils": "file:../testing"
+    "@aws-lambda-powertools/testing-utils": "file:../testing",
+    "fast-check": "^4.7.0"
   },
   "main": "./lib/cjs/index.js",
   "types": "./lib/cjs/index.d.ts",

packages/commons/package.json

@@ -45,9 +45,35 @@ const mergeArrayItemsByIndex = (
       continue;
     }
 
-    // Otherwise, replace the target item with source item
+    // Merge nested arrays by index
+    if (Array.isArray(srcItem) && Array.isArray(tgtItem)) {
+      if (!ancestors.includes(srcItem)) {
+        ancestors.push(srcItem);
+        mergeArrayItemsByIndex(tgtItem, srcItem, ancestors);
+        ancestors.pop();
+      }
+      continue;
+    }
+
+    // Otherwise, replace the target item with a clone of the source item
     if (srcItem !== undefined || tgtItem === undefined) {
-      targetArray[i] = srcItem;
+      if (isSrcPlainObject) {
+        const cloned: Record<string, unknown> = {};
+        ancestors.push(srcItem);
+        mergeRecursive(cloned, srcItem, ancestors);
+        ancestors.pop();
+        targetArray[i] = cloned;
+      } else if (Array.isArray(srcItem)) {
+        if (!ancestors.includes(srcItem)) {
+          const cloned: unknown[] = [];
+          ancestors.push(srcItem);
+          mergeArrayItemsByIndex(cloned, srcItem, ancestors);
+          ancestors.pop();
+          targetArray[i] = cloned;
+        }
+      } else {
+        targetArray[i] = srcItem;
+      }
     }
   }
 };
@@ -65,7 +91,9 @@ const handleArrayMerge = (
   ancestors: object[]
 ): void => {
   if (!Array.isArray(targetValue)) {
-    target[key] = [...sourceArray];
+    const freshArray: unknown[] = [];
+    mergeArrayItemsByIndex(freshArray, sourceArray, ancestors);
+    target[key] = freshArray;
     return;
   }
 

packages/commons/src/deepMerge.ts

@@ -0,0 +1,86 @@
+import fc from 'fast-check';
+import { describe, expect, it } from 'vitest';
+import { deepMerge } from '../../src/deepMerge.js';
+
+/**
+ * Arbitrary that generates JSON-like plain objects (no class instances,
+ * no circular refs) suitable for deepMerge property tests.
+ */
+const jsonObject = (): fc.Arbitrary<Record<string, unknown>> =>
+  fc.dictionary(
+    fc.string({ minLength: 1, maxLength: 5 }),
+    fc.letrec((tie) => ({
+      value: fc.oneof(
+        { depthSize: 'small' },
+        fc.string(),
+        fc.integer(),
+        fc.boolean(),
+        fc.constant(null),
+        fc.array(tie('value'), { maxLength: 3, depthSize: 'small' }),
+        fc.dictionary(fc.string({ minLength: 1, maxLength: 5 }), tie('value'), {
+          maxKeys: 3,
+        })
+      ),
+    })).value,
+    { maxKeys: 5 }
+  );
+
+describe('deepMerge property tests', () => {
+  it('never mutates source objects', () => {
+    fc.assert(
+      fc.property(
+        fc.array(jsonObject(), { minLength: 1, maxLength: 4 }),
+        (sources) => {
+          const snapshots = sources.map((s) => structuredClone(s));
+
+          deepMerge({}, ...sources);
+
+          for (let i = 0; i < sources.length; i++) {
+            expect(sources[i]).toEqual(snapshots[i]);
+          }
+        }
+      ),
+      { numRuns: 200 }
+    );
+  });
+
+  it('returns the target reference', () => {
+    fc.assert(
+      fc.property(jsonObject(), jsonObject(), (target, source) => {
+        const result = deepMerge(target, source);
+        expect(result).toBe(target);
+      }),
+      { numRuns: 200 }
+    );
+  });
+
+  it('result contains all top-level keys from all sources', () => {
+    fc.assert(
+      fc.property(
+        fc.array(jsonObject(), { minLength: 1, maxLength: 4 }),
+        (sources) => {
+          const result = deepMerge({}, ...sources);
+          const resultKeys = new Set(Object.keys(result));
+
+          for (const source of sources) {
+            for (const key of Object.keys(source)) {
+              expect(resultKeys.has(key)).toBe(true);
+            }
+          }
+        }
+      ),
+      { numRuns: 200 }
+    );
+  });
+
+  it('merging a source into empty object then merging same source again is idempotent', () => {
+    fc.assert(
+      fc.property(jsonObject(), (source) => {
+        const first = deepMerge({}, source);
+        const second = deepMerge(structuredClone(first), source);
+        expect(second).toEqual(first);
+      }),
+      { numRuns: 200 }
+    );
+  });
+});

packages/commons/tests/unit/deepMerge.property.test.ts

@@ -332,6 +332,26 @@ describe('Function: deepMerge', () => {
       expect(result).toHaveProperty('arr[1]', 2);
     });
 
+    it('skips circular arrays nested inside arrays', () => {
+      // Prepare - outer array contains itself as an element
+      const outer: unknown[] = [1, 2];
+      outer.push(outer); // outer[2] = outer (circular)
+      const target = {
+        arr: [
+          [10, 20],
+          [30, 40],
+          [50, 60],
+        ],
+      };
+      const source = { arr: outer };
+
+      // Act
+      const result = deepMerge(target, source);
+
+      // Assess - index 0 and 1 are primitives replacing arrays, index 2 is circular so skipped
+      expect(result).toEqual({ arr: [1, 2, [50, 60]] });
+    });
+
     it('skips array that references an ancestor array', () => {
       // Prepare
       const arr: unknown[] = [];
@@ -556,6 +576,75 @@ describe('Function: deepMerge', () => {
     });
   });
 
+  describe('Source immutability', () => {
+    it('does not mutate sources when merging arrays of objects across multiple sources', () => {
+      // Prepare
+      const source1 = { a: [{ a: 1 }] };
+      const source2 = { a: [{ b: 2 }] };
+
+      // Act
+      const result = deepMerge({}, source1, source2);
+
+      // Assess
+      expect(result).toEqual({ a: [{ a: 1, b: 2 }] });
+      expect(source1).toEqual({ a: [{ a: 1 }] });
+      expect(source2).toEqual({ a: [{ b: 2 }] });
+    });
+
+    it('does not mutate sources when merging nested arrays across multiple sources', () => {
+      // Prepare
+      const src1 = { a: [[1, 2, 3]] };
+      const src2 = { a: [[3, 4]] };
+
+      // Act
+      const result = deepMerge({}, src1, src2);
+
+      // Assess
+      expect(result).toEqual({ a: [[3, 4, 3]] });
+      expect(src1).toEqual({ a: [[1, 2, 3]] });
+      expect(src2).toEqual({ a: [[3, 4]] });
+    });
+
+    it('does not mutate a single source with array of objects merged into empty target', () => {
+      // Prepare
+      const source = { a: [{ x: 1 }, { y: 2 }] };
+
+      // Act
+      const result = deepMerge({}, source);
+      result.a[0].x = 999;
+
+      // Assess
+      expect(source).toEqual({ a: [{ x: 1 }, { y: 2 }] });
+    });
+
+    it('does not mutate sources with plain objects (non-array path)', () => {
+      // Prepare
+      const source1 = { nested: { a: 1 } };
+      const source2 = { nested: { b: 2 } };
+
+      // Act
+      deepMerge({}, source1, source2);
+
+      // Assess
+      expect(source1).toEqual({ nested: { a: 1 } });
+      expect(source2).toEqual({ nested: { b: 2 } });
+    });
+
+    it('does not mutate sources with mixed arrays and nested objects', () => {
+      // Prepare
+      const source1 = { data: [{ items: [{ id: 1 }] }] };
+      const source2 = { data: [{ items: [{ name: 'a' }] }] };
+
+      // Act
+      const result = deepMerge({}, source1, source2);
+
+      // Assess
+      expect(result).toEqual({ data: [{ items: [{ id: 1, name: 'a' }] }] });
+      expect(source1).toEqual({ data: [{ items: [{ id: 1 }] }] });
+      expect(source2).toEqual({ data: [{ items: [{ name: 'a' }] }] });
+    });
+  });
+
   describe('Edge cases', () => {
     it('handles Date objects (treats as value, not merged)', () => {
       // Prepare