refactor: add a new crossRealm option for performance

Author: JounQin

.changeset/four-beds-visit.md

@@ -0,0 +1,5 @@
+---
+"stable-hash-x": minor
+---
+
+refactor: add a new `crossRealm` option for performance

.size-limit.json

@@ -1,6 +1,6 @@
 [
   {
     "path": "./lib/index.js",
-    "limit": "540B"
+    "limit": "600B"
   }
 ]

README.md

@@ -13,7 +13,7 @@
 [![Code Style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 [![changesets](https://img.shields.io/badge/maintained%20with-changesets-176de3.svg)](https://github.com/changesets/changesets)
 
-A tiny and fast (540b <sup>[unpkg](https://unpkg.com/stable-hash-x@latest/lib/index.js)</sup>) lib for "stably hashing" a JavaScript value, works with cross-realm objects. Originally created for [SWR](https://github.com/vercel/swr) by [Shu Ding][] at [`stable-hash`](https://github.com/shuding/stable-hash), we forked it because the original one is a bit out of maintenance for a long time.
+A tiny and fast (600b <sup>[unpkg](https://unpkg.com/stable-hash-x@latest/lib/index.js)</sup>) lib for "stably hashing" a JavaScript value, works with cross-realm objects. Originally created for [SWR](https://github.com/vercel/swr) by [Shu Ding][] at [`stable-hash`](https://github.com/shuding/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:
 
@@ -31,6 +31,7 @@ It's similar to `JSON.stringify(value)`, but:
   - [Array](#array)
   - [Object](#object)
   - [`Function`, `Class`, `Set`, `Map`, `Buffer`...](#function-class-set-map-buffer)
+  - [Cross-realm](#cross-realm)
 - [Benchmark](#benchmark)
 - [Notes](#notes)
 - [Sponsors and Backers](#sponsors-and-backers)
@@ -49,6 +50,8 @@ 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
@@ -153,37 +156,39 @@ hash(foo) === hash(foo)
 hash(foo) !== hash(new Set([1]))
 ```
 
+### Cross-realm
+
+```js
+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
+```
+
 ## Benchmark
 
 ```log
-clk: ~2.91 GHz
-cpu: Apple M1 Max
-runtime: node 22.16.0 (arm64-darwin)
-
-benchmark                   avg (min … max) p75 / p99    (min … top 1%)
-------------------------------------------- -------------------------------
-stable-hash-x                  7.87 µs/iter   7.38 µs   █
-                      (6.67 µs … 749.13 µs)  11.42 µs  ▇█▃
-                    (104.00  b … 859.30 kb)  10.89 kb ▁███▅▂▂▂▂▁▁▁▁▁▁▁▁▁▁▁▁
-                  4.41 ipc (  1.81% stalls)  98.08% L1 data cache
-         28.04k cycles 123.52k instructions  29.75% retired LD/ST ( 36.75k)
-
-hash-object                   15.07 µs/iter  14.95 µs             █   █
-                      (14.77 µs … 16.93 µs)  15.00 µs ▅  ▅      ▅▅█  ▅█▅  ▅
-                    (659.78  b …   3.26 kb)   1.95 kb █▁▁█▁▁▁▁▁▁███▁▁███▁▁█
-                  4.97 ipc (  1.22% stalls)  99.33% L1 data cache
-         46.36k cycles 230.44k instructions  35.12% retired LD/ST ( 80.94k)
-
-json-stringify-deterministic   8.37 µs/iter   8.41 µs        █
-                        (8.29 µs … 8.50 µs)   8.44 µs     █  █
-                    (  1.65 kb …   1.65 kb)   1.65 kb █▁████▁██▁█▁▁▁█▁█▁███
-                  5.17 ipc (  1.28% stalls)  99.40% L1 data cache
-         25.99k cycles 134.30k instructions  35.51% retired LD/ST ( 47.69k)
-
-summary
-  stable-hash-x
-   1.06x faster than json-stringify-deterministic
-   1.91x faster than hash-object
+┌─────────┬────────────────────────────────┬──────────────────┬───────────────────┬────────────────────────┬────────────────────────┬─────────┐
+│ (index) │ Task name                      │ Latency avg (ns) │ Latency med (ns)  │ Throughput avg (ops/s) │ Throughput med (ops/s) │ Samples │
+├─────────┼────────────────────────────────┼──────────────────┼───────────────────┼────────────────────────┼────────────────────────┼─────────┤
+│ 0       │ 'stable-hash-x'                │ '7790.5 ± 1.63%' │ '6917.0 ± 166.00' │ '141091 ± 0.05%'       │ '144571 ± 3388'        │ 128362  │
+│ 1       │ 'hash-object'                  │ '17673 ± 0.69%'  │ '16583 ± 292.00'  │ '59046 ± 0.07%'        │ '60303 ± 1043'         │ 56583   │
+│ 2       │ 'json-stringify-deterministic' │ '10842 ± 0.86%'  │ '10167 ± 250.00'  │ '96508 ± 0.05%'        │ '98357 ± 2361'         │ 92235   │
+│ 3       │ 'stable-hash'                  │ '7801.1 ± 1.68%' │ '6958.0 ± 167.00' │ '141110 ± 0.05%'       │ '143719 ± 3534'        │ 128187  │
+└─────────┴────────────────────────────────┴──────────────────┴───────────────────┴────────────────────────┴────────────────────────┴─────────┘
 ```
 
 ## Notes

benchmark.js

@@ -6,9 +6,10 @@ import { encodeUrl } from 'ab64'
 import { flattie } from 'flattie'
 import hashObject from 'hash-object'
 import stringify from 'json-stringify-deterministic'
-import { bench, run, summary } from 'mitata'
+import { stableHash } from 'stable-hash'
+import { Bench } from 'tinybench'
 
-import { hash } from 'stable-hash-x'
+import { stableHash as hash } from './lib/index.js'
 
 // this is an example of payload
 const payload = {
@@ -42,7 +43,7 @@ const payload = {
 
 /**
  * Benchmarking `stable-hash-x` vs. `hash-object` vs.
- * `json-stringify-deterministic`
+ * `json-stringify-deterministic` vs. `stable-hash`
  *
  * The goal is to represent a real use-case. Because that:
  *
@@ -87,12 +88,26 @@ const getHashThree = obj =>
       .digest('base64'),
   )
 
-summary(() => {
-  bench('stable-hash-x', () => getHashOne(payload)).baseline()
+/**
+ * @param {unknown} obj
+ * @returns {string} The hash
+ */
+const getHashFour = obj =>
+  encodeUrl(
+    crypto
+      .createHash('sha512')
+      .update(stableHash(flattie(obj)))
+      .digest('base64'),
+  )
+
+const bench = new Bench()
 
-  bench('hash-object', () => getHashTwo(payload))
+bench
+  .add('stable-hash-x', () => getHashOne(payload))
+  .add('hash-object', () => getHashTwo(payload))
+  .add('json-stringify-deterministic', () => getHashThree(payload))
+  .add('stable-hash', () => getHashFour(payload))
 
-  bench('json-stringify-deterministic', () => getHashThree(payload))
-})
+await bench.run()
 
-await run()
+console.table(bench.table())

benchmark.txt

@@ -1,28 +1,8 @@
-clk: ~2.91 GHz
-cpu: Apple M1 Max
-runtime: node 22.16.0 (arm64-darwin)
-
-benchmark                   avg (min … max) p75 / p99    (min … top 1%)
-------------------------------------------- -------------------------------
-stable-hash-x                  7.87 µs/iter   7.38 µs   █                  
-                      (6.67 µs … 749.13 µs)  11.42 µs  ▇█▃                 
-                    (104.00  b … 859.30 kb)  10.89 kb ▁███▅▂▂▂▂▁▁▁▁▁▁▁▁▁▁▁▁
-                  4.41 ipc (  1.81% stalls)  98.08% L1 data cache
-         28.04k cycles 123.52k instructions  29.75% retired LD/ST ( 36.75k)
-
-hash-object                   15.07 µs/iter  14.95 µs             █   █    
-                      (14.77 µs … 16.93 µs)  15.00 µs ▅  ▅      ▅▅█  ▅█▅  ▅
-                    (659.78  b …   3.26 kb)   1.95 kb █▁▁█▁▁▁▁▁▁███▁▁███▁▁█
-                  4.97 ipc (  1.22% stalls)  99.33% L1 data cache
-         46.36k cycles 230.44k instructions  35.12% retired LD/ST ( 80.94k)
-
-json-stringify-deterministic   8.37 µs/iter   8.41 µs        █             
-                        (8.29 µs … 8.50 µs)   8.44 µs     █  █             
-                    (  1.65 kb …   1.65 kb)   1.65 kb █▁████▁██▁█▁▁▁█▁█▁███
-                  5.17 ipc (  1.28% stalls)  99.40% L1 data cache
-         25.99k cycles 134.30k instructions  35.51% retired LD/ST ( 47.69k)
-
-summary
-  stable-hash-x
-   1.06x faster than json-stringify-deterministic
-   1.91x faster than hash-object
+┌─────────┬────────────────────────────────┬──────────────────┬───────────────────┬────────────────────────┬────────────────────────┬─────────┐
+│ (index) │ Task name                      │ Latency avg (ns) │ Latency med (ns)  │ Throughput avg (ops/s) │ Throughput med (ops/s) │ Samples │
+├─────────┼────────────────────────────────┼──────────────────┼───────────────────┼────────────────────────┼────────────────────────┼─────────┤
+│ 0       │ 'stable-hash-x'                │ '7790.5 ± 1.63%' │ '6917.0 ± 166.00' │ '141091 ± 0.05%'       │ '144571 ± 3388'        │ 128362  │
+│ 1       │ 'hash-object'                  │ '17673 ± 0.69%'  │ '16583 ± 292.00'  │ '59046 ± 0.07%'        │ '60303 ± 1043'         │ 56583   │
+│ 2       │ 'json-stringify-deterministic' │ '10842 ± 0.86%'  │ '10167 ± 250.00'  │ '96508 ± 0.05%'        │ '98357 ± 2361'         │ 92235   │
+│ 3       │ 'stable-hash'                  │ '7801.1 ± 1.68%' │ '6958.0 ± 167.00' │ '141110 ± 0.05%'       │ '143719 ± 3534'        │ 128187  │
+└─────────┴────────────────────────────────┴──────────────────┴───────────────────┴────────────────────────┴────────────────────────┴─────────┘

package.json

@@ -34,7 +34,7 @@
     "lib"
   ],
   "scripts": {
-    "benchmark": "sudo env NO_COLOR=1 node benchmark > benchmark.txt",
+    "benchmark": "node benchmark > benchmark.txt",
     "build": "tsdown -d lib -f cjs,esm",
     "dev": "vitest",
     "docs": "vite",
@@ -73,7 +73,6 @@
     "github-markdown-css": "^5.8.1",
     "hash-object": "^5.0.1",
     "json-stringify-deterministic": "^1.0.12",
-    "mitata": "^1.0.34",
     "nano-staged": "^0.8.0",
     "npm-run-all2": "^8.0.4",
     "prettier": "^3.5.3",
@@ -84,6 +83,8 @@
     "simple-git-hooks": "^2.13.0",
     "size-limit": "^11.2.0",
     "size-limit-preset-node-lib": "^0.4.0",
+    "stable-hash": "^0.0.6",
+    "tinybench": "^4.0.1",
     "tsdown": "^0.12.6",
     "type-coverage": "^2.29.7",
     "typescript": "^5.8.3",

src/index.ts

@@ -31,11 +31,16 @@ const isPlainObject = (val: object) => {
 // This is not a serialization function, and the result is not guaranteed to be
 // parsable.
 // eslint-disable-next-line sonarjs/cognitive-complexity
-export function stableHash(arg: unknown): string {
+export function stableHash(arg: unknown, crossRealm?: boolean): string {
   const type = typeof arg
-  const isDate = isType(arg, 'Date')
+  const constructor = arg?.constructor
+  const isDate = crossRealm ? isType(arg, 'Date') : constructor === Date
 
-  if (Object(arg) === arg && !isDate && !isType(arg, 'RegExp')) {
+  if (
+    Object(arg) === arg &&
+    !isDate &&
+    !(crossRealm ? isType(arg, 'RegExp') : constructor === RegExp)
+  ) {
     const arg_ = arg as object
     // Object/function, not null/date/regexp. Use WeakMap to store the id first.
     // If it's already hashed, directly return the result.
@@ -49,15 +54,15 @@ export function stableHash(arg: unknown): string {
     result = ++counter + '~'
     table.set(arg_, result)
     let index: number | string | undefined
-    if (Array.isArray(arg)) {
+    if (crossRealm ? Array.isArray(arg) : constructor === Array) {
       const arg_ = arg as unknown[]
       // Array.
       result = '@'
       for (index = 0; index < arg_.length; index++) {
-        result += stableHash(arg_[index]) + ','
+        result += stableHash(arg_[index], crossRealm) + ','
       }
       table.set(arg_, result)
-    } else if (isPlainObject(arg_)) {
+    } else if (crossRealm ? isPlainObject(arg_) : constructor === Object) {
       // Object, sort keys.
       result = '#'
       // eslint-disable-next-line sonarjs/no-alphabetical-sort
@@ -66,7 +71,7 @@ export function stableHash(arg: unknown): string {
         const index_ = index as keyof typeof arg_
         // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
         if (arg_[index_] !== undefined) {
-          result += index + ':' + stableHash(arg_[index_]) + ','
+          result += index + ':' + stableHash(arg_[index_], crossRealm) + ','
         }
       }
       table.set(arg_, result)

tests/unit.spec.ts

@@ -379,6 +379,6 @@ describe(`The Func-y Bunch featuring The Referential Squad`, () => {
       f: Symbol('test'),
     })`) as typeof obj1
     expect(obj1).not.toEqual(obj2)
-    expect(hash(obj1)).toEqual(hash(obj2))
+    expect(hash(obj1)).toEqual(hash(obj2, true))
   })
 })

yarn.lock

@@ -10130,13 +10130,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"mitata@npm:^1.0.34":
-  version: 1.0.34
-  resolution: "mitata@npm:1.0.34"
-  checksum: 10c0/a78a0dd18203e47f444915e64e900e9686d5b6c53c461105f79a6b4795983a2f1fa573ce6fea697ebb29c31ff31b2e7e4f0ce072e0611e0313ebef274a0a5811
-  languageName: node
-  linkType: hard
-
 "mkdirp@npm:^0.5.1":
   version: 0.5.6
   resolution: "mkdirp@npm:0.5.6"
@@ -13113,7 +13106,6 @@ __metadata:
     github-markdown-css: "npm:^5.8.1"
     hash-object: "npm:^5.0.1"
     json-stringify-deterministic: "npm:^1.0.12"
-    mitata: "npm:^1.0.34"
     nano-staged: "npm:^0.8.0"
     npm-run-all2: "npm:^8.0.4"
     prettier: "npm:^3.5.3"
@@ -13124,6 +13116,8 @@ __metadata:
     simple-git-hooks: "npm:^2.13.0"
     size-limit: "npm:^11.2.0"
     size-limit-preset-node-lib: "npm:^0.4.0"
+    stable-hash: "npm:^0.0.6"
+    tinybench: "npm:^4.0.1"
     tsdown: "npm:^0.12.6"
     type-coverage: "npm:^2.29.7"
     typescript: "npm:^5.8.3"
@@ -13140,6 +13134,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"stable-hash@npm:^0.0.6":
+  version: 0.0.6
+  resolution: "stable-hash@npm:0.0.6"
+  checksum: 10c0/5dfd823931b789daf60d9eecbed284dafba60640b92f606c9f13e8c28e3c823d3dc595b419f2df169265ab6a107384f6d0625648be12f3b17f4d6175d9690896
+  languageName: node
+  linkType: hard
+
 "stackback@npm:0.0.2":
   version: 0.0.2
   resolution: "stackback@npm:0.0.2"
@@ -13447,6 +13448,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"tinybench@npm:^4.0.1":
+  version: 4.0.1
+  resolution: "tinybench@npm:4.0.1"
+  checksum: 10c0/42ed8abf2eb914cfbff2cede5fa98cca7dcaf135ab5342a3701d2f90ed3d29fc1a2dcc092a91b1dc483d0de1fa69feac3fea64fad2ddef284bba34391bc96405
+  languageName: node
+  linkType: hard
+
 "tinyexec@npm:^0.3.2":
   version: 0.3.2
   resolution: "tinyexec@npm:0.3.2"