# object-identity [](https://licenses.dev/npm/object-identity)
**A tiny, fast utility that canonicalizes any value into a stable identity, for structurally
equality.**
This is free to use software, but if you do like it, consider supporting me โค๏ธ
[](https://github.com/sponsors/maraisr)
[](https://www.buymeacoffee.com/marais)
## โก Features
- ๐งฌ **Canonical.** The same shape always produces the same id.
- ๐ **Deep and cycle-safe.** Handles nested objects, arrays, sets, maps, and circular references.
- ๐ **Fast.** See the [benchmarks](#-benchmark).
- ๐ชถ **Tiny.** Around 535B minified and gzipped, with zero
[dependencies](https://npm.anvaka.com/#/view/2d/object-identity/).
## โ๏ธ Install
- **npm** โ available as [`object-identity`](https://www.npmjs.com/package/object-identity)
- **JSR** โ available as [`@mr/object-identity`](https://jsr.io/@mr/object-identity)
## ๐ Usage
```ts
import { identify } from 'object-identity';
// same shape, different key order, same id
identify({ a: 1, b: 2 }) === identify({ b: 2, a: 1 }); // true
// a plain object and an equivalent Map produce the same id
identify({ a: 'b' }) === identify(new Map([['a', 'b']])); // true
// nesting, Sets, Dates, and RegExps are all supported
const key = identify({ user: 7, filters: new Set(['active', 'new']) });
```
## ๐จ Benchmark
- **simple** a complete nested object, with an arrays and other mixed primitives.
- **deep** a long, narrow nesting chain.
- **deep circular** the deep chain, but every node points back and the tail closes the loop.
- **big** a wide object: hundreds of keys, but with small values.
- **leafy** a large flat array of mixed primitives.
```
โ simple ~ 1.1ยตs @ 932,332 ops/sec ยฑ 0.76%
โ deep ~ 8.0ยตs @ 124,505 ops/sec ยฑ 2.85%
โ deep circular ~ 5.5ยตs @ 183,042 ops/sec ยฑ 0.16%
โ big ~ 80.2ยตs @ 12,467 ops/sec ยฑ 0.42%
โ leafy ~ 23.7ยตs @ 42,223 ops/sec ยฑ 0.63%
```
All candidates
```
simple
โ object-identity ~ 1.1ยตs @ 932,332 ops/sec ยฑ 0.76%
โ safe-stable-stringify ~ 1.7ยตs @ 588,871 ops/sec ยฑ 0.67%
โ ohash ~ 3.5ยตs @ 285,750 ops/sec ยฑ 0.28%
โ object-hash ~ 9.7ยตs @ 102,617 ops/sec ยฑ 2.08%
โ hash-it โ ~ 2.8ยตs @ 361,547 ops/sec ยฑ 2.62%
โ json-stable-stringify ~ 3.1ยตs @ 325,737 ops/sec ยฑ 0.08%
โ fast-json-stable-stringify ~ 2.1ยตs @ 480,206 ops/sec ยฑ 0.44%
โ tiny-stable-stringify ~ 2.4ยตs @ 409,949 ops/sec ยฑ 1.60%
โ json-stringify-deterministic ~ 3.1ยตs @ 326,067 ops/sec ยฑ 2.55%
โ json-stable-stringify-without-jsonify ~ 3.0ยตs @ 329,660 ops/sec ยฑ 0.25%
โ json-sorted-stringify ~ 2.3ยตs @ 429,194 ops/sec ยฑ 0.54%
โ canonicalize ~ 3.5ยตs @ 284,416 ops/sec ยฑ 1.62%
โ @tufjs/canonical-json
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.58x faster than safe-stable-stringify)
deep
โ object-identity ~ 8.0ยตs @ 124,505 ops/sec ยฑ 2.85%
โ safe-stable-stringify ~ 13.6ยตs @ 73,292 ops/sec ยฑ 0.45%
โ ohash ~ 25.6ยตs @ 39,078 ops/sec ยฑ 0.79%
โ object-hash ~ 53.3ยตs @ 18,748 ops/sec ยฑ 1.73%
โ hash-it โ ~ 21.1ยตs @ 47,506 ops/sec ยฑ 1.23%
โ json-stable-stringify ~ 22.9ยตs @ 43,649 ops/sec ยฑ 1.24%
โ fast-json-stable-stringify ~ 14.4ยตs @ 69,262 ops/sec ยฑ 0.14%
โ tiny-stable-stringify ~ 16.4ยตs @ 60,994 ops/sec ยฑ 0.38%
โ json-stringify-deterministic ~ 22.5ยตs @ 44,468 ops/sec ยฑ 1.25%
โ json-stable-stringify-without-jsonify ~ 22.7ยตs @ 43,964 ops/sec ยฑ 0.53%
โ json-sorted-stringify ~ 16.1ยตs @ 61,935 ops/sec ยฑ 0.64%
โ canonicalize ~ 26.7ยตs @ 37,508 ops/sec ยฑ 0.76%
โ @tufjs/canonical-json ~ 34.5ยตs @ 29,020 ops/sec ยฑ 1.45%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.70x faster than safe-stable-stringify)
deep circular
โ object-identity ~ 5.5ยตs @ 183,042 ops/sec ยฑ 0.16%
โ safe-stable-stringify ~ 7.2ยตs @ 139,264 ops/sec ยฑ 0.32%
โ ohash ~ 16.6ยตs @ 60,357 ops/sec ยฑ 0.66%
โ object-hash ~ 44.1ยตs @ 22,688 ops/sec ยฑ 1.50%
โ hash-it โ ~ 15.1ยตs @ 66,295 ops/sec ยฑ 1.39%
โ json-stable-stringify
โ fast-json-stable-stringify ~ 10.0ยตs @ 100,160 ops/sec ยฑ 0.67%
โ tiny-stable-stringify
โ json-stringify-deterministic ~ 14.8ยตs @ 67,354 ops/sec ยฑ 1.50%
โ json-stable-stringify-without-jsonify
โ json-sorted-stringify
โ canonicalize
โ @tufjs/canonical-json
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.31x faster than safe-stable-stringify)
big
โ object-identity ~ 80.2ยตs @ 12,467 ops/sec ยฑ 0.42%
โ safe-stable-stringify ~ 135.1ยตs @ 7,404 ops/sec ยฑ 0.88%
โ ohash ~ 289.9ยตs @ 3,449 ops/sec ยฑ 0.63%
โ object-hash ~ 490.0ยตs @ 2,041 ops/sec ยฑ 1.51%
โ hash-it โ ~ 258.9ยตs @ 3,862 ops/sec ยฑ 0.48%
โ json-stable-stringify ~ 214.5ยตs @ 4,662 ops/sec ยฑ 0.69%
โ fast-json-stable-stringify ~ 156.8ยตs @ 6,379 ops/sec ยฑ 0.69%
โ tiny-stable-stringify ~ 174.3ยตs @ 5,736 ops/sec ยฑ 0.24%
โ json-stringify-deterministic ~ 223.6ยตs @ 4,471 ops/sec ยฑ 0.38%
โ json-stable-stringify-without-jsonify ~ 215.6ยตs @ 4,639 ops/sec ยฑ 0.21%
โ json-sorted-stringify ~ 165.3ยตs @ 6,049 ops/sec ยฑ 0.13%
โ canonicalize ~ 245.5ยตs @ 4,073 ops/sec ยฑ 0.44%
โ @tufjs/canonical-json ~ 369.7ยตs @ 2,705 ops/sec ยฑ 0.11%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.68x faster than safe-stable-stringify)
leafy
โ object-identity ~ 23.7ยตs @ 42,223 ops/sec ยฑ 0.63%
โ safe-stable-stringify ~ 51.0ยตs @ 19,622 ops/sec ยฑ 0.66%
โ ohash ~ 30.6ยตs @ 32,645 ops/sec ยฑ 0.38%
โ object-hash ~ 82.1ยตs @ 12,183 ops/sec ยฑ 0.10%
โ hash-it โ ~ 83.0ยตs @ 12,050 ops/sec ยฑ 0.42%
โ json-stable-stringify ~ 113.6ยตs @ 8,800 ops/sec ยฑ 0.02%
โ fast-json-stable-stringify ~ 59.2ยตs @ 16,901 ops/sec ยฑ 1.06%
โ tiny-stable-stringify ~ 103.5ยตs @ 9,661 ops/sec ยฑ 0.11%
โ json-stringify-deterministic ~ 111.5ยตs @ 8,965 ops/sec ยฑ 0.00%
โ json-stable-stringify-without-jsonify ~ 113.7ยตs @ 8,796 ops/sec ยฑ 2.00%
โ json-sorted-stringify ~ 107.3ยตs @ 9,324 ops/sec ยฑ 0.97%
โ canonicalize ~ 92.4ยตs @ 10,821 ops/sec ยฑ 1.36%
โ @tufjs/canonical-json ~ 207.2ยตs @ 4,826 ops/sec ยฑ 0.72%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.29x faster than ohash)
```
> `object-identity` only handles mainly JSON-like data by design. It won't fingerprint functions or
> every Node builtin the way some alternatives do, so these numbers only reflect the payloads it
> targets.
## License
MIT ยฉ [Marais Rossouw](https://marais.io)