@superhero/deep 4.4.0 → 4.5.0

package/README.md

@@ -134,7 +134,33 @@ console.log(result)
 
 ---
 
-## 6. **Deep**
+## 6. **DeepEqual**
+
+### Purpose:
+Performs a deep equal compare between two values. Supports objects, arrays, and nested structures, and handles circular references. Values are strictly compared by default.
+
+### Features:
+- Compares first and second argument - returns a boolean.
+- Can perform a loose compare by passing a false third argument.
+
+### Example:
+```javascript
+import deepequal from '@superhero/deep/equal'
+
+const a = { foo: { bar: 1 }, arr: [1, 2, 3] }
+const b = { foo: { bar: 1 }, arr: [1, 2, 3] }
+const c = { foo: { bar: 1 }, arr: ['1', '2', '3'] }
+
+deepequal(a, b)         // true
+deepequal(a, c)         // false
+deepequal(a, c, false)  // true
+deepequal(a, b, false)  // true
+deepequal(a, b, c)      // throws AssertionError
+```
+
+---
+
+## 7. **Deep**
 
 ### Purpose:
 Makes the functions accessible through the imported default object.
@@ -149,6 +175,7 @@ import deep from '@superhero/deep'
 
 deep.assign(/* ... */)
 deep.clone(/* ... */)
+deep.equal(/* ... */)
 deep.freeze(/* ... */)
 deep.intersect(/* ... */)
 deep.merge(/* ... */)
@@ -156,10 +183,11 @@ deep.merge(/* ... */)
 
 ### Example:
 ```javascript
-import { assign, clone, freeze, intersect, merge } from '@superhero/deep'
+import { assign, clone, equal, freeze, intersect, merge } from '@superhero/deep'
 
 assign(/* ... */)
 clone(/* ... */)
+equal(/* ... */)
 freeze(/* ... */)
 intersect(/* ... */)
 merge(/* ... */)
@@ -180,103 +208,115 @@ npm test
 
 ```
 ▶ @superhero/deep/assign
-  ✔ Assigns arrays correctly (3.552823ms)
-  ✔ Assigns objects correctly (0.702394ms)
-  ✔ Overwrites non-object properties correctly (1.106746ms)
-  ✔ Handles undefined values correctly (0.592877ms)
-
+  ✔ Assigns arrays correctly (2.973718ms)
+  ✔ Assigns objects correctly (0.70144ms)
+  ✔ Overwrites non-object properties correctly (0.318183ms)
+  ✔ Handles undefined values correctly (1.009161ms)
   ▶ Descriptor properties
     ▶ Retains
-      ✔ 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)
-
+      ✔ non-writable, non-configurable and non-enumarable (0.479579ms)
+      ✔ writable but non-configurable and non-enumarable (0.466066ms)
+      ✔ writable and configurable but non-enumarable (0.309409ms)
+    ✔ Retains (1.735145ms)
+    
     ▶ Assigns
-      ✔ 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)
+      ✔ non-writable, non-configurable and non-enumarable (0.384251ms)
+    ✔ Assigns (0.73481ms)
+  ✔ Descriptor properties (3.130721ms)
+  ✔ Merges nested arrays correctly (2.917128ms)
+  ✔ Merges nested objects correctly (0.937044ms)
+  ✔ Does not alter objects with no conflicts (0.274969ms)
+✔ @superhero/deep/assign (15.154613ms)
 
 ▶ @superhero/deep/clone
-  ✔ 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)
+  ✔ Clones simple objects (3.281531ms)
+  ✔ Clones nested objects (0.470928ms)
+  ✔ Do not preserves descriptors (0.56486ms)
+  ✔ Preserves descriptors (0.547388ms)
+  ✔ Does not preserve frozen object state (1.833744ms)
+  ✔ Clones arrays (0.707413ms)
+  ✔ Handles circular references (0.320116ms)
+  ✔ Clones objects with null prototype (0.620148ms)
+✔ @superhero/deep/clone (12.239426ms)
+
+▶ @superhero/deep/equal
+  ✔ Strict equality: same values, same types (5.24189ms)
+  ✔ Strict equality: fails on type mismatch (0.422575ms)
+  ✔ Loose equality: same values, different types (0.457711ms)
+  ✔ Loose equality: different values (1.583009ms)
+  ✔ Deep equality with nested structure (0.678751ms)
+  ✔ Fails on missing property (0.721941ms)
+  ✔ Validates third argument is boolean (2.323427ms)
+✔ @superhero/deep/equal (13.789463ms)
 
 ▶ @superhero/deep/freeze
-  ✔ 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)
+  ✔ Freezes a simple object (3.92657ms)
+  ✔ Freezes nested objects recursively (0.371321ms)
+  ✔ Handles circular references gracefully (1.267506ms)
+  ✔ Freezes objects with symbols (0.444381ms)
+  ✔ Handles already frozen objects without error (0.930388ms)
+  ✔ Freezes objects with non-enumerable properties (0.455779ms)
+  ✔ Freezes arrays (0.477364ms)
+  ✔ Handles objects with null prototype (0.536402ms)
+  ✔ Freezes objects with multiple property types (0.776249ms)
+✔ @superhero/deep/freeze (15.887295ms)
 
 ▶ @superhero/deep
-  ✔ 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)
+  ✔ All functions are accessible as a member to the default import object (1.711564ms)
+  ✔ All functions are accessible to import from the default import object (0.375857ms)
+✔ @superhero/deep (4.37013ms)
 
 ▶ @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)
+  ✔ Intersects arrays by value and position (5.404912ms)
+  ✔ Intersects nested arrays (0.367099ms)
+  ✔ Handles empty array intersection (0.687107ms)
+  ✔ Intersects objects with matching keys and values (2.015991ms)
+  ✔ Deeply intersects nested objects (0.501549ms)
+  ✔ Intersection stops at type mismatch (0.423998ms)
+  ✔ Throws on circular references (1.079638ms)
+  ✔ Intersects arrays with undefined positions (0.399501ms)
+  ✔ Handles intersection of primitive types (0.576801ms)
+  ✔ Returns undefined for non-intersecting primitives (2.684012ms)
+  ✔ Handles multiple sequential intersections (0.511929ms)
+✔ @superhero/deep/intersect (19.049326ms)
 
 ▶ @superhero/deep/merge
-  ✔ 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
+  ✔ Merges arrays with unique values (4.448622ms)
+  ✔ Merges arrays with order preserved (0.439982ms)
+  ✔ Handles empty arrays correctly (0.291365ms)
+  ✔ Handles arrays with duplicate values (0.497621ms)
+  ✔ Merges objects and prioritizes restrictive descriptors (3.844952ms)
+  ✔ Merges objects with non-enumerable properties (0.710082ms)
+  ✔ Handles nested object merging (0.412465ms)
+  ✔ Stops at circular references (0.446904ms)
+  ✔ Stops when nested and with circular references (1.003584ms)
+  ✔ Returns second value for non-object types (3.370647ms)
+  ✔ Handles multiple merges sequentially (10.429993ms)
+✔ @superhero/deep/merge (37.960347ms)
+
+tests 59
+suites 10
+pass 59
 
 ------------------------------------------------------------------------
 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.js            |  89.47 |    83.33 |  100.00 | 27-28 87-94
 clone.test.js       | 100.00 |   100.00 |  100.00 | 
+equal.js            |  87.10 |    85.71 |  100.00 | 26-29
+equal.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.js        |  95.15 |    91.67 |  100.00 | 70-71 97-98 146-149
 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 | 
+all files           |  98.15 |    95.43 |  100.00 | 
 ------------------------------------------------------------------------
 ```
 

package/equal.js

@@ -0,0 +1,31 @@
+import assert from 'node:assert'
+import util   from 'node:util'
+
+export default function equal(a, b, strict = true) 
+{
+  assert.strictEqual(typeof strict, 'boolean', 'Third argument "loose" must be a boolean')
+
+  return strict
+    ? util.isDeepStrictEqual(a, b)
+    : isDeepLooseEqual(a, b)
+}
+
+function isDeepLooseEqual(a, b)
+{
+  try
+  {
+    assert.deepEqual(a, b)
+    return true
+  }
+  catch(error)
+  {
+    if(error instanceof assert.AssertionError)
+    {
+      return false
+    }
+    else
+    {
+      throw error
+    }
+  }
+}

package/equal.test.js

@@ -0,0 +1,62 @@
+import assert          from 'assert'
+import { suite, test } from 'node:test'
+import deepequal       from './equal.js'
+
+suite('@superhero/deep/equal', () =>
+{
+  test('Strict equality: same values, same types', () =>
+  {
+    const a = { foo: 'bar', baz: 42 }
+    const b = { foo: 'bar', baz: 42 }
+
+    assert.strictEqual(deepequal(a, b), true)
+  })
+
+  test('Strict equality: fails on type mismatch', () =>
+  {
+    const a = { foo: 'bar', baz: 42 }
+    const b = { foo: 'bar', baz: '42' }
+
+    assert.strictEqual(deepequal(a, b, true), false)
+  })
+
+  test('Loose equality: same values, different types', () =>
+  {
+    const a = { foo: 'bar', baz: 42 }
+    const b = { foo: 'bar', baz: '42' }
+
+    assert.strictEqual(deepequal(a, b, false), true)
+  })
+
+  test('Loose equality: different values', () =>
+  {
+    const a = { foo: 'bar', baz: 42 }
+    const b = { foo: 'bar', baz: 99 }
+
+    assert.strictEqual(deepequal(a, b, false), false)
+  })
+
+  test('Deep equality with nested structure', () =>
+  {
+    const a = { foo: { bar: [1, 2] } }
+    const b = { foo: { bar: [1, 2] } }
+
+    assert.strictEqual(deepequal(a, b), true)
+    assert.strictEqual(deepequal(a, b, false), true)
+  })
+
+  test('Fails on missing property', () =>
+  {
+    const a = { foo: 'bar', baz: 42 }
+    const b = { foo: 'bar' }
+
+    assert.strictEqual(deepequal(a, b), false)
+    assert.strictEqual(deepequal(a, b, false), false)
+  })
+
+  test('Validates third argument is boolean', () =>
+  {
+    assert.throws(() => deepequal({}, {}, 'loose'), 
+    { name : 'AssertionError' })
+  })
+})

package/index.js

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

package/package.json

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