stable-hash-x

A tiny and fast (600B ^unpkg) lib for "stably hashing" a JavaScript value, works with cross-realm objects. Originally created for SWR by Shu Ding at stable-hash, we forked it because the original one is a bit out of maintenance for a long time.

It's similar to JSON.stringify(value), but:

1. Supports any JavaScript value (BigInt, NaN, Symbol, function, class, ...)
2. Sorts object keys (stable)
3. Supports circular objects

TOC

• Use
• Examples
  • Primitive Value
  • Regex
  • Date
  • Array
  • Object
  • Function, Class, Set, Map, Buffer...
  • Cross-realm
• Benchmark
• Notes
• Sponsors and Backers
  • Sponsors
  • Backers
• Changelog
• License

Use

yarn add stable-hash-x

import { hash } from 'stable-hash-x'

hash(anyJavaScriptValueHere) // returns a string

hash(anyJavaScriptValueHere, true) // if you're running in cross-realm environment, it's disabled by default for performance

Examples

Primitive Value

hash(1)
hash('foo')
hash(true)
hash(undefined)
hash(null)
hash(NaN)

BigInt:

hash(1) === hash(1n)
hash(1) !== hash(2n)

Symbol:

hash(Symbol.for('foo')) === hash(Symbol.for('foo'))
hash(Symbol.for('foo')) === hash(Symbol('foo'))
hash(Symbol('foo')) === hash(Symbol('foo'))
hash(Symbol('foo')) !== hash(Symbol('bar'))

Since Symbols cannot be serialized, stable-hash-x simply uses its description as the hash.

Regex

hash(/foo/) === hash(/foo/)
hash(/foo/) !== hash(/bar/)

Date

hash(new Date(1)) === hash(new Date(1))

Array

hash([1, '2', [new Date(3)]]) === hash([1, '2', [new Date(3)]])
hash([1, 2]) !== hash([2, 1])

Circular:

const foo = []
foo.push(foo)
hash(foo) === hash(foo)

Object

hash({ foo: 'bar' }) === hash({ foo: 'bar' })
hash({ foo: { bar: 1 } }) === hash({ foo: { bar: 1 } })

Stable:

hash({ a: 1, b: 2, c: 3 }) === hash({ c: 3, b: 2, a: 1 })

Circular:

const foo = {}
foo.foo = foo
hash(foo) === hash(foo)

Function, Class, Set, Map, Buffer...

stable-hash-x guarantees reference consistency (===) for objects that the constructor isn't Object.

const foo = () => {}
hash(foo) === hash(foo)
hash(foo) !== hash(() => {})

class Foo {}
hash(Foo) === hash(Foo)
hash(Foo) !== hash(class {})

const foo = new Set([1])
hash(foo) === hash(foo)
hash(foo) !== hash(new Set([1]))

Cross-realm

import { runInNewContext } from 'node:vm'

const obj1 = {
  a: 1,
  b: new Date('2022-06-25T01:55:27.743Z'),
  c: /test/,
  f: Symbol('test'),
}
const obj2 = runInNewContext(`({
  a: 1,
  b: new Date('2022-06-25T01:55:27.743Z'),
  c: /test/,
  f: Symbol('test'),
})`)

obj1 === obj2 // false
hash(obj1) === hash(obj2, true) // true

Benchmark

┌─────────┬────────────────────────────────┬──────────────────┬───────────────────┬────────────────────────┬────────────────────────┬─────────┐
│ (index) │ Task name                      │ Latency avg (ns) │ Latency med (ns)  │ Throughput avg (ops/s) │ Throughput med (ops/s) │ Samples │
├─────────┼────────────────────────────────┼──────────────────┼───────────────────┼────────────────────────┼────────────────────────┼─────────┤
│ 0       │ 'stable-hash-x'                │ '7877.4 ± 1.57%' │ '7042.0 ± 167.00' │ '138708 ± 0.05%'       │ '142005 ± 3449'        │ 126975  │
│ 1       │ 'hash-object'                  │ '17632 ± 0.73%'  │ '16708 ± 458.00'  │ '58820 ± 0.07%'        │ '59852 ± 1600'         │ 56716   │
│ 2       │ 'json-stringify-deterministic' │ '10901 ± 0.83%'  │ '10250 ± 250.00'  │ '95860 ± 0.05%'        │ '97561 ± 2439'         │ 91739   │
│ 3       │ 'stable-hash'                  │ '8318.5 ± 3.27%' │ '7042.0 ± 208.00' │ '138347 ± 0.06%'       │ '142005 ± 4074'        │ 120214  │
└─────────┴────────────────────────────────┴──────────────────┴───────────────────┴────────────────────────┴────────────────────────┴─────────┘

Notes

This function does something similar to JSON.stringify, but more than it. It doesn't generate a secure checksum, which usually has a fixed length and is hard to be reversed. With stable-hash-x it's still possible to get the original data. Also, the output might include any charaters, not just alphabets and numbers like other hash algorithms. So:

• Use another encoding layer on top of it if you want to display the output.
• Use another crypto layer on top of it if you want to have a secure and fixed length hash.

import crypto from 'node:crypto'

import { hash } from 'stable-hash-x'

const weakHash = hash(anyJavaScriptValueHere)
const encodedHash = Buffer.from(weakHash).toString('base64')
const safeHash = crypto.createHash('MD5').update(weakHash).digest('hex')

Also, the consistency of this lib is sometimes guaranteed by the singularity of the WeakMap instance. So it might not generate the consistent results when running in different runtimes, e.g. server/client or parent/worker scenarios.

Sponsors and Backers

Sponsors

1stG	RxTS	UnRS	UnTS

Backers

1stG	RxTS	UnRS	UnTS

Changelog

Detailed changes for each release are documented in CHANGELOG.md.

License

Originally created by Shu Ding.

MIT © JounQin@1stG.me

Change Log

0.2.0

Minor Changes

• #11 304fe40 Thanks @JounQin! - refactor: add a new crossRealm option for performance

Patch Changes

• #9 8dcd38d Thanks @JounQin! - fix: use toString and prototype instead of constructor for type checking

0.1.1

Patch Changes

• #6 78a433d Thanks @JounQin! - chore: add engines field, compatible with Node 12+

0.1.0

Minor Changes

• #1 cb7340b Thanks @JounQin! - feat: let's fork and release as stable-hash-x