Skip to content

README.md

Latest commit

 

History

History
211 lines (144 loc) · 5.43 KB

README.md

File metadata and controls

211 lines (144 loc) · 5.43 KB
Arcjet Logo

@arcjet/stable-hash

npm badge

Arcjet stable hashing utility.

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 for how to use Arcjet in your application.

Install

This package is ESM only. Install with npm in Node.js:

npm install @arcjet/stable-hash

Use

import * as hasher from "@arcjet/stable-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

API

This package exports the identifiers bool, hash, makeHasher, stringSliceOrdered, string, and uint32. There is no default export.

This package exports the TypeScript types FieldHasher and StringWriter.

FieldHasher

This type represents a function that hashes a single field. You get one of these back from bool, string, stringSliceOrdered, and uint32.

Type
type FieldHasher = (data: StringWriter) => void;

StringWriter

This type represents a writer that the hasher writes data into.

Fields
  • writeString(data: string): void — writes data to the hash

bool(key, value)

Creates a field hasher for a boolean value.

Parameters
  • key (string) — the field name
  • value (boolean) — the boolean value to hash
Returns

A field hasher (FieldHasher).

hash(…hashers)

Hashes multiple fields together and returns a stable hash string. You pass in the field hashers created by bool, string, stringSliceOrdered, and uint32.

Parameters
Returns

A Promise that resolves to the hash (Promise<string>).

makeHasher(subtle)

Creates a new hash function using the provided SubtleCrypto implementation. We use this internally to support different crypto implementations across runtimes.

Parameters
  • subtle (SubtleCryptoLike) — a SubtleCrypto-like implementation
Returns

A hash function (hash).

stringSliceOrdered(key, values)

Creates a field hasher for an ordered array of strings.

Parameters
  • key (string) — the field name
  • values (ReadonlyArray<string>) — the string array to hash
Returns

A field hasher (FieldHasher).

string(key, value)

Creates a field hasher for a string value.

Parameters
  • key (string) — the field name
  • value (string) — the string value to hash
Returns

A field hasher (FieldHasher).

uint32(key, value)

Creates a field hasher for an unsigned 32-bit integer.

Parameters
  • key (string) — the field name
  • value (number) — the integer value to hash
Returns

A field hasher (FieldHasher).

License

Apache License, Version 2.0 © Arcjet Labs, Inc.

Derivative work based on feross/buffer licensed under MIT © Feross Aboukhadijeh and contributors. Our work picks its internal hex encoding logic adjusted for our use.