@anizoptera/uuid-slug 0.5.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 (125) hide show
  1. package/README.md +51 -139
  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 +2 -2
  101. package/src/alphabet.ts +82 -237
  102. package/src/errors.ts +27 -40
  103. package/src/feistel.ts +3 -3
  104. package/src/index.ts +3 -0
  105. package/src/mask-handle.ts +7 -11
  106. package/src/mask.ts +16 -14
  107. package/src/masked-bytes.ts +203 -0
  108. package/src/masking-codec-types.ts +124 -24
  109. package/src/masking-codec.ts +43 -42
  110. package/src/migration.ts +8 -7
  111. package/src/payload.ts +69 -51
  112. package/src/runtime/portable.ts +2 -2
  113. package/src/runtime/types.ts +2 -4
  114. package/src/slug.ts +39 -48
  115. package/src/types.ts +108 -17
  116. package/src/uuid-value.ts +2 -9
  117. package/src/uuid.ts +19 -33
  118. package/src/v4.ts +12 -9
  119. package/src/v7-bounds.ts +4 -2
  120. package/src/v7-generator-input.ts +2 -5
  121. package/src/v7-generator.ts +2 -2
  122. package/src/v7-keyless.ts +29 -0
  123. package/src/v7-slug.ts +20 -1
  124. package/src/v7-value.ts +9 -4
  125. package/src/v7.ts +26 -0
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
  }
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,
@@ -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
- }
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) {
@@ -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
  /**
@@ -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)
@@ -474,10 +465,7 @@ 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;
@@ -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
  );
@@ -521,13 +508,12 @@ export function isUuidV7Text(value: unknown): value is UuidV7Text {
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
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;
@@ -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(
@@ -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"];
@@ -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,
@@ -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
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";
@@ -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 {