@anizoptera/uuid-slug 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (163) hide show
  1. package/LICENSE +54 -31
  2. package/README.md +1175 -30
  3. package/dist/alphabet.d.ts +9 -0
  4. package/dist/alphabet.d.ts.map +1 -0
  5. package/dist/alphabet.js +166 -0
  6. package/dist/alphabet.js.map +1 -0
  7. package/dist/base64url-name.d.ts +7 -0
  8. package/dist/base64url-name.d.ts.map +1 -0
  9. package/dist/base64url-name.js +8 -0
  10. package/dist/base64url-name.js.map +1 -0
  11. package/dist/errors.d.ts +57 -0
  12. package/dist/errors.d.ts.map +1 -0
  13. package/dist/errors.js +162 -0
  14. package/dist/errors.js.map +1 -0
  15. package/dist/feistel.js +39 -0
  16. package/dist/feistel.js.map +1 -0
  17. package/dist/generation-options.js +20 -0
  18. package/dist/generation-options.js.map +1 -0
  19. package/dist/index.d.ts +23 -168
  20. package/dist/index.js +22 -649
  21. package/dist/instant.js +83 -0
  22. package/dist/instant.js.map +1 -0
  23. package/dist/mask-handle.d.ts +16 -0
  24. package/dist/mask-handle.d.ts.map +1 -0
  25. package/dist/mask-handle.js +60 -0
  26. package/dist/mask-handle.js.map +1 -0
  27. package/dist/mask.d.ts +27 -0
  28. package/dist/mask.d.ts.map +1 -0
  29. package/dist/mask.js +164 -0
  30. package/dist/mask.js.map +1 -0
  31. package/dist/masking-codec-protocol.js +23 -0
  32. package/dist/masking-codec-protocol.js.map +1 -0
  33. package/dist/masking-codec-types.d.ts +245 -0
  34. package/dist/masking-codec-types.d.ts.map +1 -0
  35. package/dist/masking-codec.d.ts +19 -0
  36. package/dist/masking-codec.d.ts.map +1 -0
  37. package/dist/masking-codec.js +391 -0
  38. package/dist/masking-codec.js.map +1 -0
  39. package/dist/migration.js +129 -0
  40. package/dist/migration.js.map +1 -0
  41. package/dist/node/runtime.js +39 -0
  42. package/dist/node/runtime.js.map +1 -0
  43. package/dist/payload.d.ts +7 -0
  44. package/dist/payload.d.ts.map +1 -0
  45. package/dist/payload.js +118 -0
  46. package/dist/payload.js.map +1 -0
  47. package/dist/runtime/pool.js +30 -0
  48. package/dist/runtime/pool.js.map +1 -0
  49. package/dist/runtime/portable.js +27 -0
  50. package/dist/runtime/portable.js.map +1 -0
  51. package/dist/sentinel.js +10 -0
  52. package/dist/sentinel.js.map +1 -0
  53. package/dist/siphash.js +29 -0
  54. package/dist/siphash.js.map +1 -0
  55. package/dist/slug.d.ts +169 -0
  56. package/dist/slug.d.ts.map +1 -0
  57. package/dist/slug.js +268 -0
  58. package/dist/slug.js.map +1 -0
  59. package/dist/timestamp.d.ts +19 -0
  60. package/dist/timestamp.d.ts.map +1 -0
  61. package/dist/timestamp.js +44 -0
  62. package/dist/timestamp.js.map +1 -0
  63. package/dist/types.d.ts +535 -0
  64. package/dist/types.d.ts.map +1 -0
  65. package/dist/types.js +8 -0
  66. package/dist/types.js.map +1 -0
  67. package/dist/uuid-value-protocol.js +46 -0
  68. package/dist/uuid-value-protocol.js.map +1 -0
  69. package/dist/uuid-value.d.ts +17 -0
  70. package/dist/uuid-value.d.ts.map +1 -0
  71. package/dist/uuid-value.js +127 -0
  72. package/dist/uuid-value.js.map +1 -0
  73. package/dist/uuid.d.ts +65 -0
  74. package/dist/uuid.d.ts.map +1 -0
  75. package/dist/uuid.js +232 -0
  76. package/dist/uuid.js.map +1 -0
  77. package/dist/v4-slug.d.ts +16 -0
  78. package/dist/v4-slug.d.ts.map +1 -0
  79. package/dist/v4-slug.js +16 -0
  80. package/dist/v4-slug.js.map +1 -0
  81. package/dist/v4.d.ts +42 -0
  82. package/dist/v4.d.ts.map +1 -0
  83. package/dist/v4.js +85 -0
  84. package/dist/v4.js.map +1 -0
  85. package/dist/v7-bounds.d.ts +36 -0
  86. package/dist/v7-bounds.d.ts.map +1 -0
  87. package/dist/v7-bounds.js +49 -0
  88. package/dist/v7-bounds.js.map +1 -0
  89. package/dist/v7-generator-input.js +75 -0
  90. package/dist/v7-generator-input.js.map +1 -0
  91. package/dist/v7-generator.d.ts +43 -0
  92. package/dist/v7-generator.d.ts.map +1 -0
  93. package/dist/v7-generator.js +105 -0
  94. package/dist/v7-generator.js.map +1 -0
  95. package/dist/v7-keyless.d.ts +46 -0
  96. package/dist/v7-keyless.d.ts.map +1 -0
  97. package/dist/v7-keyless.js +106 -0
  98. package/dist/v7-keyless.js.map +1 -0
  99. package/dist/v7-payload.js +54 -0
  100. package/dist/v7-payload.js.map +1 -0
  101. package/dist/v7-slug.d.ts +46 -0
  102. package/dist/v7-slug.d.ts.map +1 -0
  103. package/dist/v7-slug.js +127 -0
  104. package/dist/v7-slug.js.map +1 -0
  105. package/dist/v7-timestamp.js +9 -0
  106. package/dist/v7-timestamp.js.map +1 -0
  107. package/dist/v7-value-options.js +28 -0
  108. package/dist/v7-value-options.js.map +1 -0
  109. package/dist/v7-value.d.ts +23 -0
  110. package/dist/v7-value.d.ts.map +1 -0
  111. package/dist/v7-value.js +31 -0
  112. package/dist/v7-value.js.map +1 -0
  113. package/dist/v7.js +143 -0
  114. package/dist/v7.js.map +1 -0
  115. package/package.json +18 -17
  116. package/src/alphabet.ts +616 -0
  117. package/src/base64url-name.ts +5 -0
  118. package/src/errors.ts +423 -13
  119. package/src/feistel.ts +141 -0
  120. package/src/generation-options.ts +48 -0
  121. package/src/index.ts +137 -57
  122. package/src/instant.ts +196 -0
  123. package/src/keyless.ts +9 -0
  124. package/src/mask-handle.ts +141 -0
  125. package/src/mask.ts +377 -90
  126. package/src/masking-codec-protocol.ts +29 -0
  127. package/src/masking-codec-types.ts +380 -0
  128. package/src/masking-codec.ts +923 -0
  129. package/src/migration.ts +257 -0
  130. package/src/payload.ts +321 -0
  131. package/src/runtime/bun.ts +31 -25
  132. package/src/runtime/node.ts +55 -18
  133. package/src/runtime/pool.ts +90 -0
  134. package/src/runtime/portable.ts +68 -0
  135. package/src/runtime/types.ts +30 -5
  136. package/src/sentinel.ts +13 -0
  137. package/src/siphash.ts +128 -0
  138. package/src/slug.ts +884 -0
  139. package/src/timestamp.ts +122 -0
  140. package/src/types.ts +799 -61
  141. package/src/uuid-value-protocol.ts +77 -0
  142. package/src/uuid-value.ts +341 -0
  143. package/src/uuid.ts +527 -108
  144. package/src/v4-slug.ts +27 -0
  145. package/src/v4.ts +234 -0
  146. package/src/v7-bounds.ts +171 -0
  147. package/src/v7-generator-input.ts +169 -0
  148. package/src/v7-generator.ts +245 -0
  149. package/src/v7-keyless.ts +354 -0
  150. package/src/v7-payload.ts +121 -0
  151. package/src/v7-slug.ts +293 -0
  152. package/src/v7-timestamp.ts +21 -0
  153. package/src/v7-value-options.ts +62 -0
  154. package/src/v7-value.ts +54 -0
  155. package/src/v7.ts +433 -84
  156. package/dist/index.d.ts.map +0 -1
  157. package/dist/index.js.map +0 -1
  158. package/dist/node/index.js +0 -647
  159. package/dist/web/index.js +0 -648
  160. package/src/base64url.ts +0 -76
  161. package/src/codec.ts +0 -218
  162. package/src/runtime/web.ts +0 -20
  163. package/src/schema.ts +0 -123
@@ -1,23 +1,60 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
1
3
  import crypto from "node:crypto";
2
- import { UuidRuntimeError } from "../errors";
3
- import type { Runtime } from "./types";
4
+ import { Buffer } from "node:buffer";
5
+ import { pooledFill } from "./pool.ts";
6
+ import type { Runtime } from "./types.ts";
4
7
 
5
- type NodeCryptoWithV7 = {
6
- randomUUIDv7?: () => string;
7
- };
8
+ const JITLESS_FLAG = "--jitless";
9
+ const JIT_ENABLED_FLAG = "--no-jitless";
10
+ let jitless: boolean | undefined;
11
+ // NODE_OPTIONS is applied before command-line flags; the final explicit setting wins. Keep this
12
+ // startup-only so bounds and generation share the selection without probing each identifier.
13
+ // Quoted option words remain whole: a filename containing a flag is not a flag.
14
+ for (let index = process.execArgv.length - 1; index >= 0; index -= 1) {
15
+ const flag = process.execArgv[index];
16
+ if (flag === JITLESS_FLAG || flag === JIT_ENABLED_FLAG) {
17
+ jitless = flag === JITLESS_FLAG;
18
+ break;
19
+ }
20
+ }
8
21
 
9
- const cryptoWithV7 = crypto as typeof crypto & NodeCryptoWithV7;
22
+ // CLI overrides settle the answer without parsing the environment. Ordinary imports allocate no
23
+ // token array; quoted environment words need tokenization only when a mode flag could be present.
24
+ const nodeOptions = jitless === undefined ? process.env.NODE_OPTIONS : undefined;
25
+ if (nodeOptions?.includes("jitless")) {
26
+ const words = nodeOptions.match(/(?:[^\s"\\]|\\.|"(?:[^"\\]|\\.)*")+/g);
27
+ for (let index = (words?.length ?? 0) - 1; index >= 0; index -= 1) {
28
+ const flag = words?.[index]?.replace(/"|\\(?=.)/g, "");
29
+ if (flag === JITLESS_FLAG || flag === JIT_ENABLED_FLAG) {
30
+ jitless = flag === JITLESS_FLAG;
31
+ break;
32
+ }
33
+ }
34
+ }
10
35
 
11
- export const runtime: Runtime = {
12
- fillRandom(bytes) {
13
- bytes.set(crypto.randomBytes(bytes.length));
14
- },
15
- uuidV4() {
16
- return crypto.randomUUID();
17
- },
18
- uuidV7() {
19
- if (!cryptoWithV7.randomUUIDv7)
20
- throw new UuidRuntimeError("Node crypto.randomUUIDv7 is unavailable.");
21
- return cryptoWithV7.randomUUIDv7();
22
- },
36
+ /**
37
+ * Node's native UTF-8 encoder materially reduces string-seed construction; the portable adapter
38
+ * remains the compatibility boundary. bench/PERFORMANCE.md owns the measured runtime scope.
39
+ */
40
+ export const encodeUtf8 = /* @__NO_SIDE_EFFECTS__ */ (text: string): Uint8Array =>
41
+ Buffer.from(text, "utf8");
42
+
43
+ const nodeRuntime: Runtime = {
44
+ /**
45
+ * `randomFillSync` writes into the buffer it is given. `randomBytes` would allocate a fresh
46
+ * `Buffer` per call and copy out of it, leaving a second, unzeroed copy of the random
47
+ * material on the heap for the collector to get to whenever it does. Pooled because the
48
+ * per-call cost dominates at 16 bytes; see `pool.ts`.
49
+ */
50
+ fillRandom: /*#__PURE__*/ pooledFill((into) => {
51
+ crypto.randomFillSync(into);
52
+ return undefined;
53
+ }),
54
+ // Pooled formatting wins with the JIT; native text wins without it. Missing native capability
55
+ // stays undefined so the generator uses its tested portable fallback. Remeasure both modes
56
+ // after Node changes; bench/PERFORMANCE.md owns the compared calls and resource limits.
57
+ ...(jitless ? { jitless: true, uuidV4: crypto.randomUUID } : {}),
23
58
  };
59
+
60
+ export const runtime = nodeRuntime;
@@ -0,0 +1,90 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ import { randomFailure } from "../errors.ts";
4
+ import type { UuidSlugError } from "../errors.ts";
5
+
6
+ /**
7
+ * Draws cryptographic randomness a page at a time instead of per id.
8
+ *
9
+ * Randomness calls cost more than copying the 16 bytes an identifier needs. The bounded pool
10
+ * amortizes that call without retaining more unissued material than needed.
11
+ *
12
+ * The source is unchanged — this batches the same CSPRNG, it does not replace or stretch it.
13
+ */
14
+ export const POOL_BYTES = 8192;
15
+
16
+ /**
17
+ * Wraps a direct random-fill primitive in a pool.
18
+ *
19
+ * Consumed bytes are zeroed as they are handed out. Batching is what creates the need: without
20
+ * a pool, material for an id is gone once used, whereas a live 8 KiB buffer would otherwise
21
+ * retain the random half of up to 512 already-issued ids, so a heap dump would expose ids the
22
+ * process had already handed out. Zeroing restores the property batching would remove; the cost
23
+ * is one write per byte already being copied.
24
+ *
25
+ * Each module instance owns its pool, so worker threads never share one. This is safe under
26
+ * Node's process model because a new process gets a fresh heap; it would NOT be safe under a
27
+ * POSIX `fork` that copies the heap, where parent and child would issue identical bytes.
28
+ */
29
+ /*#__NO_SIDE_EFFECTS__*/
30
+ export function pooledFill(
31
+ fill: (into: Uint8Array<ArrayBuffer>) => unknown,
32
+ ): (bytes: Uint8Array<ArrayBuffer>) => undefined | UuidSlugError {
33
+ let pool: Uint8Array<ArrayBuffer> | undefined;
34
+ // STARTS EMPTY, and must. Pre-filling here would move the first call's syscall off the hot path,
35
+ // which looks like a free win and is the one change that breaks heap-snapshot safety: a snapshot
36
+ // taken at import time (V8 or JavaScriptCore startup snapshots, and the serverless platforms
37
+ // built on them) would capture drawn randomness, and every process restored from it would issue
38
+ // the SAME identifiers. Nothing else would notice — the bytes stay perfectly random within any
39
+ // one process, so every other case in this suite passes. `__test__/entropy.test.ts` gates it by
40
+ // importing the package under the instrument and requiring that no source was touched.
41
+ let offset = POOL_BYTES;
42
+ return (bytes) => {
43
+ const { length } = bytes;
44
+ // A request larger than the pool would refill for a single use; serve it directly instead.
45
+ if (length > POOL_BYTES) {
46
+ return randomFailure(fill(bytes));
47
+ }
48
+ if (pool === undefined || offset + length > POOL_BYTES) {
49
+ pool ??= new Uint8Array(POOL_BYTES);
50
+ const failed = randomFailure(fill(pool));
51
+ if (failed) return failed;
52
+ offset = 0;
53
+ }
54
+ // Copy and erase in one pass; `subarray` plus `set` would allocate a view per call.
55
+ // Continuation draws need four bytes. Fixed stores avoid their loop without another view
56
+ // or retained buffer. Owned draws use four-byte blocks, reusing each source offset rather
57
+ // than repeating its arithmetic. Blocks keep the body smaller than fully expanded stores;
58
+ // other lengths keep the indexed loop. Complete-call comparisons in bench/PERFORMANCE.md
59
+ // decide this shape, not copy-only timing. Remeasure if draw widths
60
+ // or the runtime's typed-array handling change.
61
+ if (length === 4) {
62
+ bytes[0] = pool[offset + 0] as number;
63
+ pool[offset + 0] = 0;
64
+ bytes[1] = pool[offset + 1] as number;
65
+ pool[offset + 1] = 0;
66
+ bytes[2] = pool[offset + 2] as number;
67
+ pool[offset + 2] = 0;
68
+ bytes[3] = pool[offset + 3] as number;
69
+ pool[offset + 3] = 0;
70
+ } else if (length === 16) {
71
+ for (let i = 0; i < 16; i += 4) {
72
+ const sourceOffset = offset + i;
73
+ bytes[i] = pool[sourceOffset] as number;
74
+ pool[sourceOffset] = 0;
75
+ bytes[i + 1] = pool[sourceOffset + 1] as number;
76
+ pool[sourceOffset + 1] = 0;
77
+ bytes[i + 2] = pool[sourceOffset + 2] as number;
78
+ pool[sourceOffset + 2] = 0;
79
+ bytes[i + 3] = pool[sourceOffset + 3] as number;
80
+ pool[sourceOffset + 3] = 0;
81
+ }
82
+ } else
83
+ for (let i = 0; i < length; i += 1) {
84
+ bytes[i] = pool[offset + i] as number;
85
+ pool[offset + i] = 0;
86
+ }
87
+ offset += length;
88
+ return undefined;
89
+ };
90
+ }
@@ -0,0 +1,68 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ import { RNG_UNAVAILABLE, UuidSlugError } from "../errors.ts";
4
+ import { pooledFill } from "./pool.ts";
5
+ import type { Latin1Scratch, Runtime } from "./types.ts";
6
+
7
+ let utf8Encoder: TextEncoder | undefined;
8
+ const nativeToHex = (Uint8Array.prototype as { toHex?: () => string }).toHex;
9
+
10
+ /** Create the shared encoder only when mask construction needs it; generation imports this adapter too. */
11
+ export const encodeUtf8 = (text: string): Uint8Array =>
12
+ (utf8Encoder ??= new TextEncoder()).encode(text);
13
+
14
+ const runtimeCapabilities: Runtime = {
15
+ /**
16
+ * Pooled for the same reason as Node's: `getRandomValues` costs far more per call than per
17
+ * byte, and a v7 id needs 16. Bun draws this path too, where pooling measured 16x.
18
+ */
19
+ fillRandom: /*#__PURE__*/ pooledFill((into) => {
20
+ // Resolve per draw so instrumentation installed after import observes the source.
21
+ const crypto = globalThis.crypto;
22
+ if (!crypto?.getRandomValues)
23
+ return new UuidSlugError(RNG_UNAVAILABLE, "Web Crypto getRandomValues is unavailable.");
24
+ crypto.getRandomValues(into);
25
+ return undefined;
26
+ }),
27
+ };
28
+
29
+ // WebKit's fixed formatter slowed unrelated successful calls in mixed comparisons. Native hex
30
+ // did not reproduce a repeated loss while other engines retain their fixed writers. This identity
31
+ // selects cost only; absent hex support still uses the portable writer. Remeasure after browser
32
+ // changes (bench/PERFORMANCE.md); the shared ASCII decoder also slowed slug output.
33
+ if (
34
+ typeof navigator !== "undefined" &&
35
+ navigator.vendor === "Apple Computer, Inc." &&
36
+ typeof nativeToHex === "function"
37
+ )
38
+ runtimeCapabilities.uuidHex = (bytes) => nativeToHex.call(bytes);
39
+
40
+ type Latin1Buffer = Uint8Array & {
41
+ toString(encoding: "latin1", start: number, end: number): string;
42
+ };
43
+ type HostBuffer = { alloc(size: number): Latin1Buffer } | undefined;
44
+
45
+ /** Build scratch text through a Node-compatible `Buffer` constructor. */
46
+ export function bufferLatin1Scratch(hostBuffer: NonNullable<HostBuffer>) {
47
+ return (length: number): Latin1Scratch => {
48
+ const bytes = hostBuffer.alloc(length);
49
+ return { bytes, text: () => bytes.toString("latin1", 0, length) };
50
+ };
51
+ }
52
+
53
+ // Deno's Web Crypto UUID method is faster than the portable formatter; Chromium's is slower.
54
+ // Runtime identity decides only this measured performance split—the entropy and UUID contracts
55
+ // are the same, and both paths remain covered by the shared runtime corpus.
56
+ if (typeof (globalThis as { Deno?: unknown }).Deno !== "undefined") {
57
+ if (globalThis.crypto?.randomUUID)
58
+ runtimeCapabilities.uuidV4 = globalThis.crypto.randomUUID.bind(globalThis.crypto);
59
+ }
60
+
61
+ /**
62
+ * Browser `randomUUID` is intentionally not selected. Chromium measured it about five times
63
+ * slower than this package's pooled byte generator and formatter, while insecure contexts can
64
+ * expose `getRandomValues` without `randomUUID`. Leaving the shortcut absent gives every browser
65
+ * context the faster common path. Reconsider when another browser engine or Chromium release
66
+ * overturns the complete public-route measurement.
67
+ */
68
+ export const runtime: Runtime = runtimeCapabilities;
@@ -1,12 +1,37 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ import type { UuidSlugError } from "../errors.ts";
4
+
1
5
  export interface Runtime {
6
+ /** Node has disabled executable JavaScript code generation for this process. */
7
+ readonly jitless?: true;
2
8
  /**
3
9
  * The buffer is pinned to a plain `ArrayBuffer` because Web Crypto's `getRandomValues`
4
10
  * rejects a `SharedArrayBuffer` view at runtime, and the unparameterised `Uint8Array`
5
11
  * admits one. Narrowing here makes that refusal unrepresentable instead of a throw.
6
12
  */
7
- fillRandom(bytes: Uint8Array<ArrayBuffer>): void;
8
- uuidV4?(): string;
9
- uuidV7?(): string;
10
- uuidV7Bytes?(out?: Uint8Array, offset?: number): Uint8Array;
11
- uuidV7Slug?(): string;
13
+ fillRandom(this: void, bytes: Uint8Array<ArrayBuffer>): undefined | UuidSlugError;
14
+ /**
15
+ * Hooks are detached from the adapter, so `this: void` rejects implementations that depend on
16
+ * method binding.
17
+ */
18
+ /** Native UUIDv4 text; default calls trust the proper native generator's result directly. */
19
+ uuidV4?(this: void): string;
20
+ /** Native current-time UUIDv7 text; configured clocks and sequence state stay on generators. */
21
+ uuidV7?(this: void): string;
22
+ /** Native current-time UUIDv7 as one canonical unpadded base64url plain slug. */
23
+ uuidV7Slug?(this: void): string;
24
+ /** Optional native hex conversion for the runtime's selected UUID text writer. */
25
+ uuidHex?(this: void, bytes: Uint8Array): string;
26
+ /**
27
+ * Create a reusable buffer whose bytes a native call turns into a flat Latin-1 string. Adapters
28
+ * provide it only where that call beats building text from JavaScript strings.
29
+ */
30
+ latin1Scratch?(this: void, length: number): Latin1Scratch;
31
+ }
32
+
33
+ export interface Latin1Scratch {
34
+ readonly bytes: Uint8Array;
35
+ /** Return every byte of `bytes` as one Latin-1 string. */
36
+ text(this: void): string;
12
37
  }
@@ -0,0 +1,13 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ // Only the 26-character plain spelling is case-insensitive. Normalizing a base64url key would
4
+ // merge distinct UUIDs; exact hits and codecs without sentinels require no normalization.
5
+ export function findSentinel<Value>(
6
+ sentinels: ReadonlyMap<string, Value>,
7
+ slug: string,
8
+ ): Value | undefined {
9
+ return (
10
+ sentinels.get(slug) ??
11
+ (slug.length === 26 && sentinels.size !== 0 ? sentinels.get(slug.toLowerCase()) : undefined)
12
+ );
13
+ }
package/src/siphash.ts ADDED
@@ -0,0 +1,128 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ /**
4
+ * HalfSipHash-2-4 with 64-bit output — the 32-bit-word member of the SipHash family (Aumasson and
5
+ * Bernstein), transcribed from the reference implementation. It is a KEYED pseudorandom function:
6
+ * without the key its output on a chosen input is not computable, which is exactly what `mix32` — a
7
+ * fixed, public, unkeyed bijection — could never be, and the reason it replaced it.
8
+ *
9
+ * Key derivation (`mask.ts`) calls this function. The Feistel round (`feistel.ts`) writes the same
10
+ * function out for its fixed two-word message because the call cost measurably more per masked slug;
11
+ * the published vectors grade this transcription, and the Feistel and wire-format vectors grade that one.
12
+ *
13
+ * Chosen over full SipHash-2-4 because that is defined over 64-bit words, which JavaScript has only
14
+ * as `BigInt` or as hand-emulated 32-bit pairs — the first far too slow for a hot path, the second a
15
+ * re-implementation whose errors nothing would catch. HalfSipHash is 32-bit BY SPECIFICATION, so
16
+ * this is a transcription, and `__test__/siphash.test.ts` holds it to all 64 published vectors. That
17
+ * external check is the whole reason a standard primitive beat anything tuned here: nothing in this
18
+ * repository can grade a mixing function (see `feistel.ts` — every instrument here passes a
19
+ * two-round network), so agreement with a specification somebody else wrote is the only evidence
20
+ * available that can actually fail.
21
+ *
22
+ * Its key is 64 bits. `mask.ts` runs two independently keyed instances and XORs them, the standard
23
+ * cascade for widening a PRF's key; see there.
24
+ */
25
+
26
+ /** Message-absorption rounds per block — the `2` of HalfSipHash-**2**-4. */
27
+ const C_ROUNDS = 2;
28
+ /** Finalisation rounds per output word — the `4` of HalfSipHash-2-**4**. */
29
+ const D_ROUNDS = 4;
30
+
31
+ /** Private continuation: resume only with the same message, keys, byte length and output. */
32
+ export interface HashContinuation {
33
+ readonly block: number;
34
+ readonly v0: number;
35
+ readonly v1: number;
36
+ readonly v2: number;
37
+ readonly v3: number;
38
+ }
39
+
40
+ /**
41
+ * HalfSipHash-2-4 over a message supplied as 32-bit LITTLE-ENDIAN words, writing the two output
42
+ * words into `out`.
43
+ *
44
+ * Words rather than bytes because both callers already hold words, and the specification absorbs the
45
+ * message in 32-bit little-endian blocks regardless — so this is the same function with the byte
46
+ * reassembly left to whoever actually has bytes. Taking a `Uint8Array` would make the hot path pack
47
+ * bytes it had just unpacked.
48
+ *
49
+ * `byteLength` is the message length the specification hashes and stamps into the final block.
50
+ * `words` must therefore hold `ceil(byteLength / 4)` entries, with any trailing 1-3 bytes packed
51
+ * little-endian into the low bytes of the last one. Internal cooperative callers may pass a
52
+ * positive block limit and resume the returned continuation with exactly the same inputs.
53
+ */
54
+ export function halfSipHash(
55
+ key0: number,
56
+ key1: number,
57
+ words: Int32Array,
58
+ byteLength: number,
59
+ out: Int32Array,
60
+ continuation?: HashContinuation,
61
+ blockLimit = Infinity,
62
+ ): HashContinuation | undefined {
63
+ let v0 = key0 | 0;
64
+ let v1 = (key1 ^ 0xee) | 0;
65
+ let v2 = (key0 ^ 0x6c796765) | 0;
66
+ let v3 = (key1 ^ 0x74656462) | 0;
67
+ if (continuation) ({ v0, v1, v2, v3 } = continuation);
68
+
69
+ // The length-stamped final block is absorbed exactly like a message block, so it rides the same
70
+ // loop rather than a second copy of it. Seeds may end mid-word; mask blocks use whole words.
71
+ // The reference vectors exercise every tail length, including an empty message.
72
+ const fullWords = byteLength >>> 2;
73
+ const spare = byteLength & 3;
74
+ const tail = spare === 0 ? 0 : (words[fullWords] as number) & ((1 << (spare * 8)) - 1);
75
+ const lengthBlock = (byteLength << 24) | tail | 0;
76
+ const start = continuation?.block ?? 0;
77
+ const end = blockLimit === Infinity ? fullWords : Math.min(fullWords, start + blockLimit - 1);
78
+ for (let block = start; block <= end; block += 1) {
79
+ const m = block === fullWords ? lengthBlock : (words[block] as number);
80
+ v3 ^= m;
81
+ for (let round = 0; round < C_ROUNDS; round += 1) {
82
+ v0 = (v0 + v1) | 0;
83
+ v1 = (v1 << 5) | (v1 >>> 27);
84
+ v1 ^= v0;
85
+ v0 = (v0 << 16) | (v0 >>> 16);
86
+ v2 = (v2 + v3) | 0;
87
+ v3 = (v3 << 8) | (v3 >>> 24);
88
+ v3 ^= v2;
89
+ v0 = (v0 + v3) | 0;
90
+ v3 = (v3 << 7) | (v3 >>> 25);
91
+ v3 ^= v0;
92
+ v2 = (v2 + v1) | 0;
93
+ v1 = (v1 << 13) | (v1 >>> 19);
94
+ v1 ^= v2;
95
+ v2 = (v2 << 16) | (v2 >>> 16);
96
+ }
97
+ v0 ^= m;
98
+ }
99
+
100
+ // No output is published until absorption and finalisation are complete. The synchronous
101
+ // hot path has an unlimited block budget and never allocates a continuation.
102
+ if (end < fullWords) return { block: end + 1, v0, v1, v2, v3 };
103
+
104
+ // Two squeezes, and the `0xdd` between them is what makes the second output word something other
105
+ // than a rerun of the first.
106
+ v2 ^= 0xee;
107
+ for (let half = 0; half < 2; half += 1) {
108
+ for (let round = 0; round < D_ROUNDS; round += 1) {
109
+ v0 = (v0 + v1) | 0;
110
+ v1 = (v1 << 5) | (v1 >>> 27);
111
+ v1 ^= v0;
112
+ v0 = (v0 << 16) | (v0 >>> 16);
113
+ v2 = (v2 + v3) | 0;
114
+ v3 = (v3 << 8) | (v3 >>> 24);
115
+ v3 ^= v2;
116
+ v0 = (v0 + v3) | 0;
117
+ v3 = (v3 << 7) | (v3 >>> 25);
118
+ v3 ^= v0;
119
+ v2 = (v2 + v1) | 0;
120
+ v1 = (v1 << 13) | (v1 >>> 19);
121
+ v1 ^= v2;
122
+ v2 = (v2 << 16) | (v2 >>> 16);
123
+ }
124
+ out[half] = v1 ^ v3;
125
+ v1 ^= 0xdd;
126
+ }
127
+ return undefined;
128
+ }