@superhero/deep 4.2.0 → 4.4.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,87 +180,104 @@ npm test
 
 ```
 ▶ @superhero/deep/assign
-  ✔ Assigns arrays correctly (3.167398ms)
-  ✔ Assigns objects correctly (0.763768ms)
-  ✔ Overwrites non-object properties correctly (0.347727ms)
-  ✔ Handles undefined values correctly (0.521744ms)
+  ✔ 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.474666ms)
-      ✔ writable but non-configurable and non-enumarable (0.649244ms)
-      ✔ writable and configurable but non-enumarable (0.298073ms)
-    ✔ Retains (1.918778ms)
+      ✔ 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.485428ms)
-    ✔ Assigns (0.889839ms)
-  ✔ Descriptor properties (3.74915ms)
-  
-  ✔ Merges nested arrays correctly (1.898073ms)
-  ✔ Merges nested objects correctly (0.761838ms)
-  ✔ Does not alter objects with no conflicts (0.277694ms)
-✔ @superhero/deep/assign (14.053485ms)
+      ✔ 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 (7.235299ms)
-  ✔ Clones nested objects (0.634553ms)
-  ✔ Clones arrays (0.650244ms)
-  ✔ Handles circular references (0.382144ms)
-  ✔ Clones objects with null prototype (0.375334ms)
-✔ @superhero/deep/clone (11.89498ms)
+  ✔ 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 (3.683567ms)
-  ✔ Freezes nested objects recursively (0.406919ms)
-  ✔ Handles circular references gracefully (0.309979ms)
-  ✔ Freezes objects with symbols (0.405137ms)
-  ✔ Handles already frozen objects without error (0.337038ms)
-  ✔ Freezes objects with non-enumerable properties (0.354681ms)
-  ✔ Freezes arrays (0.662049ms)
-  ✔ Handles objects with null prototype (0.387428ms)
-  ✔ Freezes objects with multiple property types (0.626902ms)
-✔ @superhero/deep/freeze (10.607326ms)
+  ✔ 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.734551ms)
-  ✔ All functions are accessible to import from the default import object (0.255022ms)
-✔ @superhero/deep (5.188429ms)
+  ✔ 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.271451ms)
-  ✔ Merges arrays with order preserved (0.455376ms)
-  ✔ Handles empty arrays correctly (0.283857ms)
-  ✔ Handles arrays with duplicate values (0.538911ms)
-  ✔ Merges objects and prioritizes restrictive descriptors (0.592729ms)
-  ✔ Merges objects with non-enumerable properties (0.343159ms)
-  ✔ Handles nested object merging (0.359878ms)
-  ✔ Stops at circular references (0.554345ms)
-  ✔ Stops when nested and with circular references (0.667265ms)
-  ✔ Returns second value for non-object types (0.744991ms)
-  ✔ Handles multiple merges sequentially (0.327608ms)
-✔ @superhero/deep/merge (11.803686ms)
-
-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         |  95.83 |    92.86 |  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 | 
-merge.js         | 100.00 |   100.00 |  100.00 | 
-merge.test.js    | 100.00 |   100.00 |  100.00 | 
------------------------------------------------------------------
-all files        |  99.78 |    99.25 |  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,21 +1,26 @@
-export default function clone(input) 
+export default function clone(input, options = {}) 
 {
   const seen = new WeakSet()
-  return deepClone(input, seen)
+
+  options.preservesImutable   = options.preservesImutable   ?? false
+  options.preservesEnumerable = options.preservesEnumerable ?? true
+  options.fallback            = options.fallback            ?? cloneFallback.bind(null, options, seen)
+
+  return deepClone(input, options, seen)
 }
 
-function deepClone(value, seen) 
+function deepClone(value, options, seen) 
 {
   switch(Object.prototype.toString.call(value))
   {
-    case '[object Array]'  : return cloneArray(value, seen)
-    case '[object Object]' : return cloneObject(value, seen)
+    case '[object Array]'  : return cloneArray(value, options, seen)
+    case '[object Object]' : return cloneObject(value, options, seen)
   }
 
-  return structuredClone(value)
+  return options.fallback(value)
 }
 
-function cloneArray(array, seen) 
+function cloneArray(array, options, seen) 
 {
   if(seen.has(array)) 
   {
@@ -23,10 +28,10 @@ function cloneArray(array, seen)
   }
 
   seen.add(array)
-  return array.map((item) => deepClone(item, seen))
+  return array.map((item) => deepClone(item, options, seen))
 }
 
-function cloneObject(obj, seen) 
+function cloneObject(obj, options, seen) 
 {
   if(seen.has(obj)) 
   {
@@ -39,10 +44,52 @@ function cloneObject(obj, seen)
 
   for(const key of Object.getOwnPropertyNames(obj)) 
   {
-    const descriptor = Object.getOwnPropertyDescriptor(obj, key)
-    Object.defineProperty(output, key, 
-      { ...descriptor, value : deepClone(descriptor.value, seen) })
+    if(options.preservesImutable)
+    {
+      const descriptor = Object.getOwnPropertyDescriptor(obj, key)
+      Object.defineProperty(output, key, 
+      { 
+        enumerable    : options.preservesEnumerable ? descriptor.enumerable : true,
+        writable      : descriptor.writable, 
+        configurable  : descriptor.configurable, 
+        value         : deepClone(descriptor.value, options, seen) 
+      })
+      continue
+    }
+    else if(options.preservesEnumerable)
+    {
+      const descriptor = Object.getOwnPropertyDescriptor(obj, key)
+      Object.defineProperty(output, key, 
+      { 
+        enumerable    : descriptor.enumerable, 
+        writable      : true, 
+        configurable  : true, 
+        value         : deepClone(descriptor.value, options, seen) 
+      })
+      continue
+    }
+    else
+    {
+      output[key] = deepClone(obj[key], options, seen)
+    }
   }
 
   return output
+}
+
+function cloneFallback(options, seen, value)
+{
+  if(typeof value !== 'object'
+  || value === null) 
+  {
+    return value
+  }
+
+  const clone = Object.create(Object.getPrototypeOf(value))
+  for(const key in value) 
+  {
+    clone[key] = deepClone(value[key], options, seen)
+  }
+
+  return clone
 }

package/clone.test.js

@@ -24,6 +24,32 @@ suite('@superhero/deep/clone', () =>
     assert.notStrictEqual(cloned.foo, obj.foo, 'Not the same reference as the original')
   })
 
+  test('Do not 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, { preservesImutable: false, preservesEnumerable: false })
+
+    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')
+
+    const
+      clonedDescriptors = Object.getOwnPropertyDescriptors(cloned),
+      originDescriptors = Object.getOwnPropertyDescriptors(origin)
+
+    for(const key in originDescriptors)
+    {
+      assert.equal(clonedDescriptors[key].enumerable,    true)
+      assert.equal(clonedDescriptors[key].writable,      true)
+      assert.equal(clonedDescriptors[key].configurable,  true)
+    }
+  })
+
   test('Preserves descriptors', () =>
   {
     const origin = {}
@@ -33,7 +59,7 @@ suite('@superhero/deep/clone', () =>
     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)
+    const cloned = deepclone(origin, { preservesImutable: true, preservesEnumerable: true })
 
     assert.deepStrictEqual(cloned,    origin,     'Cloned nested object should be equal to the original')
     assert.notStrictEqual(cloned,     origin,     'Not the same reference as the original')
@@ -51,6 +77,21 @@ suite('@superhero/deep/clone', () =>
     }
   })
 
+  test('Does not preserve frozen object state', () =>
+  {
+    const origin = { foo:'bar', baz: 42, qux: true }
+
+    Object.freeze(origin)
+
+    assert.ok(Object.isFrozen(origin), 'Origin object should be frozen')
+
+    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.ok(false === Object.isFrozen(cloned), 'Cloned object should not be frozen')
+  })
+
   test('Clones arrays', () =>
   {
     const 

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, { preservesImutable: true })
 }
 
 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.2.0",
+  "version": "4.4.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",