@superhero/deep 4.0.0

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Erik Landvall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+
+# Deep Utilities
+
+This repository contains a set of deep utility classes for handling common operations like cloning, freezing, merging, and assigning objects and arrays. Below is the documentation for each utility class, its purpose, and examples.
+
+---
+
+## 1. **DeepAssign**
+
+### Purpose:
+Deeply assigns properties from one or more source objects to a target object. Handles nested structures, arrays, and property descriptors.
+
+### Features:
+- Merges arrays with unique values.
+- Deeply merges nested objects.
+- Handles property descriptors (`writable`, `configurable`, `enumerable`).
+
+### Example:
+```javascript
+import deepassign from '@superhero/deep/assign'
+
+const target = { foo: { bar: 1 } }
+const source = { foo: { baz: 2 } }
+
+deepassign.assign(target, source)
+
+console.log(target) // { foo: { bar: 1, baz: 2 } }
+```
+
+---
+
+## 2. **DeepMerge**
+
+### Purpose:
+Deeply merges two or more objects into a new object. Handles nested structures, circular references, arrays, and property descriptors.
+
+### Features:
+- Merges arrays with unique values while maintaining order.
+- Merges nested objects with priority for restrictive property descriptors.
+- Detects and handles circular references.
+
+### Example:
+```javascript
+import deepmerge from '@superhero/deep/merge'
+
+const obj1 = { foo: { bar: 1 }, arr: [1, 2] }
+const obj2 = { foo: { baz: 2 }, arr: [2, 3] }
+
+const result = deepmerge.merge(obj1, obj2)
+
+console.log(result)
+// { foo: { bar: 1, baz: 2 }, arr: [1, 2, 3] }
+```
+
+---
+
+## 3. **DeepFreeze**
+
+### Purpose:
+Recursively freezes an object, making it immutable. Handles nested structures and circular references.
+
+### Features:
+- Freezes nested objects and arrays.
+- Handles circular references gracefully.
+
+### Example:
+```javascript
+import deepfreeze from '@superhero/deep/freeze'
+
+const obj = { foo: { bar: 'baz' } }
+obj.foo.self = obj.foo // Circular reference
+
+deepfreeze.freeze(obj)
+
+obj.foo.bar = 'new value' // TypeError: Cannot assign to read-only property
+```
+
+---
+
+## 4. **DeepClone**
+
+### Purpose:
+Creates a deep clone of an object. Supports nested structures, circular references, arrays, and custom serialization methods.
+
+### Features:
+- Uses `structuredClone` if available, falling back to JSON-based cloning.
+- Handles nested objects, arrays, and custom `toJSON` methods.
+- Supports circular references if `structuredClone` is available.
+
+### Example:
+```javascript
+import deepclone from '@superhero/deep/clone'
+
+const obj = { foo: { bar: 'baz' }, arr: [1, 2, 3] }
+
+const clone = deepclone.clone(obj)
+
+console.log(clone) // Deeply cloned object
+console.log(clone === obj) // false
+```
+
+---
+
+## Testing
+Each utility class has a set of unit tests to ensure correctness across different cases.
+
+### Run Tests
+To execute the tests:
+```bash
+npm test
+```
+
+### Test Coverage
+
+```
+▶ @superhero/deep/assign
+  ✔ Merges arrays correctly (2.205053ms)
+  ✔ Merges objects correctly (0.37599ms)
+  ✔ Overwrites non-object properties correctly (0.211516ms)
+  ✔ Handles undefined values correctly (0.174874ms)
+  ▶ Descriptor properties
+    ▶ Retains
+      ✔ non-writable, non-configurable and non-enumarable (0.302976ms)
+      ✔ writable but non-configurable and non-enumarable (0.250721ms)
+      ✔ writable and configurable but non-enumarable (0.148421ms)
+    ✔ Retains (0.912545ms)
+    ▶ Assigns
+      ✔ non-writable, non-configurable and non-enumarable (0.266101ms)
+    ✔ Assigns (1.379408ms)
+  ✔ Descriptor properties (2.578897ms)
+  ✔ Merges nested arrays correctly (0.188364ms)
+  ✔ Merges nested objects correctly (0.159693ms)
+  ✔ Does not alter objects with no conflicts (0.127767ms)
+✔ @superhero/deep/assign (7.763161ms)
+
+▶ @superhero/deep/clone
+  ✔ Clones simple objects (2.379372ms)
+  ✔ Clones nested objects (0.316103ms)
+  ✔ Clones arrays (0.31091ms)
+  ✔ Handles circular references (0.204913ms)
+  ✔ Clones objects with null prototype (0.385473ms)
+✔ @superhero/deep/clone (5.133978ms)
+
+▶ @superhero/deep/freeze
+  ✔ Freezes a simple object (1.831304ms)
+  ✔ Freezes nested objects recursively (0.242757ms)
+  ✔ Handles circular references gracefully (0.155595ms)
+  ✔ Freezes objects with symbols (0.190945ms)
+  ✔ Handles already frozen objects without error (0.129469ms)
+  ✔ Freezes objects with non-enumerable properties (0.193278ms)
+  ✔ Freezes arrays (0.168815ms)
+  ✔ Handles objects with null prototype (0.160426ms)
+  ✔ Freezes objects with multiple property types (0.351257ms)
+✔ @superhero/deep/freeze (5.204715ms)
+
+▶ @superhero/deep/merge
+  ✔ Merges arrays with unique values (2.511877ms)
+  ✔ Merges arrays with order preserved (0.324244ms)
+  ✔ Handles empty arrays correctly (0.319828ms)
+  ✔ Handles arrays with duplicate values (0.258181ms)
+  ✔ Merges objects and prioritizes restrictive descriptors (0.462677ms)
+  ✔ Merges objects with non-enumerable properties (0.203703ms)
+  ✔ Handles nested object merging (0.198121ms)
+  ✔ Stops at circular references (0.137618ms)
+  ✔ Stops when nested and with circular references (0.34896ms)
+  ✔ Returns second value for non-object types (0.230399ms)
+  ✔ Handles multiple merges sequentially (0.294846ms)
+✔ @superhero/deep/merge (7.196893ms)
+
+tests 36
+pass 36
+
+-----------------------------------------------------------------
+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 | 
+merge.js         | 100.00 |   100.00 |  100.00 | 
+merge.test.js    | 100.00 |   100.00 |  100.00 | 
+-----------------------------------------------------------------
+all files        |  99.65 |    99.15 |  100.00 | 
+-----------------------------------------------------------------
+```
+
+---
+
+## License
+This project is licensed under the MIT License.
+
+---
+
+## Contributing
+Feel free to submit issues or pull requests for improvements or additional features.

package/assign.js

@@ -0,0 +1,89 @@
+export default new class DeepAssign
+{
+  assign(a, ...b)
+  {
+    b.forEach((b) => this.#assign(a, b))
+  }
+
+  #assign(a, b)
+  {
+    if(b === undefined)
+    {
+      return a
+    }
+
+    if(Object.prototype.toString.call(a) === '[object Array]'
+    && Object.prototype.toString.call(b) === '[object Array]')
+    {
+      return this.#assignArray(a, b)
+    }
+
+    if(Object.prototype.toString.call(a) === '[object Object]'
+    && Object.prototype.toString.call(b) === '[object Object]')
+    {
+      return this.#assignObject(a, b)
+    }
+
+    return b
+  }
+
+  #assignArray(a, b)
+  {
+    const values = new Set(a.concat(b))
+    a.length = 0
+    a.push(...values)
+    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
+   */
+  #assignObject(a, b)
+  {
+    for (const key of Object.getOwnPropertyNames(b))
+    {
+      if(Object.prototype.toString.call(a[key]) === '[object Object]'
+      && Object.prototype.toString.call(b[key]) === '[object Object]')
+      {
+        this.#assignObject(a[key], b[key])
+      }
+      else if(Object.hasOwnProperty.call(a, key))
+      {
+        const descriptor_a = Object.getOwnPropertyDescriptor(a, key)
+
+        if(descriptor_a.configurable)
+        {
+          this.#assignPropertyDescriptor(a, b, key)
+        }
+        else if(descriptor_a.writable)
+        {
+          descriptor_a.value = b[key]
+          Object.defineProperty(a, key, descriptor_a)
+        }
+        else
+        {
+          continue
+        }
+      }
+      else
+      {
+        this.#assignPropertyDescriptor(a, b, key)
+      }
+    }
+
+    return a
+  }
+
+  #assignPropertyDescriptor(a, b, key)
+  {
+    const descriptor_b = Object.getOwnPropertyDescriptor(b, key)
+    descriptor_b.value = this.#assign(a[key], b[key])
+    Object.defineProperty(a, key, descriptor_b)
+  }
+}

package/assign.test.js

@@ -0,0 +1,188 @@
+import assert           from 'assert'
+import { suite, test }  from 'node:test'
+import deepassign       from '@superhero/deep/assign'
+
+suite('@superhero/deep/assign', () =>
+{
+  test('Merges arrays correctly', () => 
+  {
+    const 
+      a         = [1, 2, 3],
+      b         = [3, 4, 5],
+      expected  = [1, 2, 3, 4, 5]
+  
+    deepassign.assign(a, b)
+    assert.deepStrictEqual(a, expected, 'Arrays should merge with unique values')
+  })
+
+  test('Merges objects correctly', () => 
+  {
+    const 
+      a         = { foo: 1, bar: { baz: 2 } },
+      b         = { bar: { qux: 3 }, hello: 'world' },
+      expected  = { foo: 1, bar: { baz: 2, qux: 3 }, hello: 'world' }
+  
+    deepassign.assign(a, b)
+    assert.deepStrictEqual(a, expected, 'Objects should deep merge')
+  })
+  
+  test('Overwrites non-object properties correctly', () => 
+  {
+    const 
+      a         = { foo: 1 },
+      b         = { foo: 2 },
+      expected  = { foo: 2 }
+  
+    deepassign.assign(a, b)
+    assert.deepStrictEqual(a, expected, 'Properties should be overwritten')
+  })
+  
+  test('Handles undefined values correctly', () => 
+  {
+    const 
+      a         = { foo: 1 },
+      b         = { foo: undefined },
+      expected  = { foo: 1 }
+  
+    deepassign.assign(a, b)
+    assert.deepStrictEqual(a, expected, 'Undefined values should not overwrite existing properties')
+  })
+
+  suite('Descriptor properties', () =>
+  {
+    suite('Retains', () =>
+    {
+      test('non-writable, non-configurable and non-enumarable', () => 
+      {
+        const a = {}
+      
+        Object.defineProperty(a, 'foo', 
+        {
+          value         : 1,
+          writable      : false,
+          configurable  : false,
+          enumerable    : false
+        })
+      
+        const b = { foo: 2 }
+      
+        deepassign.assign(a, b)
+      
+        const descriptor_a = Object.getOwnPropertyDescriptor(a, 'foo')
+      
+        assert.strictEqual(descriptor_a.value,        1,     'Value of non-writeable property should not be overwritten')
+        assert.strictEqual(descriptor_a.writable,     false, 'Writable state should remain unchanged')
+        assert.strictEqual(descriptor_a.configurable, false, 'Configurable state should remain unchanged')
+        assert.strictEqual(descriptor_a.enumerable,   false, 'Enumerable state should remain unchanged')
+      })
+      
+      test('writable but non-configurable and non-enumarable', () => 
+      {
+        const a = {}
+      
+        Object.defineProperty(a, 'foo', 
+        {
+          value         : 1,
+          writable      : true,
+          configurable  : false,
+          enumerable    : false
+        })
+      
+        const b = { foo: 2 }
+      
+        deepassign.assign(a, b)
+      
+        const descriptor_a = Object.getOwnPropertyDescriptor(a, 'foo')
+      
+        assert.strictEqual(descriptor_a.value,        2,     'Value of writeable property should be overwritten')
+        assert.strictEqual(descriptor_a.writable,     true,  'Writable state should remain unchanged')
+        assert.strictEqual(descriptor_a.configurable, false, 'Configurable state should remain unchanged')
+        assert.strictEqual(descriptor_a.enumerable,   false, 'Enumerable state should remain unchanged')
+      })
+      
+      test('writable and configurable but non-enumarable', () => 
+      {
+        const a = {}
+      
+        Object.defineProperty(a, 'foo', 
+        {
+          value         : 1,
+          writable      : true,
+          configurable  : true,
+          enumerable    : false
+        })
+      
+        const b = { foo: 2 }
+      
+        deepassign.assign(a, b)
+      
+        const descriptor_a = Object.getOwnPropertyDescriptor(a, 'foo')
+      
+        assert.strictEqual(descriptor_a.value,        2,     'Value of writeable property should be overwritten')
+        assert.strictEqual(descriptor_a.writable,     true,  'Writable state should remain unchanged')
+        assert.strictEqual(descriptor_a.configurable, true,  'Configurable state should remain unchanged')
+        assert.strictEqual(descriptor_a.enumerable,   true,  'Enumerable state should change to becouse the property is configurable')
+      })
+    })
+    
+    suite('Assigns', () =>
+    {
+      test('non-writable, non-configurable and non-enumarable', () => 
+      {
+        const 
+          a = { foo: 1 },
+          b = {}
+      
+        Object.defineProperty(a, 'foo', 
+        {
+          value         : 2,
+          writable      : false,
+          configurable  : false,
+          enumerable    : false
+        })
+      
+        deepassign.assign(a, b)
+      
+        const descriptor_a = Object.getOwnPropertyDescriptor(a, 'foo')
+      
+        assert.strictEqual(descriptor_a.value,        2,     'Value should be overwritten')
+        assert.strictEqual(descriptor_a.writable,     false, 'Writable state should be assigned')
+        assert.strictEqual(descriptor_a.configurable, false, 'Configurable state should be assigned')
+        assert.strictEqual(descriptor_a.enumerable,   false, 'Enumerable state should be assigned')
+      })
+    })
+  })
+  
+  test('Merges nested arrays correctly', () => 
+  {
+    const 
+      a         = { foo: [1, 2] },
+      b         = { foo: [2, 3] },
+      expected  = { foo: [1, 2, 3] }
+  
+    deepassign.assign(a, b)
+    assert.deepStrictEqual(a, expected, 'Nested arrays should merge with unique values')
+  })
+  
+  test('Merges nested objects correctly', () => 
+  {
+    const 
+      a         = { foo: { bar: { baz: 1 }}},
+      b         = { foo: { bar: { qux: 2 }}},
+      expected  = { foo: { bar: { baz: 1, qux: 2 }}}
+  
+    deepassign.assign(a, b)
+    assert.deepStrictEqual(a, expected, 'Nested objects should deep merge')
+  })
+  
+  test('Does not alter objects with no conflicts', () => 
+  {
+    const 
+      a         = { foo: 1 },
+      b         = { bar: 2 },
+      expected  = { foo: 1, bar: 2 }
+  
+    deepassign.assign(a, b)
+    assert.deepStrictEqual(a, expected, 'Objects without conflicts should merge correctly')
+  })
+})

package/clone.js

@@ -0,0 +1,9 @@
+export default new class DeepClone
+{
+  clone(a, legacy = false)
+  {
+    return structuredClone && false === legacy
+         ? structuredClone(a)
+         : JSON.parse(JSON.stringify(a))
+  }
+}

package/clone.test.js

@@ -0,0 +1,82 @@
+import assert           from 'assert'
+import { suite, test }  from 'node:test'
+import deepclone        from '@superhero/deep/clone'
+
+suite('@superhero/deep/clone', () =>
+{
+  test('Clones simple objects', () =>
+  {
+    const 
+      obj     = { foo: 'bar', baz: 42 },
+      result  = deepclone.clone(obj),
+      legacy  = deepclone.clone(obj, true)
+
+    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)')
+  })
+
+  test('Clones nested objects', () =>
+  {
+    const obj = { foo: { bar: { baz: 'qux' } } }
+
+    const 
+      result = deepclone.clone(obj),
+      legacy = deepclone.clone(obj, true)
+
+    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)')
+
+    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)')
+  })
+
+  test('Clones arrays', () =>
+  {
+    const arr = [1, 2, 3, [4, 5]]
+
+    const 
+      result = deepclone.clone(arr),
+      legacy = deepclone.clone(arr, true)
+
+    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.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)')
+
+    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)')
+  })
+
+  if(false === !!structuredClone)
+  {
+    test.skip('Handles circular references (structuredClone not available)')
+    test.skip('Clones objects with null prototype (structuredClone not available)')
+  }
+  else
+  {
+    test('Handles circular references', () =>
+    {
+      const obj = {}
+      obj.self = obj
+  
+      const result = deepclone.clone(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.clone(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')
+    })
+  }
+})

package/config.json

@@ -0,0 +1,10 @@
+{
+  "locator":
+  {
+    "@superhero/deep"         : true,
+    "@superhero/deep/assign"  : true,
+    "@superhero/deep/clone"   : true,
+    "@superhero/deep/freeze"  : true,
+    "@superhero/deep/merge"   : true
+  }
+}

package/freeze.js

@@ -0,0 +1,33 @@
+export default new class DeepFreeze
+{
+  freeze(obj)
+  {
+    const seen = new WeakSet
+    this.#freeze(obj, seen)
+  }
+
+  #freeze(obj, seen)
+  {
+    const objType = Object.prototype.toString.call(obj)
+
+    if('[object Array]'   === objType
+    || '[object Object]'  === objType)
+    {
+      if(seen.has(obj))
+      {
+        return
+      }
+      else
+      {
+        seen.add(obj)
+      }
+
+      for(const key of [...Object.getOwnPropertyNames(obj), ...Object.getOwnPropertySymbols(obj)])
+      {
+        this.#freeze(obj[key], seen)
+      }
+
+      Object.freeze(obj)
+    }
+  }
+}

package/freeze.test.js

@@ -0,0 +1,123 @@
+import assert           from 'assert'
+import { suite, test }  from 'node:test'
+import deepfreeze       from '@superhero/deep/freeze'
+
+suite('@superhero/deep/freeze', () =>
+{
+  test('Freezes a simple object', () =>
+  {
+    const obj = { foo: 'bar' }
+
+    deepfreeze.freeze(obj)
+
+    assert.throws(() => { obj.foo = 'baz' }, TypeError, 'Should not allow modifying a frozen object')
+    assert.strictEqual(Object.isFrozen(obj), true,      'Object should be frozen')
+  })
+
+  test('Freezes nested objects recursively', () =>
+  {
+    const obj = { foo: { bar: { baz: 'qux' } } }
+
+    deepfreeze.freeze(obj)
+
+    assert.throws(() => { obj.foo.bar.baz = 'changed' }, TypeError, 'Should not allow modifying nested properties')
+    assert.strictEqual(Object.isFrozen(obj.foo.bar),  true, 'Nested object should be frozen')
+    assert.strictEqual(Object.isFrozen(obj.foo),      true, 'Parent object should be frozen')
+  })
+
+  test('Handles circular references gracefully', () =>
+  {
+    const obj = {}
+    obj.self = obj
+
+    deepfreeze.freeze(obj)
+
+    assert.strictEqual(Object.isFrozen(obj),      true, 'Object with circular reference should be frozen')
+    assert.strictEqual(Object.isFrozen(obj.self), true, 'Circular reference should also be frozen')
+  })
+
+  test('Freezes objects with symbols', () =>
+  {
+    const sym = Symbol('test')
+    const obj = { [sym]: 'value' }
+
+    deepfreeze.freeze(obj)
+
+    assert.throws(() => { obj[sym] = 'new value' }, TypeError,  'Should not allow modifying properties with symbols')
+    assert.strictEqual(Object.isFrozen(obj), true,              'Object with symbols should be frozen')
+  })
+
+  test('Handles already frozen objects without error', () =>
+  {
+    const obj = Object.freeze({ foo: 'bar' })
+
+    deepfreeze.freeze(obj) // Should not throw an error
+    assert.strictEqual(Object.isFrozen(obj), true, 'Already frozen object should remain frozen')
+  })
+
+  test('Freezes objects with non-enumerable properties', () =>
+  {
+    const obj = {}
+    Object.defineProperty(obj, 'foo',
+    {
+      value         : 'bar',
+      enumerable    : false,
+      configurable  : true,
+      writable      : true
+    })
+
+    deepfreeze.freeze(obj)
+
+    assert.throws(() => { obj.foo = 'baz' }, TypeError, 'Should not allow modifying non-enumerable properties')
+    assert.strictEqual(Object.isFrozen(obj), true,      'Object with non-enumerable properties should be frozen')
+  })
+
+  test('Freezes arrays', () =>
+  {
+    const arr = [1, 2, 3]
+
+    deepfreeze.freeze(arr)
+
+    assert.throws(() => { arr[0] = 4 }, TypeError, 'Should not allow modifying an array')
+    assert.strictEqual(Object.isFrozen(arr), true, 'Array should be frozen')
+  })
+
+  test('Handles objects with null prototype', () =>
+  {
+    const obj = Object.create(null)
+    obj.foo = 'bar'
+
+    deepfreeze.freeze(obj)
+
+    assert.throws(() => { obj.foo = 'baz' }, TypeError, 'Should not allow modifying properties of objects with null prototype')
+    assert.strictEqual(Object.isFrozen(obj), true,      'Object with null prototype should be frozen')
+  })
+
+  test('Freezes objects with multiple property types', () =>
+  {
+    const 
+      sym = Symbol('test'),
+      obj = 
+      {
+        [sym]  : 'value',
+        foo    : 'bar',
+        nested : { baz: 'qux' }
+      }
+
+    Object.defineProperty(obj, 'nonEnum',
+    {
+      value         : 'hidden',
+      enumerable    : false,
+      configurable  : true,
+      writable      : true
+    })
+
+    deepfreeze.freeze(obj)
+
+    assert.throws(() => { obj.nested.baz  = 'changed'   }, TypeError, 'Should not allow modifying nested properties')
+    assert.throws(() => { obj[sym]        = 'new value' }, TypeError, 'Should not allow modifying symbol properties')
+    assert.throws(() => { obj.nonEnum     = 'visible'   }, TypeError, 'Should not allow modifying non-enumerable properties')
+    assert.strictEqual(Object.isFrozen(obj.nested), true, 'Nested object should be frozen')
+    assert.strictEqual(Object.isFrozen(obj),        true, 'Parent object should be frozen')
+  })
+})

package/index.js

@@ -0,0 +1,4 @@
+export * from '@superhero/deep/assign'
+export * from '@superhero/deep/clone'
+export * from '@superhero/deep/freeze'
+export * from '@superhero/deep/merge'

package/merge.js

@@ -0,0 +1,152 @@
+/**
+ * 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 new class DeepMerge
+{
+  merge(a, b, ...c)
+  {
+    const 
+      seen    = new WeakSet,
+      output  = this.#merge(a, b, seen)
+
+    return c.length
+    ? this.merge(output, ...c)
+    : output
+  }
+
+  #merge(a, b, seen)
+  {
+    if(b === undefined)
+    {
+      return a
+    }
+
+    const
+      aType = Object.prototype.toString.call(a),
+      bType = Object.prototype.toString.call(b)
+
+    if('[object Array]' === aType
+    && '[object Array]' === bType)
+    {
+      return this.#mergeArray(a, b)
+    }
+
+    if('[object Object]' === aType
+    && '[object Object]' === bType)
+    {
+      return this.#mergeObject(a, b, seen)
+    }
+
+    return b
+  }
+
+  #mergeArray(a, b)
+  {
+    return [...new Set(a.concat(b))]
+  }
+
+  #mergeObject(a, b, seen)
+  {
+    if(seen.has(a))
+    {
+      return b
+    }
+
+    seen.add(a)
+
+    const output = {}
+
+    for(const key of Object.getOwnPropertyNames(a))
+    {
+      if(key in b)
+      {
+        continue
+      }
+      else
+      {
+        const descriptor = Object.getOwnPropertyDescriptor(a, key)
+        Object.defineProperty(output, key, descriptor)
+      }
+    }
+
+    for(const key of Object.getOwnPropertyNames(b))
+    {
+      if(key in a)
+      {
+        const
+          descriptor_a = Object.getOwnPropertyDescriptor(a, key),
+          descriptor_b = Object.getOwnPropertyDescriptor(b, key)
+  
+        Object.defineProperty(output, key,
+        {
+          configurable : descriptor_a.configurable && descriptor_b.configurable,
+          enumerable   : descriptor_a.enumerable   && descriptor_b.enumerable,
+          writable     : descriptor_a.writable     && descriptor_b.writable,
+          value        : this.#merge(a[key], b[key], seen)
+        })
+      }
+      else
+      {
+        const descriptor = Object.getOwnPropertyDescriptor(b, key)
+        Object.defineProperty(output, key, descriptor)
+      }
+    }
+
+    return output
+  }
+}

package/merge.test.js

@@ -0,0 +1,181 @@
+import assert           from 'assert'
+import { suite, test }  from 'node:test'
+import deepmerge        from '@superhero/deep/merge'
+
+suite('@superhero/deep/merge', () =>
+{
+  test('Merges arrays with unique values', () =>
+  {
+    const 
+      a         = [1, 2, 3],
+      b         = [2, 3, 4],
+      expected  = [1, 2, 3, 4]
+    
+    const result = deepmerge.merge(a, b)
+    assert.deepStrictEqual(result, expected, 'Arrays should merge with unique values')
+  })
+
+  test('Merges arrays with order preserved', () =>
+  {
+    const 
+      a         = [2, 3, 4],
+      b         = [1, 2, 3],
+      expected  = [2, 3, 4, 1]
+    
+    const result = deepmerge.merge(a, b)
+    assert.deepStrictEqual(result, expected, 'Order of values should be preserved')
+  })
+
+  test('Handles empty arrays correctly', () =>
+  {
+    const 
+      a         = [1, 2, 3],
+      b         = [],
+      expected  = [1, 2, 3]
+    
+    const result = deepmerge.merge(a, b)
+    assert.deepStrictEqual(result, expected, 'Merging with empty array should not alter values')
+  })
+
+  test('Handles arrays with duplicate values', () =>
+  {
+    const 
+      a         = [1, 1, 2, 2],
+      b         = [2, 2, 3, 3],
+      expected  = [1, 2, 3]
+    
+    const result = deepmerge.merge(a, b)
+    assert.deepStrictEqual(result, expected, 'Duplicate values should be removed')
+  })
+
+  test('Merges objects and prioritizes restrictive descriptors', () =>
+  {
+    const 
+      a = {},
+      b = {}
+
+    Object.defineProperty(a, 'foo',
+    {
+      value         : 1,
+      writable      : true,
+      configurable  : false,
+      enumerable    : true
+    })
+
+    Object.defineProperty(b, 'foo',
+    {
+      value         : 2,
+      writable      : false,
+      configurable  : true,
+      enumerable    : true
+    })
+
+    const 
+      result      = deepmerge.merge(a, b),
+      descriptor  = Object.getOwnPropertyDescriptor(result, 'foo')
+
+    assert.strictEqual(descriptor.value,        2,      'Value should prioritize the second object')
+    assert.strictEqual(descriptor.writable,     false,  'Writable state should reflect the more restrictive descriptor')
+    assert.strictEqual(descriptor.configurable, false,  'Configurable state should reflect the more restrictive descriptor')
+    assert.strictEqual(descriptor.enumerable,   true,   'Enumerable state should remain unchanged')
+  })
+
+  test('Merges objects with non-enumerable properties', () =>
+  {
+    const 
+      a = {},
+      b = {}
+
+    Object.defineProperty(a, 'foo',
+    {
+      value         : 1,
+      writable      : true,
+      configurable  : true,
+      enumerable    : false
+    })
+
+    Object.defineProperty(b, 'foo',
+    {
+      value         : 2,
+      writable      : false,
+      configurable  : false,
+      enumerable    : false
+    })
+
+    const 
+      result      = deepmerge.merge(a, b),
+      descriptor  = Object.getOwnPropertyDescriptor(result, 'foo')
+
+    assert.strictEqual(descriptor.value,        2,      'Value should prioritize the second object')
+    assert.strictEqual(descriptor.writable,     false,  'Writable state should reflect the more restrictive descriptor')
+    assert.strictEqual(descriptor.configurable, false,  'Configurable state should reflect the more restrictive descriptor')
+    assert.strictEqual(descriptor.enumerable,   false,  'Enumerable state should remain unchanged')
+  })
+
+  test('Handles nested object merging', () =>
+  {
+    const 
+      a         = { foo: { bar: 1 } },
+      b         = { foo: { baz: 2 } },
+      expected  = { foo: { bar: 1, baz: 2 } }
+    
+    const result = deepmerge.merge(a, b)
+    assert.deepStrictEqual(result, expected, 'Nested objects should merge correctly')
+  })
+
+  test('Stops at circular references', () =>
+  {
+    const 
+      a = {},
+      b = {}
+
+    a.self = a
+    b.self = b
+
+    const result = deepmerge.merge(a, b)
+
+    assert.strictEqual(result.self, b.self, 'Circular references should not merge further')
+  })
+
+  test('Stops when nested and with circular references', () =>
+  {
+    const 
+      a = { foo: { bar: { foo: { bar: 'baz' } } } },
+      b = { foo: {} }
+
+    b.foo.bar = b
+
+    const 
+      resultA = deepmerge.merge(a, b),
+      resultB = deepmerge.merge(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')
+  })
+
+  test('Returns second value for non-object types', () =>
+  {
+    const 
+      a         = { foo: 'string' },
+      b         = { foo: 42 },
+      expected  = { foo: 42 }
+    
+    const result = deepmerge.merge(a, b)
+    assert.deepStrictEqual(result, expected, 'Non-object types should replace with the second value')
+  })
+
+  test('Handles multiple merges sequentially', () =>
+  {
+    const 
+      a         = { foo: 1 },
+      b         = { bar: 2 },
+      c         = { baz: 3 },
+      expected  = { foo: 1, bar: 2, baz: 3 }
+
+    const resultA = deepmerge.merge(a, b, c)
+    assert.deepStrictEqual(resultA, expected, 'Multiple objects should merge sequentially')
+
+    const resultB = deepmerge.merge(a, b, undefined, c)
+    assert.deepStrictEqual(resultB, expected, 'Ignore undefined attributes')
+  })
+})

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@superhero/deep",
+  "version": "4.0.0",
+  "description": "A collection of deep structure operations",
+  "keywords": ["deep", "assign", "clone", "freeze", "merge"],
+  "main": "index.js",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./index.js",
+    "./*": "./*.js"
+  },
+  "scripts": {
+    "test": "node --trace-warnings --test --experimental-test-coverage"
+  },
+  "author": {
+    "name": "Erik Landvall",
+    "email": "erik@landvall.se"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/superhero/deep"
+  }
+}