deep-equal

deep-equal extracts the exact recursive comparison algorithm behind Node’s assert.deepEqual() into a standalone, dependency-injectable module that runs anywhere JavaScript runs, including browsers. Rather than reimplementing a simplified equality check, it mirrors the real internal semantics Node uses, tracking cyclic references through a side-channel, distinguishing boxed primitives, typed arrays, ArrayBuffers, SharedArrayBuffers, Dates, RegExps, and Map/Set collections, and offering both loose (==) and opts.strict (===) comparison modes.

It’s maintained as part of the inspect-js / ljharb ecosystem of small, spec-correct utility packages, and leans on sibling packages like is-array-buffer, which-typed-array, which-collection, and side-channel instead of hand-rolled type checks. That composition keeps each individual concern narrow and independently tested while the top-level deepEqual(a, b, opts) API stays a single function call with one option.

What You Get

• A single deepEqual(a, b, opts) function that recursively compares objects, arrays, Maps, Sets, typed arrays, ArrayBuffers, Dates, RegExps, and boxed primitives
• An opts.strict flag to switch between coercive (==) and strict (===) leaf comparisons, matching assert.deepEqual vs assert.deepStrictEqual
• Cycle-safe comparison via an internal side-channel, so circular references in a or b don’t cause infinite recursion
• Cross-realm and cross-engine correctness checks (boxed primitives, typed arrays, SharedArrayBuffer) built on dedicated is-*/which-* shim packages rather than ad hoc typeof/instanceof logic
• Browser compatibility out of the box, with no Node-only APIs required at the call site

Common Use Cases

• Powering assertion logic inside custom test helpers or matcher libraries that need Node-parity deep equality without requiring Node’s assert module
• Comparing parsed configuration objects, API response payloads, or Redux/state-store snapshots for equality checks in application code
• Deduplicating or diffing collections of objects (arrays, Maps, Sets) where reference equality is insufficient
• Providing the underlying equality algorithm for other polyfill/shim packages (e.g. commonjs-assert) that need to match Node’s exact comparison semantics

Under The Hood

Architecture deep-equal is a single flat CommonJS module (index.js) built around one recursive internalDeepEqual function that layers comparisons by type: identical-value fast path, boxed-primitive check, primitive ==/=== fallback, then a full objEquiv pass for objects that checks Object.prototype.toString tags, arguments/Error/RegExp/Date special cases, typed arrays, Buffers, ArrayBuffers, SharedArrayBuffers, plain-object keys, and finally Map/Set collection equivalence via dedicated setEquiv/mapEquiv helpers. Cyclic references are handled through a side-channel-based “channel” object that records sentinel values for already-visited pairs before recursing, a pattern explicitly ported from Node’s own internal util/comparisons.js (the source comments cite the exact upstream commits). There’s no class hierarchy or dependency injection here — it’s a pure function library where an opts.strict flag threads through every recursive call to switch between loose and strict semantics.

Tech Stack The library is plain ES5-compatible CommonJS with no build step and an engines field down to Node >= 0.4. Rather than hand-rolling type detection, it composes a set of small, single-purpose shim packages by the same maintainer group (is-arguments, is-array-buffer, is-date-object, is-regex, is-shared-array-buffer, which-boxed-primitive, which-collection, which-typed-array, object-keys, object.assign, get-intrinsic, call-bound, side-channel, es-get-iterator), each providing a spec-accurate, cross-realm-safe check. Testing runs on tape with nyc coverage; linting uses eslint with @ljharb/eslint-config; publishing is gated by safe-publish-latest and npmignore; CI spans several GitHub Actions workflows testing across many Node major versions plus a post-test npm audit.

Code Quality The test suite (test/cmp.js, over 1,500 lines) exercises primitives, boxed types, arrays, typed arrays, Dates, RegExps, Buffers, ArrayBuffers, Maps, Sets, and cyclic-reference cases extensively, run through tape with an _tape.js harness. Intrinsics are accessed through cached callBound references rather than direct prototype method calls, a defensive style typical of the es-shims ecosystem that guards against prototype pollution. There are no TypeScript types or JSDoc annotations — this is intentionally plain, dependency-shimmed JavaScript — but linting is enforced as a pretest hook and CI runs the suite across a wide matrix of Node versions. Because the library performs no I/O, there’s no error-handling layer to speak of; correctness is enforced through defensive type checks rather than exceptions.

API Design The public surface is deliberately minimal: one function, deepEqual(a, b, opts), returning a boolean, with a single option (strict). There’s no configuration to learn beyond that flag, and the mental model maps directly onto what most JavaScript developers already know from Node’s assert.deepEqual/assert.deepStrictEqual. Its differentiator isn’t a richer feature set — unlike general-purpose “isEqual” utilities that add customizer callbacks — but spec-fidelity: it reproduces Node’s actual internal comparison algorithm rather than a simplified reimplementation, which is why other polyfill packages (such as commonjs-assert) reference this repo as their algorithmic source of truth.