# 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 555B 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 @ 910,961 ops/sec ยฑ 0.30%
โ deep ~ 8.7ยตs @ 115,162 ops/sec ยฑ 1.80%
โ deep circular ~ 5.7ยตs @ 175,990 ops/sec ยฑ 0.22%
โ big ~ 140.9ยตs @ 7,095 ops/sec ยฑ 0.08%
โ leafy ~ 23.0ยตs @ 43,393 ops/sec ยฑ 1.10%
```
All candidates
```
simple
โ object-identity ~ 1.1ยตs @ 910,961 ops/sec ยฑ 0.30%
โ safe-stable-stringify ~ 1.7ยตs @ 593,432 ops/sec ยฑ 0.15%
โ ohash ~ 3.5ยตs @ 286,954 ops/sec ยฑ 0.00%
โ object-hash ~ 9.5ยตs @ 105,175 ops/sec ยฑ 1.84%
โ hash-it โ ~ 2.7ยตs @ 364,963 ops/sec ยฑ 2.26%
โ json-stable-stringify ~ 3.2ยตs @ 315,125 ops/sec ยฑ 0.64%
โ fast-json-stable-stringify ~ 2.0ยตs @ 495,655 ops/sec ยฑ 0.52%
โ tiny-stable-stringify ~ 2.3ยตs @ 429,496 ops/sec ยฑ 0.00%
โ json-stringify-deterministic ~ 3.3ยตs @ 303,470 ops/sec ยฑ 0.08%
โ json-stable-stringify-without-jsonify ~ 3.1ยตs @ 323,737 ops/sec ยฑ 1.89%
โ canonicalize ~ 3.3ยตs @ 303,716 ops/sec ยฑ 0.10%
โ @tufjs/canonical-json
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (53.5% faster than safe-stable-stringify)
deep
โ object-identity ~ 8.7ยตs @ 115,162 ops/sec ยฑ 1.80%
โ safe-stable-stringify ~ 13.6ยตs @ 73,438 ops/sec ยฑ 0.24%
โ ohash ~ 26.1ยตs @ 38,257 ops/sec ยฑ 0.05%
โ object-hash ~ 53.8ยตs @ 18,572 ops/sec ยฑ 0.72%
โ hash-it โ ~ 21.7ยตs @ 46,100 ops/sec ยฑ 1.80%
โ json-stable-stringify ~ 22.5ยตs @ 44,539 ops/sec ยฑ 1.46%
โ fast-json-stable-stringify ~ 13.4ยตs @ 74,806 ops/sec ยฑ 0.88%
โ tiny-stable-stringify ~ 15.5ยตs @ 64,717 ops/sec ยฑ 0.50%
โ json-stringify-deterministic ~ 22.7ยตs @ 44,121 ops/sec ยฑ 1.10%
โ json-stable-stringify-without-jsonify ~ 22.1ยตs @ 45,243 ops/sec ยฑ 1.22%
โ canonicalize ~ 25.0ยตs @ 39,935 ops/sec ยฑ 1.16%
โ @tufjs/canonical-json ~ 33.5ยตs @ 29,867 ops/sec ยฑ 1.31%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (53.9% faster than fast-json-stable-stringify)
deep circular
โ object-identity ~ 5.7ยตs @ 175,990 ops/sec ยฑ 0.22%
โ safe-stable-stringify ~ 7.2ยตs @ 138,163 ops/sec ยฑ 1.36%
โ ohash ~ 16.9ยตs @ 59,172 ops/sec ยฑ 2.12%
โ object-hash ~ 44.8ยตs @ 22,345 ops/sec ยฑ 1.22%
โ hash-it โ ~ 15.4ยตs @ 64,834 ops/sec ยฑ 2.48%
โ json-stable-stringify
โ fast-json-stable-stringify
โ tiny-stable-stringify
โ json-stringify-deterministic
โ json-stable-stringify-without-jsonify
โ canonicalize
โ @tufjs/canonical-json
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (27.4% faster than safe-stable-stringify)
big
โ object-identity ~ 140.9ยตs @ 7,095 ops/sec ยฑ 0.08%
โ safe-stable-stringify ~ 135.6ยตs @ 7,377 ops/sec ยฑ 1.24%
โ ohash ~ 292.0ยตs @ 3,424 ops/sec ยฑ 0.02%
โ object-hash ~ 469.1ยตs @ 2,132 ops/sec ยฑ 1.36%
โ hash-it โ ~ 258.4ยตs @ 3,871 ops/sec ยฑ 0.22%
โ json-stable-stringify ~ 209.4ยตs @ 4,776 ops/sec ยฑ 0.50%
โ fast-json-stable-stringify ~ 150.4ยตs @ 6,647 ops/sec ยฑ 0.68%
โ tiny-stable-stringify ~ 164.6ยตs @ 6,076 ops/sec ยฑ 0.06%
โ json-stringify-deterministic ~ 268.9ยตs @ 3,719 ops/sec ยฑ 0.90%
โ json-stable-stringify-without-jsonify ~ 220.8ยตs @ 4,529 ops/sec ยฑ 0.10%
โ canonicalize ~ 240.3ยตs @ 4,162 ops/sec ยฑ 0.61%
โ @tufjs/canonical-json ~ 369.3ยตs @ 2,708 ops/sec ยฑ 0.38%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ safe-stable-stringify (4.0% faster than object-identity)
leafy
โ object-identity ~ 23.0ยตs @ 43,393 ops/sec ยฑ 1.10%
โ safe-stable-stringify ~ 48.8ยตs @ 20,510 ops/sec ยฑ 0.61%
โ ohash ~ 31.7ยตs @ 31,549 ops/sec ยฑ 1.41%
โ object-hash ~ 84.5ยตs @ 11,837 ops/sec ยฑ 1.50%
โ hash-it โ ~ 79.5ยตs @ 12,585 ops/sec ยฑ 0.26%
โ json-stable-stringify ~ 105.9ยตs @ 9,439 ops/sec ยฑ 0.26%
โ fast-json-stable-stringify ~ 54.8ยตs @ 18,234 ops/sec ยฑ 1.77%
โ tiny-stable-stringify ~ 101.9ยตs @ 9,810 ops/sec ยฑ 0.51%
โ json-stringify-deterministic ~ 123.0ยตs @ 8,133 ops/sec ยฑ 1.66%
โ json-stable-stringify-without-jsonify ~ 114.9ยตs @ 8,702 ops/sec ยฑ 0.25%
โ canonicalize ~ 91.0ยตs @ 10,986 ops/sec ยฑ 0.06%
โ @tufjs/canonical-json ~ 215.3ยตs @ 4,646 ops/sec ยฑ 0.31%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (37.5% 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)