@verifyhash/deep-equal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 verifyhash
+
+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,97 @@
+# @verifyhash/deep-equal
+
+Zero-dependency structural deep equality for Node.js. One function, one
+boolean, and a precisely documented rule for every awkward case: `NaN`,
+`±0`, sparse arrays, `Map`/`Set` with object keys, typed arrays, boxed
+primitives, prototype mismatches — and cyclic structures, which terminate
+instead of blowing the stack.
+
+Who it's for: anyone writing tests, cache-invalidation checks, or
+change-detection who is tired of `JSON.stringify(a) === JSON.stringify(b)`
+(which breaks on key order, `undefined`, `NaN`, `Map`, `Set`, cycles, and
+typed arrays — all of which this handles correctly).
+
+## Install
+
+```
+npm install @verifyhash/deep-equal
+```
+
+Zero runtime dependencies. CommonJS, works on any maintained Node.js.
+TypeScript declarations ship in the package (`index.d.ts`).
+
+## Example
+
+```js
+const { deepEqual } = require('@verifyhash/deep-equal');
+
+deepEqual({ a: 1, b: [NaN] }, { b: [NaN], a: 1 });            // true  (key order irrelevant, NaN === NaN)
+deepEqual(new Map([[{ id: 1 }, 'x']]),
+          new Map([[{ id: 1 }, 'x']]));                        // true  (object keys match structurally)
+deepEqual(new Set([NaN, 1]), new Set([1, NaN]));               // true
+deepEqual(0, -0);                                              // false (+0 and -0 are distinct)
+deepEqual([, 1], [undefined, 1]);                              // false (a hole is not an explicit undefined)
+deepEqual(new Float64Array(1), new Uint8Array(8));             // false (same bytes, different type)
+
+// Cycles terminate and compare correctly:
+const a = { name: 'node' }; a.self = a;
+const b = { name: 'node' }; b.self = b;
+deepEqual(a, b);                                               // true
+```
+
+## API
+
+### `deepEqual(a, b) => boolean`
+
+Returns `true` iff `a` and `b` are structurally equal under these rules:
+
+| Category | Rule |
+|---|---|
+| Primitives | `Object.is` semantics: **`NaN` equals `NaN`** (unlike `===`), and **`+0` does NOT equal `-0`** (unlike `===`). Chosen because a deep-equal that says `NaN !== NaN` is useless in tests, and collapsing `±0` silently hides real sign bugs (`1/x` flips infinity sign). |
+| `null` / `undefined` | Distinct from each other and from everything else. `{ a: undefined }` does NOT equal `{}`. |
+| Plain objects | Own **enumerable string keys** only; key order irrelevant. **Symbol keys and non-enumerable properties are ignored** — two objects differing only in symbol-keyed props are equal. |
+| Prototypes | Both sides must share the **same prototype object** (identity). A plain object never equals a class instance with the same fields; `Object.create(null)` objects only equal other null-proto objects. This is the strict rule Node's `assert.deepStrictEqual` family uses; it keeps `[]` vs `{}` and `Map` vs `Set` false for free. |
+| Arrays | Length + elements. Sparse **holes are preserved**: `[, 1]` equals `[, 1]` but not `[undefined, 1]`. Extra own enumerable props on an array are compared too. |
+| `Date` | By `getTime()`. Two Invalid Dates (both `NaN`) are equal. |
+| `RegExp` | By `source` and `flags`. `lastIndex` is ignored. |
+| `Map` | Equal `size`, and every `[key, value]` entry matches an unused entry of the other map — **keys and values both compared structurally**, so `{id:1}` keys match across maps. Insertion order irrelevant. |
+| `Set` | Equal `size`, every member structurally matches an unused member. `NaN` in a Set works (Sets use SameValueZero internally). Insertion order irrelevant. |
+| `ArrayBuffer` / TypedArrays / `DataView` | **Byte-wise**, and only against the *same* type: a `Float64Array` never equals a `Uint8Array` even over identical bytes. A `subarray()` view compares only its own window, not the whole backing buffer. |
+| Boxed primitives | `new Number(3)` equals `new Number(3)` (unwrapped via `valueOf`, `Object.is` semantics) but never equals primitive `3` — object vs primitive is a type mismatch. |
+| Functions | Reference equality only. Two distinct closures with identical source are not equal. |
+| Cycles | Self-referential and mutually-referential structures terminate via an in-progress pair memo (WeakMap). Equality is **coinductive**: two cycles are equal when their infinite unrollings agree — so a 1-cycle `a→a` equals a 2-cycle `b→b'→b` when every payload matches. A cyclic structure never equals an acyclic one of different shape. |
+
+### Honest limits
+
+- **Symbol-keyed and non-enumerable properties are invisible** to the
+  comparison, by design. If those carry meaning for you, this is the wrong
+  tool.
+- Map/Set matching of *object* keys/members uses a **greedy** scan, not a full
+  bipartite matcher. With multiple structurally-equal-but-distinct candidate
+  keys mapping to different values, a pathological arrangement could greedily
+  mis-pair and report `false` where a smarter matcher finds a pairing. Sizes
+  and normal data never hit this.
+- Object-keyed `Map`/`Set` comparison is **O(n·m)** in the worst case (every
+  key of one map scanned against the other). Fine for the hundreds of entries
+  typical in tests/config; do not diff two million-entry object-keyed maps
+  with it.
+- Getters are **invoked** (values are read as a consumer would see them), and
+  cross-realm objects (e.g. from `node:vm`) fail the prototype-identity rule.
+- Floats in typed arrays compare **byte-wise**: `Float64Array [0]` vs `[-0]`
+  differ (different bit patterns), and two `NaN`s with different bit payloads
+  would differ — plain-number `NaN`s (outside typed arrays) always compare
+  equal.
+
+## Running the tests
+
+```
+cd deep-equal
+node test/index.test.js
+```
+
+231 deterministic golden-vector checks (every table row is asserted in both
+argument orders), no timers, no network, exit code 0 on success.
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Type declarations for @verifyhash/deep-equal — zero-dependency structural
+ * equality with Map/Set/Date/RegExp/typed-array/cycle support.
+ *
+ * Hand-written against index.js — every runtime export is declared here.
+ */
+
+/**
+ * Structural deep equality.
+ *
+ * Rules (documented in the README):
+ *  - Primitives compare with Object.is semantics: `NaN` equals `NaN`,
+ *    `+0` does NOT equal `-0`.
+ *  - `null` and `undefined` are distinct.
+ *  - Plain objects: key order irrelevant; only own enumerable STRING keys
+ *    are compared (symbol keys and non-enumerable properties are ignored).
+ *  - Objects must share the same prototype (identity) — a plain object never
+ *    equals a class instance.
+ *  - Arrays: length + elements; a sparse hole is NOT an explicit `undefined`.
+ *  - `Date` by `getTime()` (two Invalid Dates are equal), `RegExp` by
+ *    source + flags.
+ *  - `Map` / `Set`: equal size and structurally matching entries/members
+ *    (object keys and members match structurally, not by identity).
+ *  - `ArrayBuffer`, every TypedArray, and `DataView` compare byte-wise, and
+ *    only against the same type.
+ *  - Cyclic (self- or mutually-referential) structures terminate and compare
+ *    correctly.
+ *  - Functions are equal only by reference.
+ *
+ * @param a - first value
+ * @param b - second value
+ * @returns `true` iff `a` and `b` are structurally equal under the rules above.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;

package/index.js

@@ -0,0 +1,216 @@
+'use strict';
+
+/**
+ * @verifyhash/deep-equal — zero-dependency structural equality for Node.js.
+ *
+ * deepEqual(a, b) -> boolean. Handles primitives (NaN equals NaN; +0 and -0
+ * are DIFFERENT), plain objects (key order irrelevant, symbol keys ignored),
+ * arrays (sparse holes are not the same as explicit undefined), Date, RegExp,
+ * Map, Set, ArrayBuffer / every TypedArray / DataView (byte-wise), boxed
+ * primitives, and cyclic structures (self- and mutually-referential graphs
+ * terminate and compare correctly via an in-progress pair memo).
+ *
+ * Documented rules (see README for the full rationale):
+ *  - Numbers compare with Object.is semantics: NaN === NaN is TRUE, +0 vs -0
+ *    is FALSE.
+ *  - Objects must share the SAME prototype (identity): a plain object never
+ *    equals a class instance, even with identical own properties.
+ *  - Only own ENUMERABLE STRING keys are compared; symbol-keyed and
+ *    non-enumerable properties are ignored.
+ *  - Functions are equal only by reference.
+ *  - Typed arrays / DataView / ArrayBuffer compare BYTE-WISE and only against
+ *    the same view type (Float64Array never equals a Uint8Array, even over
+ *    identical bytes).
+ */
+
+const toString = Object.prototype.toString;
+const hasOwn = Object.prototype.hasOwnProperty;
+
+/** Byte-wise comparison of two Uint8Array views of equal length. */
+function eqBytes(a, b) {
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}
+
+/**
+ * Own enumerable string-keyed properties: same key set, structurally equal
+ * values. Symbol keys and non-enumerable properties are deliberately ignored.
+ */
+function eqOwnKeys(a, b, seen) {
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  // Membership must be checked against b's ENUMERABLE keys, not hasOwnProperty,
+  // so a non-enumerable own property on b can never mask a real mismatch.
+  const setB = new Set(keysB);
+  for (const k of keysA) {
+    if (!setB.has(k)) return false;
+    if (!eq(a[k], b[k], seen)) return false;
+  }
+  return true;
+}
+
+/**
+ * Maps: equal size, and every [key, value] entry of `a` matches an unused
+ * entry of `b` — keys and values both compared STRUCTURALLY. Uses a fast path
+ * through b.get() for SameValueZero-identical keys, then a greedy scan for
+ * structural key matches (object keys).
+ */
+function eqMap(a, b, seen) {
+  if (a.size !== b.size) return false;
+  const usedB = new Set();
+  for (const [ka, va] of a) {
+    // Fast path: b has an identical (SameValueZero) key with an equal value.
+    if (b.has(ka) && !usedB.has(ka) && eq(va, b.get(ka), seen)) {
+      usedB.add(ka);
+      continue;
+    }
+    // Structural path: find any unused key of b that deep-equals ka with a
+    // deep-equal value (needed for object keys, which differ by identity).
+    let found = false;
+    for (const [kb, vb] of b) {
+      if (usedB.has(kb)) continue;
+      if (eq(ka, kb, seen) && eq(va, vb, seen)) {
+        usedB.add(kb);
+        found = true;
+        break;
+      }
+    }
+    if (!found) return false;
+  }
+  return true;
+}
+
+/**
+ * Sets: equal size, and every member of `a` structurally matches an unused
+ * member of `b`. Fast path via b.has() (SameValueZero — this is what makes
+ * NaN-in-a-Set work directly), then a greedy structural scan for objects.
+ */
+function eqSet(a, b, seen) {
+  if (a.size !== b.size) return false;
+  const usedB = new Set();
+  for (const va of a) {
+    if (b.has(va) && !usedB.has(va)) {
+      usedB.add(va);
+      continue;
+    }
+    let found = false;
+    for (const vb of b) {
+      if (usedB.has(vb)) continue;
+      if (eq(va, vb, seen)) {
+        usedB.add(vb);
+        found = true;
+        break;
+      }
+    }
+    if (!found) return false;
+  }
+  return true;
+}
+
+/**
+ * Core recursive comparison. `seen` is a WeakMap<object, WeakSet<object>> of
+ * IN-PROGRESS (a, b) pairs: when a cycle re-enters a pair already being
+ * compared, we return true (coinductive equality — the cycle itself cannot
+ * introduce a difference; any real difference is found elsewhere in the
+ * graph). Pairs are removed when their comparison completes, so a `false`
+ * verdict is never wrongly memoized as `true` for later sibling comparisons.
+ */
+function eq(a, b, seen) {
+  // Object.is: identical references, identical primitives, NaN === NaN true,
+  // +0 vs -0 false — exactly the documented primitive semantics.
+  if (Object.is(a, b)) return true;
+  if (
+    a === null || b === null ||
+    typeof a !== 'object' || typeof b !== 'object'
+  ) {
+    // Covers null/undefined distinction, primitive vs object (a boxed Number
+    // never equals its primitive), and functions (reference-only equality —
+    // already handled by Object.is above).
+    return false;
+  }
+
+  // Documented prototype rule: both sides must share the SAME prototype
+  // object. Plain object vs class instance -> false; subclassed Array vs
+  // plain Array -> false; also separates [] from {} and Map from Set.
+  if (Object.getPrototypeOf(a) !== Object.getPrototypeOf(b)) return false;
+
+  const tag = toString.call(a);
+  if (tag !== toString.call(b)) return false; // belt-and-braces cross-type guard
+
+  switch (tag) {
+    case '[object Date]':
+      // Object.is so two Invalid Dates (getTime() = NaN) compare equal.
+      return Object.is(a.getTime(), b.getTime());
+    case '[object RegExp]':
+      return a.source === b.source && a.flags === b.flags;
+    case '[object Number]':
+    case '[object String]':
+    case '[object Boolean]':
+    case '[object BigInt]':
+    case '[object Symbol]':
+      // Boxed primitives: unwrap and compare with Object.is (so
+      // new Number(NaN) equals new Number(NaN), new Number(0) vs
+      // new Number(-0) is false). Extra expando props are ignored.
+      return Object.is(a.valueOf(), b.valueOf());
+    case '[object ArrayBuffer]':
+      return eqBytes(new Uint8Array(a), new Uint8Array(b));
+    default:
+      break;
+  }
+
+  if (ArrayBuffer.isView(a)) {
+    // Same view type guaranteed by the prototype + tag checks above, so
+    // Float64Array vs Uint8Array over identical bytes is already false here.
+    // DataView and every TypedArray flavor compare byte-wise.
+    if (a.byteLength !== b.byteLength) return false;
+    return eqBytes(
+      new Uint8Array(a.buffer, a.byteOffset, a.byteLength),
+      new Uint8Array(b.buffer, b.byteOffset, b.byteLength)
+    );
+  }
+
+  // --- Containers that can participate in cycles: memo the in-progress pair.
+  let pairs = seen.get(a);
+  if (pairs !== undefined && pairs.has(b)) return true; // cycle re-entry
+  if (pairs === undefined) {
+    pairs = new WeakSet();
+    seen.set(a, pairs);
+  }
+  pairs.add(b);
+
+  let result;
+  if (tag === '[object Map]') {
+    result = eqMap(a, b, seen);
+  } else if (tag === '[object Set]') {
+    result = eqSet(a, b, seen);
+  } else if (Array.isArray(a)) {
+    // length compared explicitly (it is not an enumerable key); sparse holes
+    // then fall out of the key comparison: a hole has no own key, an explicit
+    // undefined does — so [ ,1 ] never equals [ undefined, 1 ].
+    result = a.length === b.length && eqOwnKeys(a, b, seen);
+  } else {
+    // Plain objects and same-class instances (prototype identity was already
+    // required above).
+    result = eqOwnKeys(a, b, seen);
+  }
+
+  pairs.delete(b);
+  return result;
+}
+
+/**
+ * Structural deep equality.
+ * @param {*} a
+ * @param {*} b
+ * @returns {boolean} true iff a and b are structurally equal under the
+ *   documented rules.
+ */
+function deepEqual(a, b) {
+  return eq(a, b, new WeakMap());
+}
+
+module.exports = { deepEqual };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@verifyhash/deep-equal",
+  "version": "0.1.0",
+  "description": "Zero-dependency structural deep equality for Node.js: plain objects, arrays (sparse-hole aware), Date, RegExp, Map/Set with structural object keys, ArrayBuffer/TypedArray/DataView (byte-wise), boxed primitives, NaN-equals-NaN with +0/-0 distinction, and cyclic structures — fully typed from birth.",
+  "keywords": [
+    "deep-equal",
+    "deep-equality",
+    "structural-equality",
+    "equal",
+    "compare",
+    "cycles",
+    "circular",
+    "map",
+    "set",
+    "typed-array",
+    "zero-dependency",
+    "typescript"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "test": "node test/index.test.js"
+  },
+  "license": "MIT",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "index.d.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/verifyhash/libs.git",
+    "directory": "deep-equal"
+  },
+  "homepage": "https://github.com/verifyhash/libs/tree/main/deep-equal#readme",
+  "bugs": {
+    "url": "https://github.com/verifyhash/libs/issues"
+  }
+}