@anizoptera/uuid-slug 0.5.0 → 0.7.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 (141) hide show
  1. package/AGENTS.md +14 -0
  2. package/README.md +54 -140
  3. package/dist/alphabet.d.ts +1 -3
  4. package/dist/alphabet.d.ts.map +1 -1
  5. package/dist/alphabet.js +33 -91
  6. package/dist/alphabet.js.map +1 -1
  7. package/dist/base64url-name.d.ts +1 -3
  8. package/dist/base64url-name.d.ts.map +1 -1
  9. package/dist/base64url-name.js +2 -3
  10. package/dist/errors.d.ts +1 -3
  11. package/dist/errors.d.ts.map +1 -1
  12. package/dist/errors.js +7 -24
  13. package/dist/errors.js.map +1 -1
  14. package/dist/feistel.js +3 -4
  15. package/dist/feistel.js.map +1 -1
  16. package/dist/generation-options.js +2 -3
  17. package/dist/generation-options.js.map +1 -1
  18. package/dist/index.d.ts +10 -10
  19. package/dist/index.js +21 -21
  20. package/dist/instant.js +4 -5
  21. package/dist/instant.js.map +1 -1
  22. package/dist/mask-handle.d.ts +1 -3
  23. package/dist/mask-handle.d.ts.map +1 -1
  24. package/dist/mask-handle.js +19 -17
  25. package/dist/mask-handle.js.map +1 -1
  26. package/dist/mask.d.ts +1 -3
  27. package/dist/mask.d.ts.map +1 -1
  28. package/dist/mask.js +23 -24
  29. package/dist/mask.js.map +1 -1
  30. package/dist/masked-bytes.js +74 -0
  31. package/dist/masked-bytes.js.map +1 -0
  32. package/dist/masking-codec-protocol.js +2 -3
  33. package/dist/masking-codec-protocol.js.map +1 -1
  34. package/dist/masking-codec-types.d.ts +60 -19
  35. package/dist/masking-codec-types.d.ts.map +1 -1
  36. package/dist/masking-codec.d.ts +1 -3
  37. package/dist/masking-codec.d.ts.map +1 -1
  38. package/dist/masking-codec.js +119 -115
  39. package/dist/masking-codec.js.map +1 -1
  40. package/dist/migration.js +39 -40
  41. package/dist/migration.js.map +1 -1
  42. package/dist/node/runtime.js +9 -10
  43. package/dist/node/runtime.js.map +1 -1
  44. package/dist/payload.d.ts +1 -3
  45. package/dist/payload.d.ts.map +1 -1
  46. package/dist/payload.js +65 -64
  47. package/dist/payload.js.map +1 -1
  48. package/dist/runtime/pool.js +2 -3
  49. package/dist/runtime/pool.js.map +1 -1
  50. package/dist/runtime/portable.js +2 -3
  51. package/dist/runtime/portable.js.map +1 -1
  52. package/dist/sentinel.js +2 -3
  53. package/dist/sentinel.js.map +1 -1
  54. package/dist/siphash.js +4 -5
  55. package/dist/siphash.js.map +1 -1
  56. package/dist/slug.d.ts +14 -13
  57. package/dist/slug.d.ts.map +1 -1
  58. package/dist/slug.js +145 -153
  59. package/dist/slug.js.map +1 -1
  60. package/dist/timestamp.d.ts +1 -3
  61. package/dist/timestamp.d.ts.map +1 -1
  62. package/dist/timestamp.js +2 -3
  63. package/dist/timestamp.js.map +1 -1
  64. package/dist/types.d.ts +38 -16
  65. package/dist/types.d.ts.map +1 -1
  66. package/dist/types.js +2 -3
  67. package/dist/types.js.map +1 -1
  68. package/dist/uuid-value-protocol.js +2 -3
  69. package/dist/uuid-value-protocol.js.map +1 -1
  70. package/dist/uuid-value.d.ts +3 -5
  71. package/dist/uuid-value.d.ts.map +1 -1
  72. package/dist/uuid-value.js +74 -78
  73. package/dist/uuid-value.js.map +1 -1
  74. package/dist/uuid.d.ts +6 -8
  75. package/dist/uuid.d.ts.map +1 -1
  76. package/dist/uuid.js +38 -49
  77. package/dist/uuid.js.map +1 -1
  78. package/dist/v4-slug.d.ts +2 -4
  79. package/dist/v4-slug.d.ts.map +1 -1
  80. package/dist/v4-slug.js +6 -7
  81. package/dist/v4-slug.js.map +1 -1
  82. package/dist/v4.d.ts +8 -6
  83. package/dist/v4.d.ts.map +1 -1
  84. package/dist/v4.js +38 -44
  85. package/dist/v4.js.map +1 -1
  86. package/dist/v7-bounds.d.ts +3 -5
  87. package/dist/v7-bounds.d.ts.map +1 -1
  88. package/dist/v7-bounds.js +10 -11
  89. package/dist/v7-bounds.js.map +1 -1
  90. package/dist/v7-generator-input.js +10 -12
  91. package/dist/v7-generator-input.js.map +1 -1
  92. package/dist/v7-generator.d.ts +1 -3
  93. package/dist/v7-generator.d.ts.map +1 -1
  94. package/dist/v7-generator.js +45 -46
  95. package/dist/v7-generator.js.map +1 -1
  96. package/dist/v7-keyless.d.ts +12 -4
  97. package/dist/v7-keyless.d.ts.map +1 -1
  98. package/dist/v7-keyless.js +54 -55
  99. package/dist/v7-keyless.js.map +1 -1
  100. package/dist/v7-payload.js +3 -4
  101. package/dist/v7-payload.js.map +1 -1
  102. package/dist/v7-slug.d.ts +8 -5
  103. package/dist/v7-slug.d.ts.map +1 -1
  104. package/dist/v7-slug.js +69 -70
  105. package/dist/v7-slug.js.map +1 -1
  106. package/dist/v7-timestamp.js +2 -3
  107. package/dist/v7-timestamp.js.map +1 -1
  108. package/dist/v7-value-options.js +2 -3
  109. package/dist/v7-value-options.js.map +1 -1
  110. package/dist/v7-value.d.ts +5 -8
  111. package/dist/v7-value.d.ts.map +1 -1
  112. package/dist/v7-value.js +10 -11
  113. package/dist/v7-value.js.map +1 -1
  114. package/dist/v7.js +16 -17
  115. package/dist/v7.js.map +1 -1
  116. package/package.json +9 -2
  117. package/src/alphabet.ts +82 -237
  118. package/src/errors.ts +27 -40
  119. package/src/feistel.ts +3 -3
  120. package/src/index.ts +3 -0
  121. package/src/mask-handle.ts +7 -11
  122. package/src/mask.ts +16 -14
  123. package/src/masked-bytes.ts +203 -0
  124. package/src/masking-codec-types.ts +124 -24
  125. package/src/masking-codec.ts +43 -42
  126. package/src/migration.ts +8 -7
  127. package/src/payload.ts +69 -51
  128. package/src/runtime/portable.ts +2 -2
  129. package/src/runtime/types.ts +2 -4
  130. package/src/slug.ts +39 -48
  131. package/src/types.ts +107 -17
  132. package/src/uuid-value.ts +2 -9
  133. package/src/uuid.ts +19 -33
  134. package/src/v4.ts +12 -9
  135. package/src/v7-bounds.ts +4 -2
  136. package/src/v7-generator-input.ts +2 -5
  137. package/src/v7-generator.ts +2 -2
  138. package/src/v7-keyless.ts +29 -0
  139. package/src/v7-slug.ts +20 -1
  140. package/src/v7-value.ts +9 -4
  141. package/src/v7.ts +26 -0
package/src/types.ts CHANGED
@@ -33,6 +33,30 @@ 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
+ ? | Extract<Input["textCase"], UuidTextCase>
43
+ | (undefined extends Input["textCase"] ? typeof UUID_TEXT_LOWERCASE : never)
44
+ : typeof UUID_TEXT_LOWERCASE
45
+ : typeof UUID_TEXT_LOWERCASE;
46
+
47
+ // Module presets and omission throw entropy failures; configured calls return error values.
48
+ export type UuidGenerationFailure<Input> = Input extends object ? UuidSlugError : never;
49
+
50
+ // Capturing an argument suppresses excess-property checks; keep misspelled options rejected.
51
+ // Byte destinations are caller-owned arrays, so their own additional properties remain valid.
52
+ export type UuidGenerationInput<Input, Options> = Input extends Uint8Array
53
+ ? Input
54
+ : Input extends object
55
+ ? Exclude<keyof Input, keyof Options> extends never
56
+ ? Input
57
+ : Input & { [Key in Exclude<keyof Input, keyof Options>]: never }
58
+ : Input;
59
+
36
60
  // Keep selector inference at the property while requiring a non-default selector in reusable options.
37
61
  type UuidTextCaseOptions<Case extends UuidTextCase> = typeof UUID_TEXT_LOWERCASE extends Case
38
62
  ? { readonly textCase?: Case }
@@ -133,7 +157,7 @@ export type PreserveUuidVersion<Input, UnknownVersion, Version4, Version7> =
133
157
  ? Version7
134
158
  : UnknownVersion;
135
159
  /** Infer a version from immutable input; mutable bytes retain the complete version-field range. */
136
- export type UuidVersionOf<Input> = Input extends UuidSlugError
160
+ type UuidVersionOf<Input> = Input extends UuidSlugError
137
161
  ? never
138
162
  : Input extends Uuid<infer Version, boolean, boolean>
139
163
  ? Version
@@ -162,6 +186,13 @@ export type SentinelUuidV7Slug = Brand<PlainUuidV7Slug, "SentinelUuidV7Slug">;
162
186
  /** A masking result: either a masked UUIDv7 or a registered plain sentinel. */
163
187
  export type MaskedOrSentinelUuidV7Slug = MaskedUuidV7Slug | SentinelUuidV7Slug;
164
188
 
189
+ /** An owned 16-byte mixed UUIDv7 block with its 12-bit inner check; not raw UUID bytes. */
190
+ export type MaskedUuidV7Bytes = Brand<Uint8Array, "MaskedUuidV7Bytes">;
191
+ /** A registered sentinel's unmasked UUIDv7 bytes. */
192
+ export type SentinelUuidV7Bytes = Brand<UuidV7Bytes, "SentinelUuidV7Bytes">;
193
+ /** Binary masking output: a mixed block or a registered sentinel's raw UUID bytes. */
194
+ export type MaskedOrSentinelUuidV7Bytes = MaskedUuidV7Bytes | SentinelUuidV7Bytes;
195
+
165
196
  /** One generated UUIDv7 in the selected text case and one selected slug made from the same bytes. */
166
197
  export interface GeneratedUuidV7<
167
198
  Slug extends PlainUuidV7Slug | MaskedOrSentinelUuidV7Slug,
@@ -333,6 +364,14 @@ type RejectKnownInput<Input, Invalid> = [Extract<Exclude<Input, UuidSlugError>,
333
364
  ? Input
334
365
  : never;
335
366
 
367
+ /** Raw UUID readers cannot infer masked provenance from the identical 16-byte shape. */
368
+ // Keep the exclusion on the parameter: explicit case/output generics can default an inferred
369
+ // input to unbranded bytes. The object intersection accepts unrelated UUID brands too.
370
+ // Fixed byte-source unions use Readonly first so methods returning `this` do not revive a
371
+ // destination's previous brand after a writer returns its unbranded view.
372
+ export type UnmaskedUuidInput<Input> = Input & {
373
+ readonly [brand]?: object & { readonly MaskedUuidV7Bytes?: never };
374
+ };
336
375
  /** Reject a known slug; the operation parses UUID text. A bare string is validated at runtime. */
337
376
  export type UuidStringInput<Input extends string | UuidSlugError> = RejectKnownInput<
338
377
  Input,
@@ -358,18 +397,25 @@ export type PlainUuidV7SlugInput<Input extends string | UuidSlugError> = RejectK
358
397
  Input,
359
398
  UuidText | MaskedUuidSlug | PlainUuidV4Slug
360
399
  >;
361
- /** Reject masked slugs and known UUIDv4 values across text and byte timestamp inputs. */
400
+ /** Reject masked slugs, mixed bytes and known UUIDv4 values across timestamp inputs. */
362
401
  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. */
402
+ RejectKnownInput<
403
+ Input,
404
+ MaskedUuidSlug | MaskedUuidV7Bytes | UuidV4Text | PlainUuidV4Slug | UuidV4Bytes
405
+ >;
406
+ /** Reject mixed and known UUIDv4 bytes; the operation needs raw UUIDv7 bytes. */
365
407
  export type UuidV7BytesInput<Input extends UuidByteInput | UuidSlugError> = RejectKnownInput<
366
408
  Input,
367
- UuidV4Bytes
409
+ UuidV4Bytes | MaskedUuidV7Bytes
368
410
  >;
369
411
  /** Reject known non-v7 values; a masking codec accepts every UUIDv7 form. */
370
412
  export type UuidV7ValueInput<Input extends UuidInput> = RejectKnownInput<
371
413
  Input,
372
- UuidV4Text | UuidV4Bytes | PlainUuidV4Slug | AnyUuidForVersion<Exclude<UuidVersion, 7>>
414
+ | UuidV4Text
415
+ | UuidV4Bytes
416
+ | PlainUuidV4Slug
417
+ | MaskedUuidV7Bytes
418
+ | AnyUuidForVersion<Exclude<UuidVersion, 7>>
373
419
  >;
374
420
  /** Exactly 16 validated UUID bytes. Package-owned values are plain `Uint8Array`. */
375
421
  export type UuidBytes = Brand<Uint8Array, "UuidBytes">;
@@ -380,10 +426,17 @@ export type UuidV7Bytes = Brand<UuidBytes, "UuidV7Bytes">;
380
426
 
381
427
  // Writers preserve the array and its methods, but prior UUID facts describe the replaced bytes.
382
428
  // 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
429
+ export type UuidOutput<Output extends Uint8Array> = Output extends UuidBytes | MaskedUuidV7Bytes
384
430
  ? Omit<Output, typeof brand>
385
431
  : Output;
386
432
 
433
+ // Storage remains a caller choice even when a wrapper forwards several generation forms.
434
+ export type UuidGenerationBytes<Input, Owned extends UuidBytes> = Input extends Uint8Array
435
+ ? UuidOutput<Input>
436
+ : Input extends { readonly output: infer Output extends Uint8Array }
437
+ ? UuidOutput<Output>
438
+ : Owned;
439
+
387
440
  /** A UUID byte source: a `Uint8Array`, a complete `ArrayBuffer`, or a `DataView`'s declared range. */
388
441
  export type UuidByteInput = Uint8Array | ArrayBuffer | DataView;
389
442
  type AnyUuidForVersion<Version extends UuidVersion> = Uuid<Version, boolean, boolean>;
@@ -409,12 +462,8 @@ export type ParsedUuidResult<Input, WithCodec extends boolean = false> = Uuid<
409
462
  * implementations also normalize genuine `String` objects; TypeScript uses primitive strings.
410
463
  */
411
464
  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;
465
+ /** Reject branded masked slugs or bytes where no masking codec is available. */
466
+ export type KeylessUuidInput<Input> = UnmaskedUuidInput<RejectKnownInput<Input, MaskedUuidV7Slug>>;
418
467
  /** UUID text or the error returned while converting the captured input. */
419
468
  export type UuidStringResult<Input, Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE> =
420
469
  | PreserveUuidVersion<Input, UuidStringFor<Case>, UuidV4StringFor<Case>, UuidV7StringFor<Case>>
@@ -453,7 +502,7 @@ export interface UuidV7Generator {
453
502
  /** Payload layout emitted by this generator; pass it to UUIDv7 payload extraction. */
454
503
  readonly payloadLayout: UuidV7PayloadLayout;
455
504
  /** Generate an immutable UUIDv7 that remembers this generator's payload layout. */
456
- generateUuidV7Value(this: void, options?: undefined): Uuid<7, false, true> | UuidSlugError;
505
+ generateUuidV7Value(this: void): Uuid<7, false, true> | UuidSlugError;
457
506
  /** Generate with supplied time or masking options; only a supplied codec is retained. */
458
507
  generateUuidV7Value<const Options extends UuidV7GeneratorValueOptions | undefined>(
459
508
  this: void,
@@ -471,6 +520,19 @@ export interface UuidV7Generator {
471
520
  this: void,
472
521
  options: Omit<GenerateUuidV7Options<Case>, "generator">,
473
522
  ): UuidV7StringFor<Case> | UuidSlugError;
523
+ /** Forward a spelling preset or optional settings through this generator's sequence. */
524
+ generateUuidV7<
525
+ const Input extends
526
+ | UuidTextCase
527
+ | Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
528
+ | undefined,
529
+ >(
530
+ this: void,
531
+ textCaseOrOptions: UuidGenerationInput<
532
+ Input,
533
+ Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
534
+ >,
535
+ ): UuidV7StringFor<UuidGenerationTextCase<Input>> | UuidSlugError;
474
536
  /** Generate a new plain 16-byte `Uint8Array` for the current clock reading. */
475
537
  generateUuidV7Bytes(this: void): UuidV7Bytes | UuidSlugError;
476
538
  /**
@@ -495,6 +557,20 @@ export interface UuidV7Generator {
495
557
  this: void,
496
558
  options: Omit<GenerateUuidV7BytesIntoOptions<Output>, "generator">,
497
559
  ): UuidOutput<Output> | UuidSlugError;
560
+ /** Forward optional storage or settings, preserving caller-array types and sequence state. */
561
+ generateUuidV7Bytes<
562
+ const Input extends
563
+ | Uint8Array
564
+ | Omit<GenerateUuidV7BytesOptions, "generator">
565
+ | Omit<GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
566
+ | undefined,
567
+ >(
568
+ this: void,
569
+ outOrOptions: UuidGenerationInput<
570
+ Input,
571
+ Omit<GenerateUuidV7BytesOptions & GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
572
+ >,
573
+ ): UuidGenerationBytes<Input, UuidV7Bytes> | UuidSlugError;
498
574
  /**
499
575
  * Generate a plain UUIDv7 slug in this sequence. Lowercase base32hex preserves UUID byte order;
500
576
  * base64url does not preserve that order under text comparison.
@@ -523,7 +599,7 @@ export interface UuidV7Generator {
523
599
  ): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
524
600
  generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
525
601
  this: void,
526
- alphabet: SlugAlphabet,
602
+ alphabet: SlugAlphabet | undefined,
527
603
  textCase: Case,
528
604
  ): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
529
605
  /** Generate the pair at an explicit time or the current clock reading, in the selected spellings. */
@@ -531,6 +607,20 @@ export interface UuidV7Generator {
531
607
  this: void,
532
608
  options: Omit<GenerateUuidV7WithPlainSlugOptions<Case>, "generator">,
533
609
  ): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
610
+ /** Forward presets or optional settings through this sequence, retaining the UUID text case. */
611
+ generateUuidV7WithPlainSlug<
612
+ const Input extends
613
+ | SlugAlphabet
614
+ | UuidTextCase
615
+ | Omit<GenerateUuidV7WithPlainSlugOptions<UuidTextCase>, "generator">
616
+ | undefined,
617
+ >(
618
+ this: void,
619
+ alphabetOrCaseOrOptions: UuidGenerationInput<
620
+ Input,
621
+ Omit<GenerateUuidV7WithPlainSlugOptions<UuidTextCase>, "generator">
622
+ >,
623
+ ): GeneratedUuidV7<PlainUuidV7Slug, UuidGenerationTextCase<Input>> | UuidSlugError;
534
624
  }
535
625
 
536
626
  /**
@@ -792,7 +882,7 @@ export interface UuidSlugMigrationDecoder<
792
882
  uuidSlugToUuidString<Input extends string | UuidSlugError, Case extends UuidTextCase>(
793
883
  this: void,
794
884
  uuidSlug: SlugStringInput<Input>,
795
- format: Format,
885
+ format: Format | undefined,
796
886
  textCase: Case,
797
887
  ): UuidStringFor<Case> | UuidSlugError;
798
888
  /**
@@ -821,7 +911,7 @@ export interface UuidSlugMigrationDecoder<
821
911
  uuidSlugToUuidStringCandidates<Input extends string | UuidSlugError, Case extends UuidTextCase>(
822
912
  this: void,
823
913
  uuidSlug: SlugStringInput<Input>,
824
- format: Format,
914
+ format: Format | undefined,
825
915
  textCase: Case,
826
916
  ): readonly UuidStringFor<Case>[] | UuidSlugError;
827
917
  }
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 {