@superhero/deep 4.8.0 → 4.8.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+---
+#### v4.8.2
+---
+
+Better support for different data structures, mainly Map and Set
+
+---
+#### v4.8.1
+---\n\nVersion alignment...
+
 ---
 ## Version: 4.8.0
 ---\n\nVersion alignment...

package/assign.js

@@ -1,6 +1,7 @@
 export default function assign(a, ...b)
 {
   b.forEach((b) => assignB2A(a, b))
+  return a
 }
 
 function assignB2A(a, b)
@@ -15,18 +16,30 @@ function assignB2A(a, b)
     return a
   }
 
-  if(Object.prototype.toString.call(a) === '[object Array]'
-  && Object.prototype.toString.call(b) === '[object Array]')
+  const
+    aType = Object.prototype.toString.call(a),
+    bType = Object.prototype.toString.call(b)
+
+  if(aType === '[object Array]' && bType === '[object Array]')
   {
     return assignArray(a, b)
   }
 
-  if(Object.prototype.toString.call(a) === '[object Object]'
-  && Object.prototype.toString.call(b) === '[object Object]')
+  if(aType === '[object Object]' && bType === '[object Object]')
   {
     return assignObject(a, b)
   }
 
+  if(aType === '[object Set]' && bType === '[object Set]')
+  {
+    return assignSet(a, b)
+  }
+
+  if(aType === '[object Map]' && bType === '[object Map]')
+  {
+    return assignMap(a, b)
+  }
+
   return b
 }
 
@@ -38,36 +51,82 @@ function assignArray(a, b)
   return a
 }
 
+function assignSet(a, b)
+{
+  for(const v of b)
+  {
+    a.add(v)
+  }
+  return a
+}
+
+function assignMap(a, b)
+{
+  for(const [k, v] of b)
+  {
+    if(a.has(k))
+    {
+      a.set(k, assignB2A(a.get(k), v))
+    }
+    else
+    {
+      a.set(k, v)
+    }
+  }
+  return a
+}
+
 /**
- * @param {Object} a 
- * @param {Object} b 
- * 
- * @throws {TypeError} If a property in "a" is also in "b", 
- *                     but the property in "a" is not configurable.
- * 
- * @returns {Object} a
+ * Mutates "a" by assigning properties from "b".
+ *
+ * Rules:
+ * - If both sides are plain objects, recurse.
+ * - If property exists in a:
+ *   - if configurable: redefine with b's descriptor (value is assigned/merged)
+ *   - else if writable and data property: write value
+ *   - else: leave as-is
+ * - Accessors are copied as accessors; never forced into data descriptors.
  */
 function assignObject(a, b)
 {
-  for (const key of Object.getOwnPropertyNames(b))
+  for(const key of Reflect.ownKeys(b))
   {
-    if(Object.prototype.toString.call(a[key]) === '[object Object]'
-    && Object.prototype.toString.call(b[key]) === '[object Object]')
+    const
+      hasA = Object.prototype.hasOwnProperty.call(a, key),
+      da   = hasA ? Object.getOwnPropertyDescriptor(a, key) : undefined,
+      db   = Object.getOwnPropertyDescriptor(b, key)
+
+    if(!db)
     {
-      assignObject(a[key], b[key])
+      continue
     }
-    else if(Object.hasOwnProperty.call(a, key))
+
+    const aIsData = !!da && ('value' in da)
+    const bIsData = 'value' in db
+
+    // recurse only when both are data props holding plain objects
+    if(hasA
+    && aIsData
+    && bIsData
+    && Object.prototype.toString.call(da.value) === '[object Object]'
+    && Object.prototype.toString.call(db.value) === '[object Object]')
     {
-      const descriptor_a = Object.getOwnPropertyDescriptor(a, key)
+      assignObject(da.value, db.value)
+      continue
+    }
 
-      if(descriptor_a.configurable)
+    if(hasA)
+    {
+      // if not configurable, we can only write if it's a writable data prop
+      if(da && da.configurable)
       {
-        assignPropertyDescriptor(a, b, key)
+        assignPropertyDescriptor(a, da, db, key)
       }
-      else if(descriptor_a.writable)
+      else if(da && ('value' in da) && da.writable)
       {
-        descriptor_a.value = b[key]
-        Object.defineProperty(a, key, descriptor_a)
+        // only safe for data properties
+        const next = assignB2A(da.value, bIsData ? db.value : undefined)
+        Object.defineProperty(a, key, { ...da, value: next })
       }
       else
       {
@@ -76,16 +135,26 @@ function assignObject(a, b)
     }
     else
     {
-      assignPropertyDescriptor(a, b, key)
+      // define new property with b's descriptor, but merge the value if needed
+      assignPropertyDescriptor(a, undefined, db, key)
     }
   }
 
   return a
 }
 
-function assignPropertyDescriptor(a, b, key)
+function assignPropertyDescriptor(a, da, db, key)
 {
-  const descriptor_b = Object.getOwnPropertyDescriptor(b, key)
-  descriptor_b.value = assignB2A(a[key], b[key])
-  Object.defineProperty(a, key, descriptor_b)
-}
+  // Accessor: copy as-is (no merging of get/set)
+  if(!('value' in db))
+  {
+    Object.defineProperty(a, key, db)
+    return
+  }
+
+  const aValue = da && ('value' in da) ? da.value : undefined
+  const next   = assignB2A(aValue, db.value)
+
+  const descriptor = { ...db, value: next }
+  Object.defineProperty(a, key, descriptor)
+}

package/assign.test.js

@@ -185,4 +185,165 @@ suite('@superhero/deep/assign', () =>
     deepassign(a, b)
     assert.deepStrictEqual(a, expected, 'Objects without conflicts should merge correctly')
   })
+
+  suite('Map/Set + accessors', () =>
+  {
+    test('Assigns sets as a union', () =>
+    {
+      const
+        a = new Set([1, 2, 3]),
+        b = new Set([3, 4, 5])
+
+      deepassign(a, b)
+
+      assert.deepStrictEqual(a, new Set([1, 2, 3, 4, 5]))
+    })
+
+    test('Assigns maps by key and merges values on conflict', () =>
+    {
+      const
+        a = new Map([['x', { foo: 1 }], ['y', 1]]),
+        b = new Map([['x', { bar: 2 }], ['z', 3]])
+
+      deepassign(a, b)
+
+      assert.ok(a instanceof Map)
+      assert.deepStrictEqual(a.get('x'), { foo: 1, bar: 2 })
+      assert.strictEqual(a.get('y'), 1)
+      assert.strictEqual(a.get('z'), 3)
+    })
+
+    test('Assigns symbol keys (including non-enumerables)', () =>
+    {
+      const k = Symbol('k')
+
+      const a = {}
+      const b = {}
+
+      Object.defineProperty(b, k,
+      {
+        value         : 42,
+        writable      : true,
+        configurable  : true,
+        enumerable    : false
+      })
+
+      deepassign(a, b)
+
+      const d = Object.getOwnPropertyDescriptor(a, k)
+      assert.strictEqual(d.value, 42)
+      assert.strictEqual(d.enumerable, false)
+    })
+
+    test('Does not invoke getters while assigning', () =>
+    {
+      const a = {}
+      const b = {}
+
+      let calls = 0
+
+      Object.defineProperty(a, 'foo',
+      {
+        enumerable    : true,
+        configurable  : true,
+        get() { calls++; return { foo: 1 } }
+      })
+
+      Object.defineProperty(b, 'foo',
+      {
+        enumerable    : true,
+        configurable  : true,
+        value         : { bar: 2 },
+        writable      : true
+      })
+
+      deepassign(a, b)
+
+      assert.strictEqual(calls, 0, 'Getter must not be invoked during assign')
+
+      const d = Object.getOwnPropertyDescriptor(a, 'foo')
+      assert.ok('value' in d)
+      assert.deepStrictEqual(d.value, { bar: 2 })
+    })
+
+    test('Copies accessor descriptors from b when a does not have the property', () =>
+    {
+      const a = {}
+      const b = {}
+
+      const getB = () => 123
+
+      Object.defineProperty(b, 'foo',
+      {
+        enumerable    : true,
+        configurable  : true,
+        get           : getB
+      })
+
+      deepassign(a, b)
+
+      const d = Object.getOwnPropertyDescriptor(a, 'foo')
+      assert.strictEqual(d.get, getB)
+      assert.strictEqual(d.set, undefined)
+      assert.strictEqual(d.value, undefined)
+    })
+
+    test('Does not override a non-configurable accessor on a', () =>
+    {
+      const a = {}
+      const b = {}
+
+      const getA = () => 1
+      const getB = () => 2
+
+      Object.defineProperty(a, 'foo',
+      {
+        enumerable    : true,
+        configurable  : false,
+        get           : getA
+      })
+
+      Object.defineProperty(b, 'foo',
+      {
+        enumerable    : true,
+        configurable  : true,
+        get           : getB
+      })
+
+      deepassign(a, b)
+
+      const d = Object.getOwnPropertyDescriptor(a, 'foo')
+      assert.strictEqual(d.get, getA, 'Non-configurable accessor must remain')
+    })
+
+    test('Assigns into writable non-configurable data properties', () =>
+    {
+      const a = {}
+      const b = {}
+
+      Object.defineProperty(a, 'foo',
+      {
+        enumerable    : false,
+        configurable  : false,
+        writable      : true,
+        value         : 1
+      })
+
+      Object.defineProperty(b, 'foo',
+      {
+        enumerable    : true,
+        configurable  : true,
+        writable      : true,
+        value         : 2
+      })
+
+      deepassign(a, b)
+
+      const d = Object.getOwnPropertyDescriptor(a, 'foo')
+      assert.strictEqual(d.value, 2)
+      assert.strictEqual(d.configurable, false)
+      assert.strictEqual(d.enumerable, false)
+      assert.strictEqual(d.writable, true)
+    })
+  })
 })

package/clone.js

@@ -1,95 +1,173 @@
 export default function clone(input, options = {}) 
 {
-  const seen = new WeakSet()
+  const seen = new WeakMap()
 
   options.preservesImutable   = options.preservesImutable   ?? false
   options.preservesEnumerable = options.preservesEnumerable ?? true
-  options.fallback            = options.fallback            ?? cloneFallback.bind(null, options, seen)
+  options.fallback            = options.fallback            ?? ((value) => cloneObject(options, seen, value))
 
-  return deepClone(input, options, seen)
+  return deepClone(options, seen, input)
 }
 
-function deepClone(value, options, seen) 
+function deepClone(options, seen, value) 
 {
+  let clone
+
   switch(Object.prototype.toString.call(value))
   {
-    case '[object Array]'  : return cloneArray(value, options, seen)
-    case '[object Object]' : return cloneObject(value, options, seen)
+    case '[object Array]'   : clone = cloneArray(options, seen, value)        ; break
+    case '[object Object]'  : clone = cloneObject(options, seen, value)       ; break
+    case '[object Set]'     : clone = cloneSet(options, seen, value)          ; break
+    case '[object Map]'     : clone = cloneMap(options, seen, value)          ; break
+    case '[object Date]'    : clone = new Date(value.getTime())               ; break
+    case '[object RegExp]'  : clone = new RegExp(value.source, value.flags)   ; break
+    default                 : clone = options.fallback(value)                 ; break
+  }
+
+  if(options.preservesImutable
+  && value && typeof value === 'object'
+  && clone && typeof clone === 'object')
+  {
+    if(false === Object.isExtensible(value))
+    {
+      Object.preventExtensions(clone)
+    }
+
+    if(Object.isSealed(value))
+    {
+      Object.seal(clone)
+    }
+
+    if(Object.isFrozen(value))
+    {
+      Object.freeze(clone)
+    }
   }
 
-  return options.fallback(value)
+  return clone
 }
 
-function cloneArray(array, options, seen) 
+function cloneArray(options, seen, array) 
 {
-  if(seen.has(array)) 
+  const already = seen.get(array)
+
+  if(already) 
+  {
+    return already
+  }
+
+  const clone = new Array(array.length)
+
+  seen.set(array, clone)
+
+  for(let i = 0; i < array.length; i++)
   {
-    return array
+    clone[i] = deepClone(options, seen, array[i])
   }
 
-  seen.add(array)
-  return array.map((item) => deepClone(item, options, seen))
+  return clone
 }
 
-function cloneObject(obj, options, seen) 
+function cloneObject(options, seen, value)
 {
-  if(seen.has(obj)) 
+  if(typeof value !== 'object' || value === null) 
+  {
+    return value
+  }
+
+  const already = seen.get(value)
+
+  if(already) 
   {
-    return obj
+    return already
   }
 
-  seen.add(obj)
+  const clone = Object.create(Object.getPrototypeOf(value))
 
-  const output = {}
+  seen.set(value, clone)
 
-  for(const key of Object.getOwnPropertyNames(obj)) 
+  for (const key of Reflect.ownKeys(value))
   {
-    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)
-    }
+    cloneProperty(options, seen, value, clone, key)
   }
 
-  return output
+  return clone
 }
 
-function cloneFallback(options, seen, value)
+function cloneSet(options, seen, set)
 {
-  if(typeof value !== 'object'
-  || value === null) 
+  const already = seen.get(set)
+
+  if(already)
   {
-    return value
+    return already
   }
 
-  const clone = Object.create(Object.getPrototypeOf(value))
-  for(const key in value) 
+  const clone = new Set()
+  
+  seen.set(set, clone)
+
+  for(const value of set)
+  {
+    clone.add(deepClone(options, seen, value))
+  }
+
+  return clone
+}
+
+function cloneMap(options, seen, map)
+{
+  const already = seen.get(map)
+
+  if(already)
+  {
+    return already
+  }
+
+  const clone = new Map()
+  
+  seen.set(map, clone)
+
+  for(const [key, value] of map)
   {
-    clone[key] = deepClone(value[key], options, seen)
+    clone.set(
+      deepClone(options, seen, key),
+      deepClone(options, seen, value)
+    )
   }
 
   return clone
-}
+}
+
+function cloneProperty(options, seen, src, target, key)
+{
+  const descriptor = Object.getOwnPropertyDescriptor(src, key)
+
+  if(!descriptor)
+  {
+    return
+  }
+
+  if('value' in descriptor)
+  {
+    const clonedValue = deepClone(options, seen, descriptor.value)
+
+    Object.defineProperty(target, key,
+    {
+      enumerable    : options.preservesEnumerable ? descriptor.enumerable   : true,
+      writable      : options.preservesImutable   ? descriptor.writable     : true,
+      configurable  : options.preservesImutable   ? descriptor.configurable : true,
+      value         : clonedValue
+    })
+  }
+  else
+  {
+    Object.defineProperty(target, key,
+    {
+      enumerable    : options.preservesEnumerable ? descriptor.enumerable   : true,
+      configurable  : options.preservesImutable   ? descriptor.configurable : true,
+      get           : descriptor.get,
+      set           : descriptor.set
+    })
+  }
+}

package/clone.test.js

@@ -109,7 +109,21 @@ suite('@superhero/deep/clone', () =>
     obj.self = obj
 
     const cloned = deepclone(obj)
-    assert.strictEqual(cloned.self, obj, 'Circular references should be preserved in the clone')
+
+    assert.notStrictEqual(cloned, obj)
+    assert.strictEqual(cloned.self, cloned)
+  })
+
+  test('Preserves shared references', () =>
+  {
+    const shared = { x: 1 }
+    const obj = { a: shared, b: shared }
+
+    const cloned = deepclone(obj)
+
+    assert.notStrictEqual(cloned, obj)
+    assert.strictEqual(cloned.a, cloned.b)
+    assert.notStrictEqual(cloned.a, shared)
   })
 
   test('Clones objects with null prototype', () =>

package/merge.js

@@ -1,66 +1,8 @@
 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 
- * new object is determined by the descriptors of the properties in the two 
- * objects being merged. The priority of the property descriptor is set on the 
- * new object according to the more restrictive definition in the two sources.
- * 
- * @example if the descriptor of the property in object "a" has "configurable" 
- * set to "false", and the descriptor of the property in object "b" has the 
- * "configurable" set to "true", the new object will have the descriptor for 
- * "configurable" set to "false".
- * 
- * @example if the descriptor of the property in object "a" has "enumerable" 
- * set to "true", and the descriptor of the property in object "b" has the 
- * "enumerable" set to "true", the new object will have the descriptor for 
- * "enumerable" set to "true".
- * 
- * @example if the descriptor of the property in object "a" has "writable" set 
- * to "false", and the descriptor of the property in object "b" has the 
- * "writable" set to "false", the new object will have the descriptor for 
- * "writable" set to "false".
- * 
- * ----------------------------------------------------------------------------
- * 
- * When merging two nested objects [object Object], and there is a circular 
- * reference, the merge will stop at the circular reference and return the
- * object that contains the circular reference.
- * 
- * ----------------------------------------------------------------------------
- * 
- * When merging a and b of different types, the value of b is returned.
- * 
- * @example if the type of the property in object "a" is object "c", and the 
- * type of the property in object "b" is a number, then the value of the 
- * property in the new object will be the number.
- * 
- * @example if the type of the property in object "a" is a string, and the type
- * of the property in object "b" is object "c", then the value of the property 
- * in the new object will be the object "c".
- * 
- * ----------------------------------------------------------------------------
- * 
- * When merging two arrays [object Array], a new array is created with the 
- * unique values of both arrays. The order of the values in the new array is 
- * determined by the order of the values in the two arrays being merged.
- * 
- * @example if array "a" with values [1, 2, 3] is merged with array "b" with 
- * values [2, 3, 4], the new array will have values [1, 2, 3, 4].
- * 
- * @example if array "a" with values [2, 3, 4] is merged with array "b" with 
- * values [1, 2, 3], the new array will have values [2, 3, 4, 1].
- * 
- * @example if array "a" with values [1, 2, 3] is merged with an empty array 
- * "b", the new array will still have values [1, 2, 3].
- * 
- * @example if array "a" with values [1, 1, 2, 2] is merged with array "b" with
- * values [2, 2, 3, 3], the new array will have values [1, 2, 3].
- */
 export default function merge(a, b, ...c)
 {
-  const 
+  const
     seen    = new WeakSet,
     output  = mergeAandB(a, b, seen)
 
@@ -97,6 +39,18 @@ function mergeAandB(a, b, seen)
     return mergeObject(a, b, seen)
   }
 
+  if('[object Set]' === aType
+  && '[object Set]' === bType)
+  {
+    return mergeSet(a, b)
+  }
+
+  if('[object Map]' === aType
+  && '[object Map]' === bType)
+  {
+    return mergeMap(a, b, seen)
+  }
+
   return b
 }
 
@@ -105,6 +59,37 @@ function mergeArray(a, b)
   return [...new Set(a.concat(b))]
 }
 
+function mergeSet(a, b)
+{
+  return new Set([...a, ...b])
+}
+
+function mergeMap(a, b, seen)
+{
+  if(seen.has(a))
+  {
+    return b
+  }
+
+  seen.add(a)
+
+  const output = new Map(a)
+
+  for(const [key, bValue] of b)
+  {
+    if(output.has(key))
+    {
+      const aValue = output.get(key)
+      output.set(key, mergeAandB(aValue, bValue, seen))
+    }
+    else
+    {
+      output.set(key, bValue)
+    }
+  }
+
+  return output
+}
 function mergeObject(a, b, seen)
 {
   if(seen.has(a))
@@ -114,43 +99,100 @@ function mergeObject(a, b, seen)
 
   seen.add(a)
 
-  const output = {}
+  const output = Object.create(Object.getPrototypeOf(a))
 
-  for(const key of Object.getOwnPropertyNames(a))
+  // copy keys unique to a
+  for(const key of Reflect.ownKeys(a))
   {
-    if(key in b)
+    if(Object.prototype.hasOwnProperty.call(b, key))
     {
       continue
     }
-    else
+
+    const descriptor = Object.getOwnPropertyDescriptor(a, key)
+    if(descriptor)
     {
-      const descriptor = Object.getOwnPropertyDescriptor(a, key)
       Object.defineProperty(output, key, descriptor)
     }
   }
 
-  for(const key of Object.getOwnPropertyNames(b))
+  // merge/copy keys from b
+  for(const key of Reflect.ownKeys(b))
   {
-    if(key in a)
+    if(Object.prototype.hasOwnProperty.call(a, key))
     {
-      const
-        descriptor_a = Object.getOwnPropertyDescriptor(a, key),
-        descriptor_b = Object.getOwnPropertyDescriptor(b, key)
+      const da = Object.getOwnPropertyDescriptor(a, key)
+      const db = Object.getOwnPropertyDescriptor(b, key)
 
-      Object.defineProperty(output, key,
+      if(!da || !db)
       {
-        configurable : descriptor_a.configurable && descriptor_b.configurable,
-        enumerable   : descriptor_a.enumerable   && descriptor_b.enumerable,
-        writable     : descriptor_a.writable     && descriptor_b.writable,
-        value        : mergeAandB(a[key], b[key], seen)
-      })
+        continue
+      }
+
+      Object.defineProperty(output, key, mergeDescriptor(da, db, seen))
     }
     else
     {
       const descriptor = Object.getOwnPropertyDescriptor(b, key)
-      Object.defineProperty(output, key, descriptor)
+      if(descriptor)
+      {
+        Object.defineProperty(output, key, descriptor)
+      }
     }
   }
 
   return output
-}
+}
+
+function mergeDescriptor(da, db, seen)
+{
+  const enumerable   = (da.enumerable   ?? true) && (db.enumerable   ?? true)
+  const configurable = (da.configurable ?? true) && (db.configurable ?? true)
+
+  const aIsData = 'value' in da
+  const bIsData = 'value' in db
+
+  // data + data: keep “most restrictive” flags and merge the values
+  if(aIsData && bIsData)
+  {
+    const writable = (da.writable ?? true) && (db.writable ?? true)
+
+    return {
+      enumerable,
+      configurable,
+      writable,
+      value: mergeAandB(da.value, db.value, seen)
+    }
+  }
+
+  // accessor + accessor: keep “most restrictive” flags and combine get/set
+  // (b wins when both define the same accessor)
+  if(!aIsData && !bIsData)
+  {
+    return {
+      enumerable,
+      configurable,
+      get: db.get ?? da.get,
+      set: db.set ?? da.set
+    }
+  }
+
+  // mixed (data vs accessor): do NOT evaluate accessors; prefer b’s shape,
+  // but apply “most restrictive” flags
+  if(bIsData)
+  {
+    return {
+      enumerable,
+      configurable,
+      writable: (da.writable ?? true) && (db.writable ?? true),
+      value: db.value
+    }
+  }
+
+  return {
+    enumerable,
+    configurable,
+    get: db.get,
+    set: db.set
+  }
+}

package/merge.test.js

@@ -178,4 +178,233 @@ suite('@superhero/deep/merge', () =>
     const resultB = deepmerge(a, b, undefined, c)
     assert.deepStrictEqual(resultB, expected, 'Ignore undefined attributes')
   })
+
+  test('Merges sets with unique values', () =>
+  {
+    const
+      a        = new Set([1, 2, 3]),
+      b        = new Set([2, 3, 4]),
+      expected = new Set([1, 2, 3, 4])
+
+    const result = deepmerge(a, b)
+    assert.deepStrictEqual(result, expected, 'Sets should merge as a union')
+  })
+
+  test('Merges maps by key and keeps b for new keys', () =>
+  {
+    const
+      a = new Map([['a', 1]]),
+      b = new Map([['b', 2]])
+
+    const result = deepmerge(a, b)
+
+    assert.ok(result instanceof Map)
+    assert.strictEqual(result.get('a'), 1)
+    assert.strictEqual(result.get('b'), 2)
+  })
+
+  test('Merges maps by key and deep-merges values on conflicts', () =>
+  {
+    const
+      a = new Map([['x', { foo: 1 }]]),
+      b = new Map([['x', { bar: 2 }]])
+
+    const result = deepmerge(a, b)
+
+    assert.ok(result instanceof Map)
+    assert.deepStrictEqual(result.get('x'), { foo: 1, bar: 2 })
+  })
+
+  test('Merges accessor descriptors without evaluating getters', () =>
+  {
+    const a = {}
+    const b = {}
+
+    let getterCalls = 0
+
+    Object.defineProperty(a, 'foo',
+    {
+      enumerable    : true,
+      configurable  : true,
+      get() { getterCalls++; return 1 }
+    })
+
+    Object.defineProperty(b, 'foo',
+    {
+      enumerable    : true,
+      configurable  : true,
+      get() { getterCalls++; return 2 }
+    })
+
+    const result = deepmerge(a, b)
+    const descriptor = Object.getOwnPropertyDescriptor(result, 'foo')
+
+    assert.strictEqual(getterCalls, 0, 'Getters must not be invoked during merge')
+    assert.ok(descriptor.get, 'Merged property should keep a getter')
+    assert.strictEqual(typeof descriptor.get, 'function')
+  })
+
+  test('Merges accessor+accessor and prefers b get/set when present', () =>
+  {
+    const a = {}
+    const b = {}
+
+    const getA = () => 1
+    const setA = () => {}
+    const getB = () => 2
+
+    Object.defineProperty(a, 'foo',
+    {
+      enumerable    : true,
+      configurable  : true,
+      get           : getA,
+      set           : setA
+    })
+
+    Object.defineProperty(b, 'foo',
+    {
+      enumerable    : true,
+      configurable  : true,
+      get           : getB
+      // no set here
+    })
+
+    const result = deepmerge(a, b)
+    const d = Object.getOwnPropertyDescriptor(result, 'foo')
+
+    assert.strictEqual(d.get, getB, 'Getter should prefer b')
+    assert.strictEqual(d.set, setA, 'Setter should fall back to a when b lacks it')
+  })
+
+  test('Merges data+accessor and prefers b shape without invoking accessors', () =>
+  {
+    const a = {}
+    const b = {}
+
+    Object.defineProperty(a, 'foo',
+    {
+      enumerable    : true,
+      configurable  : true,
+      value         : 1,
+      writable      : true
+    })
+
+    let calls = 0
+    Object.defineProperty(b, 'foo',
+    {
+      enumerable    : true,
+      configurable  : true,
+      get() { calls++; return 2 }
+    })
+
+    const result = deepmerge(a, b)
+    const d = Object.getOwnPropertyDescriptor(result, 'foo')
+
+    assert.strictEqual(calls, 0, 'Getter must not be invoked during merge')
+    assert.ok(d.get, 'Result should be an accessor (b shape)')
+    assert.strictEqual(d.value, undefined)
+  })
+
+  // ... to cover some edge cases ...
+
+  test('Returns first value when second is undefined', () =>
+  {
+    const a = { foo: 1 }
+    const result = deepmerge(a, undefined)
+
+    assert.deepStrictEqual(result, a)
+    assert.notStrictEqual(result, a)
+  })
+
+  test('Short-circuits on identical references', () =>
+  {
+    const a = { foo: 1 }
+    const result = deepmerge(a, a)
+
+    assert.deepStrictEqual(result, a)
+    assert.notStrictEqual(result, a)
+  })
+
+  test('Merges symbol keys and prioritizes restrictive descriptors', () =>
+  {
+    const
+      a   = {},
+      b   = {},
+      key = Symbol('foo')
+
+    Object.defineProperty(a, key,
+    {
+      value         : 1,
+      writable      : false,
+      configurable  : false,
+      enumerable    : false
+    })
+
+    Object.defineProperty(b, key,
+    {
+      value         : 2,
+      writable      : true,
+      configurable  : true,
+      enumerable    : true
+    })
+
+    const
+      result      = deepmerge(a, b),
+      descriptor  = Object.getOwnPropertyDescriptor(result, key)
+
+    assert.strictEqual(descriptor.value,        2)
+    assert.strictEqual(descriptor.writable,     false)
+    assert.strictEqual(descriptor.configurable, false)
+    assert.strictEqual(descriptor.enumerable,   false)
+  })
+
+  test('Merges accessor+data and prefers b data without invoking getter', () =>
+  {
+    const a = {}
+    const b = {}
+
+    let calls = 0
+
+    Object.defineProperty(a, 'foo',
+    {
+      enumerable    : true,
+      configurable  : true,
+      get() { calls++; return 1 }
+    })
+
+    Object.defineProperty(b, 'foo',
+    {
+      enumerable    : true,
+      configurable  : true,
+      writable      : true,
+      value         : 42
+    })
+
+    const
+      result = deepmerge(a, b),
+      d      = Object.getOwnPropertyDescriptor(result, 'foo')
+
+    assert.strictEqual(calls, 0)
+    assert.strictEqual(d.value, 42)
+    assert.strictEqual(d.get, undefined)
+    assert.strictEqual(d.set, undefined)
+  })
+
+  test('Stops at circular references inside maps', () =>
+  {
+    const a = new Map()
+    const b = new Map()
+
+    a.set('self', a)
+    b.set('self', b)
+
+    const result = deepmerge(a, b)
+
+    assert.ok(result instanceof Map)
+
+    const inner = result.get('self')
+    assert.ok(inner instanceof Map)
+    assert.strictEqual(inner.get('self'), inner)
+  })
+
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@superhero/deep",
-  "version": "4.8.0",
+  "version": "4.8.2",
   "description": "A collection of deep structure operations",
   "keywords": [
     "deep",
@@ -24,7 +24,7 @@
   },
   "dependencies": {},
   "devDependencies": {
-    "@superhero/audit": "4.8.0",
+    "@superhero/audit": "4.8.2",
     "@superhero/syntax-check": "0.0.2"
   },
   "author": {