react-deep-check

Lightweight deep equality helpers and React hooks for stable dependency management and optimization.

Features

• deepEqual(a,b) fast structural comparison (supports cycles, Map, Set, Date, RegExp, typed arrays)
• stableHash(value) deterministic structural hash (order-independent for Set, sorted object keys)
• Hooks:
  • useDeepCompareEffect(effect, deps) like useEffect but deep-compares deps
  • useDeepCompareMemoize(value) returns stable ref that only changes when deep-equal changes
  • useShallowStable(obj) preserves reference for shallow-equal objects across renders
  • useStableHash(value) deep structural hash memoized hook

Install

npm install react-deep-check
# or
yarn add react-deep-check

Peer dependency: react >=16.8.

Usage

import { useDeepCompareEffect, deepEqual, useStableHash } from 'react-deep-check';

function Demo({ config }) {
  const hash = useStableHash(config);
  useDeepCompareEffect(() => {
    // runs only when config structurally changes
    console.log('config changed');
  }, [config]);
  return <div>Config hash: {hash}</div>;
}

API

deepEqual(a, b, options?)

Options:

• strict (default true) – same semantics as === except NaN equals NaN.
• compare(a,b,path) custom comparator may return boolean to override or undefined to continue default.

stableHash(value)

Generates a stable base36-ish style string representing value structure (not cryptographic).

useDeepCompareEffect(effect, deps)

Drop-in replacement for useEffect when your deps are objects/arrays built inline.

useDeepCompareMemoize(value)

Returns memoized value reference only updating when deep-equal differs.

useShallowStable(obj)

Keeps same reference for objects whose shallow key/value pairs are unchanged.

useStableHash(value)

Returns memoized structural hash string for a value.

Why not JSON.stringify?

• Key order differences produce false negatives.
• Fails on cycles, Set, Map, functions, RegExp.
• Performance overhead due to full serialization each render.

Performance Notes

• Avoids allocations where possible; early exit on inequality.
• Set equality uses O(n^2) fallback; acceptable for typical small sizes. Future optimization: bucket hashing.

License

MIT