@anizoptera/uuid-slug 0.3.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 (202) hide show
  1. package/LICENSE +54 -31
  2. package/README.md +1052 -261
  3. package/dist/alphabet.d.ts +5 -17
  4. package/dist/alphabet.d.ts.map +1 -1
  5. package/dist/alphabet.js +146 -112
  6. package/dist/alphabet.js.map +1 -1
  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 +50 -9
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/errors.js +145 -63
  14. package/dist/errors.js.map +1 -1
  15. package/dist/feistel.js +29 -95
  16. package/dist/feistel.js.map +1 -1
  17. package/dist/generation-options.js +20 -0
  18. package/dist/generation-options.js.map +1 -0
  19. package/dist/index.d.ts +22 -10
  20. package/dist/index.js +21 -9
  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 +151 -95
  30. package/dist/mask.js.map +1 -1
  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 +114 -51
  40. package/dist/migration.js.map +1 -1
  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 +21 -46
  48. package/dist/runtime/pool.js.map +1 -1
  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 +20 -99
  54. package/dist/siphash.js.map +1 -1
  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 +480 -200
  64. package/dist/types.d.ts.map +1 -1
  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 +51 -64
  74. package/dist/uuid.d.ts.map +1 -1
  75. package/dist/uuid.js +203 -199
  76. package/dist/uuid.js.map +1 -1
  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 +127 -171
  114. package/dist/v7.js.map +1 -1
  115. package/package.json +14 -9
  116. package/src/alphabet.ts +456 -27
  117. package/src/base64url-name.ts +5 -0
  118. package/src/errors.ts +373 -37
  119. package/src/feistel.ts +69 -56
  120. package/src/generation-options.ts +48 -0
  121. package/src/index.ts +134 -80
  122. package/src/instant.ts +196 -0
  123. package/src/keyless.ts +7 -134
  124. package/src/mask-handle.ts +141 -0
  125. package/src/mask.ts +354 -129
  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 +195 -42
  130. package/src/payload.ts +321 -0
  131. package/src/runtime/bun.ts +30 -49
  132. package/src/runtime/node.ts +43 -24
  133. package/src/runtime/pool.ts +49 -21
  134. package/src/runtime/portable.ts +68 -0
  135. package/src/runtime/types.ts +23 -35
  136. package/src/sentinel.ts +13 -0
  137. package/src/siphash.ts +5 -4
  138. package/src/slug.ts +884 -0
  139. package/src/timestamp.ts +122 -0
  140. package/src/types.ts +759 -205
  141. package/src/uuid-value-protocol.ts +77 -0
  142. package/src/uuid-value.ts +341 -0
  143. package/src/uuid.ts +514 -234
  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 +377 -200
  156. package/dist/base64url.d.ts +0 -20
  157. package/dist/base64url.d.ts.map +0 -1
  158. package/dist/base64url.js +0 -33
  159. package/dist/base64url.js.map +0 -1
  160. package/dist/codec.d.ts +0 -17
  161. package/dist/codec.d.ts.map +0 -1
  162. package/dist/codec.js +0 -192
  163. package/dist/codec.js.map +0 -1
  164. package/dist/keyless.d.ts +0 -31
  165. package/dist/keyless.d.ts.map +0 -1
  166. package/dist/keyless.js +0 -93
  167. package/dist/keyless.js.map +0 -1
  168. package/dist/legacy-mask.js +0 -55
  169. package/dist/legacy-mask.js.map +0 -1
  170. package/dist/node/alphabet.js +0 -130
  171. package/dist/node/base64url.js +0 -31
  172. package/dist/node/codec.js +0 -190
  173. package/dist/node/errors.js +0 -78
  174. package/dist/node/feistel.js +0 -103
  175. package/dist/node/index.js +0 -10
  176. package/dist/node/keyless.js +0 -91
  177. package/dist/node/legacy-mask.js +0 -53
  178. package/dist/node/mask.js +0 -106
  179. package/dist/node/migration.js +0 -64
  180. package/dist/node/runtime/node.js +0 -33
  181. package/dist/node/runtime/pool.js +0 -53
  182. package/dist/node/schema.js +0 -214
  183. package/dist/node/siphash.js +0 -106
  184. package/dist/node/uuid.js +0 -226
  185. package/dist/node/v7.js +0 -185
  186. package/dist/node/yield.js +0 -20
  187. package/dist/runtime/web.js +0 -39
  188. package/dist/runtime/web.js.map +0 -1
  189. package/dist/schema.d.ts +0 -20
  190. package/dist/schema.d.ts.map +0 -1
  191. package/dist/schema.js +0 -216
  192. package/dist/schema.js.map +0 -1
  193. package/dist/v7.d.ts +0 -12
  194. package/dist/v7.d.ts.map +0 -1
  195. package/dist/yield.js +0 -22
  196. package/dist/yield.js.map +0 -1
  197. package/src/base64url.ts +0 -41
  198. package/src/codec.ts +0 -320
  199. package/src/legacy-mask.ts +0 -25
  200. package/src/runtime/web.ts +0 -48
  201. package/src/schema.ts +0 -300
  202. package/src/yield.ts +0 -22
package/src/alphabet.ts CHANGED
@@ -1,12 +1,19 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
 
3
- import { checkRange, UuidSlugError } from "./errors";
4
- import type { UuidSlugErrorCode } from "./errors";
3
+ import { runtime } from "#runtime";
4
+ import { BASE64URL_NAME } from "./base64url-name.ts";
5
+ import { checkRange, INVALID_BASE32HEX, INVALID_BASE64URL, UuidSlugError } from "./errors.ts";
6
+ import type { UuidSlugErrorCode } from "./errors.ts";
7
+ import type { Latin1Scratch } from "./runtime/types.ts";
8
+
9
+ /** Select lowercase base32hex slug output. */
10
+ export const BASE32HEX_NAME = "base32hex";
11
+ export { BASE64URL_NAME } from "./base64url-name.ts";
5
12
 
6
13
  /**
7
14
  * A power-of-two alphabet plus its reverse lookup. Encoding is pure bit packing, so the only
8
- * thing that varies between base64url and base32 is the character set and how many bits each
9
- * character carries — one routine serves both rather than two hand-unrolled loops.
15
+ * character set and bits per character define the wire format. Fixed UUID writers specialize
16
+ * that format; the generic accumulator uses the same tables for other payload lengths.
10
17
  */
11
18
  export interface Alphabet {
12
19
  readonly bitsPerChar: number;
@@ -16,27 +23,39 @@ export interface Alphabet {
16
23
  readonly decode: Int16Array;
17
24
  readonly name: string;
18
25
  readonly invalidChars: RegExp;
26
+ readonly invalidInputChars: RegExp;
19
27
  }
20
28
 
21
- function alphabet(name: string, chars: string, code: UuidSlugErrorCode): Alphabet {
29
+ /*#__NO_SIDE_EFFECTS__*/
30
+ function alphabet(
31
+ name: string,
32
+ chars: string,
33
+ code: UuidSlugErrorCode,
34
+ acceptUppercase = false,
35
+ ): Alphabet {
22
36
  const bitsPerChar = Math.log2(chars.length);
23
- if (!Number.isInteger(bitsPerChar)) throw new Error(`${name} alphabet must be a power of two.`);
24
37
  const decode = new Int16Array(128).fill(-1);
25
- for (let i = 0; i < chars.length; i += 1) decode[chars.charCodeAt(i)] = i;
38
+ for (let i = 0; i < chars.length; i += 1) {
39
+ const charCode = chars.charCodeAt(i);
40
+ decode[charCode] = i;
41
+ if (acceptUppercase && charCode >= 97 && charCode <= 122) decode[charCode - 32] = i;
42
+ }
43
+ const invalidCharacterPattern = `[^${chars.replaceAll("-", "\\-")}]`;
26
44
  return {
27
45
  bitsPerChar,
28
46
  chars,
29
47
  code,
30
48
  decode,
31
49
  name,
32
- invalidChars: new RegExp(`[^${chars.replaceAll("-", "\\-")}]`),
50
+ invalidChars: new RegExp(invalidCharacterPattern),
51
+ invalidInputChars: new RegExp(invalidCharacterPattern, acceptUppercase ? "i" : ""),
33
52
  };
34
53
  }
35
54
 
36
- export const BASE64URL: Alphabet = alphabet(
37
- "base64url",
55
+ export const BASE64URL: Alphabet = /*#__PURE__*/ alphabet(
56
+ BASE64URL_NAME,
38
57
  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_",
39
- "invalid_base64url",
58
+ INVALID_BASE64URL,
40
59
  );
41
60
 
42
61
  /**
@@ -44,25 +63,39 @@ export const BASE64URL: Alphabet = alphabet(
44
63
  * its characters are in ASCII order, so encoded values sort the same way the underlying bytes do —
45
64
  * the one property base64url cannot offer, and the reason a second alphabet exists at all.
46
65
  *
47
- * Spelled LOWERCASE where the RFC writes `0-9A-V`, matching how this package renders UUIDs, and
48
- * decoding accepts only that spelling so an id has exactly one form. The cost is interop: verified
49
- * 2026-08-12 against CPython, `base64.b32hexdecode` rejects these slugs unless called with
50
- * `casefold=True`. Upper-case them at the boundary if a strict RFC decoder has to read them.
66
+ * Writers use lowercase to match UUID text. Decoders also accept the RFC uppercase spelling, while
67
+ * canonical guards accept only lowercase so callers can enforce one stored form.
51
68
  */
52
- export const BASE32HEX: Alphabet = alphabet(
53
- "base32hex",
69
+ export const BASE32HEX: Alphabet = /*#__PURE__*/ alphabet(
70
+ BASE32HEX_NAME,
54
71
  "0123456789abcdefghijklmnopqrstuv",
55
- "invalid_base32",
72
+ INVALID_BASE32HEX,
73
+ true,
56
74
  );
57
75
 
58
76
  // Native encoding is strict on output; decoding stays here because it must reject aliases,
59
77
  // whitespace and nonzero padding that platform decoders may accept.
60
- const nativeToBase64 = (
78
+ const denoVersion = (globalThis as { Deno?: { version?: { deno?: string } } }).Deno?.version?.deno;
79
+ const availableNativeToBase64 = (
61
80
  Uint8Array.prototype as {
62
- toBase64?: (options: { alphabet: "base64url"; omitPadding: boolean }) => string;
81
+ toBase64?: (options: { alphabet: typeof BASE64URL_NAME; omitPadding: boolean }) => string;
63
82
  }
64
83
  ).toBase64;
65
- const BASE64_OPTIONS = { alphabet: "base64url", omitPadding: true } as const;
84
+ // Deno 2.9.6 implements this capability but takes longer than the fixed 16-byte encoder. Treat
85
+ // that implementation as unavailable until a Deno update overturns the repeated public-route result.
86
+ const nativeToBase64 = denoVersion === undefined ? availableNativeToBase64 : undefined;
87
+ const BASE64_OPTIONS = { alphabet: BASE64URL_NAME, omitPadding: true } as const;
88
+ const createLatin1Scratch = runtime.latin1Scratch;
89
+ let base64urlScratch: Latin1Scratch | undefined;
90
+ let base32hexScratch: Latin1Scratch | undefined;
91
+ let maskedBase32hexScratch: Latin1Scratch | undefined;
92
+ let base64urlCodes: Uint8Array | undefined;
93
+ let base32hexCodes: Uint8Array | undefined;
94
+
95
+ /*#__NO_SIDE_EFFECTS__*/
96
+ function characterCodes(alpha: Alphabet): Uint8Array {
97
+ return Uint8Array.from(alpha.chars, (character) => character.charCodeAt(0));
98
+ }
66
99
 
67
100
  /**
68
101
  * Bits left over when `byteLength` bytes are written in this alphabet. A slug rounds up to whole
@@ -70,25 +103,52 @@ const BASE64_OPTIONS = { alphabet: "base64url", omitPadding: true } as const;
70
103
  * base64url (22 chars = 132 bits), 2 in base32hex (26 chars = 130 bits). Callers may spend them
71
104
  * on a trailing value at zero cost in length — see `encode`.
72
105
  */
106
+ /*#__NO_SIDE_EFFECTS__*/
73
107
  export function spareBits(alpha: Alphabet, byteLength: number): number {
74
108
  const bits = byteLength * 8;
75
109
  return (alpha.bitsPerChar - (bits % alpha.bitsPerChar)) % alpha.bitsPerChar;
76
110
  }
77
111
 
78
112
  /** Boolean validation needs no output buffer or diagnostic allocation. */
79
- export function isEncoded(value: string, alpha: Alphabet, byteLength: number): boolean {
113
+ /*#__NO_SIDE_EFFECTS__*/
114
+ export function isEncoded(
115
+ value: string,
116
+ alpha: Alphabet,
117
+ byteLength: number,
118
+ acceptsMixedCase = false,
119
+ tailBits = 0,
120
+ ): boolean {
80
121
  if (
81
- value.length !== Math.ceil((byteLength * 8) / alpha.bitsPerChar) ||
82
- alpha.invalidChars.test(value)
122
+ value.length !== Math.ceil((byteLength * 8 + tailBits) / alpha.bitsPerChar) ||
123
+ (acceptsMixedCase ? alpha.invalidInputChars : alpha.invalidChars).test(value)
83
124
  )
84
125
  return false;
85
- const spare = spareBits(alpha, byteLength);
126
+ const spare =
127
+ (alpha.bitsPerChar - ((byteLength * 8 + tailBits) % alpha.bitsPerChar)) % alpha.bitsPerChar;
86
128
  return (
87
129
  spare === 0 ||
88
130
  ((alpha.decode[value.charCodeAt(value.length - 1)] as number) & ((1 << spare) - 1)) === 0
89
131
  );
90
132
  }
91
133
 
134
+ function invalidCharacter(alpha: Alphabet, value: string, offset: number): UuidSlugError {
135
+ return new UuidSlugError(
136
+ alpha.code,
137
+ `Invalid ${alpha.name} character ${JSON.stringify(value[offset])} at offset ${offset}.`,
138
+ );
139
+ }
140
+
141
+ /** Report the first character of a fixed-length value that a single-check decode rejected. */
142
+ function firstInvalidCharacter(alpha: Alphabet, value: string): UuidSlugError {
143
+ let offset = 0;
144
+ while (offset < value.length - 1) {
145
+ const charCode = value.charCodeAt(offset);
146
+ if (charCode > 127 || (alpha.decode[charCode] as number) < 0) break;
147
+ offset += 1;
148
+ }
149
+ return invalidCharacter(alpha, value, offset);
150
+ }
151
+
92
152
  /**
93
153
  * Pack bytes, optionally followed by `tailBits` low bits of `tail`, into `alpha`.
94
154
  *
@@ -96,7 +156,20 @@ export function isEncoded(value: string, alpha: Alphabet, byteLength: number): b
96
156
  * `tail = 0` reproduces a plain encoding byte for byte, which is what keeps identifiers issued
97
157
  * before the tail existed valid afterwards.
98
158
  */
159
+ /*#__NO_SIDE_EFFECTS__*/
99
160
  export function encode(bytes: Uint8Array, alpha: Alphabet, tail = 0, tailBits = 0): string {
161
+ if (createLatin1Scratch && bytes.length === 16) {
162
+ if (alpha === BASE64URL && (tailBits === 0 || tailBits === 4))
163
+ return encodeBase64urlLatin1(createLatin1Scratch, bytes, tail);
164
+ if (alpha === BASE32HEX && (tailBits === 0 || tailBits === 2 || tailBits === 4))
165
+ return encodeBase32hexLatin1(createLatin1Scratch, bytes, tail, tailBits);
166
+ }
167
+ if (bytes.length === 16) {
168
+ if (alpha === BASE64URL && (tailBits === 0 || tailBits === 4))
169
+ return writeBase64url(bytes, (base64urlCodes ??= characterCodes(BASE64URL)), tail);
170
+ if (alpha === BASE32HEX && (tailBits === 0 || tailBits === 2 || tailBits === 4))
171
+ return writeBase32hex(bytes, (base32hexCodes ??= characterCodes(BASE32HEX)), tail, tailBits);
172
+ }
100
173
  if (
101
174
  nativeToBase64 &&
102
175
  alpha === BASE64URL &&
@@ -112,6 +185,135 @@ export function encode(bytes: Uint8Array, alpha: Alphabet, tail = 0, tailBits =
112
185
  const trailing = (tail & ((1 << tailBits) - 1)) << (spareBits(alpha, bytes.length) - tailBits);
113
186
  return encoded.slice(0, last) + alpha.chars[digit | trailing];
114
187
  }
188
+ return encodePortable(bytes, alpha, tail, tailBits);
189
+ }
190
+
191
+ /**
192
+ * Write a UUID payload's character codes into reused scratch and read them back with one native
193
+ * Latin-1 conversion. The result is flat text, where native base64url output needs a slice and a
194
+ * concatenation for the check tail and portable output concatenates characters. The scratch is safe
195
+ * to share because nothing between these writes and the read can re-enter encoding.
196
+ */
197
+ function encodeBase64urlLatin1(
198
+ create: NonNullable<typeof createLatin1Scratch>,
199
+ bytes: Uint8Array,
200
+ tail: number,
201
+ ): string {
202
+ const scratch = (base64urlScratch ??= create(22));
203
+ const codes = (base64urlCodes ??= characterCodes(BASE64URL));
204
+ const text = scratch.bytes;
205
+ for (let offset = 0, written = 0; offset < 15; offset += 3, written += 4) {
206
+ const block =
207
+ ((bytes[offset] as number) << 16) |
208
+ ((bytes[offset + 1] as number) << 8) |
209
+ (bytes[offset + 2] as number);
210
+ text[written] = codes[block >>> 18] as number;
211
+ text[written + 1] = codes[(block >>> 12) & 63] as number;
212
+ text[written + 2] = codes[(block >>> 6) & 63] as number;
213
+ text[written + 3] = codes[block & 63] as number;
214
+ }
215
+ const last = bytes[15] as number;
216
+ text[20] = codes[last >>> 2] as number;
217
+ text[21] = codes[((last & 3) << 4) | (tail & 15)] as number;
218
+ return scratch.text();
219
+ }
220
+
221
+ /**
222
+ * The base32hex counterpart of `encodeBase64urlLatin1`. A 4-bit tail needs a 27th character, which
223
+ * holds the tail's low two bits followed by three zero bits.
224
+ */
225
+ function encodeBase32hexLatin1(
226
+ create: NonNullable<typeof createLatin1Scratch>,
227
+ bytes: Uint8Array,
228
+ tail: number,
229
+ tailBits: number,
230
+ ): string {
231
+ const scratch =
232
+ tailBits === 4 ? (maskedBase32hexScratch ??= create(27)) : (base32hexScratch ??= create(26));
233
+ const codes = (base32hexCodes ??= characterCodes(BASE32HEX));
234
+ const text = scratch.bytes;
235
+ for (let offset = 0, written = 0; offset < 15; offset += 5, written += 8) {
236
+ const a = bytes[offset] as number;
237
+ const b = bytes[offset + 1] as number;
238
+ const c = bytes[offset + 2] as number;
239
+ const d = bytes[offset + 3] as number;
240
+ const e = bytes[offset + 4] as number;
241
+ text[written] = codes[a >>> 3] as number;
242
+ text[written + 1] = codes[((a & 7) << 2) | (b >>> 6)] as number;
243
+ text[written + 2] = codes[(b >>> 1) & 31] as number;
244
+ text[written + 3] = codes[((b & 1) << 4) | (c >>> 4)] as number;
245
+ text[written + 4] = codes[((c & 15) << 1) | (d >>> 7)] as number;
246
+ text[written + 5] = codes[(d >>> 2) & 31] as number;
247
+ text[written + 6] = codes[((d & 3) << 3) | (e >>> 5)] as number;
248
+ text[written + 7] = codes[e & 31] as number;
249
+ }
250
+ const last = bytes[15] as number;
251
+ text[24] = codes[last >>> 3] as number;
252
+ if (tailBits === 4) {
253
+ text[25] = codes[((last & 7) << 2) | ((tail >>> 2) & 3)] as number;
254
+ text[26] = codes[(tail & 3) << 3] as number;
255
+ } else text[25] = codes[((last & 7) << 2) | (tail & 3)] as number;
256
+ return scratch.text();
257
+ }
258
+
259
+ /** Encode without runtime-native delegation so fallback performance can be measured directly. */
260
+ /*#__NO_SIDE_EFFECTS__*/
261
+ export function encodePortable(bytes: Uint8Array, alpha: Alphabet, tail = 0, tailBits = 0): string {
262
+ // UUID routes always encode one 16-byte block. Fixed groups remove the generic accumulator;
263
+ // keep the generic path for every other supported shape and tail width.
264
+ if (alpha === BASE64URL && bytes.length === 16 && (tailBits === 0 || tailBits === 4)) {
265
+ let encoded = "";
266
+ for (let offset = 0; offset < 15; offset += 3) {
267
+ const block =
268
+ ((bytes[offset] as number) << 16) |
269
+ ((bytes[offset + 1] as number) << 8) |
270
+ (bytes[offset + 2] as number);
271
+ encoded +=
272
+ (alpha.chars[block >>> 18] as string) +
273
+ (alpha.chars[(block >>> 12) & 63] as string) +
274
+ (alpha.chars[(block >>> 6) & 63] as string) +
275
+ (alpha.chars[block & 63] as string);
276
+ }
277
+ const last = bytes[15] as number;
278
+ return (
279
+ encoded +
280
+ (alpha.chars[last >>> 2] as string) +
281
+ (alpha.chars[((last & 3) << 4) | (tail & 15)] as string)
282
+ );
283
+ }
284
+ if (
285
+ alpha === BASE32HEX &&
286
+ bytes.length === 16 &&
287
+ (tailBits === 0 || tailBits === 2 || tailBits === 4)
288
+ ) {
289
+ let encoded = "";
290
+ const chars = alpha.chars;
291
+ for (let offset = 0; offset < 15; offset += 5) {
292
+ const a = bytes[offset] as number;
293
+ const b = bytes[offset + 1] as number;
294
+ const c = bytes[offset + 2] as number;
295
+ const d = bytes[offset + 3] as number;
296
+ const e = bytes[offset + 4] as number;
297
+ encoded +=
298
+ (chars[a >>> 3] as string) +
299
+ (chars[((a & 7) << 2) | (b >>> 6)] as string) +
300
+ (chars[(b >>> 1) & 31] as string) +
301
+ (chars[((b & 1) << 4) | (c >>> 4)] as string) +
302
+ (chars[((c & 15) << 1) | (d >>> 7)] as string) +
303
+ (chars[(d >>> 2) & 31] as string) +
304
+ (chars[((d & 3) << 3) | (e >>> 5)] as string) +
305
+ (chars[e & 31] as string);
306
+ }
307
+ const last = bytes[15] as number;
308
+ if (tailBits === 4)
309
+ return (
310
+ encoded +
311
+ chars[last >>> 3] +
312
+ chars[((last & 7) << 2) | ((tail >>> 2) & 3)] +
313
+ chars[(tail & 3) << 3]
314
+ );
315
+ return encoded + chars[last >>> 3] + chars[((last & 7) << 2) | (tail & 3)];
316
+ }
115
317
  const { bitsPerChar, chars } = alpha;
116
318
  const mask = (1 << bitsPerChar) - 1;
117
319
  let out = "";
@@ -153,7 +355,7 @@ export function decodeInto(
153
355
  offset: number,
154
356
  byteLength: number,
155
357
  tailBits = 0,
156
- ): UuidSlugError | number {
358
+ ): number | UuidSlugError {
157
359
  const { bitsPerChar, decode: table, code, name } = alpha;
158
360
  const expected = Math.ceil((byteLength * 8 + tailBits) / bitsPerChar);
159
361
  if (value.length !== expected)
@@ -161,13 +363,115 @@ export function decodeInto(
161
363
  const badRange = checkRange(out.length, offset, byteLength);
162
364
  if (badRange) return badRange;
163
365
 
366
+ // UUID base64url has five complete groups and one byte. Decode that fixed wire shape directly;
367
+ // keep the accumulator below for every other byte length, alphabet, and tail width.
368
+ // Fixed paths check every character once after the loop: ORing the codes exposes any code
369
+ // above 127, whose low bits the table read would alias, and ORing the digits turns any -1
370
+ // negative. A branch per character was slower on Node and Bun (bench/PERFORMANCE.md).
371
+ if (alpha === BASE64URL && byteLength === 16 && (tailBits === 0 || tailBits === 4)) {
372
+ let codes = 0;
373
+ let digits = 0;
374
+ let written = offset;
375
+ for (let start = 0; start < 20; start += 4) {
376
+ const a = value.charCodeAt(start);
377
+ const b = value.charCodeAt(start + 1);
378
+ const c = value.charCodeAt(start + 2);
379
+ const d = value.charCodeAt(start + 3);
380
+ const block =
381
+ ((table[a & 127] as number) << 18) |
382
+ ((table[b & 127] as number) << 12) |
383
+ ((table[c & 127] as number) << 6) |
384
+ (table[d & 127] as number);
385
+ codes |= a | b | c | d;
386
+ digits |= block;
387
+ out[written] = block >>> 16;
388
+ out[written + 1] = block >>> 8;
389
+ out[written + 2] = block;
390
+ written += 3;
391
+ }
392
+ const firstCode = value.charCodeAt(20);
393
+ const lastCode = value.charCodeAt(21);
394
+ const first = table[firstCode & 127] as number;
395
+ const last = table[lastCode & 127] as number;
396
+ if ((codes | firstCode | lastCode) > 127 || (digits | first | last) < 0)
397
+ return firstInvalidCharacter(alpha, value);
398
+ out[written] = (first << 2) | (last >>> 4);
399
+ if (tailBits === 4) return last & 15;
400
+ // A masked base64url slug has the same length and carries check bits here, so this is the
401
+ // error a caller sees after feeding a masked slug to the plain decoder. Say so.
402
+ if ((last & 15) !== 0)
403
+ return new UuidSlugError(
404
+ code,
405
+ `${name} value has non-canonical trailing bits; a masked slug of this length decodes only through its codec.`,
406
+ );
407
+ return 0;
408
+ }
409
+
410
+ // UUID base32hex has three complete eight-character groups and one byte; a 4-bit masked tail adds
411
+ // a 27th character. Fixed byte formulas remove the general accumulator and its length guards.
412
+ if (
413
+ alpha === BASE32HEX &&
414
+ byteLength === 16 &&
415
+ (tailBits === 0 || tailBits === 2 || tailBits === 4)
416
+ ) {
417
+ let codes = 0;
418
+ let digits = 0;
419
+ let written = offset;
420
+ for (let start = 0; start < 24; start += 8) {
421
+ // Eight 5-bit digits exceed int32, so each byte is assembled from the digits it spans.
422
+ const d0 = value.charCodeAt(start);
423
+ const d1 = value.charCodeAt(start + 1);
424
+ const d2 = value.charCodeAt(start + 2);
425
+ const d3 = value.charCodeAt(start + 3);
426
+ const d4 = value.charCodeAt(start + 4);
427
+ const d5 = value.charCodeAt(start + 5);
428
+ const d6 = value.charCodeAt(start + 6);
429
+ const d7 = value.charCodeAt(start + 7);
430
+ codes |= d0 | d1 | d2 | d3 | d4 | d5 | d6 | d7;
431
+ const v0 = table[d0 & 127] as number;
432
+ const v1 = table[d1 & 127] as number;
433
+ const v2 = table[d2 & 127] as number;
434
+ const v3 = table[d3 & 127] as number;
435
+ const v4 = table[d4 & 127] as number;
436
+ const v5 = table[d5 & 127] as number;
437
+ const v6 = table[d6 & 127] as number;
438
+ const v7 = table[d7 & 127] as number;
439
+ digits |= v0 | v1 | v2 | v3 | v4 | v5 | v6 | v7;
440
+ out[written] = (v0 << 3) | (v1 >>> 2);
441
+ out[written + 1] = (v1 << 6) | (v2 << 1) | (v3 >>> 4);
442
+ out[written + 2] = (v3 << 4) | (v4 >>> 1);
443
+ out[written + 3] = (v4 << 7) | (v5 << 2) | (v6 >>> 3);
444
+ out[written + 4] = (v6 << 5) | v7;
445
+ written += 5;
446
+ }
447
+ const firstCode = value.charCodeAt(24);
448
+ const lastCode = value.charCodeAt(25);
449
+ // Only a 27-character value has this code; reading past a 26-character value would return NaN.
450
+ const paddingCode = tailBits === 4 ? value.charCodeAt(26) : 48;
451
+ const first = table[firstCode & 127] as number;
452
+ const last = table[lastCode & 127] as number;
453
+ const padding = table[paddingCode & 127] as number;
454
+ if ((codes | firstCode | lastCode | paddingCode) > 127 || (digits | first | last | padding) < 0)
455
+ return firstInvalidCharacter(alpha, value);
456
+ out[written] = (first << 3) | (last >>> 2);
457
+ if (tailBits === 4) {
458
+ if ((padding & 7) !== 0)
459
+ return new UuidSlugError(code, `${name} value has non-canonical trailing bits.`);
460
+ return ((last & 3) << 2) | (padding >>> 3);
461
+ }
462
+ if (tailBits === 2) return last & 3;
463
+ if ((last & 3) !== 0)
464
+ return new UuidSlugError(code, `${name} value has non-canonical trailing bits.`);
465
+ return 0;
466
+ }
467
+
164
468
  let acc = 0;
165
469
  let bits = 0;
166
470
  let written = 0;
167
471
  for (let i = 0; i < value.length; i += 1) {
168
472
  const charCode = value.charCodeAt(i);
169
473
  const digit = charCode < 128 ? (table[charCode] as number) : -1;
170
- if (digit < 0) return new UuidSlugError(code, `Invalid ${name} character at offset ${i}.`);
474
+ if (digit < 0) return invalidCharacter(alpha, value, i);
171
475
  acc = (acc << bitsPerChar) | digit;
172
476
  bits += bitsPerChar;
173
477
  while (bits >= 8 && written < byteLength) {
@@ -185,3 +489,128 @@ export function decodeInto(
185
489
  return new UuidSlugError(code, `${name} value has non-canonical trailing bits.`);
186
490
  return tail;
187
491
  }
492
+
493
+ // Fixed 16-byte groups avoid per-character concatenation and temporary text buffers on V8.
494
+ // Bun keeps its Latin-1 writer; remeasure after engine changes (bench/PERFORMANCE.md).
495
+ // Character tables belong to the alphabet owner; callers select only supported tail widths.
496
+ /*#__NO_SIDE_EFFECTS__*/
497
+ function writeBase64url(bytes: Uint8Array, codes: Uint8Array, tail: number): string {
498
+ const a = ((bytes[0] as number) << 16) | ((bytes[1] as number) << 8) | (bytes[2] as number);
499
+ const b = ((bytes[3] as number) << 16) | ((bytes[4] as number) << 8) | (bytes[5] as number);
500
+ const c = ((bytes[6] as number) << 16) | ((bytes[7] as number) << 8) | (bytes[8] as number);
501
+ const d = ((bytes[9] as number) << 16) | ((bytes[10] as number) << 8) | (bytes[11] as number);
502
+ const e = ((bytes[12] as number) << 16) | ((bytes[13] as number) << 8) | (bytes[14] as number);
503
+ const f = bytes[15] as number;
504
+ return String.fromCharCode(
505
+ codes[a >>> 18] as number,
506
+ codes[(a >>> 12) & 63] as number,
507
+ codes[(a >>> 6) & 63] as number,
508
+ codes[a & 63] as number,
509
+ codes[b >>> 18] as number,
510
+ codes[(b >>> 12) & 63] as number,
511
+ codes[(b >>> 6) & 63] as number,
512
+ codes[b & 63] as number,
513
+ codes[c >>> 18] as number,
514
+ codes[(c >>> 12) & 63] as number,
515
+ codes[(c >>> 6) & 63] as number,
516
+ codes[c & 63] as number,
517
+ codes[d >>> 18] as number,
518
+ codes[(d >>> 12) & 63] as number,
519
+ codes[(d >>> 6) & 63] as number,
520
+ codes[d & 63] as number,
521
+ codes[e >>> 18] as number,
522
+ codes[(e >>> 12) & 63] as number,
523
+ codes[(e >>> 6) & 63] as number,
524
+ codes[e & 63] as number,
525
+ codes[f >>> 2] as number,
526
+ codes[((f & 3) << 4) | (tail & 15)] as number,
527
+ );
528
+ }
529
+
530
+ /*#__NO_SIDE_EFFECTS__*/
531
+ function writeBase32hex(
532
+ bytes: Uint8Array,
533
+ codes: Uint8Array,
534
+ tail: number,
535
+ tailBits: number,
536
+ ): string {
537
+ const a = bytes[0] as number,
538
+ b = bytes[1] as number,
539
+ c = bytes[2] as number;
540
+ const d = bytes[3] as number,
541
+ e = bytes[4] as number,
542
+ f = bytes[5] as number;
543
+ const g = bytes[6] as number,
544
+ h = bytes[7] as number,
545
+ i = bytes[8] as number;
546
+ const j = bytes[9] as number,
547
+ k = bytes[10] as number,
548
+ l = bytes[11] as number;
549
+ const m = bytes[12] as number,
550
+ n = bytes[13] as number,
551
+ o = bytes[14] as number;
552
+ const p = bytes[15] as number;
553
+ // A four-bit check extends the payload to 27 digits. Keep three padding bits zero;
554
+ // a plain payload has only two spare bits and must remain 26 digits.
555
+ const last = codes[((p & 7) << 2) | (tailBits === 4 ? (tail >>> 2) & 3 : tail & 3)] as number;
556
+ // Keep masked output flat too: a concatenated check character changes the string shape seen
557
+ // by decoders. The two fixed arities avoid an argument array or a substring on plain output.
558
+ if (tailBits === 4)
559
+ return String.fromCharCode(
560
+ codes[a >>> 3] as number,
561
+ codes[((a & 7) << 2) | (b >>> 6)] as number,
562
+ codes[(b >>> 1) & 31] as number,
563
+ codes[((b & 1) << 4) | (c >>> 4)] as number,
564
+ codes[((c & 15) << 1) | (d >>> 7)] as number,
565
+ codes[(d >>> 2) & 31] as number,
566
+ codes[((d & 3) << 3) | (e >>> 5)] as number,
567
+ codes[e & 31] as number,
568
+ codes[f >>> 3] as number,
569
+ codes[((f & 7) << 2) | (g >>> 6)] as number,
570
+ codes[(g >>> 1) & 31] as number,
571
+ codes[((g & 1) << 4) | (h >>> 4)] as number,
572
+ codes[((h & 15) << 1) | (i >>> 7)] as number,
573
+ codes[(i >>> 2) & 31] as number,
574
+ codes[((i & 3) << 3) | (j >>> 5)] as number,
575
+ codes[j & 31] as number,
576
+ codes[k >>> 3] as number,
577
+ codes[((k & 7) << 2) | (l >>> 6)] as number,
578
+ codes[(l >>> 1) & 31] as number,
579
+ codes[((l & 1) << 4) | (m >>> 4)] as number,
580
+ codes[((m & 15) << 1) | (n >>> 7)] as number,
581
+ codes[(n >>> 2) & 31] as number,
582
+ codes[((n & 3) << 3) | (o >>> 5)] as number,
583
+ codes[o & 31] as number,
584
+ codes[p >>> 3] as number,
585
+ last,
586
+ codes[(tail & 3) << 3] as number,
587
+ );
588
+ return String.fromCharCode(
589
+ codes[a >>> 3] as number,
590
+ codes[((a & 7) << 2) | (b >>> 6)] as number,
591
+ codes[(b >>> 1) & 31] as number,
592
+ codes[((b & 1) << 4) | (c >>> 4)] as number,
593
+ codes[((c & 15) << 1) | (d >>> 7)] as number,
594
+ codes[(d >>> 2) & 31] as number,
595
+ codes[((d & 3) << 3) | (e >>> 5)] as number,
596
+ codes[e & 31] as number,
597
+ codes[f >>> 3] as number,
598
+ codes[((f & 7) << 2) | (g >>> 6)] as number,
599
+ codes[(g >>> 1) & 31] as number,
600
+ codes[((g & 1) << 4) | (h >>> 4)] as number,
601
+ codes[((h & 15) << 1) | (i >>> 7)] as number,
602
+ codes[(i >>> 2) & 31] as number,
603
+ codes[((i & 3) << 3) | (j >>> 5)] as number,
604
+ codes[j & 31] as number,
605
+ codes[k >>> 3] as number,
606
+ codes[((k & 7) << 2) | (l >>> 6)] as number,
607
+ codes[(l >>> 1) & 31] as number,
608
+ codes[((l & 1) << 4) | (m >>> 4)] as number,
609
+ codes[((m & 15) << 1) | (n >>> 7)] as number,
610
+ codes[(n >>> 2) & 31] as number,
611
+ codes[((n & 3) << 3) | (o >>> 5)] as number,
612
+ codes[o & 31] as number,
613
+ codes[p >>> 3] as number,
614
+ last,
615
+ );
616
+ }
@@ -0,0 +1,5 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ // Native generation needs the selector without importing alphabet.ts, which depends on #runtime.
4
+ /** Select unpadded base64url slug output. */
5
+ export const BASE64URL_NAME = "base64url";