Deep Equality Checker

Performs a deep comparison between two values (arrays, objects, and primitives) to determine if they are structurally and value-wise equal.
This function is one of the foundational utilities, used internally throughout the nhb-toolbox package to compare arrays, objects, or any deeply nested structures.

---

Import

import { isDeepEqual } from 'nhb-toolbox';

---

Function Signature

function isDeepEqual<T>(a: T, b: T): boolean

---

Usage Examples

Primitive Values

isDeepEqual(42, 42)
// true

isDeepEqual('hello', 'world')
// false

Arrays

isDeepEqual([1, 2, 3], [1, 2, 3])
// true

isDeepEqual([1, 2, 3], [3, 2, 1])
// false

isDeepEqual([1, [2, 3]], [1, [2, 3]])
// true

Objects

isDeepEqual({ a: 1, b: { c: 2 } }, { a: 1, b: { c: 2 } })
// true

isDeepEqual({ x: 1, y: undefined }, { x: 1 })
// false (key set mismatch)

Nested Structures

isDeepEqual(
  { foo: [1, 2, { bar: 'baz' }] },
  { foo: [1, 2, { bar: 'baz' }] }
)
// true

isDeepEqual(
  { foo: [1, 2, { bar: 'baz' }] },
  { foo: [1, 2, { bar: 'qux' }] }
)
// false

Null & Undefined

isDeepEqual(null, null)    // true
isDeepEqual(undefined, undefined)  // true
isDeepEqual(null, undefined)       // false

---

API Reference

Parameters

Name	Type	Description
a	T	First value to compare.
b	T	Second value to compare.

Returns

• true if the values are deeply equal.
• false otherwise.

---

How it Works

• Strict Equality First: If a and b are the same reference or primitive value, returns true immediately.
• Type & Null Checks: If types differ or either value is null, returns false unless both are strictly equal.
• Array Handling: Arrays compared recursively, including nested arrays.
• Object Handling: Objects compared recursively, ensuring both keys and values match exactly.
• Shallow/Deep: Works for deeply nested arrays/objects as well as simple values.

---

Key Features

• Recursive & Robust: Handles arbitrary nesting for arrays and objects.
• Type Safety: Works generically for any consistent types.
• Foundational Utility: This deep comparison utility powers internal checks across many toolbox functions (e.g., deduplication, merging, diffing, and more).

---

Limitations

• No Cycles Supported: Will stack overflow on circular references.
• No Symbol/Function/Date Support: Only works for plain objects, arrays, and primitives. Special types (functions, Dates, Maps, Sets, Symbols) are not deeply compared.
• No Non-Enumerable or Prototype Chain: Only owns keys compared, prototype chain & non-enumerable properties are ignored.
• No Partial/Object Subset Comparison: Strict equality over all keys and values only.

---

Notes

• If you compare objects with arrays, types, or keys in different order but same values, equality will follow JavaScript’s structure (order matters in arrays, not in objects).
• For performance sensitive code, avoid using on excessively large or deeply nested structures unless necessary.
• This function is extensively used internally in nhb-toolbox for object/array equality checks.

---

Recommended Use Cases

• Deduplicating structurally equal objects/arrays.
• Testing and assertion helpers.
• Data merging, diffing, or synchronization.
• Safely comparing complex API payloads or configurations.

---

Conclusion:
isDeepEqual is a robust, recursive deep comparison tool for reliably testing equality of complex JavaScript values.
Its reliability and correctness make it a key foundation internally across many nhb-toolbox features.