@anizoptera/uuid-slug 0.4.0 → 0.6.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 (132) hide show
  1. package/README.md +232 -1062
  2. package/dist/alphabet.d.ts +1 -3
  3. package/dist/alphabet.d.ts.map +1 -1
  4. package/dist/alphabet.js +32 -90
  5. package/dist/alphabet.js.map +1 -1
  6. package/dist/base64url-name.d.ts +1 -3
  7. package/dist/base64url-name.d.ts.map +1 -1
  8. package/dist/base64url-name.js +2 -3
  9. package/dist/errors.d.ts +1 -3
  10. package/dist/errors.d.ts.map +1 -1
  11. package/dist/errors.js +7 -24
  12. package/dist/errors.js.map +1 -1
  13. package/dist/feistel.js +1 -2
  14. package/dist/generation-options.js +2 -3
  15. package/dist/index.d.ts +10 -10
  16. package/dist/index.js +21 -21
  17. package/dist/instant.js +2 -3
  18. package/dist/mask-handle.d.ts +1 -3
  19. package/dist/mask-handle.d.ts.map +1 -1
  20. package/dist/mask-handle.js +19 -17
  21. package/dist/mask-handle.js.map +1 -1
  22. package/dist/mask.d.ts +1 -3
  23. package/dist/mask.d.ts.map +1 -1
  24. package/dist/mask.js +23 -24
  25. package/dist/mask.js.map +1 -1
  26. package/dist/masked-bytes.js +74 -0
  27. package/dist/masked-bytes.js.map +1 -0
  28. package/dist/masking-codec-protocol.js +2 -3
  29. package/dist/masking-codec-types.d.ts +60 -19
  30. package/dist/masking-codec-types.d.ts.map +1 -1
  31. package/dist/masking-codec.d.ts +1 -3
  32. package/dist/masking-codec.d.ts.map +1 -1
  33. package/dist/masking-codec.js +115 -111
  34. package/dist/masking-codec.js.map +1 -1
  35. package/dist/migration.js +39 -40
  36. package/dist/migration.js.map +1 -1
  37. package/dist/node/runtime.js +2 -3
  38. package/dist/payload.d.ts +1 -3
  39. package/dist/payload.d.ts.map +1 -1
  40. package/dist/payload.js +65 -64
  41. package/dist/payload.js.map +1 -1
  42. package/dist/runtime/pool.js +2 -3
  43. package/dist/runtime/portable.js +2 -3
  44. package/dist/runtime/portable.js.map +1 -1
  45. package/dist/sentinel.js +2 -3
  46. package/dist/siphash.js +1 -2
  47. package/dist/slug.d.ts +14 -13
  48. package/dist/slug.d.ts.map +1 -1
  49. package/dist/slug.js +144 -152
  50. package/dist/slug.js.map +1 -1
  51. package/dist/timestamp.d.ts +1 -3
  52. package/dist/timestamp.d.ts.map +1 -1
  53. package/dist/timestamp.js +2 -3
  54. package/dist/types.d.ts +38 -16
  55. package/dist/types.d.ts.map +1 -1
  56. package/dist/types.js +2 -3
  57. package/dist/types.js.map +1 -1
  58. package/dist/uuid-value-protocol.js +2 -3
  59. package/dist/uuid-value.d.ts +3 -5
  60. package/dist/uuid-value.d.ts.map +1 -1
  61. package/dist/uuid-value.js +74 -78
  62. package/dist/uuid-value.js.map +1 -1
  63. package/dist/uuid.d.ts +6 -8
  64. package/dist/uuid.d.ts.map +1 -1
  65. package/dist/uuid.js +34 -45
  66. package/dist/uuid.js.map +1 -1
  67. package/dist/v4-slug.d.ts +2 -4
  68. package/dist/v4-slug.d.ts.map +1 -1
  69. package/dist/v4-slug.js +6 -7
  70. package/dist/v4.d.ts +8 -6
  71. package/dist/v4.d.ts.map +1 -1
  72. package/dist/v4.js +3 -9
  73. package/dist/v4.js.map +1 -1
  74. package/dist/v7-bounds.d.ts +3 -5
  75. package/dist/v7-bounds.d.ts.map +1 -1
  76. package/dist/v7-bounds.js +8 -9
  77. package/dist/v7-bounds.js.map +1 -1
  78. package/dist/v7-generator-input.js +10 -11
  79. package/dist/v7-generator-input.js.map +1 -1
  80. package/dist/v7-generator.d.ts +1 -3
  81. package/dist/v7-generator.d.ts.map +1 -1
  82. package/dist/v7-generator.js +13 -14
  83. package/dist/v7-keyless.d.ts +12 -4
  84. package/dist/v7-keyless.d.ts.map +1 -1
  85. package/dist/v7-keyless.js +2 -3
  86. package/dist/v7-keyless.js.map +1 -1
  87. package/dist/v7-payload.js +2 -3
  88. package/dist/v7-slug.d.ts +8 -5
  89. package/dist/v7-slug.d.ts.map +1 -1
  90. package/dist/v7-slug.js +28 -29
  91. package/dist/v7-slug.js.map +1 -1
  92. package/dist/v7-timestamp.js +2 -3
  93. package/dist/v7-value-options.js +2 -3
  94. package/dist/v7-value.d.ts +5 -8
  95. package/dist/v7-value.d.ts.map +1 -1
  96. package/dist/v7-value.js +10 -11
  97. package/dist/v7-value.js.map +1 -1
  98. package/dist/v7.js +16 -17
  99. package/dist/v7.js.map +1 -1
  100. package/package.json +6 -4
  101. package/src/alphabet.ts +84 -239
  102. package/src/errors.ts +30 -43
  103. package/src/feistel.ts +4 -4
  104. package/src/generation-options.ts +1 -1
  105. package/src/index.ts +3 -0
  106. package/src/mask-handle.ts +7 -11
  107. package/src/mask.ts +16 -14
  108. package/src/masked-bytes.ts +203 -0
  109. package/src/masking-codec-protocol.ts +1 -1
  110. package/src/masking-codec-types.ts +124 -24
  111. package/src/masking-codec.ts +44 -43
  112. package/src/migration.ts +8 -7
  113. package/src/payload.ts +71 -53
  114. package/src/runtime/bun.ts +1 -1
  115. package/src/runtime/node.ts +2 -2
  116. package/src/runtime/pool.ts +1 -1
  117. package/src/runtime/portable.ts +3 -3
  118. package/src/runtime/types.ts +2 -4
  119. package/src/slug.ts +45 -54
  120. package/src/types.ts +108 -17
  121. package/src/uuid-value-protocol.ts +1 -1
  122. package/src/uuid-value.ts +3 -10
  123. package/src/uuid.ts +27 -41
  124. package/src/v4.ts +14 -11
  125. package/src/v7-bounds.ts +7 -5
  126. package/src/v7-generator-input.ts +4 -7
  127. package/src/v7-generator.ts +2 -2
  128. package/src/v7-keyless.ts +35 -6
  129. package/src/v7-payload.ts +1 -1
  130. package/src/v7-slug.ts +21 -2
  131. package/src/v7-value.ts +9 -4
  132. package/src/v7.ts +27 -1
package/src/uuid.ts CHANGED
@@ -18,6 +18,7 @@ import type { Latin1Scratch } from "./runtime/types.ts";
18
18
  import { UUID_TEXT_LOWERCASE, UUID_TEXT_UPPERCASE } from "./types.ts";
19
19
  import type {
20
20
  PreserveUuidVersion,
21
+ UnmaskedUuidInput,
21
22
  UuidBytes,
22
23
  UuidByteInput,
23
24
  UuidV4Bytes,
@@ -36,11 +37,6 @@ import type {
36
37
  UuidVersion,
37
38
  } from "./types.ts";
38
39
 
39
- export { isUuidSlugError } from "./errors.ts";
40
- export { UuidSlugError };
41
- export type { UuidSlugErrorCode } from "./errors.ts";
42
- export type { UuidBytes, UuidString } from "./types.ts";
43
-
44
40
  /** Report byte input that does not hold exactly one 16-byte UUID. */
45
41
  export const invalidUuidBytes = /* @__NO_SIDE_EFFECTS__ */ (): UuidSlugError =>
46
42
  new UuidSlugError(INVALID_BUFFER, "UUID byte input must contain exactly 16 bytes.");
@@ -70,16 +66,12 @@ export const isUuidTextCase = (value: unknown): value is UuidTextCase =>
70
66
  export function resolveUuidTextCase(value: unknown): UuidTextCase | UuidSlugError {
71
67
  if (value === UUID_TEXT_LOWERCASE || value === UUID_TEXT_UPPERCASE) return value;
72
68
  const textCase = stringInput(value);
73
- return isUuidTextCase(textCase) ? textCase : invalidUuidTextCase();
74
- }
75
- export function invalidUuidTextCase(): UuidSlugError {
76
- return new UuidSlugError(INVALID_OPTIONS, "UUID text case must be lowercase or uppercase.");
69
+ return isUuidTextCase(textCase)
70
+ ? textCase
71
+ : new UuidSlugError(INVALID_OPTIONS, "UUID text case must be lowercase or uppercase.");
77
72
  }
78
73
  const createLatin1Scratch = runtime.latin1Scratch;
79
74
  const nativeToHex = runtime.uuidHex;
80
- const HEX_DECODE = new Int8Array(128).fill(-1);
81
- for (let i = 0; i < 10; i += 1) HEX_DECODE[48 + i] = i;
82
- for (let i = 0; i < 6; i += 1) HEX_DECODE[97 + i] = 10 + i;
83
75
  // Nibbles of both hex cases; 0x100 marks every other ASCII character so OR-ed pairs expose it.
84
76
  const HEX_NIBBLES = new Uint16Array(128).fill(0x100);
85
77
  for (let i = 0; i < 16; i += 1) {
@@ -87,7 +79,7 @@ for (let i = 0; i < 16; i += 1) {
87
79
  HEX_NIBBLES[UPPERCASE_HEX.charCodeAt(i)] = i;
88
80
  }
89
81
  // Bun's Latin-1 writer and the fixed writer share lazily built case tables; native hex needs none.
90
- // bench/PERFORMANCE.md owns the comparison and recheck conditions. Tables are built on first use.
82
+ // bench/decisions.md owns the comparison and recheck conditions. Tables are built on first use.
91
83
  let uuidTextScratch: Latin1Scratch | undefined;
92
84
  let lowercaseHexCodes: Uint8Array | undefined;
93
85
  let uppercaseHexCodes: Uint8Array | undefined;
@@ -123,7 +115,7 @@ function formatUuidBytesLatin1(
123
115
  : (lowercaseHexCodes ??= hexCodes(HEX));
124
116
  const text = scratch.bytes;
125
117
  // Fixed positions remove the loop and offset-table reads on Bun's selected writer.
126
- // The indexed loop loses repeated complete text calls; bench/PERFORMANCE.md owns the evidence.
118
+ // The indexed loop loses repeated complete text calls; bench/decisions.md owns the evidence.
127
119
  // Keep native string construction and shared storage; remeasure after JSC or writer changes.
128
120
  const code0 = (bytes[offset + 0] as number) * 2;
129
121
  text[0] = codes[code0] as number;
@@ -202,14 +194,11 @@ function uuidTextStart(value: string): number {
202
194
  return INVALID_UUID_TEXT_START;
203
195
  }
204
196
 
197
+ // Either hex case; above 15 means not a digit. `charCodeAt` past the end gives NaN and non-ASCII
198
+ // codes index past the table; both read undefined, hence the fallback.
205
199
  /*#__NO_SIDE_EFFECTS__*/
206
- function lowercaseHexValue(code: number) {
207
- return HEX_DECODE[code] ?? -1;
208
- }
209
-
210
- /*#__NO_SIDE_EFFECTS__*/
211
- function parsedHexValue(code: number) {
212
- return code >= 65 && code <= 70 ? code - 55 : lowercaseHexValue(code);
200
+ function hexNibble(code: number) {
201
+ return HEX_NIBBLES[code] ?? 0x100;
213
202
  }
214
203
 
215
204
  /**
@@ -267,7 +256,7 @@ export function uuidStringToBytes(
267
256
 
268
257
  // One pass decodes and validates: OR-ing every character code and every decoded pair exposes a
269
258
  // non-ASCII or non-hex character after the loop. Validating before a second decoding pass cost
270
- // about twice as much on Node and three times on Bun (bench/PERFORMANCE.md). Only failing text
259
+ // about twice as much on Node and three times on Bun (bench/decisions.md). Only failing text
271
260
  // pays a second scan, which locates the offset for the message.
272
261
  const target = out === undefined ? new Uint8Array(16) : decodedUuidScratch;
273
262
  let codes = 0;
@@ -286,7 +275,7 @@ export function uuidStringToBytes(
286
275
  if (codes < 128 && pairs < 256) {
287
276
  if (out === undefined) return target;
288
277
  // A byte loop rather than `set`: the native call made Bun text-to-slug conversion slower
289
- // (bench/PERFORMANCE.md).
278
+ // (bench/decisions.md).
290
279
  for (let byteIndex = 0; byteIndex < 16; byteIndex += 1)
291
280
  out[offset + byteIndex] = target[byteIndex] as number;
292
281
  return out;
@@ -316,6 +305,7 @@ export function uuidStringToBytes(
316
305
  * `ArrayBuffer` uses its whole contents; a `DataView` uses its declared range. Only `Uint8Array`
317
306
  * input accepts an explicit offset. Invalid input returns `invalid_buffer`, and a preceding
318
307
  * `UuidSlugError` is returned unchanged.
308
+ * TypeScript rejects known masked bytes; decode them with their masking codec first.
319
309
  *
320
310
  * @param bytes - One supported UUID byte source.
321
311
  * @param textCase - Built-in output spelling. Omit for lowercase.
@@ -323,11 +313,11 @@ export function uuidStringToBytes(
323
313
  * @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
324
314
  */
325
315
  export function bytesToUuidString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
326
- bytes: UuidByteInput | UuidSlugError,
316
+ bytes: UnmaskedUuidInput<Readonly<UuidByteInput> | UuidSlugError>,
327
317
  ...textCase: UuidTextCaseArguments<Case>
328
318
  ): UuidStringFor<Case> | UuidSlugError;
329
319
  export function bytesToUuidString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
330
- bytes: Uint8Array | UuidSlugError,
320
+ bytes: UnmaskedUuidInput<Readonly<Uint8Array> | UuidSlugError>,
331
321
  byteOffset: number,
332
322
  ...textCase: UuidTextCaseArguments<Case>
333
323
  ): UuidStringFor<Case> | UuidSlugError;
@@ -350,6 +340,7 @@ export function bytesToUuidString(
350
340
  if (badRange) return badRange;
351
341
  if (nativeToHex) {
352
342
  // A small existing view avoids another view; a larger buffer must not encode unrelated bytes.
343
+ // Keep range selection here: unchecked fixed-size callers should not pay this branch.
353
344
  const hex =
354
345
  view.length <= 32
355
346
  ? nativeToHex(view)
@@ -374,7 +365,7 @@ export function formatUuidBytesUnchecked<Case extends UuidTextCase = typeof UUID
374
365
  // Bun retains its Latin-1 writer. A fixed argument list makes one flat string without
375
366
  // temporary bytes, intermediate hex or concatenation. WebKit selects native hex to avoid
376
367
  // repeated mixed-workload losses; remeasure both paths after engine changes
377
- // (bench/PERFORMANCE.md). Keep case selection and fixed writing together to avoid another call.
368
+ // (bench/decisions.md). Keep case selection and fixed writing together to avoid another call.
378
369
  if (createLatin1Scratch)
379
370
  return formatUuidBytesLatin1(
380
371
  createLatin1Scratch,
@@ -474,20 +465,17 @@ export function isUuidText(value: unknown): value is UuidText {
474
465
  return false;
475
466
  for (let i = 0; i < UUID_BYTE_OFFSETS.length; i += 1) {
476
467
  const offset = hyphenated ? textStart + (UUID_BYTE_OFFSETS[i] as number) : i * 2;
477
- if (
478
- parsedHexValue(value.charCodeAt(offset)) < 0 ||
479
- parsedHexValue(value.charCodeAt(offset + 1)) < 0
480
- )
468
+ if (hexNibble(value.charCodeAt(offset)) > 15 || hexNibble(value.charCodeAt(offset + 1)) > 15)
481
469
  return false;
482
470
  }
483
471
  return true;
484
472
  }
485
473
 
486
474
  // Canonical guards stay regular expressions: a character loop measured slower on Node and Bun
487
- // (bench/PERFORMANCE.md, Canonical UUID text).
475
+ // (bench/decisions.md, Canonical UUID text).
488
476
  // Pair repetition improves canonical calls, but slows Bun's successful base32 normalization.
489
477
  // Reuse its existing Latin-1 selection once; neither pattern needs a builder or per-call dispatch.
490
- // Remeasure normalization if this capability moves to another adapter (bench/PERFORMANCE.md).
478
+ // Remeasure normalization if this capability moves to another adapter (bench/decisions.md).
491
479
  const UUID_RE = createLatin1Scratch
492
480
  ? /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
493
481
  : /^(?:[0-9a-f][0-9a-f]){4}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){6}$/;
@@ -500,13 +488,12 @@ const UUID_V7_TEXT_RE = /*#__PURE__*/ new RegExp(UUID_V7_RE.source, "i");
500
488
  export function isUuidV4Text(value: unknown): value is UuidV4Text {
501
489
  if (!isUuidText(value)) return false;
502
490
  const textStart = uuidTextStart(value);
503
- const variant = parsedHexValue(
491
+ const variant = hexNibble(
504
492
  value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 16 : textStart + 19),
505
493
  );
506
494
  return (
507
- parsedHexValue(
508
- value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 12 : textStart + 14),
509
- ) === 4 &&
495
+ hexNibble(value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 12 : textStart + 14)) ===
496
+ 4 &&
510
497
  variant >= 8 &&
511
498
  variant <= 11
512
499
  );
@@ -517,17 +504,16 @@ export function isUuidV4Text(value: unknown): value is UuidV4Text {
517
504
  export function isUuidV7Text(value: unknown): value is UuidV7Text {
518
505
  // Canonical text uses the same syntax with either case, avoiding the full digit loop before
519
506
  // timestamp parsing. Other spellings retain their existing checks; remeasure after engine or
520
- // accepted-syntax changes (bench/PERFORMANCE.md).
507
+ // accepted-syntax changes (bench/decisions.md).
521
508
  if (typeof value === "string" && value.length === UUID_LENGTH) return UUID_V7_TEXT_RE.test(value);
522
509
  if (!isUuidText(value)) return false;
523
510
  const textStart = uuidTextStart(value);
524
- const variant = parsedHexValue(
511
+ const variant = hexNibble(
525
512
  value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 16 : textStart + 19),
526
513
  );
527
514
  return (
528
- parsedHexValue(
529
- value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 12 : textStart + 14),
530
- ) === 7 &&
515
+ hexNibble(value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 12 : textStart + 14)) ===
516
+ 7 &&
531
517
  variant >= 8 &&
532
518
  variant <= 11
533
519
  );
package/src/v4.ts CHANGED
@@ -13,6 +13,8 @@ import {
13
13
  } from "./errors.ts";
14
14
  import { UUID_TEXT_LOWERCASE, UUID_TEXT_UPPERCASE } from "./types.ts";
15
15
  import type {
16
+ UuidGenerationBytes,
17
+ UuidGenerationFailure,
16
18
  UuidRandomFill,
17
19
  UuidOutput,
18
20
  UuidTextCase,
@@ -27,9 +29,6 @@ import {
27
29
  resolveUuidTextCase,
28
30
  } from "./uuid.ts";
29
31
 
30
- export { isUuidSlugError } from "./errors.ts";
31
- export { UuidSlugError };
32
- export type { UuidSlugErrorCode } from "./errors.ts";
33
32
  export type { UuidV4Bytes, UuidV4String } from "./types.ts";
34
33
  export { isUuidV4Bytes, isUuidV4String, isUuidV4Text } from "./uuid.ts";
35
34
 
@@ -62,6 +61,13 @@ export function generateUuidV4Bytes<Output extends Uint8Array>(
62
61
  output: Output,
63
62
  outputOffset?: number,
64
63
  ): UuidOutput<Output> | UuidSlugError;
64
+ /**
65
+ * Use caller storage when supplied; otherwise allocate UUIDv4 bytes.
66
+ * @throws `UuidSlugError` with code `rng_unavailable` when storage is omitted and secure randomness is unavailable.
67
+ */
68
+ export function generateUuidV4Bytes<const Input extends Uint8Array | undefined>(
69
+ output: Input,
70
+ ): UuidGenerationBytes<Input, UuidV4Bytes> | UuidGenerationFailure<Input>;
65
71
  export function generateUuidV4Bytes(
66
72
  output?: Uint8Array,
67
73
  outputOffset = 0,
@@ -91,7 +97,7 @@ export function generateUuidV4Bytes(
91
97
  // Keep owned output separate so it can draw directly into its result without adding a post-draw
92
98
  // ownership branch to caller-buffer writes. Merge the paths if either primary runtime loses this win.
93
99
  // Failures are returned so slug and text callers can decide at their own public seam.
94
- export function generateOwnedUuidV4Bytes(): UuidV4Bytes | UuidSlugError {
100
+ function generateOwnedUuidV4Bytes(): UuidV4Bytes | UuidSlugError {
95
101
  if (generating) return new UuidSlugError(RNG_UNAVAILABLE, REENTRANT_GENERATION_MESSAGE);
96
102
  const output = new Uint8Array(16);
97
103
  generating = true;
@@ -109,15 +115,12 @@ export function generateOwnedUuidV4Bytes(): UuidV4Bytes | UuidSlugError {
109
115
  /**
110
116
  * Generate UUIDv4 text through the portable implementation, even on native-capable hosts.
111
117
  * Failures are returned so the native path can aggregate them with its own cause.
118
+ * `textCase` must already be resolved: `generateUuidV4` resolves it before calling, and the native
119
+ * fallback passes lowercase, so a second check here would only slow every portable call.
112
120
  */
113
121
  export function generatePortableUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
114
122
  textCase: Case = UUID_TEXT_LOWERCASE as Case,
115
123
  ): UuidV4StringFor<Case> | UuidSlugError {
116
- if (!isUuidTextCase(textCase)) {
117
- const selectedCase = resolveUuidTextCase(textCase);
118
- if (selectedCase instanceof Error) return selectedCase;
119
- textCase = selectedCase as Case;
120
- }
121
124
  const bytes = drawUuidV4Scratch();
122
125
  return bytes instanceof Error
123
126
  ? bytes
@@ -127,7 +130,7 @@ export function generatePortableUuidV4<Case extends UuidTextCase = typeof UUID_T
127
130
  /**
128
131
  * Fill the module scratch with UUIDv4 bytes for a writer that reads them before its next draw. Text
129
132
  * and slug writers never expose the scratch, so they skip a new array and the public converters'
130
- * input checks, which cost about a third of Node's portable text call (bench/PERFORMANCE.md).
133
+ * input checks, which cost about a third of Node's portable text call (bench/decisions.md).
131
134
  * Encoding cannot draw entropy, so the scratch cannot change between this return and the read.
132
135
  */
133
136
  export function drawUuidV4Scratch(): Uint8Array | UuidSlugError {
@@ -172,7 +175,7 @@ export function generateUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWE
172
175
  // Trust proper native output directly: validation and identity tracking impose guarantees
173
176
  // beyond the default native baseline. Configured entropy still validates at its caller seam.
174
177
  // Remeasure each output form if case normalization, host APIs or engine inlining
175
- // changes; bench/PERFORMANCE.md owns the evidence.
178
+ // changes; bench/decisions.md owns the evidence.
176
179
  const native = runtime.uuidV4;
177
180
  if (!native) return generatedOrThrow(generatePortableUuidV4(textCase));
178
181
  let uuid: string | UuidSlugError;
package/src/v7-bounds.ts CHANGED
@@ -27,6 +27,8 @@ function intervalEnd(startUnixMs: number, endUnixMs: number): number | UuidSlugE
27
27
  function endpoint(unixMs: number, upper: boolean): UuidV7Bytes {
28
28
  const bytes = new Uint8Array(16);
29
29
  if (upper) bytes.fill(0xff);
30
+ // Keep this fixed write local: sharing the generator's word writer slows JITless bounds calls.
31
+ // Reconsider extraction only with complete-call evidence across the supported engines.
30
32
  const high = Math.floor(unixMs / 0x1_0000_0000);
31
33
  bytes[0] = high >>> 8;
32
34
  bytes[1] = high;
@@ -70,7 +72,7 @@ function fixedTextEndpoint<Case extends UuidTextCase>(
70
72
  ): UuidV7StringFor<Case> {
71
73
  // Fixed character arguments reduce consumed bounds costs on V8 with the JIT. Byte pairs remain
72
74
  // faster on Bun and JITless Node; selection is outside per-ID calls. Remeasure engine changes
73
- // against bench/PERFORMANCE.md, including both endpoint reads and lazy table construction.
75
+ // against bench/decisions.md, including both endpoint reads and lazy table construction.
74
76
  const hex = (hexCodes ??= Uint8Array.from("0123456789abcdef", (digit) => digit.charCodeAt(0)));
75
77
  // Validated timestamps have 48 bits; splitting avoids truncating their upper 16 bits.
76
78
  const high = Math.floor(unixMs / 0x1_0000_0000);
@@ -102,7 +104,7 @@ function textEndpoint<Case extends UuidTextCase>(
102
104
  ): UuidV7StringFor<Case> {
103
105
  // Byte pairs avoid radix formatting and beat fixed character arguments on Bun and JITless Node.
104
106
  // Build the table on first use so imports that never request bounds pay no table construction.
105
- // Remeasure radix formatting and fixed arguments after engine changes (bench/PERFORMANCE.md).
107
+ // Remeasure radix formatting and fixed arguments after engine changes (bench/decisions.md).
106
108
  const hex = (hexBytes ??= Array.from({ length: 256 }, (_, byte) =>
107
109
  byte.toString(16).padStart(2, "0"),
108
110
  ));
@@ -143,13 +145,13 @@ export function uuidV7StringBounds<Case extends UuidTextCase = typeof UUID_TEXT_
143
145
  * interval. The comparison must preserve UUID byte order.
144
146
  *
145
147
  * @param startUnixMs - First whole Unix millisecond, inclusive.
146
- * @param endUnixMs - Last whole Unix millisecond, inclusive.
148
+ * @param endUnixMs - Last whole Unix millisecond, inclusive. Use `undefined` for `startUnixMs`.
147
149
  * @param textCase - Built-in output spelling. Omit for lowercase.
148
150
  * @returns Canonical UUIDv7 endpoints, or `invalid_timestamp` for an invalid interval.
149
151
  */
150
152
  export function uuidV7StringBounds<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
151
153
  startUnixMs: number,
152
- endUnixMs: number,
154
+ endUnixMs: number | undefined,
153
155
  ...textCase: UuidTextCaseArguments<Case>
154
156
  ): UuidV7Bounds<UuidV7StringFor<Case>> | UuidSlugError;
155
157
  export function uuidV7StringBounds(
@@ -163,7 +165,7 @@ export function uuidV7StringBounds(
163
165
  const end = intervalEnd(startUnixMs, endUnixMs);
164
166
  if (typeof end !== "number") return end;
165
167
  // Direct formatting avoids two temporary byte arrays. Keep the byte writer independent unless
166
- // repeated public-route measurements reverse this result; bench/PERFORMANCE.md owns that trigger.
168
+ // repeated public-route measurements reverse this result; bench/decisions.md owns that trigger.
167
169
  return {
168
170
  startInclusive: selectedTextEndpoint(startUnixMs, false, textCase),
169
171
  endInclusive: selectedTextEndpoint(end, true, textCase),
@@ -9,6 +9,7 @@ import {
9
9
  UuidSlugError,
10
10
  } from "./errors.ts";
11
11
  import type { UuidV7Generator, UuidV7Instant, UuidV7PayloadLayout } from "./types.ts";
12
+ import type { GenerationOptionValues } from "./generation-options.ts";
12
13
  import type { PortableUuidV7Generator } from "./v7.ts";
13
14
  import { readUuidV7Instant } from "./instant.ts";
14
15
  import { readUuidV7PayloadLayout, uuidV7PayloadFromBytesUnchecked } from "./v7-payload.ts";
@@ -17,11 +18,7 @@ import { isUuidV7Bytes, uuidTimestampFromBytesUnchecked } from "./uuid.ts";
17
18
  const AT_OPTION = "at";
18
19
  const UUID_V7_GENERATOR_REQUIRED = "generator must be a UUIDv7 generator.";
19
20
 
20
- export interface UuidV7GenerationValues {
21
- readonly at?: unknown;
22
- readonly output?: unknown;
23
- readonly outputOffset?: unknown;
24
- }
21
+ export type UuidV7GenerationValues = Pick<GenerationOptionValues, "at" | "output" | "outputOffset">;
25
22
 
26
23
  export interface ValidatedUuidV7Generator {
27
24
  readonly generateUuidV7Bytes: UuidV7Generator["generateUuidV7Bytes"];
@@ -48,7 +45,7 @@ class ReturnObject {
48
45
  *
49
46
  * Structural validation allocated a validated object and rescanned the layout keys on every call
50
47
  * that passed `generator`, and the untrusted-generator call then needed a scratch buffer, byte
51
- * validation, an `at` check, and a copy (bench/PERFORMANCE.md). The stamp adds a private field
48
+ * validation, an `at` check, and a copy (bench/decisions.md). The stamp adds a private field
52
49
  * instead of a class prototype, so the public object stays plain. A module `WeakMap` is the rejected
53
50
  * alternative: registration made default generator creation 1.6 times slower. Remeasure if engines
54
51
  * change how they store private fields or weak collections.
@@ -106,7 +103,7 @@ export function readUuidV7Generator(
106
103
  *
107
104
  * The generator receives the result buffer and may keep a reference to it, so a result the caller
108
105
  * keeps is a copy. Pass `borrowed` only when the package consumes the bytes before returning and
109
- * never returns them: text, slug, and masked-slug writers skip that copy (bench/PERFORMANCE.md).
106
+ * never returns them: text, slug, and masked-slug writers skip that copy (bench/decisions.md).
110
107
  */
111
108
  export function generateUuidV7BytesWithGenerator(
112
109
  generator: ValidatedUuidV7Generator,
@@ -180,8 +180,8 @@ function buildGenerator(
180
180
  return instant instanceof Error ? instant : generator.drawUuidV7Bytes(instant);
181
181
  };
182
182
  // Omission cannot prove a retained codec; the configured overload requires its runtime options.
183
- function generateUuidV7Value(valueOptions?: undefined): Uuid<7, false, true> | UuidSlugError;
184
- function generateUuidV7Value<const Options extends UuidV7GeneratorValueOptions>(
183
+ function generateUuidV7Value(): Uuid<7, false, true> | UuidSlugError;
184
+ function generateUuidV7Value<const Options extends UuidV7GeneratorValueOptions | undefined>(
185
185
  valueOptions: Options,
186
186
  ):
187
187
  | Uuid<7, Options extends { readonly maskingCodec: UuidV7MaskingCodec } ? true : false, true>
package/src/v7-keyless.ts CHANGED
@@ -19,6 +19,10 @@ import type {
19
19
  GenerateUuidV7BytesIntoOptions,
20
20
  GenerateUuidV7BytesOptions,
21
21
  UuidOutput,
22
+ UuidGenerationBytes,
23
+ UuidGenerationFailure,
24
+ UuidGenerationInput,
25
+ UuidGenerationTextCase,
22
26
  UuidTextCase,
23
27
  UuidTextCaseArguments,
24
28
  UuidV7Bytes,
@@ -48,7 +52,7 @@ const UUID_V7_BYTE_OPTIONS = {
48
52
  /**
49
53
  * Text and bytes keep independent lazy state so neither output form pays cross-form coordination.
50
54
  * Native defaults avoid constructing this generator. Explicit time, configured generators and
51
- * native failure still need portable state; bench/PERFORMANCE.md owns the selection evidence.
55
+ * native failure still need portable state; bench/decisions.md owns the selection evidence.
52
56
  */
53
57
  let textGenerator: PortableUuidV7Generator | undefined;
54
58
  let byteGenerator: PortableUuidV7Generator | undefined;
@@ -69,7 +73,7 @@ const keylessTextBytes = new Uint8Array(16);
69
73
 
70
74
  /**
71
75
  * Draw with options this module already read. Rebuilding an options object for the generator's
72
- * public method allocated it and read every option a second time (bench/PERFORMANCE.md).
76
+ * public method allocated it and read every option a second time (bench/decisions.md).
73
77
  */
74
78
  function drawFromReadOptions(
75
79
  generator: PortableUuidV7Generator,
@@ -101,10 +105,10 @@ export const uuidV7BytesAt = (at: unknown): Uint8Array | UuidSlugError => drawAt
101
105
  * Slug and pair writers encode their bytes before returning and draw nothing in between, so they
102
106
  * borrow the generator's private text scratch instead of validating a second module buffer as
103
107
  * caller output. Text keeps cached generator delegation; replacing it with a direct module
104
- * formatter has not earned its cost on the primary calls (bench/PERFORMANCE.md).
108
+ * formatter has not earned its cost on the primary calls (bench/decisions.md).
105
109
  * Keep configured output validation and the generator's reentrancy guard; a borrowed buffer
106
110
  * must never escape or survive another draw. Remeasure complete calls when either writer changes
107
- * (bench/PERFORMANCE.md), rather than assuming fewer checks improve every runtime.
111
+ * (bench/decisions.md), rather than assuming fewer checks improve every runtime.
108
112
  */
109
113
  export const currentUuidV7Scratch = (): Uint8Array | UuidSlugError =>
110
114
  v7Text().drawUuidV7Bytes(undefined, keylessTextBytes);
@@ -123,7 +127,7 @@ const portableUuidV7Text = (textCase: UuidTextCase): string | UuidSlugError =>
123
127
 
124
128
  // Trust proper native results directly; validation and identity tracking add guarantees beyond
125
129
  // the default native baseline. Keep exception fallback separate from configured calls, and
126
- // remeasure complete calls when host capabilities change; bench/PERFORMANCE.md owns evidence.
130
+ // remeasure complete calls when host capabilities change; bench/decisions.md owns evidence.
127
131
  function generateNativeDefaultUuidV7<Case extends UuidTextCase>(
128
132
  selectedCase: Case,
129
133
  ): UuidV7StringFor<Case> | UuidSlugError {
@@ -174,6 +178,15 @@ export function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWE
174
178
  export function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
175
179
  options: GenerateUuidV7Options<Case>,
176
180
  ): UuidV7StringFor<Case> | UuidSlugError;
181
+ /**
182
+ * Forward a spelling preset or optional settings without branching.
183
+ * @throws `UuidSlugError` with code `rng_unavailable` on a preset or undefined branch when secure randomness is unavailable.
184
+ */
185
+ export function generateUuidV7<
186
+ const Input extends UuidTextCase | GenerateUuidV7Options<UuidTextCase> | undefined,
187
+ >(
188
+ textCaseOrOptions: UuidGenerationInput<Input, GenerateUuidV7Options<UuidTextCase>>,
189
+ ): UuidV7StringFor<UuidGenerationTextCase<Input>> | UuidGenerationFailure<Input>;
177
190
  export function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
178
191
  textCaseOrOptions?: Case | GenerateUuidV7Options<Case>,
179
192
  ): UuidV7StringFor<Case> | UuidSlugError {
@@ -261,6 +274,22 @@ export function generateUuidV7Bytes(
261
274
  export function generateUuidV7Bytes<Output extends Uint8Array>(
262
275
  options: GenerateUuidV7BytesIntoOptions<Output>,
263
276
  ): UuidOutput<Output> | UuidSlugError;
277
+ /**
278
+ * Forward optional storage or generation settings; caller storage keeps its own array type.
279
+ * @throws `UuidSlugError` with code `rng_unavailable` on an undefined branch when secure randomness is unavailable.
280
+ */
281
+ export function generateUuidV7Bytes<
282
+ const Input extends
283
+ | Uint8Array
284
+ | GenerateUuidV7BytesOptions
285
+ | GenerateUuidV7BytesIntoOptions<Uint8Array>
286
+ | undefined,
287
+ >(
288
+ outOrOptions: UuidGenerationInput<
289
+ Input,
290
+ GenerateUuidV7BytesOptions & GenerateUuidV7BytesIntoOptions<Uint8Array>
291
+ >,
292
+ ): UuidGenerationBytes<Input, UuidV7Bytes> | UuidGenerationFailure<Input>;
264
293
  export function generateUuidV7Bytes(
265
294
  outOrOptions?:
266
295
  | Uint8Array
@@ -281,7 +310,7 @@ export const currentUuidV7Bytes = (): UuidV7Bytes | UuidSlugError =>
281
310
  // Independent draws remove unrequested sequence work from owned defaults. Keep JITless on its
282
311
  // measured generator path; configured calls and immutable values retain their declared layout.
283
312
  // Remeasure complete calls if entropy, timestamp writing or runtime selection changes;
284
- // bench/PERFORMANCE.md owns runtime comparisons rather than this selection comment.
313
+ // bench/decisions.md owns runtime comparisons rather than this selection comment.
285
314
  const generateSelectedDefaultUuidV7Bytes = runtime.jitless
286
315
  ? currentUuidV7Bytes
287
316
  : generateDefaultOwnedUuidV7Bytes;
package/src/v7-payload.ts CHANGED
@@ -68,7 +68,7 @@ export function readUuidV7PayloadLayout(
68
68
  * Join `rand_a` and `rand_b`; version and variant bits are separators, not payload.
69
69
  *
70
70
  * The upper 34 and lower 40 payload bits are assembled as exact numbers and joined once, because a
71
- * BigInt conversion and shift per byte cost more than twice as much (bench/PERFORMANCE.md).
71
+ * BigInt conversion and shift per byte cost more than twice as much (bench/decisions.md).
72
72
  */
73
73
  export function uuidV7PayloadFromBytesUnchecked(bytes: Uint8Array, offset: number): bigint {
74
74
  const upper =
package/src/v7-slug.ts CHANGED
@@ -14,6 +14,9 @@ import type {
14
14
  UuidTextCase,
15
15
  UuidV7Generator,
16
16
  UuidV7StringFor,
17
+ UuidGenerationFailure,
18
+ UuidGenerationInput,
19
+ UuidGenerationTextCase,
17
20
  } from "./types.ts";
18
21
  import { currentUuidV7Scratch, uuidV7ScratchAt } from "./v7-keyless.ts";
19
22
  import { generateUuidV7BytesWithGenerator, readUuidV7Generator } from "./v7-generator-input.ts";
@@ -56,7 +59,7 @@ const portableUuidV7Slug = (): string | UuidSlugError => {
56
59
 
57
60
  // Direct native output removes clock, entropy, byte writing and encoding from ordinary calls.
58
61
  // Configured calls and base32hex remain portable. Remeasure complete calls and resources if this
59
- // boundary changes; bench/PERFORMANCE.md owns evidence. Trust proper native results directly;
62
+ // boundary changes; bench/decisions.md owns evidence. Trust proper native results directly;
60
63
  // result validation and identity tracking would impose stronger default guarantees.
61
64
  function nativeUuidV7Slug(): string | UuidSlugError {
62
65
  const native = runtime.uuidV7Slug;
@@ -250,7 +253,7 @@ export function generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
250
253
  textCase: Case,
251
254
  ): GeneratedUuidV7<PlainUuidV7Slug, Case>;
252
255
  export function generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
253
- alphabet: SlugAlphabet,
256
+ alphabet: SlugAlphabet | undefined,
254
257
  textCase: Case,
255
258
  ): GeneratedUuidV7<PlainUuidV7Slug, Case>;
256
259
  /**
@@ -261,6 +264,22 @@ export function generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
261
264
  export function generateUuidV7WithPlainSlug<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
262
265
  options: GenerateUuidV7WithPlainSlugOptions<Case>,
263
266
  ): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
267
+ /**
268
+ * Forward presets or optional settings, retaining their UUID text case and default branches.
269
+ * @throws `UuidSlugError` with code `rng_unavailable` on a preset or undefined branch when secure randomness is unavailable.
270
+ */
271
+ export function generateUuidV7WithPlainSlug<
272
+ const Input extends
273
+ | SlugAlphabet
274
+ | UuidTextCase
275
+ | GenerateUuidV7WithPlainSlugOptions<UuidTextCase>
276
+ | undefined,
277
+ >(
278
+ alphabetOrCaseOrOptions: UuidGenerationInput<
279
+ Input,
280
+ GenerateUuidV7WithPlainSlugOptions<UuidTextCase>
281
+ >,
282
+ ): GeneratedUuidV7<PlainUuidV7Slug, UuidGenerationTextCase<Input>> | UuidGenerationFailure<Input>;
264
283
  export function generateUuidV7WithPlainSlug(
265
284
  alphabetOrCaseOrOptions:
266
285
  | SlugAlphabet
package/src/v7-value.ts CHANGED
@@ -1,6 +1,11 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
2
 
3
- import type { Uuid, UuidV7MaskingCodec, UuidV7ValueOptions } from "./types.ts";
3
+ import type {
4
+ Uuid,
5
+ UuidGenerationFailure,
6
+ UuidV7MaskingCodec,
7
+ UuidV7ValueOptions,
8
+ } from "./types.ts";
4
9
  import { UuidSlugError } from "./errors.ts";
5
10
  import { createUuidValue } from "./uuid-value.ts";
6
11
  import { currentUuidV7Bytes, uuidV7BytesAt, uuidV7DefaultPayloadLayout } from "./v7-keyless.ts";
@@ -23,17 +28,17 @@ const UUID_V7_VALUE_OPTIONS = {
23
28
  * @throws `UuidSlugError` with code `rng_unavailable` when generation cannot obtain
24
29
  * secure randomness.
25
30
  */
26
- export function generateUuidV7Value(options?: undefined): Uuid<7, false, true>;
31
+ export function generateUuidV7Value(): Uuid<7, false, true>;
27
32
  /**
28
33
  * Generate an immutable UUIDv7 with optional time, generator, and retained masking codec.
29
34
  * Only a supplied codec is retained; an undefined options branch uses default generation.
30
35
  * @throws `UuidSlugError` with code `rng_unavailable` if options are undefined and secure randomness is unavailable.
31
36
  */
32
- export function generateUuidV7Value<const Options extends UuidV7ValueOptions | undefined = {}>(
37
+ export function generateUuidV7Value<const Options extends UuidV7ValueOptions | undefined>(
33
38
  options: Options,
34
39
  ):
35
40
  | Uuid<7, Options extends { readonly maskingCodec: UuidV7MaskingCodec } ? true : false, true>
36
- | UuidSlugError;
41
+ | UuidGenerationFailure<Options>;
37
42
  export function generateUuidV7Value(
38
43
  options?: UuidV7ValueOptions,
39
44
  ): Uuid<7, boolean, true> | UuidSlugError {
package/src/v7.ts CHANGED
@@ -21,6 +21,9 @@ import type {
21
21
  GenerateUuidV7BytesIntoOptions,
22
22
  GenerateUuidV7BytesOptions,
23
23
  GenerateUuidV7Options,
24
+ UuidGenerationBytes,
25
+ UuidGenerationTextCase,
26
+ UuidGenerationInput,
24
27
  UuidOutput,
25
28
  UuidTextCase,
26
29
  UuidTextCaseArguments,
@@ -105,7 +108,7 @@ function writeTimestampLoop(bytes: Uint8Array, ms: number, offset: number) {
105
108
  }
106
109
 
107
110
  // Measured Bun favors the loop while Node and Chromium favor fixed writes; select once so generation
108
- // pays no per-call branch. bench/PERFORMANCE.md owns the measurements and replacement condition.
111
+ // pays no per-call branch. bench/decisions.md owns the measurements and replacement condition.
109
112
  const writeTimestamp = (globalThis as { Bun?: object }).Bun
110
113
  ? writeTimestampLoop
111
114
  : writeTimestampWords;
@@ -368,6 +371,18 @@ export function createPortableUuidV7Generator(
368
371
  function generateUuidV7Bytes<Output extends Uint8Array>(
369
372
  options: Omit<GenerateUuidV7BytesIntoOptions<Output>, "generator">,
370
373
  ): UuidOutput<Output> | UuidSlugError;
374
+ function generateUuidV7Bytes<
375
+ const Input extends
376
+ | Uint8Array
377
+ | Omit<GenerateUuidV7BytesOptions, "generator">
378
+ | Omit<GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
379
+ | undefined,
380
+ >(
381
+ outOrOptions: UuidGenerationInput<
382
+ Input,
383
+ Omit<GenerateUuidV7BytesOptions & GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
384
+ >,
385
+ ): UuidGenerationBytes<Input, UuidV7Bytes> | UuidSlugError;
371
386
  function generateUuidV7Bytes(
372
387
  outOrOptions?:
373
388
  | Uint8Array
@@ -408,6 +423,17 @@ export function createPortableUuidV7Generator(
408
423
  function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
409
424
  options: Omit<GenerateUuidV7Options<Case>, "generator">,
410
425
  ): UuidV7StringFor<Case> | UuidSlugError;
426
+ function generateUuidV7<
427
+ const Input extends
428
+ | UuidTextCase
429
+ | Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
430
+ | undefined,
431
+ >(
432
+ textCaseOrOptions: UuidGenerationInput<
433
+ Input,
434
+ Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
435
+ >,
436
+ ): UuidV7StringFor<UuidGenerationTextCase<Input>> | UuidSlugError;
411
437
  function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
412
438
  textCaseOrOptions:
413
439
  | Case