# 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 @ 870,271 ops/sec ยฑ 0.22%
โ deep ~ 8.4ยตs @ 118,807 ops/sec ยฑ 0.01%
โ deep circular ~ 6.0ยตs @ 166,470 ops/sec ยฑ 0.51%
โ big ~ 82.1ยตs @ 12,175 ops/sec ยฑ 1.06%
โ leafy ~ 23.8ยตs @ 41,957 ops/sec ยฑ 0.70%
```
All candidates
```
simple
โ object-identity ~ 1.1ยตs @ 870,271 ops/sec ยฑ 0.22%
โ safe-stable-stringify ~ 1.8ยตs @ 563,781 ops/sec ยฑ 0.46%
โ ohash ~ 3.8ยตs @ 262,901 ops/sec ยฑ 0.25%
โ object-hash ~ 10.2ยตs @ 98,164 ops/sec ยฑ 1.84%
โ hash-it โ ~ 3.0ยตs @ 335,235 ops/sec ยฑ 2.05%
โ json-stable-stringify ~ 3.1ยตs @ 317,679 ops/sec ยฑ 0.30%
โ fast-json-stable-stringify ~ 2.1ยตs @ 471,606 ops/sec ยฑ 0.22%
โ tiny-stable-stringify ~ 2.5ยตs @ 403,418 ops/sec ยฑ 1.49%
โ json-stringify-deterministic ~ 3.2ยตs @ 313,455 ops/sec ยฑ 0.63%
โ json-stable-stringify-without-jsonify ~ 3.2ยตs @ 312,450 ops/sec ยฑ 0.59%
โ json-sorted-stringify ~ 2.4ยตs @ 411,299 ops/sec ยฑ 0.86%
โ canonicalize ~ 3.7ยตs @ 271,025 ops/sec ยฑ 0.17%
โ swr/_internal/stableHash ~ 3.9ยตs @ 255,223 ops/sec ยฑ 0.60%
โ @tufjs/canonical-json
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.54x faster than safe-stable-stringify)
deep
โ object-identity ~ 8.4ยตs @ 118,807 ops/sec ยฑ 0.01%
โ safe-stable-stringify ~ 13.3ยตs @ 75,024 ops/sec ยฑ 0.66%
โ ohash ~ 26.0ยตs @ 38,497 ops/sec ยฑ 0.57%
โ object-hash ~ 56.2ยตs @ 17,807 ops/sec ยฑ 0.95%
โ hash-it โ ~ 22.8ยตs @ 43,812 ops/sec ยฑ 0.14%
โ json-stable-stringify ~ 24.1ยตs @ 41,487 ops/sec ยฑ 0.95%
โ fast-json-stable-stringify ~ 14.2ยตs @ 70,522 ops/sec ยฑ 0.39%
โ tiny-stable-stringify ~ 16.1ยตs @ 62,039 ops/sec ยฑ 0.56%
โ json-stringify-deterministic ~ 23.2ยตs @ 43,102 ops/sec ยฑ 0.15%
โ json-stable-stringify-without-jsonify ~ 23.3ยตs @ 42,858 ops/sec ยฑ 0.18%
โ json-sorted-stringify ~ 15.8ยตs @ 63,287 ops/sec ยฑ 0.73%
โ canonicalize ~ 26.8ยตs @ 37,383 ops/sec ยฑ 0.16%
โ swr/_internal/stableHash ~ 29.0ยตs @ 34,460 ops/sec ยฑ 22.90%
โ @tufjs/canonical-json ~ 34.9ยตs @ 28,625 ops/sec ยฑ 0.17%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.58x faster than safe-stable-stringify)
deep circular
โ object-identity ~ 6.0ยตs @ 166,470 ops/sec ยฑ 0.51%
โ safe-stable-stringify ~ 7.5ยตs @ 132,624 ops/sec ยฑ 0.27%
โ ohash ~ 17.2ยตs @ 58,116 ops/sec ยฑ 0.49%
โ object-hash ~ 45.7ยตs @ 21,863 ops/sec ยฑ 0.07%
โ hash-it โ ~ 16.1ยตs @ 61,985 ops/sec ยฑ 0.31%
โ json-stable-stringify
โ fast-json-stable-stringify ~ 10.2ยตs @ 97,666 ops/sec ยฑ 0.51%
โ tiny-stable-stringify
โ json-stringify-deterministic ~ 15.5ยตs @ 64,604 ops/sec ยฑ 0.41%
โ json-stable-stringify-without-jsonify
โ json-sorted-stringify
โ canonicalize
โ swr/_internal/stableHash ~ 15.4ยตs @ 65,066 ops/sec ยฑ 21.11%
โ @tufjs/canonical-json
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.26x faster than safe-stable-stringify)
big
โ object-identity ~ 82.1ยตs @ 12,175 ops/sec ยฑ 1.06%
โ safe-stable-stringify ~ 140.5ยตs @ 7,118 ops/sec ยฑ 0.04%
โ ohash ~ 304.4ยตs @ 3,285 ops/sec ยฑ 0.53%
โ object-hash ~ 513.2ยตs @ 1,949 ops/sec ยฑ 1.23%
โ hash-it โ ~ 276.5ยตs @ 3,617 ops/sec ยฑ 0.61%
โ json-stable-stringify ~ 228.2ยตs @ 4,382 ops/sec ยฑ 1.06%
โ fast-json-stable-stringify ~ 164.2ยตs @ 6,091 ops/sec ยฑ 0.56%
โ tiny-stable-stringify ~ 180.0ยตs @ 5,556 ops/sec ยฑ 1.08%
โ json-stringify-deterministic ~ 224.9ยตs @ 4,447 ops/sec ยฑ 1.01%
โ json-stable-stringify-without-jsonify ~ 224.1ยตs @ 4,463 ops/sec ยฑ 0.66%
โ json-sorted-stringify ~ 172.5ยตs @ 5,797 ops/sec ยฑ 0.21%
โ canonicalize ~ 262.7ยตs @ 3,807 ops/sec ยฑ 1.01%
โ swr/_internal/stableHash ~ 287.7ยตs @ 3,476 ops/sec ยฑ 16.90%
โ @tufjs/canonical-json ~ 387.7ยตs @ 2,580 ops/sec ยฑ 0.32%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.71x faster than safe-stable-stringify)
leafy
โ object-identity ~ 23.8ยตs @ 41,957 ops/sec ยฑ 0.70%
โ safe-stable-stringify ~ 50.3ยตs @ 19,896 ops/sec ยฑ 0.47%
โ ohash ~ 30.9ยตs @ 32,336 ops/sec ยฑ 0.38%
โ object-hash ~ 87.7ยตs @ 11,397 ops/sec ยฑ 1.27%
โ hash-it โ ~ 84.3ยตs @ 11,860 ops/sec ยฑ 0.97%
โ json-stable-stringify ~ 115.1ยตs @ 8,686 ops/sec ยฑ 0.87%
โ fast-json-stable-stringify ~ 59.6ยตs @ 16,765 ops/sec ยฑ 0.11%
โ tiny-stable-stringify ~ 107.8ยตs @ 9,277 ops/sec ยฑ 0.23%
โ json-stringify-deterministic ~ 116.5ยตs @ 8,583 ops/sec ยฑ 0.29%
โ json-stable-stringify-without-jsonify ~ 117.2ยตs @ 8,532 ops/sec ยฑ 0.35%
โ json-sorted-stringify ~ 107.9ยตs @ 9,266 ops/sec ยฑ 0.15%
โ canonicalize ~ 93.3ยตs @ 10,720 ops/sec ยฑ 0.50%
โ swr/_internal/stableHash ~ 134.1ยตs @ 7,459 ops/sec ยฑ 31.44%
โ @tufjs/canonical-json ~ 217.2ยตs @ 4,605 ops/sec ยฑ 1.07%
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โญ๏ธ object-identity (1.30x 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)