@arcjet/stable-hash 1.0.0-beta.8 → 1.0.0

package/README.md

@@ -18,10 +18,28 @@
 
 [Arcjet][arcjet] stable hashing utility.
 
-## Installation
+- [npm package (`@arcjet/stable-hash`)](https://www.npmjs.com/package/@arcjet/stable-hash)
+- [GitHub source code (`stable-hash/` in `arcjet/arcjet-js`)](https://github.com/arcjet/arcjet-js/tree/main/stable-hash)
 
-```shell
-npm install -S @arcjet/stable-hash
+## What is this?
+
+This is an internal utility to help us create stable hashes.
+It’s super minimal and matches similar internal code in other languages.
+This exists to make sure things work the same across languages.
+
+## When should I use this?
+
+This is an internal Arcjet package not designed for public use.
+See our [_Get started_ guide][arcjet-get-started] for how to use Arcjet in your
+application.
+
+## Install
+
+This package is ESM only.
+Install with npm in Node.js:
+
+```sh
+npm install @arcjet/stable-hash
 ```
 
 ## Example
@@ -29,18 +47,28 @@ npm install -S @arcjet/stable-hash
 ```ts
 import * as hasher from "@arcjet/stable-hash";
 
-const id = hasher.hash(
+const id = await hasher.hash(
   hasher.string("type", "EMAIL"),
   hasher.uint32("version", 0),
   hasher.string("mode", "LIVE"),
   hasher.stringSliceOrdered("allow", []),
   hasher.stringSliceOrdered("deny", []),
 );
+
+console.log(id);
+// => 49573b7df8d854c2cd5d8a755a4c03aff4014493a41b963490861a279ad675b2
 ```
 
 ## License
 
-Licensed under the [Apache License, Version 2.0][apache-license].
+[Apache License, Version 2.0][apache-license] © [Arcjet Labs, Inc.][arcjet]
+
+Derivative work based on [`feross/buffer`][github-buffer] licensed under
+[MIT][github-buffer-license] © Feross Aboukhadijeh and contributors.
+Our work picks its internal hex encoding logic adjusted for our use.
 
-[arcjet]: https://arcjet.com
 [apache-license]: http://www.apache.org/licenses/LICENSE-2.0
+[arcjet]: https://arcjet.com
+[arcjet-get-started]: https://docs.arcjet.com/get-started
+[github-buffer-license]: https://github.com/feross/buffer/blob/5857e295f4d37e3ad02c3abcbf7e8e5ef51f3be6/LICENSE
+[github-buffer]: https://github.com/feross/buffer/tree/5857e295f4d37e3ad02c3abcbf7e8e5ef51f3be6

package/edge-light.js

@@ -1,6 +1,10 @@
 import { makeHasher } from './hasher.js';
 export { bool, string, stringSliceOrdered, uint32 } from './hasher.js';
 
+// @ts-ignore: this value exists in Edge Light, as it implements the DOM type for it.
+// See <https://vercel.com/docs/functions/runtimes/edge#crypto-apis>.
+// This can be verified by adding `/// <reference lib="dom" />` above.
+// But we don’t want to load the entire DOM types or edge-light-specific types.
 const hash = makeHasher(crypto.subtle);
 
 export { hash, makeHasher };

package/hasher.d.ts

@@ -1,13 +1,75 @@
+/**
+ * Writer.
+ */
 export interface StringWriter {
+    /**
+     * Write data.
+     *
+     * @param data
+     *   Value.
+     */
     writeString(data: string): void;
 }
 interface SubtleCryptoLike {
-    digest(algorithm: AlgorithmIdentifier, data: BufferSource): Promise<ArrayBuffer>;
+    digest(algorithm: {
+        name: string;
+    } | string, data: ArrayBufferView<ArrayBufferLike> | ArrayBufferLike): Promise<ArrayBuffer>;
 }
+/**
+ * Hash a field.
+ */
 export type FieldHasher = (data: StringWriter) => void;
+/**
+ * Create a hasher for a boolean.
+ *
+ * @param key
+ *   Key.
+ * @param value
+ *   Value.
+ * @returns
+ *   Hasher.
+ */
 export declare function bool(key: string, value: boolean): FieldHasher;
+/**
+ * Create a hasher for an unsigned 32-bit integer.
+ *
+ * @param key
+ *   Key.
+ * @param value
+ *   Value.
+ * @returns
+ *   Hasher.
+ */
 export declare function uint32(key: string, value: number): FieldHasher;
+/**
+ * Create a hasher for a string.
+ *
+ * @param key
+ *   Key.
+ * @param value
+ *   Value.
+ * @returns
+ *   Hasher.
+ */
 export declare function string(key: string, value: string): FieldHasher;
+/**
+ * Create a hasher for an array of strings.
+ *
+ * @param key
+ *   Key.
+ * @param values
+ *   Values.
+ * @returns
+ *   Hasher.
+ */
 export declare function stringSliceOrdered(key: string, values: string[]): FieldHasher;
+/**
+ * Create a hasher.
+ *
+ * @param subtle
+ *   Subtle crypto.
+ * @returns
+ *   Hasher.
+ */
 export declare function makeHasher(subtle: SubtleCryptoLike): (...hashers: FieldHasher[]) => Promise<string>;
 export {};

package/hasher.js

@@ -20,6 +20,16 @@ class Sha256 {
 const maxUint32 = 4294967295;
 const fieldSeparator = ":";
 const itemSeparator = ",";
+/**
+ * Create a hasher for a boolean.
+ *
+ * @param key
+ *   Key.
+ * @param value
+ *   Value.
+ * @returns
+ *   Hasher.
+ */
 function bool(key, value) {
     return (data) => {
         data.writeString(key);
@@ -32,6 +42,16 @@ function bool(key, value) {
         }
     };
 }
+/**
+ * Create a hasher for an unsigned 32-bit integer.
+ *
+ * @param key
+ *   Key.
+ * @param value
+ *   Value.
+ * @returns
+ *   Hasher.
+ */
 function uint32(key, value) {
     return (data) => {
         data.writeString(key);
@@ -44,6 +64,16 @@ function uint32(key, value) {
         }
     };
 }
+/**
+ * Create a hasher for a string.
+ *
+ * @param key
+ *   Key.
+ * @param value
+ *   Value.
+ * @returns
+ *   Hasher.
+ */
 function string(key, value) {
     return (data) => {
         data.writeString(key);
@@ -53,6 +83,16 @@ function string(key, value) {
         data.writeString(`"`);
     };
 }
+/**
+ * Create a hasher for an array of strings.
+ *
+ * @param key
+ *   Key.
+ * @param values
+ *   Values.
+ * @returns
+ *   Hasher.
+ */
 function stringSliceOrdered(key, values) {
     return (data) => {
         data.writeString(key);
@@ -67,7 +107,23 @@ function stringSliceOrdered(key, values) {
         data.writeString("]");
     };
 }
+/**
+ * Create a hasher.
+ *
+ * @param subtle
+ *   Subtle crypto.
+ * @returns
+ *   Hasher.
+ */
 function makeHasher(subtle) {
+    /**
+     * Hash fields.
+     *
+     * @param hashers
+     *   Hashers.
+     * @returns
+     *   Promise to a hash.
+     */
     return async function hash(...hashers) {
         const h = new Sha256(subtle);
         for (const hasher of hashers) {

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "@arcjet/stable-hash",
-  "version": "1.0.0-beta.8",
+  "version": "1.0.0",
   "description": "Arcjet stable hashing utility",
+  "keywords": [
+    "arcjet",
+    "hash",
+    "utility",
+    "util"
+  ],
   "license": "Apache-2.0",
   "homepage": "https://arcjet.com",
   "repository": {
@@ -19,39 +25,42 @@
     "url": "https://arcjet.com"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",
   "exports": {
     "edge-light": "./edge-light.js",
+    "workerd": "./workerd.js",
     "default": "./index.js"
   },
   "files": [
-    "LICENSE",
-    "README.md",
-    "*.js",
-    "*.d.ts",
-    "!*.config.js"
+    "edge-light.d.ts",
+    "edge-light.js",
+    "hasher.d.ts",
+    "hasher.js",
+    "index.d.ts",
+    "index.js",
+    "workerd.d.ts",
+    "workerd.js"
   ],
   "scripts": {
-    "prepublishOnly": "npm run build",
     "build": "rollup --config rollup.config.js",
     "lint": "eslint .",
-    "pretest": "npm run build",
-    "test": "node --test --experimental-test-coverage"
+    "prepublishOnly": "npm run build",
+    "test-api": "node --test -- test/*.test.js",
+    "test-coverage": "node --experimental-test-coverage --test -- test/*.test.js",
+    "test": "npm run build && npm run lint && npm run test-coverage"
   },
   "dependencies": {},
   "devDependencies": {
-    "@arcjet/eslint-config": "1.0.0-beta.8",
-    "@arcjet/rollup-config": "1.0.0-beta.8",
-    "@arcjet/tsconfig": "1.0.0-beta.8",
-    "@rollup/wasm-node": "4.41.1",
-    "@types/node": "18.18.0",
-    "eslint": "9.27.0",
-    "expect": "29.7.0",
-    "typescript": "5.8.3"
+    "@arcjet/eslint-config": "1.0.0",
+    "@arcjet/rollup-config": "1.0.0",
+    "@rollup/wasm-node": "4.55.1",
+    "@types/node": "25.0.8",
+    "eslint": "9.39.2",
+    "typescript": "5.9.3"
   },
   "publishConfig": {
     "access": "public",

package/workerd.d.ts

@@ -0,0 +1,2 @@
+export * from "./hasher.js";
+export declare const hash: (...hashers: import("./hasher.js").FieldHasher[]) => Promise<string>;

package/workerd.js

@@ -0,0 +1,10 @@
+import { makeHasher } from './hasher.js';
+export { bool, string, stringSliceOrdered, uint32 } from './hasher.js';
+
+// @ts-ignore: this value exists in Workerd, as it implements the DOM type for it.
+// See <https://developers.cloudflare.com/workers/runtime-apis/web-crypto/>.
+// This can be verified by adding `/// <reference lib="dom" />` above.
+// But we don’t want to load the entire DOM types or workerd-specific types.
+const hash = makeHasher(crypto.subtle);
+
+export { hash, makeHasher };