@anizoptera/uuid-slug 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (202) hide show
  1. package/LICENSE +54 -31
  2. package/README.md +373 -324
  3. package/dist/alphabet.d.ts +5 -17
  4. package/dist/alphabet.d.ts.map +1 -1
  5. package/dist/alphabet.js +146 -112
  6. package/dist/alphabet.js.map +1 -1
  7. package/dist/base64url-name.d.ts +7 -0
  8. package/dist/base64url-name.d.ts.map +1 -0
  9. package/dist/base64url-name.js +8 -0
  10. package/dist/base64url-name.js.map +1 -0
  11. package/dist/errors.d.ts +50 -9
  12. package/dist/errors.d.ts.map +1 -1
  13. package/dist/errors.js +145 -63
  14. package/dist/errors.js.map +1 -1
  15. package/dist/feistel.js +29 -95
  16. package/dist/feistel.js.map +1 -1
  17. package/dist/generation-options.js +20 -0
  18. package/dist/generation-options.js.map +1 -0
  19. package/dist/index.d.ts +22 -10
  20. package/dist/index.js +21 -9
  21. package/dist/instant.js +83 -0
  22. package/dist/instant.js.map +1 -0
  23. package/dist/mask-handle.d.ts +16 -0
  24. package/dist/mask-handle.d.ts.map +1 -0
  25. package/dist/mask-handle.js +60 -0
  26. package/dist/mask-handle.js.map +1 -0
  27. package/dist/mask.d.ts +27 -0
  28. package/dist/mask.d.ts.map +1 -0
  29. package/dist/mask.js +151 -95
  30. package/dist/mask.js.map +1 -1
  31. package/dist/masking-codec-protocol.js +23 -0
  32. package/dist/masking-codec-protocol.js.map +1 -0
  33. package/dist/masking-codec-types.d.ts +245 -0
  34. package/dist/masking-codec-types.d.ts.map +1 -0
  35. package/dist/masking-codec.d.ts +19 -0
  36. package/dist/masking-codec.d.ts.map +1 -0
  37. package/dist/masking-codec.js +391 -0
  38. package/dist/masking-codec.js.map +1 -0
  39. package/dist/migration.js +114 -51
  40. package/dist/migration.js.map +1 -1
  41. package/dist/node/runtime.js +39 -0
  42. package/dist/node/runtime.js.map +1 -0
  43. package/dist/payload.d.ts +7 -0
  44. package/dist/payload.d.ts.map +1 -0
  45. package/dist/payload.js +118 -0
  46. package/dist/payload.js.map +1 -0
  47. package/dist/runtime/pool.js +21 -46
  48. package/dist/runtime/pool.js.map +1 -1
  49. package/dist/runtime/portable.js +27 -0
  50. package/dist/runtime/portable.js.map +1 -0
  51. package/dist/sentinel.js +10 -0
  52. package/dist/sentinel.js.map +1 -0
  53. package/dist/siphash.js +20 -99
  54. package/dist/siphash.js.map +1 -1
  55. package/dist/slug.d.ts +169 -0
  56. package/dist/slug.d.ts.map +1 -0
  57. package/dist/slug.js +268 -0
  58. package/dist/slug.js.map +1 -0
  59. package/dist/timestamp.d.ts +19 -0
  60. package/dist/timestamp.d.ts.map +1 -0
  61. package/dist/timestamp.js +44 -0
  62. package/dist/timestamp.js.map +1 -0
  63. package/dist/types.d.ts +480 -200
  64. package/dist/types.d.ts.map +1 -1
  65. package/dist/types.js +8 -0
  66. package/dist/types.js.map +1 -0
  67. package/dist/uuid-value-protocol.js +46 -0
  68. package/dist/uuid-value-protocol.js.map +1 -0
  69. package/dist/uuid-value.d.ts +17 -0
  70. package/dist/uuid-value.d.ts.map +1 -0
  71. package/dist/uuid-value.js +127 -0
  72. package/dist/uuid-value.js.map +1 -0
  73. package/dist/uuid.d.ts +51 -64
  74. package/dist/uuid.d.ts.map +1 -1
  75. package/dist/uuid.js +203 -199
  76. package/dist/uuid.js.map +1 -1
  77. package/dist/v4-slug.d.ts +16 -0
  78. package/dist/v4-slug.d.ts.map +1 -0
  79. package/dist/v4-slug.js +16 -0
  80. package/dist/v4-slug.js.map +1 -0
  81. package/dist/v4.d.ts +42 -0
  82. package/dist/v4.d.ts.map +1 -0
  83. package/dist/v4.js +85 -0
  84. package/dist/v4.js.map +1 -0
  85. package/dist/v7-bounds.d.ts +36 -0
  86. package/dist/v7-bounds.d.ts.map +1 -0
  87. package/dist/v7-bounds.js +49 -0
  88. package/dist/v7-bounds.js.map +1 -0
  89. package/dist/v7-generator-input.js +75 -0
  90. package/dist/v7-generator-input.js.map +1 -0
  91. package/dist/v7-generator.d.ts +43 -0
  92. package/dist/v7-generator.d.ts.map +1 -0
  93. package/dist/v7-generator.js +105 -0
  94. package/dist/v7-generator.js.map +1 -0
  95. package/dist/v7-keyless.d.ts +46 -0
  96. package/dist/v7-keyless.d.ts.map +1 -0
  97. package/dist/v7-keyless.js +106 -0
  98. package/dist/v7-keyless.js.map +1 -0
  99. package/dist/v7-payload.js +54 -0
  100. package/dist/v7-payload.js.map +1 -0
  101. package/dist/v7-slug.d.ts +46 -0
  102. package/dist/v7-slug.d.ts.map +1 -0
  103. package/dist/v7-slug.js +127 -0
  104. package/dist/v7-slug.js.map +1 -0
  105. package/dist/v7-timestamp.js +9 -0
  106. package/dist/v7-timestamp.js.map +1 -0
  107. package/dist/v7-value-options.js +28 -0
  108. package/dist/v7-value-options.js.map +1 -0
  109. package/dist/v7-value.d.ts +23 -0
  110. package/dist/v7-value.d.ts.map +1 -0
  111. package/dist/v7-value.js +31 -0
  112. package/dist/v7-value.js.map +1 -0
  113. package/dist/v7.js +127 -171
  114. package/dist/v7.js.map +1 -1
  115. package/package.json +15 -8
  116. package/src/alphabet.ts +456 -27
  117. package/src/base64url-name.ts +5 -0
  118. package/src/errors.ts +373 -37
  119. package/src/feistel.ts +69 -56
  120. package/src/generation-options.ts +48 -0
  121. package/src/index.ts +134 -80
  122. package/src/instant.ts +196 -0
  123. package/src/keyless.ts +7 -134
  124. package/src/mask-handle.ts +141 -0
  125. package/src/mask.ts +354 -129
  126. package/src/masking-codec-protocol.ts +29 -0
  127. package/src/masking-codec-types.ts +380 -0
  128. package/src/masking-codec.ts +923 -0
  129. package/src/migration.ts +195 -42
  130. package/src/payload.ts +321 -0
  131. package/src/runtime/bun.ts +30 -49
  132. package/src/runtime/node.ts +43 -24
  133. package/src/runtime/pool.ts +49 -21
  134. package/src/runtime/portable.ts +68 -0
  135. package/src/runtime/types.ts +23 -35
  136. package/src/sentinel.ts +13 -0
  137. package/src/siphash.ts +5 -4
  138. package/src/slug.ts +884 -0
  139. package/src/timestamp.ts +122 -0
  140. package/src/types.ts +759 -205
  141. package/src/uuid-value-protocol.ts +77 -0
  142. package/src/uuid-value.ts +341 -0
  143. package/src/uuid.ts +514 -234
  144. package/src/v4-slug.ts +27 -0
  145. package/src/v4.ts +234 -0
  146. package/src/v7-bounds.ts +171 -0
  147. package/src/v7-generator-input.ts +169 -0
  148. package/src/v7-generator.ts +245 -0
  149. package/src/v7-keyless.ts +354 -0
  150. package/src/v7-payload.ts +121 -0
  151. package/src/v7-slug.ts +293 -0
  152. package/src/v7-timestamp.ts +21 -0
  153. package/src/v7-value-options.ts +62 -0
  154. package/src/v7-value.ts +54 -0
  155. package/src/v7.ts +377 -200
  156. package/dist/base64url.d.ts +0 -20
  157. package/dist/base64url.d.ts.map +0 -1
  158. package/dist/base64url.js +0 -33
  159. package/dist/base64url.js.map +0 -1
  160. package/dist/codec.d.ts +0 -17
  161. package/dist/codec.d.ts.map +0 -1
  162. package/dist/codec.js +0 -192
  163. package/dist/codec.js.map +0 -1
  164. package/dist/keyless.d.ts +0 -31
  165. package/dist/keyless.d.ts.map +0 -1
  166. package/dist/keyless.js +0 -93
  167. package/dist/keyless.js.map +0 -1
  168. package/dist/legacy-mask.js +0 -55
  169. package/dist/legacy-mask.js.map +0 -1
  170. package/dist/node/alphabet.js +0 -130
  171. package/dist/node/base64url.js +0 -31
  172. package/dist/node/codec.js +0 -190
  173. package/dist/node/errors.js +0 -78
  174. package/dist/node/feistel.js +0 -103
  175. package/dist/node/index.js +0 -10
  176. package/dist/node/keyless.js +0 -91
  177. package/dist/node/legacy-mask.js +0 -53
  178. package/dist/node/mask.js +0 -106
  179. package/dist/node/migration.js +0 -64
  180. package/dist/node/runtime/node.js +0 -33
  181. package/dist/node/runtime/pool.js +0 -53
  182. package/dist/node/schema.js +0 -214
  183. package/dist/node/siphash.js +0 -106
  184. package/dist/node/uuid.js +0 -226
  185. package/dist/node/v7.js +0 -185
  186. package/dist/node/yield.js +0 -20
  187. package/dist/runtime/web.js +0 -39
  188. package/dist/runtime/web.js.map +0 -1
  189. package/dist/schema.d.ts +0 -20
  190. package/dist/schema.d.ts.map +0 -1
  191. package/dist/schema.js +0 -216
  192. package/dist/schema.js.map +0 -1
  193. package/dist/v7.d.ts +0 -12
  194. package/dist/v7.d.ts.map +0 -1
  195. package/dist/yield.js +0 -22
  196. package/dist/yield.js.map +0 -1
  197. package/src/base64url.ts +0 -41
  198. package/src/codec.ts +0 -320
  199. package/src/legacy-mask.ts +0 -25
  200. package/src/runtime/web.ts +0 -48
  201. package/src/schema.ts +0 -300
  202. package/src/yield.ts +0 -22
package/dist/types.d.ts CHANGED
@@ -1,255 +1,535 @@
1
1
  // SPDX-License-Identifier: Apache-2.0
2
- // @anizoptera/uuid-slug 0.3.0 | https://github.com/Anizoptera/uuid-slug#readme
2
+ // @anizoptera/uuid-slug 0.5.0 | https://github.com/Anizoptera/uuid-slug#readme
3
3
  import { UuidSlugError } from "./errors.js";
4
- import { SlugAlphabet } from "./uuid.js";
4
+ import { SlugAlphabet } from "./slug.js";
5
+ import { UuidV7MaskingCodec, UuidV7MaskingCodecOptions, UuidV7MaskingCodecSharedOptions, UuidV7PreviousMask } from "./masking-codec-types.js";
5
6
  //#region src/types.d.ts
6
7
  declare const brand: unique symbol;
8
+ declare const uuidV7MaskBrand: unique symbol;
9
+ /** Select the standard lowercase UUID text spelling. */
10
+ export declare const UUID_TEXT_LOWERCASE = "lowercase";
11
+ /** Select the standard uppercase UUID text spelling. */
12
+ export declare const UUID_TEXT_UPPERCASE = "uppercase";
13
+ /** Keep emitting from the last UUID timestamp when the clock moves backward. */
14
+ export declare const UUID_V7_ROLLBACK_PRESERVE = "preserve";
15
+ /** Restart the sequence at the earlier clock reading after the configured tolerance. */
16
+ export declare const UUID_V7_ROLLBACK_RESET = "reset";
17
+ /** Return `invalid_timestamp` after the configured rollback tolerance. */
18
+ export declare const UUID_V7_ROLLBACK_ERROR = "error";
19
+ /** Select the hexadecimal letter case of UUID text output. JavaScript also accepts genuine `String` objects. */
20
+ export type UuidTextCase = typeof UUID_TEXT_LOWERCASE | typeof UUID_TEXT_UPPERCASE;
21
+ export type UuidTextCaseArguments<Case extends UuidTextCase> = typeof UUID_TEXT_LOWERCASE extends Case ? [textCase?: Case] : [textCase: Case];
22
+ type UuidTextCaseOptions<Case extends UuidTextCase> = typeof UUID_TEXT_LOWERCASE extends Case ? {
23
+ readonly textCase?: Case;
24
+ } : {
25
+ readonly textCase: Case;
26
+ };
27
+ /** The complete four-bit UUID version field, whether assigned or reserved. */
28
+ export type UuidVersion = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15;
29
+ /** UUID bits use the Apollo NCS layout. */
30
+ export declare const UUID_VARIANT_NCS = "ncs";
31
+ /** UUID bits use the RFC 9562 layout. */
32
+ export declare const UUID_VARIANT_RFC = "rfc";
33
+ /** UUID bits use the reserved Microsoft layout. */
34
+ export declare const UUID_VARIANT_MICROSOFT = "microsoft";
35
+ /** UUID bits use the reserved future layout. */
36
+ export declare const UUID_VARIANT_FUTURE = "future";
37
+ /** The layout family selected by the UUID variant bits. */
38
+ export type UuidVariant = typeof UUID_VARIANT_NCS | typeof UUID_VARIANT_RFC | typeof UUID_VARIANT_MICROSOFT | typeof UUID_VARIANT_FUTURE;
39
+ /** Choose how one created generator handles a clock reading below its accepted high-water mark. JavaScript also accepts a genuine `String` object for `action`. */
40
+ export type UuidV7ClockRollbackPolicy = {
41
+ readonly action: typeof UUID_V7_ROLLBACK_PRESERVE;
42
+ } | {
43
+ readonly action: typeof UUID_V7_ROLLBACK_RESET | typeof UUID_V7_ROLLBACK_ERROR;
44
+ /** Preserve the previous timestamp while total clock skew is at most this many milliseconds. */
45
+ readonly toleranceMs: number;
46
+ };
7
47
  /**
8
- * Nominal marker. The names ACCUMULATE as a key set rather than replacing one another, which is
9
- * what makes nesting work: `Brand<Brand<string, "A">, "B">` carries both keys, so it is assignable
10
- * to the "A" brand but not the reverse and not to a sibling "C".
11
- *
12
- * Writing the name as the property's TYPE instead — `{ [brand]?: Name }` — intersects to
13
- * `"A" & "B"`, i.e. `never`, on the second level. Every nested brand then has the same `never`
14
- * marker and they are all mutually assignable: measured 2026-08-12, `UuidV4Slug` and `UuidV7Slug`
15
- * were interchangeable, as were a plain slug and a masked one, for the entire life of the type.
16
- *
17
- * The property stays OPTIONAL so a string literal is still accepted wherever a brand is asked for.
18
- * These types separate values the package produces; they are not a parsing obligation on callers.
48
+ * Fill every requested byte synchronously or return `UuidSlugError`.
49
+ * The caller owns entropy quality; partial fills cannot be detected. Recognized package errors
50
+ * propagate unchanged. Thrown values and other Error values become `rng_unavailable` with a cause.
19
51
  */
20
- type Brand<T, Name extends string> = T & {
21
- readonly [brand]?: { [K in Name]: true; };
52
+ export type UuidRandomFill = (bytes: Uint8Array) => void | UuidSlugError;
53
+ /** Accumulate validated value kinds without changing their runtime representation. */
54
+ type Brand<Value, Name extends string> = Value & {
55
+ readonly [brand]: { [BrandName in Name]: true; };
22
56
  };
23
- type Base64UrlString = Brand<string, "Base64UrlString">;
24
- type UuidString = Brand<string, "UuidString">;
25
- type UuidV4String = Brand<UuidString, "UuidV4String">;
26
- type UuidV7String = Brand<UuidString, "UuidV7String">;
27
- /** Either alphabet — 22 base64url characters or 26 base32hex — so NOT a `Base64UrlString`. */
28
- type UuidSlug = Brand<string, "UuidSlug">;
29
- type UuidV4Slug = Brand<UuidSlug, "UuidV4Slug">;
30
- type UuidV7Slug = Brand<UuidSlug, "UuidV7Slug">;
31
- /** Masked slugs are base64url only, so this narrows where `UuidSlug` cannot. */
32
- type MaskedUuidSlug = Brand<Base64UrlString & UuidSlug, "MaskedUuidSlug">;
33
- type MaskedUuidV7Slug = Brand<MaskedUuidSlug, "MaskedUuidV7Slug">;
34
- type SentinelUuidV7Slug = Brand<UuidV7Slug, "SentinelUuidV7Slug">;
35
- type PublicUuidV7Slug = MaskedUuidV7Slug | SentinelUuidV7Slug;
36
- type UuidBytes = Brand<Uint8Array, "UuidBytes">;
37
- interface FreshValidationOptions {
38
- /** Finite Unix milliseconds; read once per validation. */
39
- now?: () => number;
40
- /** Finite, nonnegative radius around now, inclusive in both directions; default 24 hours. */
41
- windowMs?: number;
42
- }
43
- interface UuidV7Generator {
44
- uuidV7(this: void): UuidV7String;
45
- uuidV7Bytes(this: void, out?: Uint8Array, offset?: number): UuidSlugError | Uint8Array;
57
+ /** Valid mixed-case canonical, compact, URN, or brace-wrapped UUID text; this proves syntax only. */
58
+ export type UuidText = Brand<string, "UuidText">;
59
+ /** Valid UUIDv4 text with RFC variant bits, in any accepted spelling. */
60
+ export type UuidV4Text = Brand<UuidText, "UuidV4Text">;
61
+ /** Valid UUIDv7 text with RFC variant bits, in any accepted spelling. Its 74 payload bits have no inferred meaning. */
62
+ export type UuidV7Text = Brand<UuidText, "UuidV7Text">;
63
+ /** Canonical lowercase UUID text. This proves syntax only, not version or issuance. */
64
+ export type UuidString = Brand<UuidText, "UuidString">;
65
+ /** Standard uppercase UUID text. This proves syntax only, not version or issuance. */
66
+ export type UppercaseUuidString = Brand<UuidText, "UppercaseUuidString">;
67
+ /** UUID text inferred from its requested output case. */
68
+ export type UuidStringFor<Case extends UuidTextCase> = Case extends typeof UUID_TEXT_UPPERCASE ? UppercaseUuidString : UuidString;
69
+ /** Canonical lowercase UUIDv4 text with RFC variant bits. */
70
+ export type UuidV4String = Brand<UuidString & UuidV4Text, "UuidV4String">;
71
+ /** Uppercase UUIDv4 text with RFC variant bits. */
72
+ export type UppercaseUuidV4String = Brand<UppercaseUuidString & UuidV4Text, "UuidV4String">;
73
+ /** UUIDv4 text inferred from its requested output case. */
74
+ export type UuidV4StringFor<Case extends UuidTextCase> = Case extends typeof UUID_TEXT_UPPERCASE ? UppercaseUuidV4String : UuidV4String;
75
+ /** Canonical lowercase UUIDv7 text with RFC variant bits. */
76
+ export type UuidV7String = Brand<UuidString & UuidV7Text, "UuidV7String">;
77
+ /** Uppercase UUIDv7 text with RFC variant bits. */
78
+ export type UppercaseUuidV7String = Brand<UppercaseUuidString & UuidV7Text, "UuidV7String">;
79
+ /** UUIDv7 text inferred from its requested output case. */
80
+ export type UuidV7StringFor<Case extends UuidTextCase> = Case extends typeof UUID_TEXT_UPPERCASE ? UppercaseUuidV7String : UuidV7String;
81
+ /** A reversible plain UUID encoding: 22 base64url or 26 lowercase base32hex characters. */
82
+ export type PlainUuidSlug = Brand<string, "PlainUuidSlug">;
83
+ /** A plain slug whose decoded UUID is version 4 with the RFC variant. */
84
+ export type PlainUuidV4Slug = Brand<PlainUuidSlug, "PlainUuidV4Slug">;
85
+ /** A plain slug whose decoded UUID is version 7 with the RFC variant. */
86
+ export type PlainUuidV7Slug = Brand<PlainUuidSlug, "PlainUuidV7Slug">;
87
+ /** Carry a UUID version from immutable input; mutable bytes cannot prove their current version. */
88
+ export type PreserveUuidVersion<Input, UnknownVersion, Version4, Version7> = Input extends UuidSlugError ? never : Input extends Uuid<infer Version, boolean, boolean> ? Version extends 4 ? Version4 : Version extends 7 ? Version7 : UnknownVersion : Input extends UuidV4Text | PlainUuidV4Slug ? Version4 : Input extends UuidV7Text | PlainUuidV7Slug | MaskedUuidSlug ? Version7 : UnknownVersion;
89
+ /** Infer a version from immutable input; mutable bytes retain the complete version-field range. */
90
+ export type UuidVersionOf<Input> = Input extends UuidSlugError ? never : Input extends Uuid<infer Version, boolean, boolean> ? Version : Input extends UuidV4Text | PlainUuidV4Slug ? 4 : Input extends UuidV7Text | PlainUuidV7Slug | MaskedUuidSlug ? 7 : UuidVersion;
91
+ export type MaskingCodecUuidInput<Input> = Input extends PlainUuidV4Slug ? PlainUuidV4Slug | MaskedUuidV7Slug : Input;
92
+ /** A masked payload in either spelling; its check bits are not plain-encoding padding. */
93
+ type MaskedUuidSlug = Brand<string, "MaskedUuidSlug">;
94
+ /**
95
+ * A checked, keyed UUIDv7 payload: 22 base64url or 27 lowercase base32hex characters.
96
+ * Both spellings hide recognizable UUID field positions. The check detects wrong keys and
97
+ * malformed values; it does not prove issuance or authorization.
98
+ */
99
+ export type MaskedUuidV7Slug = Brand<MaskedUuidSlug, "MaskedUuidV7Slug">;
100
+ /** An application sentinel written as its ordinary 22- or 26-character plain UUIDv7 slug. */
101
+ export type SentinelUuidV7Slug = Brand<PlainUuidV7Slug, "SentinelUuidV7Slug">;
102
+ /** A masking result: either a masked UUIDv7 or a registered plain sentinel. */
103
+ export type MaskedOrSentinelUuidV7Slug = MaskedUuidV7Slug | SentinelUuidV7Slug;
104
+ /** One generated UUIDv7 in the selected text case and one selected slug made from the same bytes. */
105
+ export interface GeneratedUuidV7<Slug extends PlainUuidV7Slug | MaskedOrSentinelUuidV7Slug, Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE> {
106
+ /** UUIDv7 text in the requested case. */
107
+ readonly uuid: UuidV7StringFor<Case>;
108
+ /** Selected plain, masked, or sentinel spelling of the same UUID bytes. */
109
+ readonly slug: Slug;
110
+ }
111
+ /** Inclusive bounds that contain every UUIDv7 from the requested Unix-millisecond interval. */
112
+ export interface UuidV7Bounds<Value extends UuidV7StringFor<UuidTextCase> | UuidV7Bytes> {
113
+ /** Smallest RFC-variant UUIDv7 at the first requested millisecond. */
114
+ readonly startInclusive: Value;
115
+ /** Largest RFC-variant UUIDv7 at the last requested millisecond. */
116
+ readonly endInclusive: Value;
117
+ }
118
+ /** Describe the leading UUIDv7 payload fields that the caller already knows were encoded. */
119
+ export interface UuidV7PayloadLayout {
120
+ /** Number of leading `rand_a` bits holding an RFC 9562 Method 3 fraction; `0` means absent. */
121
+ readonly subMillisecondFractionBits: number;
122
+ /** Number of following bits holding an RFC 9562 Method 1 fixed counter; `0` means absent. */
123
+ readonly counterBits: number;
124
+ }
125
+ /** UUIDv7 payload decoded under a caller-supplied layout. */
126
+ export interface UuidV7Payload {
127
+ /** Standard 48-bit Unix millisecond timestamp. */
128
+ readonly unixMs: number;
129
+ /** Method 3 fraction bucket, or `undefined` when the layout assigns no fraction bits. */
130
+ readonly subMillisecondFraction: {
131
+ readonly value: number;
132
+ readonly bits: number;
133
+ } | undefined;
134
+ /** Method 1 counter, or `undefined` when the layout assigns no counter bits. */
135
+ readonly counter: {
136
+ readonly value: bigint;
137
+ readonly bits: number;
138
+ } | undefined;
139
+ /** Least-significant payload bits whose meaning the layout does not declare. */
140
+ readonly remaining: {
141
+ readonly value: bigint;
142
+ readonly bits: number;
143
+ };
144
+ }
145
+ /** Stable facts read from one immutable UUID without interpreting application-owned payload bits. */
146
+ export interface UuidInspection<Version extends UuidVersion = UuidVersion> {
147
+ /** Canonical lowercase UUID text. */
148
+ readonly uuid: UuidStringForVersion<Version, typeof UUID_TEXT_LOWERCASE>;
149
+ /** The complete four-bit version field, whether assigned or reserved. */
150
+ readonly version: Version;
151
+ /** The UUID layout family selected by the variant bits. */
152
+ readonly variant: UuidVariant;
153
+ /** Standard UUIDv7 Unix milliseconds, present only for an RFC-variant UUIDv7. */
154
+ readonly unixMs: number | undefined;
155
+ /** Whether every UUID bit is zero. */
156
+ readonly isNil: boolean;
157
+ /** Whether every UUID bit is one. */
158
+ readonly isMax: boolean;
159
+ }
160
+ /** Canonical UUID text narrowed when the parsed value proves version 4 or 7. */
161
+ export type UuidStringForVersion<Version, Case extends UuidTextCase> = Version extends 4 ? UuidV4StringFor<Case> : Version extends 7 ? UuidV7StringFor<Case> : UuidStringFor<Case>;
162
+ /** UUID bytes narrowed when the parsed value proves version 4 or 7. */
163
+ export type UuidBytesForVersion<Version> = Version extends 4 ? UuidV4Bytes : Version extends 7 ? UuidV7Bytes : UuidBytes;
164
+ /** Plain UUID slug narrowed when the parsed value proves version 4 or 7. */
165
+ export type PlainUuidSlugForVersion<Version> = Version extends 4 ? PlainUuidV4Slug : Version extends 7 ? PlainUuidV7Slug : PlainUuidSlug;
166
+ /** An immutable parsed UUID with optional preset masking and UUIDv7 payload-layout capabilities. */
167
+ export interface Uuid<Version extends UuidVersion = UuidVersion, HasMaskingCodec extends boolean = false, HasPayloadLayout extends boolean = false> {
168
+ /** Compile-time preset distinctions; no property is stored on the UUID. */
169
+ readonly [brand]?: {
170
+ readonly maskingCodec: [HasMaskingCodec] extends [true] ? true : boolean;
171
+ readonly payloadLayout: [HasPayloadLayout] extends [true] ? true : boolean;
172
+ };
173
+ /** The UUID version field. */
174
+ readonly version: Version;
175
+ /** Return stable UUID facts in one serializable record. */
176
+ inspect<Receiver extends AnyUuid>(this: Receiver): UuidInspection<Receiver["version"]>;
177
+ /** Return canonical UUID text, lowercase by default. */
178
+ toString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(this: Uuid<Version, boolean, boolean>, ...textCase: UuidTextCaseArguments<Case>): UuidStringForVersion<Version, Case>;
179
+ /** Convert a mixed-version receiver while retaining every version it proves. */
180
+ toString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE, Receiver extends AnyUuid = AnyUuid>(this: Receiver, ...textCase: UuidTextCaseArguments<Case>): UuidStringForVersion<Receiver["version"], Case>;
181
+ /** Return a new plain 16-byte UUID array. */
182
+ toBytes<Receiver extends AnyUuid>(this: Receiver): UuidBytesForVersion<Receiver["version"]>;
183
+ /** Write the UUID into caller-owned storage after validating the complete destination range. */
184
+ toBytes<Output extends Uint8Array>(this: AnyUuid, output: Output, outputOffset?: number): UuidOutput<Output> | UuidSlugError;
185
+ /** Return a plain UUID slug, using base64url by default. */
186
+ toPlainSlug<Receiver extends AnyUuid>(this: Receiver, alphabet?: SlugAlphabet): PlainUuidSlugForVersion<Receiver["version"]>;
187
+ /** Convert UUIDv7 with an explicit codec, including receivers with mixed preset capabilities. */
188
+ toMaskedSlug(this: Uuid<Version, boolean, boolean>, maskingCodec: 7 extends Version ? UuidV7MaskingCodec : never): MaskedOrSentinelUuidV7Slug | UuidSlugError;
46
189
  /**
47
- * Generate at a caller-supplied millisecond. A SEPARATE entry point rather than an optional
48
- * trailing parameter on the pair above, because an optional positional timestamp is silently
49
- * mappable: `Array.from({length: n}, gen.uuidV7Bytes)` would pass the index as the instant and
50
- * mint n ids dated 1970, with no type error. Taking the timestamp FIRST makes that impossible.
51
- *
52
- * Returns an Error rather than throwing on a bad instant: a caller-supplied value out of range
53
- * is ordinary input validation, not an exceptional condition.
190
+ * Return the masked UUIDv7 spelling using an explicit or preset masking codec.
191
+ * External codec callbacks receive isolated bytes; malformed results return `invalid_options`,
192
+ * and thrown exceptions remain available as the error's `cause`.
54
193
  */
55
- uuidV7At(this: void, timestamp: number): UuidSlugError | UuidV7String;
56
- uuidV7BytesAt(this: void, timestamp: number, out?: Uint8Array, offset?: number): UuidSlugError | Uint8Array;
194
+ toMaskedSlug(this: Uuid<Version, HasMaskingCodec, boolean>, ...codec: 7 extends Version ? [HasMaskingCodec] extends [true] ? readonly [maskingCodec?: UuidV7MaskingCodec] : readonly [maskingCodec: UuidV7MaskingCodec] : readonly [maskingCodec: never]): MaskedOrSentinelUuidV7Slug | UuidSlugError;
195
+ /** Interpret UUIDv7 with an explicit layout, including receivers with mixed preset capabilities. */
196
+ extractV7Payload(this: Uuid<Version, boolean, boolean>, payloadLayout: 7 extends Version ? UuidV7PayloadLayout : never): UuidV7Payload | UuidSlugError;
197
+ /** Decode UUIDv7 payload fields using an explicit or generated preset layout. */
198
+ extractV7Payload(this: Uuid<Version, boolean, HasPayloadLayout>, ...layout: 7 extends Version ? [HasPayloadLayout] extends [true] ? readonly [payloadLayout?: UuidV7PayloadLayout] : readonly [payloadLayout: UuidV7PayloadLayout] : readonly [payloadLayout: never]): UuidV7Payload | UuidSlugError;
199
+ /** Serialize as canonical lowercase UUID text; capabilities are process-local. */
200
+ toJSON<Receiver extends AnyUuid>(this: Receiver): UuidStringForVersion<Receiver["version"], typeof UUID_TEXT_LOWERCASE>;
57
201
  }
202
+ type RejectKnownInput<Input, Invalid> = [Extract<Exclude<Input, UuidSlugError>, Invalid>] extends [never] ? Input : never;
203
+ /** Reject a known slug; the operation parses UUID text. A bare string is validated at runtime. */
204
+ export type UuidStringInput<Input extends string | UuidSlugError> = RejectKnownInput<Input, PlainUuidSlug | MaskedUuidSlug>;
205
+ /** Reject known UUID text and masked slugs; only a plain slug decodes without a key. */
206
+ export type PlainUuidSlugInput<Input extends string | UuidSlugError> = RejectKnownInput<Input, UuidText | MaskedUuidSlug>;
207
+ /** Reject known UUID text; slug brands stay accepted because plain and masked spellings overlap. */
208
+ export type SlugStringInput<Input extends string | UuidSlugError> = RejectKnownInput<Input, UuidText>;
209
+ /** Reject known slugs and UUIDv4 text; the operation reads a UUIDv7 timestamp from text. */
210
+ export type UuidV7StringInput<Input extends string | UuidSlugError> = RejectKnownInput<Input, PlainUuidSlug | MaskedUuidSlug | UuidV4Text>;
211
+ /** Reject known UUID text, masked slugs, and UUIDv4 slugs; the operation needs a plain UUIDv7 slug. */
212
+ export type PlainUuidV7SlugInput<Input extends string | UuidSlugError> = RejectKnownInput<Input, UuidText | MaskedUuidSlug | PlainUuidV4Slug>;
213
+ /** Reject masked slugs and known UUIDv4 values across text and byte timestamp inputs. */
214
+ export type UuidV7TimestampInput<Input extends string | UuidByteInput | UuidSlugError> = RejectKnownInput<Input, MaskedUuidSlug | UuidV4Text | PlainUuidV4Slug | UuidV4Bytes>;
215
+ /** Reject known UUIDv4 bytes; the operation needs UUIDv7 bytes. */
216
+ export type UuidV7BytesInput<Input extends UuidByteInput | UuidSlugError> = RejectKnownInput<Input, UuidV4Bytes>;
217
+ /** Reject known non-v7 values; a masking codec accepts every UUIDv7 form. */
218
+ export type UuidV7ValueInput<Input extends UuidInput> = RejectKnownInput<Input, UuidV4Text | UuidV4Bytes | PlainUuidV4Slug | AnyUuidForVersion<Exclude<UuidVersion, 7>>>;
219
+ /** Exactly 16 validated UUID bytes. Package-owned values are plain `Uint8Array`. */
220
+ export type UuidBytes = Brand<Uint8Array, "UuidBytes">;
221
+ /** UUID bytes with version 4 and RFC variant bits. */
222
+ export type UuidV4Bytes = Brand<UuidBytes, "UuidV4Bytes">;
223
+ /** UUID bytes with version 7 and RFC variant bits. */
224
+ export type UuidV7Bytes = Brand<UuidBytes, "UuidV7Bytes">;
225
+ export type UuidOutput<Output extends Uint8Array> = Output extends UuidBytes ? Omit<Output, typeof brand> : Output;
226
+ /** A UUID byte source: a `Uint8Array`, a complete `ArrayBuffer`, or a `DataView`'s declared range. */
227
+ export type UuidByteInput = Uint8Array | ArrayBuffer | DataView;
228
+ type AnyUuidForVersion<Version extends UuidVersion> = Uuid<Version, boolean, boolean>;
229
+ type AnyUuid = AnyUuidForVersion<UuidVersion> | { [Version in UuidVersion]: AnyUuidForVersion<Version>; }[UuidVersion];
230
+ type UuidPreset<Input, Preset extends "maskingCodec" | "payloadLayout"> = Input extends AnyUuid ? NonNullable<Input[typeof brand]>[Preset] : false;
231
+ export type ParsedUuidResult<Input, WithCodec extends boolean = false> = Uuid<UuidVersionOf<WithCodec extends true ? MaskingCodecUuidInput<Input> : Input>, WithCodec extends true ? true : [UuidPreset<Exclude<Input, UuidSlugError>, "maskingCodec">] extends [true] ? true : false, [UuidPreset<Exclude<Input, UuidSlugError>, "payloadLayout">] extends [true] ? true : false>;
232
+ /**
233
+ * Any supported UUID text, byte, or slug input, plus a preceding package error. JavaScript
234
+ * implementations also normalize genuine `String` objects; TypeScript uses primitive strings.
235
+ */
236
+ export type UuidInput = string | UuidByteInput | AnyUuid | UuidSlugError;
237
+ /** Reject a branded masked slug where no masking codec is available. */
238
+ export type KeylessUuidInput<Input> = [Extract<Exclude<Input, UuidSlugError>, MaskedUuidV7Slug>] extends [never] ? Input : never;
239
+ /** UUID text or the error returned while converting the captured input. */
240
+ export type UuidStringResult<Input, Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE> = PreserveUuidVersion<Input, UuidStringFor<Case>, UuidV4StringFor<Case>, UuidV7StringFor<Case>> | UuidSlugError;
241
+ /** UUID bytes or the error returned while converting the captured input. */
242
+ export type UuidBytesResult<Input> = PreserveUuidVersion<Input, UuidBytes, UuidV4Bytes, UuidV7Bytes> | UuidSlugError;
243
+ /** A plain UUID slug or the error returned while converting the captured input. */
244
+ export type PlainUuidSlugResult<Input> = PreserveUuidVersion<Input, PlainUuidSlug, PlainUuidV4Slug, PlainUuidV7Slug> | UuidSlugError;
58
245
  /**
59
- * A schema is its mixing step, not the data behind one. Holding `mix` as a function rather than
60
- * exposing a permutation and an XOR table is what lets the masking code stay ignorant of which
61
- * scheme it is running: adding one is a new constructor in `schema.ts` and no branch anywhere.
62
- *
63
- * It is also the ONLY extension point, and deliberately so. This interface is public, so a caller
64
- * with a scheme of their own supplies it directly; the package ships no table-shaped constructor
65
- * beside it, because one would privilege a single foreign layout while being strictly less
66
- * capable than the function it wraps. `createUuidSlugCodec` smoke-tests supplied schemas; callers remain responsible for
67
- * invertibility across their full input domain.
246
+ * An inclusive timestamp window around `referenceUnixMs` or the current time.
247
+ * This checks clock plausibility, not expiry, authentication, replay, or issuance.
68
248
  */
69
- interface MaskSchema {
70
- readonly id: string;
249
+ export interface UuidV7TimestampWindow {
250
+ /** Maximum absolute difference from the reference time, inclusive. Must be finite and nonnegative. */
251
+ readonly maxTimestampDeltaMs: number;
71
252
  /**
72
- * Transforms 16 bytes; `forward: false` MUST be the exact inverse. `input` and `output` MUST
73
- * NOT be the same array: a scheme that permutes reads source bytes it would already have
74
- * overwritten, which corrupts silently rather than failing.
253
+ * Finite Unix milliseconds used as the reference.
254
+ *
255
+ * @defaultValue One `Date.now()` reading per validation call.
75
256
  */
76
- mix(input: Uint8Array, output: Uint8Array, forward: boolean): void;
257
+ readonly referenceUnixMs?: number;
77
258
  }
78
259
  /**
79
- * There is no scheme to choose. The check's width is fixed by arithmetic — a UUIDv7 carries 116
80
- * bits of content, so the encoding's remainder is the check — and the mixing step is the Feistel,
81
- * because the only alternative this package ever shipped left the timestamp legible: one output
82
- * byte per input byte meant 4 of 16 bytes held constant across a second, defeating the entire
83
- * point of masking. A caller who genuinely needs a different cipher passes a `MaskSchema`.
260
+ * A stateful UUIDv7 sequence using one clock and entropy source. Successful
261
+ * calls strictly increase in UUID byte order under the default preserve rollback policy, including
262
+ * calls with `at`. Methods may be detached. Expected clock
263
+ * and entropy failures return `UuidSlugError` without corrupting the next generation attempt.
84
264
  */
85
- interface MaskSchemaOptions {
86
- readonly id?: string;
265
+ export interface UuidV7Generator {
266
+ /** Payload layout emitted by this generator; pass it to UUIDv7 payload extraction. */
267
+ readonly payloadLayout: UuidV7PayloadLayout;
268
+ /** Generate an immutable UUIDv7 that remembers this generator's payload layout. */
269
+ generateUuidV7Value(this: void, options?: undefined): Uuid<7, false, true> | UuidSlugError;
270
+ /** Generate with supplied time or masking options; only a supplied codec is retained. */
271
+ generateUuidV7Value<const Options extends UuidV7GeneratorValueOptions | undefined>(this: void, options: Options): Uuid<7, Options extends {
272
+ readonly maskingCodec: UuidV7MaskingCodec;
273
+ } ? true : false, true> | UuidSlugError;
274
+ /** Generate UUIDv7 text for the current clock reading in the selected case, lowercase by default. */
275
+ generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(this: void, ...textCase: UuidTextCaseArguments<Case>): UuidV7StringFor<Case> | UuidSlugError;
276
+ /** Generate UUIDv7 text at an explicit time or the current clock reading. */
277
+ generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(this: void, options: Omit<GenerateUuidV7Options<Case>, "generator">): UuidV7StringFor<Case> | UuidSlugError;
278
+ /** Generate a new plain 16-byte `Uint8Array` for the current clock reading. */
279
+ generateUuidV7Bytes(this: void): UuidV7Bytes | UuidSlugError;
87
280
  /**
88
- * Generate a secret, for example with `openssl rand -base64 32`, and keep it outside source
89
- * control. At least 16 bytes are required; strings are UTF-8 encoded. A known UUID/slug pair
90
- * permits offline guesses, so length alone is not protection. Preserve old seeds for decoding
91
- * issued slugs; rotate by retaining their schema settings in `previousMasks`.
281
+ * Write 16 bytes only after success and return the exact supplied array.
282
+ *
283
+ * @param output - Caller-owned array that receives the 16 UUID bytes.
284
+ * @param outputOffset - Zero-based index where writing starts. Omit to start at index 0. Bytes
285
+ * outside the written range stay unchanged.
92
286
  */
93
- readonly seed: string | Uint8Array;
287
+ generateUuidV7Bytes<Output extends Uint8Array>(this: void, output: Output, outputOffset?: number): UuidOutput<Output> | UuidSlugError;
288
+ /** Generate package-owned UUIDv7 bytes at an explicit time or the current clock reading. */
289
+ generateUuidV7Bytes(this: void, options: Omit<GenerateUuidV7BytesOptions, "generator">): UuidV7Bytes | UuidSlugError;
290
+ /** Write UUIDv7 bytes at an explicit time or the current clock reading into caller-owned storage. */
291
+ generateUuidV7Bytes<Output extends Uint8Array>(this: void, options: Omit<GenerateUuidV7BytesIntoOptions<Output>, "generator">): UuidOutput<Output> | UuidSlugError;
94
292
  /**
95
- * Work factor for turning the seed into key material, default 1 — the cheapest setting, chosen so
96
- * that codec construction does only the requested work. Higher counts add construction and
97
- * seed-guessing cost; they are paid when the schema is built, never per id.
293
+ * Generate a plain UUIDv7 slug in this sequence. Lowercase base32hex preserves UUID byte order;
294
+ * base64url does not preserve that order under text comparison.
98
295
  *
99
- * WIRE-FORMAT-BEARING, exactly as `seed` is: a different count derives different keys, so every
100
- * masked slug issued under the old count stops decoding. Rotate it the way a seed is rotated —
101
- * the new setting in `mask`, the old one kept in `previousMasks` — never by editing in place.
296
+ * @param alphabetOrOptions - Output spelling, or an explicit time with that spelling. Omit for
297
+ * the shorter 22-character base64url form at the current clock reading.
102
298
  */
103
- readonly keyIterations?: number;
299
+ generatePlainUuidV7Slug(this: void, alphabetOrOptions?: SlugAlphabet | Omit<GeneratePlainUuidV7SlugOptions, "generator">): PlainUuidV7Slug | UuidSlugError;
300
+ /**
301
+ * Generate UUIDv7 text and a plain slug for the same UUID in this sequence.
302
+ *
303
+ * @param alphabet - Slug spelling. Omit for the shorter 22-character base64url form.
304
+ * @param textCase - UUID text spelling. Pass it alone to keep the default slug alphabet.
305
+ * @returns UUID text plus one slug in the selected alphabet, or `UuidSlugError` when generation fails.
306
+ */
307
+ generateUuidV7WithPlainSlug(this: void, alphabet?: SlugAlphabet): GeneratedUuidV7<PlainUuidV7Slug> | UuidSlugError;
308
+ generateUuidV7WithPlainSlug<Case extends UuidTextCase>(this: void, textCase: Case): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
309
+ generateUuidV7WithPlainSlug<Case extends UuidTextCase>(this: void, alphabet: SlugAlphabet, textCase: Case): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
310
+ /** Generate the pair at an explicit time or the current clock reading, in the selected spellings. */
311
+ generateUuidV7WithPlainSlug<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(this: void, options: Omit<GenerateUuidV7WithPlainSlugOptions<Case>, "generator">): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
104
312
  }
105
- /** The synchronous seed options plus cooperative cancellation; no scheduling knobs are required. */
106
- interface AsyncMaskSchemaOptions extends MaskSchemaOptions {
107
- readonly signal?: AbortSignal;
313
+ /**
314
+ * A standard host instant; generation uses every sub-millisecond fraction bit its layout provides.
315
+ * JavaScript also accepts genuine `String` objects for zoned timestamp text.
316
+ */
317
+ export type UuidV7Instant = number | bigint | string | Date | {
318
+ readonly epochMilliseconds: number | bigint;
319
+ } | {
320
+ readonly epochNanoseconds: bigint;
321
+ } | {
322
+ readonly seconds: number | bigint;
323
+ readonly nanoseconds?: number | bigint;
324
+ };
325
+ /** Select an explicit time and UUID text spelling for one UUIDv7. */
326
+ export type GenerateUuidV7Options<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE> = {
327
+ /** Time to encode. A created generator joins its sequence; a module call stays independent. */
328
+ readonly at?: UuidV7Instant;
329
+ /** Generator that supplies entropy, payload layout, and sequence policy. */
330
+ readonly generator?: UuidV7Generator;
331
+ /** UUID text spelling. Omit for lowercase. */
332
+ readonly textCase?: Case;
333
+ } & UuidTextCaseOptions<Case>;
334
+ /** Select an explicit time and alphabet for one plain UUIDv7 slug. */
335
+ export interface GeneratePlainUuidV7SlugOptions {
336
+ /** Time to encode. A selected generator may advance it to preserve its sequence. */
337
+ readonly at?: UuidV7Instant;
338
+ /** Slug spelling. Omit for the shorter base64url form. */
339
+ readonly alphabet?: SlugAlphabet;
340
+ /** Generator that supplies entropy, payload layout, and sequence policy. */
341
+ readonly generator?: UuidV7Generator;
108
342
  }
109
- interface UuidV7SentinelDefinition {
110
- readonly name: string;
111
- readonly uuid: UuidV7String;
343
+ /** Select an explicit time for package-owned UUIDv7 bytes. */
344
+ export interface GenerateUuidV7BytesOptions {
345
+ /** Time to encode. A created generator joins its sequence; a module call stays independent. */
346
+ readonly at?: UuidV7Instant;
347
+ /** Generator that supplies entropy, payload layout, and sequence policy. */
348
+ readonly generator?: UuidV7Generator;
349
+ readonly output?: never;
350
+ readonly outputOffset?: never;
112
351
  }
113
- interface UuidV7Sentinel {
114
- readonly name: string;
115
- readonly slug: SentinelUuidV7Slug;
116
- readonly uuid: UuidV7String;
352
+ /** Select an explicit time and caller-owned storage for UUIDv7 bytes. */
353
+ export interface GenerateUuidV7BytesIntoOptions<Output extends Uint8Array> {
354
+ /** Time to encode. A created generator joins its sequence; a module call stays independent. */
355
+ readonly at?: UuidV7Instant;
356
+ /** Generator that supplies entropy, payload layout, and sequence policy. */
357
+ readonly generator?: UuidV7Generator;
358
+ /** Caller-owned array that receives the 16 UUID bytes after successful generation. */
359
+ readonly output: Output;
360
+ /** Zero-based index where writing starts. Omit to start at index 0. */
361
+ readonly outputOffset?: number;
117
362
  }
118
- /** Select a known encoding instead of guessing from overlapping slug text. */
119
- type MigrationFormat = "current" | "original" | "plain";
120
- /** Enable only formats your application has issued; writers keep using the codec. */
121
- interface UuidSlugMigrationOptions {
122
- readonly original?: boolean;
123
- readonly plain?: boolean;
363
+ /** Select time and both spellings for one UUIDv7 text-and-plain-slug pair. */
364
+ export type GenerateUuidV7WithPlainSlugOptions<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE> = {
365
+ /** Time to encode. A selected generator may advance it to preserve its sequence. */
366
+ readonly at?: UuidV7Instant;
367
+ /** Slug spelling. Omit for the shorter base64url form. */
368
+ readonly alphabet?: SlugAlphabet;
369
+ /** Generator that supplies entropy, payload layout, and sequence policy. */
370
+ readonly generator?: UuidV7Generator;
371
+ /** UUID text spelling. Omit for lowercase. */
372
+ readonly textCase?: Case;
373
+ } & UuidTextCaseOptions<Case>;
374
+ /** Select optional state for immutable UUIDv7 generation through a generator. */
375
+ export interface UuidV7GeneratorValueOptions {
376
+ /** Time to encode through this generator's sequence state. */
377
+ readonly at?: UuidV7Instant;
378
+ /** Masking codec retained by the generated UUID for later masked conversion. */
379
+ readonly maskingCodec?: UuidV7MaskingCodec;
124
380
  }
125
- interface UuidSlugMigration {
126
- /** Return the first candidate: sentinel, current keys, original mask, then plain UUID. */
127
- decode(this: void, slug: string, format?: MigrationFormat): UuidSlugError | UuidString;
128
- /** Return distinct candidates for one application lookup; an empty array means no match. */
129
- candidates(this: void, slug: string, format?: MigrationFormat): UuidSlugError | UuidString[];
381
+ /** Select independent owners and time for top-level immutable UUIDv7 generation. */
382
+ export interface UuidV7ValueOptions extends UuidV7GeneratorValueOptions {
383
+ /** Generator that supplies entropy, sequence policy, and the retained payload layout. */
384
+ readonly generator?: UuidV7Generator;
130
385
  }
131
- interface UuidSlugCodecOptions {
386
+ /** Select optional generation state when a masking codec is already preset. */
387
+ export interface UuidV7MaskingCodecValueOptions {
388
+ /** Time to encode. A selected generator may advance it to preserve its sequence. */
389
+ readonly at?: UuidV7Instant;
390
+ /** Generator that supplies entropy, sequence policy, and the retained payload layout. */
132
391
  readonly generator?: UuidV7Generator;
392
+ }
393
+ /** Select generation state and UUID text spelling for one masked UUIDv7 pair. */
394
+ export type GenerateUuidV7WithMaskedSlugOptions<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE> = UuidV7MaskingCodecValueOptions & {
395
+ /** UUID text spelling. Omit for lowercase. */
396
+ readonly textCase?: Case;
397
+ } & UuidTextCaseOptions<Case>;
398
+ /** An immutable handle for masking the recognizable fields of a UUIDv7; key material is not exposed. */
399
+ export interface UuidV7Mask {
400
+ /** Diagnostic label only; mask objects and caller order select decoding behavior. */
401
+ readonly diagnosticLabel: string;
402
+ readonly [uuidV7MaskBrand]: true;
403
+ }
404
+ /** Define a reversible 16-byte transform for `createCustomUuidV7Mask`. */
405
+ export interface CustomUuidV7MaskOptions {
133
406
  /**
134
- * Also decode plain, unmasked slugs when no schema matches — the migration path for ids issued
135
- * before masking existed. Its own option rather than a field beside the key list, because the
136
- * two answer different questions and share only the accident of both concerning the past.
137
- *
138
- * Turn it off once the migration ends. It costs one wrong answer per 2^checkBits: a direct slug
139
- * that happens to satisfy a mask's check decodes as that mask instead, and both are the same 22
140
- * characters of the same alphabet, so nothing else can tell them apart.
407
+ * Names this mask in the error returned when a callback fails after construction, which is why
408
+ * it is required here and optional for seeded masks, whose transform cannot fail. It does not
409
+ * select the mask during decoding. JavaScript also accepts a genuine `String` object.
141
410
  */
142
- readonly acceptUnmaskedSlugs?: boolean;
411
+ readonly diagnosticLabel: string;
412
+ /** Transform an isolated 16-byte array; return exactly 16 bytes or `UuidSlugError`. */
413
+ readonly mask: (bytes: Uint8Array) => Uint8Array | UuidSlugError;
414
+ /** Invert `mask` for every possible 16-byte input. */
415
+ readonly unmask: (bytes: Uint8Array) => Uint8Array | UuidSlugError;
416
+ }
417
+ /**
418
+ * Options for deriving an immutable UUIDv7 mask from stable secret key material. Keep the seed and
419
+ * iteration count available while identifiers produced with this mask must remain readable.
420
+ */
421
+ export interface UuidV7MaskOptions {
143
422
  /**
144
- * Schemas to try after `mask`, in the order given — how a seed is rotated. Takes a seed exactly
145
- * as `mask` does: a rotated seed is the ordinary reason this list exists, and requiring a
146
- * pre-built schema for it cost the commonest case a constructor and an error branch that naming
147
- * the current seed never needed. Named for rotation rather than for legacy, because a previous
148
- * key is not a different kind of thing from the current one — rotation is only a change of
149
- * position between this list and `mask`.
423
+ * Diagnostic label only; decoding uses the mask object and caller-specified order. JavaScript
424
+ * also accepts a genuine `String` object.
150
425
  *
151
- * Keep it short. Each entry is tried in turn, so the codec's wrong-answer rate is the sum over
152
- * the whole list.
426
+ * @defaultValue `"seeded"`
153
427
  */
154
- readonly previousMasks?: readonly (MaskSchema | MaskSchemaOptions)[];
428
+ readonly diagnosticLabel?: string;
155
429
  /**
156
- * The schema that ENCODES, and the first tried when decoding. Kept separate from the list above
157
- * rather than folded into one ordered array: in a single list the encoding schema is whichever
158
- * happens to be first, so appending a rotated seed leaves you still issuing ids under the old
159
- * one while believing you rotated. Nothing about that failure is visible.
160
- *
161
- * OPTIONAL, and omitting it is the one choice here with a security consequence: the codec then
162
- * masks under `DEFAULT_MASK_SCHEMA`, whose seed is a string literal in this published package,
163
- * so its masked slugs are readable by anyone who installed it. Supply `{ seed }` — any stable
164
- * string you keep out of the repository — for masking to obfuscate anything at all.
430
+ * Stable secret key material. Generate at least 16 bytes, keep it outside source control, and
431
+ * retain old values in `previousMasks`; a known UUID/slug pair permits offline guesses.
432
+ * JavaScript also accepts a genuine `String` object.
165
433
  */
166
- readonly mask?: MaskSchema | MaskSchemaOptions;
167
- readonly sentinels?: readonly UuidV7SentinelDefinition[];
434
+ readonly seed: string | Uint8Array;
168
435
  /**
169
- * Alphabet for PLAIN slugs from `uuidV4Slug` and `uuidV7Slug`. `"base32hex"` costs four characters
170
- * (26 rather than 22) and buys chronological sort order: its characters are in ASCII order and a
171
- * UUIDv7's leading bytes are its timestamp, so base32hex slugs sort by creation time as plain
172
- * strings. base64url's alphabet cannot — it runs `A-Za-z0-9-_`, so its character order and its
173
- * value order disagree. Being alphanumeric also spares base32hex the `-` and `_` that make a
174
- * base64url slug awkward to select by double-click.
175
- *
176
- * Codec-level rather than per call so a system cannot mint half its ids in each spelling.
177
- * Decoding takes no such option: the two lengths are disjoint, so `slugToUuid` reads both and a
178
- * change of alphabet leaves every previously issued slug working.
436
+ * Key-derivation work factor in `1..16777216` (2^24), paid at mask construction rather than per ID.
437
+ * Changing it changes every derived key, so retain the old seed and count in `previousMasks`
438
+ * when identifiers issued under them must remain readable.
179
439
  *
180
- * It does NOT reach masked slugs or sentinels, which stay base64url. Masked bytes are ciphertext
181
- * and sort in no useful order, and a sentinel is matched against masked input, so a sentinel in a
182
- * different alphabet could never be recognised there.
440
+ * @defaultValue `1`
441
+ */
442
+ readonly keyDerivationIterations?: number;
443
+ }
444
+ /** Mask derivation options with cooperative cancellation for expensive construction. */
445
+ export interface AsyncUuidV7MaskOptions extends UuidV7MaskOptions {
446
+ /**
447
+ * Stop cooperative derivation and return an `aborted` error with `reason` as its cause.
183
448
  *
184
- * Costs throughput when set: `uuidV7Slug` can no longer use a runtime's native base64url slug
185
- * generator and falls back to generating bytes and encoding them.
449
+ * @defaultValue No cancellation.
186
450
  */
187
- readonly slugAlphabet?: SlugAlphabet;
451
+ readonly signal?: AbortSignal;
188
452
  }
189
- /**
190
- * Only what depends on the codec's own state: the generator it draws from, and the mask schema
191
- * plus sentinels it was built with.
192
- *
193
- * The plain conversions (`uuidToSlug`, `parseUuid`, `formatUuidSlug`, …) are module-level
194
- * functions and deliberately absent here. They are pure — the same input gives the same output
195
- * whatever seed the codec holds — so carrying them as methods implied a dependency on the seed
196
- * that does not exist, and was the single most misleading thing about the previous shape.
197
- *
198
- * Extending `UuidV7Generator` makes the compiler require forwarding every generator method.
199
- */
200
- interface UuidSlugCodec extends UuidV7Generator {
201
- readonly sentinels: readonly UuidV7Sentinel[];
202
- /** Create an opt-in reader without changing generation or ordinary codec decoding. */
203
- migration(this: void, options?: UuidSlugMigrationOptions): UuidSlugMigration;
453
+ /** Define a named UUIDv7 that must bypass masking. */
454
+ export interface UuidV7SentinelConfig {
455
+ /** Nonempty application-facing name, unique within one masking codec. JavaScript also accepts a genuine `String` object. */
456
+ readonly name: string;
204
457
  /**
205
- * `this: void` lets callers detach methods without `.bind`; implementations cannot rely on `this`.
458
+ * UUIDv7 text in an accepted spelling, unique after normalization. Sentinels bypass
459
+ * masking, so their timestamps may lie outside the codec's configured range.
206
460
  */
207
- uuidV4(this: void): UuidV4String;
208
- uuidV4Bytes(this: void, out?: Uint8Array, offset?: number): UuidSlugError | Uint8Array;
209
- uuidV4Slug(this: void): UuidV4Slug;
210
- uuidV7Slug(this: void): UuidV7Slug;
211
- uuidV7MaskedSlug(this: void): PublicUuidV7Slug;
461
+ readonly uuid: string;
462
+ }
463
+ /** A validated sentinel and its ordinary plain slug in the masking codec's masked-slug alphabet. */
464
+ export interface UuidV7Sentinel {
465
+ /** The definition's application-facing name. */
466
+ readonly name: string;
467
+ /** The reserved raw slug; it is not a masked payload. */
468
+ readonly slug: SentinelUuidV7Slug;
469
+ /** The canonical UUIDv7 represented by `slug`. */
470
+ readonly uuid: UuidV7String;
471
+ }
472
+ /** Select decoding with the codec's seeded mask. */
473
+ export declare const SEEDED_MASK_FORMAT = "seeded-mask";
474
+ /** Select decoding with the opt-in fixed mask. */
475
+ export declare const FIXED_MASK_FORMAT = "fixed-mask";
476
+ /** Select decoding as an opt-in plain UUID slug. */
477
+ export declare const PLAIN_SLUG_FORMAT = "plain-slug";
478
+ /** Select one enabled migration format when the input's original encoding is known. */
479
+ export type UuidSlugMigrationFormat = typeof SEEDED_MASK_FORMAT | typeof FIXED_MASK_FORMAT | typeof PLAIN_SLUG_FORMAT;
480
+ /** Enable only formats your application has issued; writers keep using the codec. */
481
+ export interface UuidSlugMigrationOptions {
212
482
  /**
213
- * Masking is UUIDv7-only, and the reason is that the whole format is spent. The check rides in
214
- * bits a v7 provably wastes — its constant version and variant, and the timestamp's top six —
215
- * plus whatever the encoding has left over. Another version would have to store its real
216
- * version and its full timestamp somewhere, and there is no somewhere: every one of the 132
217
- * bits in 22 characters already has a job. Supporting all versions would cost a 23rd character
218
- * on every masked slug forever, to hide a creation time only v7 discloses.
483
+ * Accept the fixed-key format with a four-bit check that predates seeded masking, from before
484
+ * package 0.2.0. Releases from 0.2.0 on write different formats, so enable it only for slugs
485
+ * issued under that earlier scheme.
486
+ *
487
+ * @defaultValue `false`
219
488
  */
220
- uuidV7ToMaskedSlug(this: void, uuid: string): UuidSlugError | PublicUuidV7Slug;
221
- maskedSlugToUuidV7(this: void, slug: string): UuidSlugError | UuidV7String;
489
+ readonly acceptFixedMask?: boolean;
222
490
  /**
223
- * Decodes to whatever version comes out, where `maskedSlugToUuidV7` insists on v7.
491
+ * Accept plain UUID slugs of any version, including retained trailing-bit aliases.
224
492
  *
225
- * NOT a redundant widening of that method, which is what it looks like: with
226
- * `acceptUnmaskedSlugs` enabled a slug that matches no schema is tried as a plain unmasked
227
- * slug, and a system migrating off unmasked ids may well have UUIDv4 ones. Those decode here
228
- * and are rejected by the v7 form. Deleting this on the assumption it was a duplicate was
229
- * measured to break exactly that migration path.
493
+ * @defaultValue `false`
230
494
  */
231
- maskedSlugToUuid(this: void, slug: string): UuidSlugError | UuidString;
495
+ readonly acceptPlainSlug?: boolean;
496
+ }
497
+ type EnabledMigrationOption<Options, Option extends keyof UuidSlugMigrationOptions> = Option extends keyof Options ? (true extends Options[Option] ? Option : never) : never;
498
+ /** Project enabled options into the only format selectors that decoder can accept. */
499
+ export type EnabledMigrationFormat<Options extends UuidSlugMigrationOptions> = typeof SEEDED_MASK_FORMAT | (EnabledMigrationOption<Options, "acceptFixedMask"> extends never ? never : typeof FIXED_MASK_FORMAT) | (EnabledMigrationOption<Options, "acceptPlainSlug"> extends never ? never : typeof PLAIN_SLUG_FORMAT);
500
+ /**
501
+ * Decode current and explicitly enabled old formats without changing masking-codec output.
502
+ * Methods may be detached. A successful decode identifies a candidate UUID, not the issuing format
503
+ * or a stored record. A preceding `UuidSlugError` is returned unchanged. JavaScript callers may
504
+ * pass genuine `String` objects; TypeScript uses primitive strings.
505
+ */
506
+ export interface UuidSlugMigrationDecoder<in Format extends UuidSlugMigrationFormat = UuidSlugMigrationFormat> {
232
507
  /**
233
- * `maskedSlugToUuidV7` plus the freshness rules of `validateUuidV7Fresh`, returning the slug.
508
+ * Return the first candidate in this order: sentinel, seeded masks, fixed mask, plain slug.
509
+ * Pass `format` when its origin is known to avoid trying unrelated readers.
234
510
  *
235
- * Lives on the codec because unmasking needs the codec's key. Its module-level predecessor
236
- * `validateMaskedUuidV7SlugFresh` did not: it reached for `defaultCodec`, whose seed is
237
- * published in this package's source, so it answered under the wrong key for every caller who
238
- * supplied their own and returned a confident Error for valid slugs. There is no keyless
239
- * counterpart to this for the same reason; `validateUuidV7SlugFresh` stays module-level because
240
- * a PLAIN slug decodes without one.
511
+ * @param uuidSlug - Identifier accepted by one enabled migration reader.
512
+ * @param format - Known source format. Omit to try enabled readers in documented order. JavaScript also accepts a genuine `String` object.
513
+ * @param textCase - UUID text spelling. Pass it after `uuidSlug` when format is unknown, or after a
514
+ * known format. Omit for lowercase.
515
+ */
516
+ uuidSlugToUuidString<Input extends string | UuidSlugError, Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(this: void, uuidSlug: SlugStringInput<Input>, ...textCase: UuidTextCaseArguments<Case>): UuidStringFor<Case> | UuidSlugError;
517
+ uuidSlugToUuidString<Input extends string | UuidSlugError>(this: void, uuidSlug: SlugStringInput<Input>, format: Format | undefined): UuidString | UuidSlugError;
518
+ uuidSlugToUuidString<Input extends string | UuidSlugError, Case extends UuidTextCase>(this: void, uuidSlug: SlugStringInput<Input>, format: Format, textCase: Case): UuidStringFor<Case> | UuidSlugError;
519
+ /**
520
+ * Return every distinct candidate in decode order for one application lookup. An empty array
521
+ * means no enabled format matched; callback failure returns `UuidSlugError`, not a partial list.
522
+ * A preceding `UuidSlugError` is returned unchanged.
241
523
  *
242
- * Returns the slug it was GIVEN, at the type it was given, which is the only type that is true
243
- * of it. Declaring `MaskedUuidV7Slug` was a lie the compiler could not catch: that brand is
244
- * `Base64UrlString & UuidSlug`, but with `acceptUnmaskedSlugs` the decode falls through to
245
- * `slugToUuid`, which accepts 26-character base32hex too — so a base32hex slug came back typed as
246
- * base64url and `isBase64Url` on it was false. Narrowing the fallback to base64url would have
247
- * been the wrong repair: a codec built with `slugAlphabet: "base32hex"` has exactly those legacy
248
- * ids, and refusing them breaks the migration this flag exists for. The behaviour is right; the
249
- * claim about it was not.
524
+ * @param uuidSlug - Identifier accepted by one or more enabled migration readers.
525
+ * @param format - Known source format. Omit to try enabled readers in documented order. JavaScript also accepts a genuine `String` object.
526
+ * @param textCase - UUID text spelling. Pass it after `uuidSlug` when format is unknown, or after a
527
+ * known format. Omit for lowercase.
250
528
  */
251
- validateMaskedSlugFresh<S extends string>(this: void, slug: S, freshness?: FreshValidationOptions): UuidSlugError | S;
529
+ uuidSlugToUuidStringCandidates<Input extends string | UuidSlugError, Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(this: void, uuidSlug: SlugStringInput<Input>, ...textCase: UuidTextCaseArguments<Case>): readonly UuidStringFor<Case>[] | UuidSlugError;
530
+ uuidSlugToUuidStringCandidates<Input extends string | UuidSlugError>(this: void, uuidSlug: SlugStringInput<Input>, format: Format | undefined): readonly UuidString[] | UuidSlugError;
531
+ uuidSlugToUuidStringCandidates<Input extends string | UuidSlugError, Case extends UuidTextCase>(this: void, uuidSlug: SlugStringInput<Input>, format: Format, textCase: Case): readonly UuidStringFor<Case>[] | UuidSlugError;
252
532
  }
253
533
  //#endregion
254
- export { AsyncMaskSchemaOptions, Base64UrlString, Brand, FreshValidationOptions, MaskSchema, MaskSchemaOptions, MaskedUuidSlug, MaskedUuidV7Slug, MigrationFormat, PublicUuidV7Slug, SentinelUuidV7Slug, UuidBytes, UuidSlug, UuidSlugCodec, UuidSlugCodecOptions, UuidSlugMigration, UuidSlugMigrationOptions, UuidString, UuidV4Slug, UuidV4String, UuidV7Generator, UuidV7Sentinel, UuidV7SentinelDefinition, UuidV7Slug, UuidV7String };
534
+ export type { UuidV7MaskingCodec, UuidV7MaskingCodecOptions, UuidV7PreviousMask };
255
535
  //# sourceMappingURL=types.d.ts.map