react-deep-check/README.md

Lightweight deep equality utilities and React hooks (useDeepCompareEffect, memo) for reliable deep checks in React.

# 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

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

Peer dependency: `react >=16.8`.

## Usage

```tsx
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