@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/slug.ts CHANGED
@@ -55,6 +55,7 @@ import type {
55
55
  UuidV7StringFor,
56
56
  UuidVersion,
57
57
  KeylessUuidInput,
58
+ UnmaskedUuidInput,
58
59
  } from "./types.ts";
59
60
  import { UUID_TEXT_LOWERCASE } from "./types.ts";
60
61
  import { uuidValueBytes } from "./uuid-value-protocol.ts";
@@ -76,9 +77,6 @@ import {
76
77
  uuidVersion,
77
78
  } from "./uuid.ts";
78
79
 
79
- export { isUuidSlugError } from "./errors.ts";
80
- export { UuidSlugError };
81
- export type { UuidSlugErrorCode } from "./errors.ts";
82
80
  export type { PlainUuidSlug, PlainUuidV4Slug, PlainUuidV7Slug } from "./types.ts";
83
81
 
84
82
  const UUID_V7_TIMESTAMP_ONLY = "Timestamp is only defined for UUIDv7.";
@@ -160,17 +158,12 @@ const BYTE_OFFSET_NEEDS_BYTES =
160
158
  */
161
159
  export type SlugAlphabet = typeof BASE64URL_NAME | typeof BASE32HEX_NAME;
162
160
 
163
- const SLUG_ALPHABET_CODECS = {
164
- base32hex: BASE32HEX,
165
- base64url: BASE64URL,
166
- } as const satisfies Record<SlugAlphabet, Alphabet>;
167
-
168
161
  /** Reject values outside the public alphabet union when untyped JavaScript bypasses TypeScript. */
169
162
  /*#__NO_SIDE_EFFECTS__*/
170
163
  export function resolveSlugAlphabet(alphabet: SlugAlphabet): Alphabet | UuidSlugError {
171
164
  const name = typeof alphabet === "string" ? alphabet : stringInput(alphabet);
172
165
  // Fixed comparisons avoid an own-property call and keyed lookup on every conversion.
173
- // Packed complete-call comparisons favor this over SLUG_ALPHABET_CODECS; remeasure if
166
+ // Packed complete-call comparisons favor this over a name-keyed lookup object; remeasure if
174
167
  // the supported alphabet vocabulary grows. Wrapper normalization remains shared.
175
168
  if (name === BASE64URL_NAME) return BASE64URL;
176
169
  if (name === BASE32HEX_NAME) return BASE32HEX;
@@ -180,38 +173,33 @@ export function resolveSlugAlphabet(alphabet: SlugAlphabet): Alphabet | UuidSlug
180
173
  );
181
174
  }
182
175
 
183
- /** Characters needed for 16 bytes: 22 in base64url, 26 in base32hex. */
184
- /*#__NO_SIDE_EFFECTS__*/
185
- function slugLength(alpha: Alphabet) {
186
- return Math.ceil(128 / alpha.bitsPerChar);
187
- }
188
-
189
176
  /**
190
177
  * Length -> alphabet, which is why decoding takes no alphabet argument: the two lengths are
191
178
  * disjoint, so a slug names its own encoding and a caller cannot pick the wrong one. Indexed
192
179
  * rather than searched because every decode and every type guard pays this lookup.
180
+ * The index is the characters 16 bytes need: ceil(128 / 6) = 22 in base64url, ceil(128 / 5) = 26
181
+ * in base32hex.
193
182
  */
194
- const SLUG_ALPHABET_BY_LENGTH: readonly (Alphabet | undefined)[] = /*#__PURE__*/ Object.values(
195
- SLUG_ALPHABET_CODECS,
196
- ).reduce<(Alphabet | undefined)[]>((table, alpha) => {
197
- table[slugLength(alpha)] = alpha;
183
+ const SLUG_ALPHABET_BY_LENGTH: readonly (Alphabet | undefined)[] = /*#__PURE__*/ (() => {
184
+ const table: (Alphabet | undefined)[] = [];
185
+ table[22] = BASE64URL;
186
+ table[26] = BASE32HEX;
198
187
  return table;
199
- }, []);
188
+ })();
200
189
 
201
- const SLUG_LENGTHS = /*#__PURE__*/ Object.values(SLUG_ALPHABET_CODECS)
202
- .map((alpha) => `${slugLength(alpha)} (${alpha.name})`)
203
- .join(ALTERNATIVE_SEPARATOR);
190
+ const SLUG_LENGTHS = `26 (${BASE32HEX_NAME})${ALTERNATIVE_SEPARATOR}22 (${BASE64URL_NAME})`;
204
191
 
205
192
  /**
206
193
  * Encode a standalone 16-byte UUID as a plain slug, using base64url by default. An `ArrayBuffer`
207
194
  * uses its whole contents; a `DataView` uses its declared range. Invalid input or alphabet returns
208
195
  * `UuidSlugError`. A preceding `UuidSlugError` is returned unchanged.
196
+ * TypeScript rejects known masked bytes; decode them with their masking codec first.
209
197
  *
210
198
  * @param bytes - One exact 16-byte UUID source.
211
199
  * @param alphabet - Output spelling. Omit for the shorter 22-character base64url form.
212
200
  */
213
201
  export function uuidBytesToPlainSlug(
214
- bytes: UuidByteInput | UuidSlugError,
202
+ bytes: UnmaskedUuidInput<Readonly<UuidByteInput> | UuidSlugError>,
215
203
  alphabet?: SlugAlphabet,
216
204
  ): PlainUuidSlug | UuidSlugError;
217
205
  /**
@@ -223,7 +211,7 @@ export function uuidBytesToPlainSlug(
223
211
  * @param alphabet - Output spelling. Omit for the shorter 22-character base64url form.
224
212
  */
225
213
  export function uuidBytesToPlainSlug(
226
- bytes: Uint8Array | UuidSlugError,
214
+ bytes: UnmaskedUuidInput<Readonly<Uint8Array> | UuidSlugError>,
227
215
  byteOffset: number,
228
216
  alphabet?: SlugAlphabet,
229
217
  ): PlainUuidSlug | UuidSlugError;
@@ -245,7 +233,7 @@ export function uuidBytesToPlainSlug(
245
233
  if (selectedAlphabet === BASE32HEX_NAME) return encode(bytes, BASE32HEX) as PlainUuidSlug;
246
234
  // Native encoding owns this exact plain-payload job. Offset windows and non-array forms retain
247
235
  // general conversion; masked tails never enter here. Keep base32 controls in the comparison
248
- // when changing this dispatch (bench/PERFORMANCE.md).
236
+ // when changing this dispatch (bench/decisions.md).
249
237
  if (selectedAlphabet === BASE64URL_NAME) {
250
238
  if (nativePlainUuidBase64) {
251
239
  try {
@@ -318,18 +306,13 @@ export function plainSlugToUuidBytes(
318
306
  ? checkRange(16, outputOffset, 16)
319
307
  : checkByteRange(output, outputOffset, 16);
320
308
  if (badRange) return badRange;
309
+ // A caller buffer must stay unchanged on failure, so invalid input is decoded into a throwaway
310
+ // array only to get the same diagnostic the no-buffer path returns. Valid input never allocates.
321
311
  if (output && !isEncoded(slug, alpha, 16, true)) {
322
- for (let i = 0; i < slug.length; i += 1) {
323
- const code = slug.charCodeAt(i);
324
- if (code >= 128 || (alpha.decode[code] as number) < 0)
325
- return new UuidSlugError(
326
- alpha.code,
327
- `Invalid ${alpha.name} character ${JSON.stringify(slug[i])} at offset ${i}.`,
328
- );
329
- }
330
- return new UuidSlugError(alpha.code, `${alpha.name} value has non-canonical trailing bits.`);
312
+ const failed = decodeInto(slug, alpha, new Uint8Array(16), 0);
313
+ if (failed instanceof Error) return failed;
331
314
  }
332
- const result = decodeInto(slug, alpha, target, outputOffset, 16);
315
+ const result = decodeInto(slug, alpha, target, outputOffset);
333
316
  return result instanceof Error ? result : target;
334
317
  }
335
318
 
@@ -361,7 +344,7 @@ export function uuidStringToPlainSlug(
361
344
  // Resolve caller selectors before scratch is live, then parse and encode without callbacks.
362
345
  // Separate text-to-slug
363
346
  // writers read hex pairs and concatenated characters, and were slower on every runtime
364
- // (bench/PERFORMANCE.md). Reassess scratch ownership if encoding adds caller-controlled work.
347
+ // (bench/decisions.md). Reassess scratch ownership if encoding adds caller-controlled work.
365
348
  const bytes = uuidStringToBytes(uuidText, textSlugScratch);
366
349
  if (bytes instanceof Error) return bytes;
367
350
  return encode(bytes, alpha) as PlainUuidSlug;
@@ -403,9 +386,7 @@ export function plainSlugToUuidString(
403
386
  // Normalize before scratch is live, then decode and format without caller callbacks. Revisit
404
387
  // reuse if either operation gains callbacks; failed writes cannot escape this private buffer.
405
388
  // The public byte decoder owns invalid-length diagnostics, so keep that exceptional path shared.
406
- const decoded = alpha
407
- ? decodeInto(slug, alpha, textSlugScratch, 0, 16)
408
- : plainSlugToUuidBytes(slug);
389
+ const decoded = alpha ? decodeInto(slug, alpha, textSlugScratch, 0) : plainSlugToUuidBytes(slug);
409
390
  if (decoded instanceof Error) return decoded;
410
391
  // A successful decode yields exactly 16 bytes, so the checked formatter would repeat work.
411
392
  return formatUuidBytesUnchecked(textSlugScratch, 0, selectedCase);
@@ -450,7 +431,8 @@ export function readObjectUuidInput(uuid: unknown): Uint8Array | string | UuidSl
450
431
  */
451
432
  export function extractUuidVersion<Input extends UuidInput>(
452
433
  uuid: KeylessUuidInput<Input>,
453
- ): UuidVersion | UuidSlugError {
434
+ ): UuidVersion | UuidSlugError;
435
+ export function extractUuidVersion(uuid: unknown): UuidVersion | UuidSlugError {
454
436
  const localBytes = exactLocalUuidBytes(uuid);
455
437
  if (localBytes) return uuidVersion(localBytes, 0);
456
438
  const bytes = decodeKeylessUuid(uuid);
@@ -460,6 +442,7 @@ export function extractUuidVersion<Input extends UuidInput>(
460
442
 
461
443
  /**
462
444
  * Convert UUID text, bytes, or a plain UUID slug to new or caller-owned UUID bytes.
445
+ * Decode masked bytes with their masking codec before calling this reader.
463
446
  * Only `Uint8Array` input accepts a non-zero offset; `0` means the same as omitting it.
464
447
  *
465
448
  * @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
@@ -472,9 +455,12 @@ export function uuidToBytes<Input extends UuidInput, Output extends Uint8Array>(
472
455
  output: Output,
473
456
  outputOffset?: number,
474
457
  ): UuidOutput<Output> | UuidSlugError;
475
- export function uuidToBytes(uuid: Uint8Array, byteOffset: number): UuidBytesResult<Uint8Array>;
476
- export function uuidToBytes<Output extends Uint8Array>(
477
- uuid: Uint8Array,
458
+ export function uuidToBytes<Input extends Uint8Array>(
459
+ uuid: KeylessUuidInput<Input>,
460
+ byteOffset: number,
461
+ ): UuidBytesResult<Uint8Array>;
462
+ export function uuidToBytes<Output extends Uint8Array, Input extends Uint8Array = Uint8Array>(
463
+ uuid: KeylessUuidInput<Input>,
478
464
  byteOffset: number,
479
465
  output: Output,
480
466
  outputOffset?: number,
@@ -521,6 +507,7 @@ export function uuidToBytes(
521
507
 
522
508
  /**
523
509
  * Convert UUID text, bytes, or a plain UUID slug to normalized UUID text.
510
+ * Decode masked bytes with their masking codec before calling this reader.
524
511
  * Only `Uint8Array` input accepts a non-zero offset; `0` means the same as omitting it.
525
512
  *
526
513
  * @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
@@ -532,8 +519,11 @@ export function uuidToString<
532
519
  uuid: KeylessUuidInput<Input>,
533
520
  ...textCase: UuidTextCaseArguments<Case>
534
521
  ): UuidStringResult<Input, Case>;
535
- export function uuidToString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
536
- uuid: Uint8Array,
522
+ export function uuidToString<
523
+ Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE,
524
+ Input extends Uint8Array = Uint8Array,
525
+ >(
526
+ uuid: KeylessUuidInput<Input>,
537
527
  byteOffset: number,
538
528
  ...textCase: UuidTextCaseArguments<Case>
539
529
  ): UuidStringResult<Uint8Array, Case>;
@@ -549,7 +539,7 @@ export function uuidToString(
549
539
  textCase = caseAfterOffset;
550
540
  } else textCase = byteOffsetOrCase;
551
541
  // Canonical lowercase text is already the default output, so it is returned without decoding.
552
- // An inline `typeof` guard ahead of the helper slowed Node mixed-case text (bench/PERFORMANCE.md).
542
+ // An inline `typeof` guard ahead of the helper slowed Node mixed-case text (bench/decisions.md).
553
543
  if (textCase === UUID_TEXT_LOWERCASE && isUuidString(uuid)) return uuid;
554
544
  const localBytes = exactLocalUuidBytes(uuid);
555
545
  if (localBytes) {
@@ -570,12 +560,12 @@ export function uuidToString(
570
560
  }
571
561
  }
572
562
  // Only text leaves this call. Reuse private scratch instead of an owned decode array;
573
- // public caller-buffer decoding adds validation and copying (bench/PERFORMANCE.md).
563
+ // public caller-buffer decoding adds validation and copying (bench/decisions.md).
574
564
  const alpha = typeof input === "string" ? SLUG_ALPHABET_BY_LENGTH[input.length] : undefined;
575
565
  const decoded =
576
566
  typeof input === "string"
577
567
  ? alpha
578
- ? decodeInto(input, alpha, textSlugScratch, 0, 16)
568
+ ? decodeInto(input, alpha, textSlugScratch, 0)
579
569
  : uuidStringToBytes(input)
580
570
  : input;
581
571
  const bytes = typeof decoded === "number" ? textSlugScratch : decoded;
@@ -589,6 +579,7 @@ export function uuidToString(
589
579
 
590
580
  /**
591
581
  * Convert UUID text, bytes, or a plain UUID slug to a plain slug.
582
+ * Decode masked bytes with their masking codec before calling this reader.
592
583
  * Only `Uint8Array` input accepts a non-zero offset; `0` means the same as omitting it.
593
584
  *
594
585
  * @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
@@ -597,8 +588,8 @@ export function uuidToPlainSlug<Input extends UuidInput>(
597
588
  uuid: KeylessUuidInput<Input>,
598
589
  alphabet?: SlugAlphabet,
599
590
  ): PlainUuidSlugResult<Input>;
600
- export function uuidToPlainSlug(
601
- uuid: Uint8Array,
591
+ export function uuidToPlainSlug<Input extends Uint8Array>(
592
+ uuid: KeylessUuidInput<Input>,
602
593
  byteOffset: number,
603
594
  alphabet?: SlugAlphabet,
604
595
  ): PlainUuidSlugResult<Uint8Array>;
@@ -671,7 +662,7 @@ function fixedCanonicalUuidV7UnixMs(text: string): number {
671
662
  // low word so timestamps above its sign bit preserve all 48 bits. Only validated canonical text
672
663
  // reaches this helper; compact text retains its contiguous parse. Table reads slightly favor
673
664
  // Bun but lose on Node in the source screen; remeasure complete calls after parser or engine
674
- // changes (bench/PERFORMANCE.md).
665
+ // changes (bench/decisions.md).
675
666
  const high =
676
667
  (validatedHexNibble(text, 0) << 12) |
677
668
  (validatedHexNibble(text, 1) << 8) |
@@ -696,7 +687,7 @@ function parsedCanonicalUuidV7UnixMs(text: string): number {
696
687
  }
697
688
 
698
689
  // Reuse the runtime's settled JIT selection; no flag parsing or table construction belongs here.
699
- // Recheck both complete calls after engine changes against bench/PERFORMANCE.md.
690
+ // Recheck both complete calls after engine changes against bench/decisions.md.
700
691
  const canonicalUuidV7UnixMsUnchecked = runtime.jitless
701
692
  ? parsedCanonicalUuidV7UnixMs
702
693
  : fixedCanonicalUuidV7UnixMs;
@@ -873,7 +864,7 @@ export function validatePlainUuidV7SlugUnixMs(
873
864
  // validator captures all byte fields before caller-owned window accessors can reenter.
874
865
  const alpha = SLUG_ALPHABET_BY_LENGTH[plainSlug.length];
875
866
  const decoded = alpha
876
- ? decodeInto(plainSlug, alpha, textSlugScratch, 0, 16)
867
+ ? decodeInto(plainSlug, alpha, textSlugScratch, 0)
877
868
  : plainSlugToUuidBytes(plainSlug);
878
869
  if (decoded instanceof Error) return decoded;
879
870
  const bytes = typeof decoded === "number" ? textSlugScratch : decoded;
package/src/types.ts CHANGED
@@ -33,6 +33,31 @@ export type UuidTextCase = typeof UUID_TEXT_LOWERCASE | typeof UUID_TEXT_UPPERCA
33
33
  export type UuidTextCaseArguments<Case extends UuidTextCase> =
34
34
  typeof UUID_TEXT_LOWERCASE extends Case ? [textCase?: Case] : [textCase: Case];
35
35
 
36
+ // Forwarded unions must keep the lowercase branch when the selector or its property is absent.
37
+ // Capturing the argument avoids claiming uppercase from an explicit generic alone.
38
+ export type UuidGenerationTextCase<Input> = Input extends UuidTextCase
39
+ ? Input
40
+ : Input extends object
41
+ ? "textCase" extends keyof Input
42
+ ?
43
+ | Extract<Input["textCase"], UuidTextCase>
44
+ | (undefined extends Input["textCase"] ? typeof UUID_TEXT_LOWERCASE : never)
45
+ : typeof UUID_TEXT_LOWERCASE
46
+ : typeof UUID_TEXT_LOWERCASE;
47
+
48
+ // Module presets and omission throw entropy failures; configured calls return error values.
49
+ export type UuidGenerationFailure<Input> = Input extends object ? UuidSlugError : never;
50
+
51
+ // Capturing an argument suppresses excess-property checks; keep misspelled options rejected.
52
+ // Byte destinations are caller-owned arrays, so their own additional properties remain valid.
53
+ export type UuidGenerationInput<Input, Options> = Input extends Uint8Array
54
+ ? Input
55
+ : Input extends object
56
+ ? Exclude<keyof Input, keyof Options> extends never
57
+ ? Input
58
+ : Input & { [Key in Exclude<keyof Input, keyof Options>]: never }
59
+ : Input;
60
+
36
61
  // Keep selector inference at the property while requiring a non-default selector in reusable options.
37
62
  type UuidTextCaseOptions<Case extends UuidTextCase> = typeof UUID_TEXT_LOWERCASE extends Case
38
63
  ? { readonly textCase?: Case }
@@ -133,7 +158,7 @@ export type PreserveUuidVersion<Input, UnknownVersion, Version4, Version7> =
133
158
  ? Version7
134
159
  : UnknownVersion;
135
160
  /** Infer a version from immutable input; mutable bytes retain the complete version-field range. */
136
- export type UuidVersionOf<Input> = Input extends UuidSlugError
161
+ type UuidVersionOf<Input> = Input extends UuidSlugError
137
162
  ? never
138
163
  : Input extends Uuid<infer Version, boolean, boolean>
139
164
  ? Version
@@ -162,6 +187,13 @@ export type SentinelUuidV7Slug = Brand<PlainUuidV7Slug, "SentinelUuidV7Slug">;
162
187
  /** A masking result: either a masked UUIDv7 or a registered plain sentinel. */
163
188
  export type MaskedOrSentinelUuidV7Slug = MaskedUuidV7Slug | SentinelUuidV7Slug;
164
189
 
190
+ /** An owned 16-byte mixed UUIDv7 block with its 12-bit inner check; not raw UUID bytes. */
191
+ export type MaskedUuidV7Bytes = Brand<Uint8Array, "MaskedUuidV7Bytes">;
192
+ /** A registered sentinel's unmasked UUIDv7 bytes. */
193
+ export type SentinelUuidV7Bytes = Brand<UuidV7Bytes, "SentinelUuidV7Bytes">;
194
+ /** Binary masking output: a mixed block or a registered sentinel's raw UUID bytes. */
195
+ export type MaskedOrSentinelUuidV7Bytes = MaskedUuidV7Bytes | SentinelUuidV7Bytes;
196
+
165
197
  /** One generated UUIDv7 in the selected text case and one selected slug made from the same bytes. */
166
198
  export interface GeneratedUuidV7<
167
199
  Slug extends PlainUuidV7Slug | MaskedOrSentinelUuidV7Slug,
@@ -333,6 +365,14 @@ type RejectKnownInput<Input, Invalid> = [Extract<Exclude<Input, UuidSlugError>,
333
365
  ? Input
334
366
  : never;
335
367
 
368
+ /** Raw UUID readers cannot infer masked provenance from the identical 16-byte shape. */
369
+ // Keep the exclusion on the parameter: explicit case/output generics can default an inferred
370
+ // input to unbranded bytes. The object intersection accepts unrelated UUID brands too.
371
+ // Fixed byte-source unions use Readonly first so methods returning `this` do not revive a
372
+ // destination's previous brand after a writer returns its unbranded view.
373
+ export type UnmaskedUuidInput<Input> = Input & {
374
+ readonly [brand]?: object & { readonly MaskedUuidV7Bytes?: never };
375
+ };
336
376
  /** Reject a known slug; the operation parses UUID text. A bare string is validated at runtime. */
337
377
  export type UuidStringInput<Input extends string | UuidSlugError> = RejectKnownInput<
338
378
  Input,
@@ -358,18 +398,25 @@ export type PlainUuidV7SlugInput<Input extends string | UuidSlugError> = RejectK
358
398
  Input,
359
399
  UuidText | MaskedUuidSlug | PlainUuidV4Slug
360
400
  >;
361
- /** Reject masked slugs and known UUIDv4 values across text and byte timestamp inputs. */
401
+ /** Reject masked slugs, mixed bytes and known UUIDv4 values across timestamp inputs. */
362
402
  export type UuidV7TimestampInput<Input extends string | UuidByteInput | UuidSlugError> =
363
- RejectKnownInput<Input, MaskedUuidSlug | UuidV4Text | PlainUuidV4Slug | UuidV4Bytes>;
364
- /** Reject known UUIDv4 bytes; the operation needs UUIDv7 bytes. */
403
+ RejectKnownInput<
404
+ Input,
405
+ MaskedUuidSlug | MaskedUuidV7Bytes | UuidV4Text | PlainUuidV4Slug | UuidV4Bytes
406
+ >;
407
+ /** Reject mixed and known UUIDv4 bytes; the operation needs raw UUIDv7 bytes. */
365
408
  export type UuidV7BytesInput<Input extends UuidByteInput | UuidSlugError> = RejectKnownInput<
366
409
  Input,
367
- UuidV4Bytes
410
+ UuidV4Bytes | MaskedUuidV7Bytes
368
411
  >;
369
412
  /** Reject known non-v7 values; a masking codec accepts every UUIDv7 form. */
370
413
  export type UuidV7ValueInput<Input extends UuidInput> = RejectKnownInput<
371
414
  Input,
372
- UuidV4Text | UuidV4Bytes | PlainUuidV4Slug | AnyUuidForVersion<Exclude<UuidVersion, 7>>
415
+ | UuidV4Text
416
+ | UuidV4Bytes
417
+ | PlainUuidV4Slug
418
+ | MaskedUuidV7Bytes
419
+ | AnyUuidForVersion<Exclude<UuidVersion, 7>>
373
420
  >;
374
421
  /** Exactly 16 validated UUID bytes. Package-owned values are plain `Uint8Array`. */
375
422
  export type UuidBytes = Brand<Uint8Array, "UuidBytes">;
@@ -380,10 +427,17 @@ export type UuidV7Bytes = Brand<UuidBytes, "UuidV7Bytes">;
380
427
 
381
428
  // Writers preserve the array and its methods, but prior UUID facts describe the replaced bytes.
382
429
  // Strip only the package brand; erasing every subtype would also discard useful caller storage APIs.
383
- export type UuidOutput<Output extends Uint8Array> = Output extends UuidBytes
430
+ export type UuidOutput<Output extends Uint8Array> = Output extends UuidBytes | MaskedUuidV7Bytes
384
431
  ? Omit<Output, typeof brand>
385
432
  : Output;
386
433
 
434
+ // Storage remains a caller choice even when a wrapper forwards several generation forms.
435
+ export type UuidGenerationBytes<Input, Owned extends UuidBytes> = Input extends Uint8Array
436
+ ? UuidOutput<Input>
437
+ : Input extends { readonly output: infer Output extends Uint8Array }
438
+ ? UuidOutput<Output>
439
+ : Owned;
440
+
387
441
  /** A UUID byte source: a `Uint8Array`, a complete `ArrayBuffer`, or a `DataView`'s declared range. */
388
442
  export type UuidByteInput = Uint8Array | ArrayBuffer | DataView;
389
443
  type AnyUuidForVersion<Version extends UuidVersion> = Uuid<Version, boolean, boolean>;
@@ -409,12 +463,8 @@ export type ParsedUuidResult<Input, WithCodec extends boolean = false> = Uuid<
409
463
  * implementations also normalize genuine `String` objects; TypeScript uses primitive strings.
410
464
  */
411
465
  export type UuidInput = string | UuidByteInput | AnyUuid | UuidSlugError;
412
- /** Reject a branded masked slug where no masking codec is available. */
413
- export type KeylessUuidInput<Input> = [
414
- Extract<Exclude<Input, UuidSlugError>, MaskedUuidV7Slug>,
415
- ] extends [never]
416
- ? Input
417
- : never;
466
+ /** Reject branded masked slugs or bytes where no masking codec is available. */
467
+ export type KeylessUuidInput<Input> = UnmaskedUuidInput<RejectKnownInput<Input, MaskedUuidV7Slug>>;
418
468
  /** UUID text or the error returned while converting the captured input. */
419
469
  export type UuidStringResult<Input, Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE> =
420
470
  | PreserveUuidVersion<Input, UuidStringFor<Case>, UuidV4StringFor<Case>, UuidV7StringFor<Case>>
@@ -453,7 +503,7 @@ export interface UuidV7Generator {
453
503
  /** Payload layout emitted by this generator; pass it to UUIDv7 payload extraction. */
454
504
  readonly payloadLayout: UuidV7PayloadLayout;
455
505
  /** Generate an immutable UUIDv7 that remembers this generator's payload layout. */
456
- generateUuidV7Value(this: void, options?: undefined): Uuid<7, false, true> | UuidSlugError;
506
+ generateUuidV7Value(this: void): Uuid<7, false, true> | UuidSlugError;
457
507
  /** Generate with supplied time or masking options; only a supplied codec is retained. */
458
508
  generateUuidV7Value<const Options extends UuidV7GeneratorValueOptions | undefined>(
459
509
  this: void,
@@ -471,6 +521,19 @@ export interface UuidV7Generator {
471
521
  this: void,
472
522
  options: Omit<GenerateUuidV7Options<Case>, "generator">,
473
523
  ): UuidV7StringFor<Case> | UuidSlugError;
524
+ /** Forward a spelling preset or optional settings through this generator's sequence. */
525
+ generateUuidV7<
526
+ const Input extends
527
+ | UuidTextCase
528
+ | Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
529
+ | undefined,
530
+ >(
531
+ this: void,
532
+ textCaseOrOptions: UuidGenerationInput<
533
+ Input,
534
+ Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
535
+ >,
536
+ ): UuidV7StringFor<UuidGenerationTextCase<Input>> | UuidSlugError;
474
537
  /** Generate a new plain 16-byte `Uint8Array` for the current clock reading. */
475
538
  generateUuidV7Bytes(this: void): UuidV7Bytes | UuidSlugError;
476
539
  /**
@@ -495,6 +558,20 @@ export interface UuidV7Generator {
495
558
  this: void,
496
559
  options: Omit<GenerateUuidV7BytesIntoOptions<Output>, "generator">,
497
560
  ): UuidOutput<Output> | UuidSlugError;
561
+ /** Forward optional storage or settings, preserving caller-array types and sequence state. */
562
+ generateUuidV7Bytes<
563
+ const Input extends
564
+ | Uint8Array
565
+ | Omit<GenerateUuidV7BytesOptions, "generator">
566
+ | Omit<GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
567
+ | undefined,
568
+ >(
569
+ this: void,
570
+ outOrOptions: UuidGenerationInput<
571
+ Input,
572
+ Omit<GenerateUuidV7BytesOptions & GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
573
+ >,
574
+ ): UuidGenerationBytes<Input, UuidV7Bytes> | UuidSlugError;
498
575
  /**
499
576
  * Generate a plain UUIDv7 slug in this sequence. Lowercase base32hex preserves UUID byte order;
500
577
  * base64url does not preserve that order under text comparison.
@@ -523,7 +600,7 @@ export interface UuidV7Generator {
523
600
  ): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
524
601
  generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
525
602
  this: void,
526
- alphabet: SlugAlphabet,
603
+ alphabet: SlugAlphabet | undefined,
527
604
  textCase: Case,
528
605
  ): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
529
606
  /** Generate the pair at an explicit time or the current clock reading, in the selected spellings. */
@@ -531,6 +608,20 @@ export interface UuidV7Generator {
531
608
  this: void,
532
609
  options: Omit<GenerateUuidV7WithPlainSlugOptions<Case>, "generator">,
533
610
  ): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
611
+ /** Forward presets or optional settings through this sequence, retaining the UUID text case. */
612
+ generateUuidV7WithPlainSlug<
613
+ const Input extends
614
+ | SlugAlphabet
615
+ | UuidTextCase
616
+ | Omit<GenerateUuidV7WithPlainSlugOptions<UuidTextCase>, "generator">
617
+ | undefined,
618
+ >(
619
+ this: void,
620
+ alphabetOrCaseOrOptions: UuidGenerationInput<
621
+ Input,
622
+ Omit<GenerateUuidV7WithPlainSlugOptions<UuidTextCase>, "generator">
623
+ >,
624
+ ): GeneratedUuidV7<PlainUuidV7Slug, UuidGenerationTextCase<Input>> | UuidSlugError;
534
625
  }
535
626
 
536
627
  /**
@@ -792,7 +883,7 @@ export interface UuidSlugMigrationDecoder<
792
883
  uuidSlugToUuidString<Input extends string | UuidSlugError, Case extends UuidTextCase>(
793
884
  this: void,
794
885
  uuidSlug: SlugStringInput<Input>,
795
- format: Format,
886
+ format: Format | undefined,
796
887
  textCase: Case,
797
888
  ): UuidStringFor<Case> | UuidSlugError;
798
889
  /**
@@ -821,7 +912,7 @@ export interface UuidSlugMigrationDecoder<
821
912
  uuidSlugToUuidStringCandidates<Input extends string | UuidSlugError, Case extends UuidTextCase>(
822
913
  this: void,
823
914
  uuidSlug: SlugStringInput<Input>,
824
- format: Format,
915
+ format: Format | undefined,
825
916
  textCase: Case,
826
917
  ): readonly UuidStringFor<Case>[] | UuidSlugError;
827
918
  }
@@ -11,7 +11,7 @@ export const UUID_VALUE_CONTEXT = Symbol.for("@anizoptera/uuid-slug.uuid-value-c
11
11
  * importing the value class, and private fields keep the state off the frozen value's own properties.
12
12
  *
13
13
  * A module `WeakMap` keyed by value is the rejected alternative: registering each value cost more
14
- * than the rest of value creation (bench/PERFORMANCE.md). Remeasure if engines change how they
14
+ * than the rest of value creation (bench/decisions.md). Remeasure if engines change how they
15
15
  * store private fields or weak collections.
16
16
  */
17
17
  export class LocalUuidValue {
package/src/uuid-value.ts CHANGED
@@ -27,6 +27,7 @@ import {
27
27
  } from "./types.ts";
28
28
  import type {
29
29
  KeylessUuidInput,
30
+ UnmaskedUuidInput,
30
31
  MaskedOrSentinelUuidV7Slug,
31
32
  PlainUuidSlugForVersion,
32
33
  ParsedUuidResult,
@@ -74,7 +75,7 @@ class ParsedUuidValue<
74
75
  {
75
76
  // Private bytes are already a complete immutable UUID; public conversion would validate them
76
77
  // again. Resolve caller selectors, then use the same writers directly without caching spellings.
77
- // Revisit if private storage becomes mutable or borrowed; measurements live in bench/PERFORMANCE.md.
78
+ // Revisit if private storage becomes mutable or borrowed; measurements live in bench/decisions.md.
78
79
  get version(): Version {
79
80
  return uuidVersion(LocalUuidValue.ownBytes(this), 0) as Version;
80
81
  }
@@ -279,7 +280,7 @@ export function parseUuid<Input extends UuidInput>(
279
280
  * thrown exceptions remain available as the error's `cause`.
280
281
  */
281
282
  export function parseUuid<Input extends UuidInput>(
282
- uuid: Input,
283
+ uuid: UnmaskedUuidInput<Input>,
283
284
  maskingCodec: UuidV7MaskingCodec,
284
285
  ): ParsedUuidResult<Input, true> | UuidSlugError;
285
286
  export function parseUuid(
@@ -331,11 +332,3 @@ export function parseUuid(
331
332
  existing ? LocalUuidValue.ownPayloadLayout(existing) : foreignContext?.payloadLayout,
332
333
  );
333
334
  }
334
-
335
- /** Parse with the supplied masking codec preset by an owner method. */
336
- export function parseUuidWithCodec<Input extends UuidInput>(
337
- uuid: Input,
338
- maskingCodec: UuidV7MaskingCodec,
339
- ): ParsedUuidResult<Input, true> | UuidSlugError {
340
- return parseUuid(uuid, maskingCodec);
341
- }