@superhero/deep 4.1.0 → 4.3.0

package/README.md

@@ -101,7 +101,40 @@ console.log(clone === obj) // false
 
 ---
 
-## 5. **Deep**
+## 5. **DeepIntersect**
+
+### Purpose:
+Performs a deep intersection between two or more values. Supports objects, arrays, and nested structures, and handles circular references. Values are strictly compared when considered intersecting.
+
+### Features:
+- Intersects arrays by values.
+- Intersects objects only when the key exists in all sources and the values intersect deeply.
+- Preserves intersected restrictive property descriptors (`writable`, `configurable`, `enumerable`).
+- Detects and throws on circular references.
+
+### Example:
+```javascript
+import deepintersect from '@superhero/deep/intersect'
+
+const a = { foo: { bar: 1 }, arr: [1, 2, 3] }
+const b = { foo: { bar: 1, baz: 2 }, arr: [1, 4, 3] }
+
+const result = deepintersect(a, b)
+
+console.log(result)
+// { foo: { bar: 1 }, arr: [1, 3] }
+```
+
+#### Note:
+- If two values are loosely equal, but of different types, they do not intersect.
+
+- Arrays with nested objects can only be compared if the nested structure shares the same index between the compared arrays.
+
+- A circular structure throws a CircularReferenceError (ReferenceError) with the code `E_DEEP_INTERSECT_CIRCULAR_REFERENCE`.
+
+---
+
+## 6. **Deep**
 
 ### Purpose:
 Makes the functions accessible through the imported default object.
@@ -117,16 +150,18 @@ import deep from '@superhero/deep'
 deep.assign(/* ... */)
 deep.clone(/* ... */)
 deep.freeze(/* ... */)
+deep.intersect(/* ... */)
 deep.merge(/* ... */)
 ```
 
 ### Example:
 ```javascript
-import { assign, clone, freeze, merge } from '@superhero/deep'
+import { assign, clone, freeze, intersect, merge } from '@superhero/deep'
 
 assign(/* ... */)
 clone(/* ... */)
 freeze(/* ... */)
+intersect(/* ... */)
 merge(/* ... */)
 ```
 
@@ -145,84 +180,104 @@ npm test
 
 ```
 ▶ @superhero/deep/assign
-  ✔ Assigns arrays correctly (1.993351ms)
-  ✔ Assigns objects correctly (0.797187ms)
-  ✔ Overwrites non-object properties correctly (0.311862ms)
-  ✔ Handles undefined values correctly (0.67959ms)
+  ✔ Assigns arrays correctly (3.552823ms)
+  ✔ Assigns objects correctly (0.702394ms)
+  ✔ Overwrites non-object properties correctly (1.106746ms)
+  ✔ Handles undefined values correctly (0.592877ms)
+
   ▶ Descriptor properties
     ▶ Retains
-      ✔ non-writable, non-configurable and non-enumarable (0.365558ms)
-      ✔ writable but non-configurable and non-enumarable (0.384859ms)
-      ✔ writable and configurable but non-enumarable (0.24546ms)
-    ✔ Retains (1.395563ms)
+      ✔ non-writable, non-configurable and non-enumarable (0.774514ms)
+      ✔ writable but non-configurable and non-enumarable (0.490026ms)
+      ✔ writable and configurable but non-enumarable (0.314062ms)
+    ✔ Retains (2.377181ms)
+
     ▶ Assigns
-      ✔ non-writable, non-configurable and non-enumarable (0.246451ms)
-    ✔ Assigns (0.528402ms)
-  ✔ Descriptor properties (2.438803ms)
-  ✔ Merges nested arrays correctly (1.67104ms)
-  ✔ Merges nested objects correctly (0.649403ms)
-  ✔ Does not alter objects with no conflicts (0.219023ms)
-✔ @superhero/deep/assign (10.784739ms)
+      ✔ non-writable, non-configurable and non-enumarable (0.415235ms)
+    ✔ Assigns (0.824789ms)
+  ✔ Descriptor properties (3.881836ms)
+
+  ✔ Merges nested arrays correctly (6.642858ms)
+  ✔ Merges nested objects correctly (0.731397ms)
+  ✔ Does not alter objects with no conflicts (0.27423ms)
+✔ @superhero/deep/assign (20.322649ms)
 
 ▶ @superhero/deep/clone
-  ✔ Clones simple objects (3.898407ms)
-  ✔ Clones nested objects (0.358366ms)
-  ✔ Clones arrays (0.347023ms)
-  ✔ Handles circular references (0.190668ms)
-  ✔ Clones objects with null prototype (0.302189ms)
-✔ @superhero/deep/clone (6.720191ms)
+  ✔ Clones simple objects (6.103605ms)
+  ✔ Clones nested objects (0.771236ms)
+  ✔ Preserves descriptors (1.57539ms)
+  ✔ Clones arrays (1.604074ms)
+  ✔ Handles circular references (0.507477ms)
+  ✔ Clones objects with null prototype (1.230476ms)
+✔ @superhero/deep/clone (14.513864ms)
 
 ▶ @superhero/deep/freeze
-  ✔ Freezes a simple object (2.561531ms)
-  ✔ Freezes nested objects recursively (0.357866ms)
-  ✔ Handles circular references gracefully (0.308297ms)
-  ✔ Freezes objects with symbols (0.210516ms)
-  ✔ Handles already frozen objects without error (0.157051ms)
-  ✔ Freezes objects with non-enumerable properties (0.214033ms)
-  ✔ Freezes arrays (0.244445ms)
-  ✔ Handles objects with null prototype (0.337528ms)
-  ✔ Freezes objects with multiple property types (0.525787ms)
-✔ @superhero/deep/freeze (7.261487ms)
+  ✔ Freezes a simple object (2.735609ms)
+  ✔ Freezes nested objects recursively (0.40638ms)
+  ✔ Handles circular references gracefully (0.781639ms)
+  ✔ Freezes objects with symbols (0.455776ms)
+  ✔ Handles already frozen objects without error (0.342712ms)
+  ✔ Freezes objects with non-enumerable properties (0.455515ms)
+  ✔ Freezes arrays (0.61924ms)
+  ✔ Handles objects with null prototype (0.57424ms)
+  ✔ Freezes objects with multiple property types (0.984788ms)
+✔ @superhero/deep/freeze (12.988297ms)
 
 ▶ @superhero/deep
-  ✔ All functions are accessible as a member to the default import object (1.250244ms)
-  ✔ All functions are accessible to import from the default import object (0.23689ms)
-✔ @superhero/deep (3.080305ms)
+  ✔ All functions are accessible as a member to the default import object (1.908797ms)
+  ✔ All functions are accessible to import from the default import object (0.603152ms)
+✔ @superhero/deep (7.176949ms)
+
+▶ @superhero/deep/intersect
+  ✔ Intersects arrays by value and position (5.556412ms)
+  ✔ Intersects nested arrays (0.312899ms)
+  ✔ Handles empty array intersection (0.297251ms)
+  ✔ Intersects objects with matching keys and values (0.554782ms)
+  ✔ Deeply intersects nested objects (0.568448ms)
+  ✔ Intersection stops at type mismatch (0.278157ms)
+  ✔ Throws on circular references (1.779685ms)
+  ✔ Intersects arrays with undefined positions (0.702569ms)
+  ✔ Handles intersection of primitive types (0.525931ms)
+  ✔ Returns undefined for non-intersecting primitives (0.867342ms)
+  ✔ Handles multiple sequential intersections (0.836957ms)
+✔ @superhero/deep/intersect (15.753992ms)
 
 ▶ @superhero/deep/merge
-  ✔ Merges arrays with unique values (3.122153ms)
-  ✔ Merges arrays with order preserved (0.298964ms)
-  ✔ Handles empty arrays correctly (0.275066ms)
-  ✔ Handles arrays with duplicate values (0.492229ms)
-  ✔ Merges objects and prioritizes restrictive descriptors (0.623443ms)
-  ✔ Merges objects with non-enumerable properties (0.342317ms)
-  ✔ Handles nested object merging (0.43726ms)
-  ✔ Stops at circular references (0.827394ms)
-  ✔ Stops when nested and with circular references (0.720571ms)
-  ✔ Returns second value for non-object types (0.925228ms)
-  ✔ Handles multiple merges sequentially (0.359582ms)
-✔ @superhero/deep/merge (12.298476ms)
-
-tests 38
-suites 8
-pass 38
-
------------------------------------------------------------------
-file             | line % | branch % | funcs % | uncovered lines
------------------------------------------------------------------
-assign.js        | 100.00 |   100.00 |  100.00 | 
-assign.test.js   | 100.00 |   100.00 |  100.00 | 
-clone.js         | 100.00 |   100.00 |  100.00 | 
-clone.test.js    |  96.34 |    87.50 |  100.00 | 56-58
-freeze.js        | 100.00 |   100.00 |  100.00 | 
-freeze.test.js   | 100.00 |   100.00 |  100.00 | 
-index.js         | 100.00 |   100.00 |  100.00 | 
-index.test.js    | 100.00 |   100.00 |  100.00 | 
-merge.js         | 100.00 |   100.00 |  100.00 | 
-merge.test.js    | 100.00 |   100.00 |  100.00 | 
------------------------------------------------------------------
-all files        |  99.66 |    99.19 |  100.00 | 
------------------------------------------------------------------
+  ✔ Merges arrays with unique values (4.014593ms)
+  ✔ Merges arrays with order preserved (0.431737ms)
+  ✔ Handles empty arrays correctly (0.409507ms)
+  ✔ Handles arrays with duplicate values (0.501899ms)
+  ✔ Merges objects and prioritizes restrictive descriptors (0.804508ms)
+  ✔ Merges objects with non-enumerable properties (0.802831ms)
+  ✔ Handles nested object merging (0.709563ms)
+  ✔ Stops at circular references (0.768717ms)
+  ✔ Stops when nested and with circular references (1.386111ms)
+  ✔ Returns second value for non-object types (1.438328ms)
+  ✔ Handles multiple merges sequentially (0.494506ms)
+✔ @superhero/deep/merge (14.798621ms)
+
+tests 50
+suites 9
+pass 50
+
+------------------------------------------------------------------------
+file                | line % | branch % | funcs % | uncovered lines
+------------------------------------------------------------------------
+assign.js           |  97.80 |    96.15 |  100.00 | 15-16
+assign.test.js      | 100.00 |   100.00 |  100.00 | 
+clone.js            |  95.83 |    93.33 |  100.00 | 22-23
+clone.test.js       | 100.00 |   100.00 |  100.00 | 
+freeze.js           | 100.00 |   100.00 |  100.00 | 
+freeze.test.js      | 100.00 |   100.00 |  100.00 | 
+index.js            | 100.00 |   100.00 |  100.00 | 
+index.test.js       | 100.00 |   100.00 |  100.00 | 
+intersect.js        |  94.77 |    91.18 |  100.00 | 70-71 85-86 134-137
+intersect.test.js   | 100.00 |   100.00 |  100.00 | 
+merge.js            |  98.72 |    96.30 |  100.00 | 81-82
+merge.test.js       | 100.00 |   100.00 |  100.00 | 
+------------------------------------------------------------------------
+all files           |  98.84 |    96.81 |  100.00 | 
+------------------------------------------------------------------------
 ```
 
 ---

package/assign.js

@@ -10,6 +10,11 @@ function assignB2A(a, b)
     return a
   }
 
+  if(Object.is(a, b))
+  {
+    return a
+  }
+
   if(Object.prototype.toString.call(a) === '[object Array]'
   && Object.prototype.toString.call(b) === '[object Array]')
   {

package/clone.js

@@ -1,6 +1,48 @@
-export default function clone(a, legacy = false)
+export default function clone(input) 
 {
-  return structuredClone && false === legacy
-        ? structuredClone(a)
-        : JSON.parse(JSON.stringify(a))
+  const seen = new WeakSet()
+  return deepClone(input, seen)
+}
+
+function deepClone(value, seen) 
+{
+  switch(Object.prototype.toString.call(value))
+  {
+    case '[object Array]'  : return cloneArray(value, seen)
+    case '[object Object]' : return cloneObject(value, seen)
+  }
+
+  return structuredClone(value)
+}
+
+function cloneArray(array, seen) 
+{
+  if(seen.has(array)) 
+  {
+    return array
+  }
+
+  seen.add(array)
+  return array.map((item) => deepClone(item, seen))
+}
+
+function cloneObject(obj, seen) 
+{
+  if(seen.has(obj)) 
+  {
+    return obj
+  }
+
+  seen.add(obj)
+
+  const output = {}
+
+  for(const key of Object.getOwnPropertyNames(obj)) 
+  {
+    const descriptor = Object.getOwnPropertyDescriptor(obj, key)
+    Object.defineProperty(output, key, 
+      { ...descriptor, value : deepClone(descriptor.value, seen) })
+  }
+
+  return output
 }

package/clone.test.js

@@ -8,75 +8,76 @@ suite('@superhero/deep/clone', () =>
   {
     const 
       obj     = { foo: 'bar', baz: 42 },
-      result  = deepclone(obj),
-      legacy  = deepclone(obj, true)
+      cloned  = deepclone(obj)
 
-    assert.deepStrictEqual(result, obj, 'Cloned object should be equal to the original')
-    assert.deepStrictEqual(legacy, obj, 'Cloned object should be equal to the original (legacy mode)')
-
-    assert.notStrictEqual(result, obj, 'Cloned object should not be the same reference as the original')
-    assert.notStrictEqual(legacy, obj, 'Cloned object should not be the same reference as the original (legacy mode)')
+    assert.deepStrictEqual(cloned, obj, 'Cloned object should be equal to the original')
+    assert.notStrictEqual(cloned, obj, 'Not the same reference as the original')
   })
 
   test('Clones nested objects', () =>
   {
-    const obj = { foo: { bar: { baz: 'qux' } } }
-
     const 
-      result = deepclone(obj),
-      legacy = deepclone(obj, true)
+      obj     = { foo: { bar: { baz: 'qux' } } },
+      cloned  = deepclone(obj)
+
+    assert.deepStrictEqual(cloned, obj, 'Cloned nested object should be equal to the original')
+    assert.notStrictEqual(cloned.foo, obj.foo, 'Not the same reference as the original')
+  })
+
+  test('Preserves descriptors', () =>
+  {
+    const origin = {}
+
+    Object.defineProperty(origin, 'foo', { value: {}, enumerable: true,  writable: true,  configurable: true  })
+    Object.defineProperty(origin, 'bar', { value: {}, enumerable: false, writable: true,  configurable: true  })
+    Object.defineProperty(origin, 'baz', { value: {}, enumerable: false, writable: false, configurable: true  })
+    Object.defineProperty(origin, 'qux', { value: {}, enumerable: false, writable: false, configurable: false })
+
+    const cloned = deepclone(origin)
+
+    assert.deepStrictEqual(cloned,    origin,     'Cloned nested object should be equal to the original')
+    assert.notStrictEqual(cloned,     origin,     'Not the same reference as the original')
+    assert.notStrictEqual(cloned.foo, origin.foo, 'Cloned nested object should not share reference with the original')
 
-    assert.deepStrictEqual(result, obj, 'Cloned nested object should be equal to the original')
-    assert.deepStrictEqual(legacy, obj, 'Cloned nested object should be equal to the original (legacy mode)')
+    const
+      clonedDescriptors = Object.getOwnPropertyDescriptors(cloned),
+      originDescriptors = Object.getOwnPropertyDescriptors(origin)
 
-    assert.notStrictEqual(result.foo, obj.foo, 'Cloned nested object should not share reference with the original')
-    assert.notStrictEqual(legacy.foo, obj.foo, 'Cloned nested object should not share reference with the original (legacy mode)')
+    for(const key in originDescriptors)
+    {
+      assert.equal(clonedDescriptors[key].enumerable,    originDescriptors[key].enumerable)
+      assert.equal(clonedDescriptors[key].writable,      originDescriptors[key].writable)
+      assert.equal(clonedDescriptors[key].configurable,  originDescriptors[key].configurable)
+    }
   })
 
   test('Clones arrays', () =>
   {
-    const arr = [1, 2, 3, [4, 5]]
-
     const 
-      result = deepclone(arr),
-      legacy = deepclone(arr, true)
+      array   = [1, 2, 3, [4, 5]],
+      cloned  = deepclone(array)
 
-    assert.deepStrictEqual(result, arr, 'Cloned array should be equal to the original')
-    assert.deepStrictEqual(legacy, arr, 'Cloned array should be equal to the original (legacy mode)')
+    assert.deepStrictEqual(cloned, array, 'Cloned array should be equal to the original')
+    assert.notStrictEqual(cloned, array, 'Not the same reference as the original')
+    assert.notStrictEqual(cloned[3], array[3], 'Nested array in clone should not share reference with the original')
+  })
 
-    assert.notStrictEqual(result, arr, 'Cloned array should not share reference with the original')
-    assert.notStrictEqual(legacy, arr, 'Cloned array should not share reference with the original (legacy mode)')
+  test('Handles circular references', () =>
+  {
+    const obj = {}
+    obj.self = obj
 
-    assert.notStrictEqual(result[3], arr[3], 'Nested array in clone should not share reference with the original')
-    assert.notStrictEqual(legacy[3], arr[3], 'Nested array in clone should not share reference with the original (legacy mode)')
+    const cloned = deepclone(obj)
+    assert.strictEqual(cloned.self, obj, 'Circular references should be preserved in the clone')
   })
 
-  if(false === !!structuredClone)
-  {
-    test.skip('Handles circular references (structuredClone not available)')
-    test.skip('Clones objects with null prototype (structuredClone not available)')
-  }
-  else
+  test('Clones objects with null prototype', () =>
   {
-    test('Handles circular references', () =>
-    {
-      const obj = {}
-      obj.self = obj
-  
-      const result = deepclone(obj)
-  
-      assert.strictEqual(result.self, result, 'Circular references should be preserved in the clone')
-    })
-  
-    test('Clones objects with null prototype', () =>
-    {
-      const obj = Object.create(null)
-      obj.foo = 'bar'
-  
-      const result = deepclone(obj)
-  
-      assert.deepEqual(result, obj, 'Cloned object with null prototype should be equal to the original')
-      assert.notStrictEqual(result, obj, 'Cloned object with null prototype should not share reference with the original')
-    })
-  }
+    const obj = Object.create(null)
+    obj.foo = 'bar'
+
+    const cloned = deepclone(obj)
+    assert.deepEqual(cloned, obj, 'Cloned object with null prototype should be equal to the original')
+    assert.notStrictEqual(cloned, obj, 'Not the same reference as the original')
+  })
 })

package/index.js

@@ -1,7 +1,8 @@
-import assign from '@superhero/deep/assign'
-import clone  from '@superhero/deep/clone'
-import freeze from '@superhero/deep/freeze'
-import merge  from '@superhero/deep/merge'
+import assign     from '@superhero/deep/assign'
+import clone      from '@superhero/deep/clone'
+import freeze     from '@superhero/deep/freeze'
+import intersect  from '@superhero/deep/intersect'
+import merge      from '@superhero/deep/merge'
 
-export          { assign, clone, freeze, merge }
-export default  { assign, clone, freeze, merge }
+export          { assign, clone, freeze, intersect, merge }
+export default  { assign, clone, freeze, intersect, merge }

package/intersect.js

@@ -0,0 +1,165 @@
+/**
+ * When intersecting two arrays [object Array], the result is a new array
+ * containing only values present in both arrays. Duplicate values are removed.
+ * 
+ * @example intersecting [1, 2, 3] and [2, 3, 4] results in [2, 3].
+ * 
+ * ----------------------------------------------------------------------------
+ * 
+ * When intersecting two objects [object Object], the result is a new object
+ * with properties that exist in both objects and whose values are also
+ * intersecting. The descriptor of the intersected property is defined by
+ * the most restrictive rules, same as the merge strategy.
+ * 
+ * @example if key exists in both objects and the values are primitives and
+ * equal, that value is kept.
+ * 
+ * @example if the values are nested objects or arrays, the intersection
+ * continues recursively.
+ * 
+ * ----------------------------------------------------------------------------
+ * 
+ * When the types differ, no value is intersected.
+ * 
+ * @example intersecting a string and an object results in no match.
+ */
+export default function intersect(a, b, ...c)
+{
+  const
+    seen = new WeakMap,
+    output = intersectAandB(a, b, seen)
+
+  return c.length
+    ? intersect(output, ...c)
+    : output
+}
+
+function intersectAandB(a, b, seen)
+{
+  if(Object.is(a, b))
+  {
+    return a
+  }
+
+  const
+    aType = Object.prototype.toString.call(a),
+    bType = Object.prototype.toString.call(b)
+
+  if(aType !== bType)
+  {
+    return undefined
+  }
+
+  if('[object Array]' === aType)
+  {
+    return intersectArray(a, b, seen)
+  }
+
+  if('[object Object]' === aType)
+  {
+    return intersectObject(a, b, seen)
+  }
+
+  return undefined
+}
+
+function intersectArray(a, b, seen)
+{
+  if(hasSeen(a, b, seen))
+  {
+    return seen.get(a).get(b)
+  }
+
+  const
+    values = a.map((value, i) => 
+    {
+      if(b.includes(value))
+      {
+        return value
+      }
+
+      if('object' === typeof value)
+      {
+        return intersectAandB(value, b[i], seen)
+      }
+    }),
+    output = values.filter((value) => value !== undefined)
+
+  seen.get(a).set(b, output)
+
+  return output
+}
+
+function intersectObject(a, b, seen)
+{
+  if(hasSeen(a, b, seen))
+  {
+    return seen.get(a).get(b)
+  }
+
+  const output = {}
+
+  for(const key of Object.getOwnPropertyNames(a))
+  {
+    if(false === (key in b))
+    {
+      continue
+    }
+
+    const value = intersectAandB(a[key], b[key], seen)
+
+    if(undefined === value)
+    {
+      continue
+    }
+
+    const
+      descriptorA = Object.getOwnPropertyDescriptor(a, key),
+      descriptorB = Object.getOwnPropertyDescriptor(b, key)
+
+    Object.defineProperty(output, key,
+    {
+      configurable : descriptorA.configurable && descriptorB.configurable,
+      enumerable   : descriptorA.enumerable   && descriptorB.enumerable,
+      writable     : descriptorA.writable     && descriptorB.writable,
+      value
+    })
+  }
+
+  seen.get(a).set(b, output)
+
+  return output
+}
+
+function hasSeen(a, b, seen)
+{
+  if(false === seen.has(a))
+  {
+    seen.set(a, new WeakMap)
+  }
+  else if(seen.get(a).has(b))
+  {
+    if(CircularReferenceError === seen.get(a).get(b))
+    {
+      throw new CircularReferenceError('Circular reference detected')
+    }
+    else
+    {
+      return true
+    }
+  }
+
+  // Avoid circular references by initiating the weak map with a 
+  // ReferenceError that is written over later when the object is 
+  // fully processed and the reference is not circular, and can 
+  // then instead be set to the output to act as a cache layer.
+  seen.get(a).set(b, CircularReferenceError)
+
+  return false
+}
+
+class CircularReferenceError extends ReferenceError
+{
+  name = 'CircularReferenceError'
+  code = 'E_DEEP_INTERSECT_CIRCULAR_REFERENCE'
+}

package/intersect.test.js

@@ -0,0 +1,129 @@
+import assert           from 'assert'
+import { suite, test }  from 'node:test'
+import deepintersect    from '@superhero/deep/intersect'
+
+suite('@superhero/deep/intersect', () =>
+{
+  test('Intersects arrays by value and position', () =>
+  {
+    const
+      a         = [1, 2, 3],
+      b         = [2, 3, 4],
+      expected  = [2, 3]
+
+    const result = deepintersect(a, b)
+    assert.deepStrictEqual(result, expected, 'Arrays should intersect by value and position')
+  })
+
+  test('Intersects nested arrays', () =>
+  {
+    const
+      a         = [1, [2, 3], 4],
+      b         = [1, [2, 4], 4],
+      expected  = [1, [2], 4]
+
+    const result = deepintersect(a, b)
+    assert.deepStrictEqual(result, expected, 'Nested arrays should intersect deeply')
+  })
+
+  test('Handles empty array intersection', () =>
+  {
+    const
+      a         = [1, 2, 3],
+      b         = [],
+      expected  = []
+
+    const result = deepintersect(a, b)
+    assert.deepStrictEqual(result, expected, 'Intersection with empty array results in empty array')
+  })
+
+  test('Intersects objects with matching keys and values', () =>
+  {
+    const
+      a         = { foo: 1, bar: 2 },
+      b         = { foo: 1, baz: 3 },
+      expected  = { foo: 1 }
+
+    const result = deepintersect(a, b)
+    assert.deepStrictEqual(result, expected, 'Only matching keys with same values should intersect')
+  })
+
+  test('Deeply intersects nested objects', () =>
+  {
+    const
+      a         = { foo: { bar: 1, baz: 2 } },
+      b         = { foo: { bar: 1, baz: 3 } },
+      expected  = { foo: { bar: 1 } }
+
+    const result = deepintersect(a, b)
+    assert.deepStrictEqual(result, expected, 'Nested objects should deeply intersect')
+  })
+
+  test('Intersection stops at type mismatch', () =>
+  {
+    const
+      a         = { foo: [1, 2] },
+      b         = { foo: { bar: 1 } },
+      expected  = {}
+
+    const result = deepintersect(a, b)
+    assert.deepStrictEqual(result, expected, 'Type mismatch should result in empty intersection')
+  })
+
+  test('Throws on circular references', () =>
+  {
+    const a = {}
+    const b = {}
+    a.self = a
+    b.self = b
+
+    assert.throws(() => deepintersect(a, b), {
+      name: 'CircularReferenceError',
+      code: 'E_DEEP_INTERSECT_CIRCULAR_REFERENCE'
+    }, 'Circular references should throw CircularReferenceError')
+  })
+
+  test('Intersects arrays with undefined positions', () =>
+  {
+    const
+      a         = [1, undefined, 3],
+      b         = [1, 2, 3],
+      expected  = [1, 3]
+
+    const result = deepintersect(a, b)
+    assert.deepStrictEqual(result, expected, 'Undefined positions should be excluded')
+  })
+
+  test('Handles intersection of primitive types', () =>
+  {
+    const
+      a         = 'string',
+      b         = 'string',
+      expected  = 'string'
+
+    const result = deepintersect(a, b)
+    assert.strictEqual(result, expected, 'Matching primitive types should intersect')
+  })
+
+  test('Returns undefined for non-intersecting primitives', () =>
+  {
+    const
+      a         = 'string',
+      b         = 'different'
+
+    const result = deepintersect(a, b)
+    assert.strictEqual(result, undefined, 'Non-matching primitive types should return undefined')
+  })
+
+  test('Handles multiple sequential intersections', () =>
+  {
+    const
+      a         = { foo: 1, bar: 2 },
+      b         = { bar: 2, baz: 3 },
+      c         = { bar: 2, qux: 4 },
+      expected  = { bar: 2 }
+
+    const result = deepintersect(a, b, c)
+    assert.deepStrictEqual(result, expected, 'Multiple objects should intersect sequentially')
+  })
+})

package/merge.js

@@ -1,3 +1,5 @@
+import deepclone from '@superhero/deep/clone'
+
 /**
  * When merging two objects [object Object], a new object is created with the 
  * properties of both objects defined. The descriptor of the property in the 
@@ -64,7 +66,7 @@ export default function merge(a, b, ...c)
 
   return c.length
   ? merge(output, ...c)
-  : output
+  : deepclone(output)
 }
 
 function mergeAandB(a, b, seen)
@@ -74,6 +76,11 @@ function mergeAandB(a, b, seen)
     return a
   }
 
+  if(Object.is(a, b))
+  {
+    return a
+  }
+
   const
     aType = Object.prototype.toString.call(a),
     bType = Object.prototype.toString.call(b)

package/merge.test.js

@@ -134,7 +134,7 @@ suite('@superhero/deep/merge', () =>
 
     const result = deepmerge(a, b)
 
-    assert.strictEqual(result.self, b.self, 'Circular references should not merge further')
+    assert.deepStrictEqual(result.self, b.self, 'Circular references should not merge further')
   })
 
   test('Stops when nested and with circular references', () =>
@@ -149,8 +149,8 @@ suite('@superhero/deep/merge', () =>
       resultA = deepmerge(a, b),
       resultB = deepmerge(b, a)
 
-      assert.strictEqual(resultA.foo.bar.foo.bar, b,      'Circular references should not interfare with the merged result')
-      assert.strictEqual(resultB.foo.bar.foo.bar, 'baz',  'Circular references should not interfare with the merged result')
+    assert.deepStrictEqual(resultA.foo.bar.foo.bar, b,      'Circular references should not interfare with the merged result')
+    assert.deepStrictEqual(resultB.foo.bar.foo.bar, 'baz',  'Circular references should not interfare with the merged result')
   })
 
   test('Returns second value for non-object types', () =>

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@superhero/deep",
-  "version": "4.1.0",
+  "version": "4.3.0",
   "description": "A collection of deep structure operations",
-  "keywords": ["deep", "assign", "clone", "freeze", "merge"],
+  "keywords": ["deep", "assign", "clone", "freeze", "intersect", "merge"],
   "main": "index.js",
   "license": "MIT",
   "type": "module",