@anizoptera/uuid-slug 0.2.0 → 0.4.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 (163) hide show
  1. package/LICENSE +54 -31
  2. package/README.md +1175 -30
  3. package/dist/alphabet.d.ts +9 -0
  4. package/dist/alphabet.d.ts.map +1 -0
  5. package/dist/alphabet.js +166 -0
  6. package/dist/alphabet.js.map +1 -0
  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 +57 -0
  12. package/dist/errors.d.ts.map +1 -0
  13. package/dist/errors.js +162 -0
  14. package/dist/errors.js.map +1 -0
  15. package/dist/feistel.js +39 -0
  16. package/dist/feistel.js.map +1 -0
  17. package/dist/generation-options.js +20 -0
  18. package/dist/generation-options.js.map +1 -0
  19. package/dist/index.d.ts +23 -168
  20. package/dist/index.js +22 -649
  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 +164 -0
  30. package/dist/mask.js.map +1 -0
  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 +129 -0
  40. package/dist/migration.js.map +1 -0
  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 +30 -0
  48. package/dist/runtime/pool.js.map +1 -0
  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 +29 -0
  54. package/dist/siphash.js.map +1 -0
  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 +535 -0
  64. package/dist/types.d.ts.map +1 -0
  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 +65 -0
  74. package/dist/uuid.d.ts.map +1 -0
  75. package/dist/uuid.js +232 -0
  76. package/dist/uuid.js.map +1 -0
  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 +143 -0
  114. package/dist/v7.js.map +1 -0
  115. package/package.json +18 -17
  116. package/src/alphabet.ts +616 -0
  117. package/src/base64url-name.ts +5 -0
  118. package/src/errors.ts +423 -13
  119. package/src/feistel.ts +141 -0
  120. package/src/generation-options.ts +48 -0
  121. package/src/index.ts +137 -57
  122. package/src/instant.ts +196 -0
  123. package/src/keyless.ts +9 -0
  124. package/src/mask-handle.ts +141 -0
  125. package/src/mask.ts +377 -90
  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 +257 -0
  130. package/src/payload.ts +321 -0
  131. package/src/runtime/bun.ts +31 -25
  132. package/src/runtime/node.ts +55 -18
  133. package/src/runtime/pool.ts +90 -0
  134. package/src/runtime/portable.ts +68 -0
  135. package/src/runtime/types.ts +30 -5
  136. package/src/sentinel.ts +13 -0
  137. package/src/siphash.ts +128 -0
  138. package/src/slug.ts +884 -0
  139. package/src/timestamp.ts +122 -0
  140. package/src/types.ts +799 -61
  141. package/src/uuid-value-protocol.ts +77 -0
  142. package/src/uuid-value.ts +341 -0
  143. package/src/uuid.ts +527 -108
  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 +433 -84
  156. package/dist/index.d.ts.map +0 -1
  157. package/dist/index.js.map +0 -1
  158. package/dist/node/index.js +0 -647
  159. package/dist/web/index.js +0 -648
  160. package/src/base64url.ts +0 -76
  161. package/src/codec.ts +0 -218
  162. package/src/runtime/web.ts +0 -20
  163. package/src/schema.ts +0 -123
@@ -0,0 +1,535 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // @anizoptera/uuid-slug 0.4.0 | https://github.com/Anizoptera/uuid-slug#readme
3
+ import { UuidSlugError } from "./errors.js";
4
+ import { SlugAlphabet } from "./slug.js";
5
+ import { UuidV7MaskingCodec, UuidV7MaskingCodecOptions, UuidV7MaskingCodecSharedOptions, UuidV7PreviousMask } from "./masking-codec-types.js";
6
+ //#region src/types.d.ts
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
+ };
47
+ /**
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.
51
+ */
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; };
56
+ };
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;
189
+ /**
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`.
193
+ */
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>;
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;
245
+ /**
246
+ * An inclusive timestamp window around `referenceUnixMs` or the current time.
247
+ * This checks clock plausibility, not expiry, authentication, replay, or issuance.
248
+ */
249
+ export interface UuidV7TimestampWindow {
250
+ /** Maximum absolute difference from the reference time, inclusive. Must be finite and nonnegative. */
251
+ readonly maxTimestampDeltaMs: number;
252
+ /**
253
+ * Finite Unix milliseconds used as the reference.
254
+ *
255
+ * @defaultValue One `Date.now()` reading per validation call.
256
+ */
257
+ readonly referenceUnixMs?: number;
258
+ }
259
+ /**
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.
264
+ */
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;
280
+ /**
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.
286
+ */
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;
292
+ /**
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.
295
+ *
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.
298
+ */
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;
312
+ }
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;
342
+ }
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;
351
+ }
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;
362
+ }
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;
380
+ }
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;
385
+ }
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. */
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 {
406
+ /**
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.
410
+ */
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 {
422
+ /**
423
+ * Diagnostic label only; decoding uses the mask object and caller-specified order. JavaScript
424
+ * also accepts a genuine `String` object.
425
+ *
426
+ * @defaultValue `"seeded"`
427
+ */
428
+ readonly diagnosticLabel?: string;
429
+ /**
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.
433
+ */
434
+ readonly seed: string | Uint8Array;
435
+ /**
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.
439
+ *
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.
448
+ *
449
+ * @defaultValue No cancellation.
450
+ */
451
+ readonly signal?: AbortSignal;
452
+ }
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;
457
+ /**
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.
460
+ */
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 {
482
+ /**
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`
488
+ */
489
+ readonly acceptFixedMask?: boolean;
490
+ /**
491
+ * Accept plain UUID slugs of any version, including retained trailing-bit aliases.
492
+ *
493
+ * @defaultValue `false`
494
+ */
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> {
507
+ /**
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.
510
+ *
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.
523
+ *
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.
528
+ */
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;
532
+ }
533
+ //#endregion
534
+ export type { UuidV7MaskingCodec, UuidV7MaskingCodecOptions, UuidV7PreviousMask };
535
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","names":[],"sources":["../src/types.ts"],"mappings":"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"}
package/dist/types.js ADDED
@@ -0,0 +1,8 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // @anizoptera/uuid-slug 0.4.0 | https://github.com/Anizoptera/uuid-slug#readme
3
+ //#region src/types.ts
4
+ const e = "lowercase", t = "uppercase", n = "preserve", r = "reset", i = "error", a = "ncs", o = "rfc", s = "microsoft", c = "future", l = "seeded-mask", u = "fixed-mask", d = "plain-slug";
5
+ //#endregion
6
+ export { u as FIXED_MASK_FORMAT, d as PLAIN_SLUG_FORMAT, l as SEEDED_MASK_FORMAT, e as UUID_TEXT_LOWERCASE, t as UUID_TEXT_UPPERCASE, i as UUID_V7_ROLLBACK_ERROR, n as UUID_V7_ROLLBACK_PRESERVE, r as UUID_V7_ROLLBACK_RESET, c as UUID_VARIANT_FUTURE, s as UUID_VARIANT_MICROSOFT, a as UUID_VARIANT_NCS, o as UUID_VARIANT_RFC };
7
+
8
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","names":["UUID_TEXT_LOWERCASE","UUID_TEXT_UPPERCASE","UUID_V7_ROLLBACK_PRESERVE","UUID_V7_ROLLBACK_RESET","UUID_V7_ROLLBACK_ERROR","UUID_VARIANT_NCS","UUID_VARIANT_RFC","UUID_VARIANT_MICROSOFT","UUID_VARIANT_FUTURE","SEEDED_MASK_FORMAT","FIXED_MASK_FORMAT","PLAIN_SLUG_FORMAT"],"sources":["../src/types.ts"],"mappings":";;;AAiBA,MAAaA,IAAsB,aAEtBC,IAAsB,aAEtBC,IAA4B,YAE5BC,IAAyB,SAEzBC,IAAyB,SAmBzBC,IAAmB,OAEnBC,IAAmB,OAEnBC,IAAyB,aAEzBC,IAAsB,UAypBtBC,IAAqB,eAErBC,IAAoB,cAEpBC,IAAoB"}
@@ -0,0 +1,46 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // @anizoptera/uuid-slug 0.4.0 | https://github.com/Anizoptera/uuid-slug#readme
3
+ import { isUint8Array as e } from "./errors.js";
4
+ //#region src/uuid-value-protocol.ts
5
+ const t = Symbol.for("@anizoptera/uuid-slug.uuid-value-bytes"), n = Symbol.for("@anizoptera/uuid-slug.uuid-value-context");
6
+ var LocalUuidValue = class {
7
+ #e;
8
+ #t;
9
+ #n;
10
+ constructor(e, t, n) {
11
+ this.#e = e, this.#t = t, this.#n = n;
12
+ }
13
+ static is(e) {
14
+ return typeof e == "object" && !!e && #e in e;
15
+ }
16
+ static ownBytes(e) {
17
+ return e.#e;
18
+ }
19
+ static ownMaskingCodec(e) {
20
+ return e.#t;
21
+ }
22
+ static ownPayloadLayout(e) {
23
+ return e.#n;
24
+ }
25
+ [n]() {
26
+ return {
27
+ maskingCodec: this.#t,
28
+ payloadLayout: this.#n && { ...this.#n }
29
+ };
30
+ }
31
+ };
32
+ function uuidValueBytes(n) {
33
+ if (LocalUuidValue.is(n)) return LocalUuidValue.ownBytes(n);
34
+ if (typeof n == "object" && n) try {
35
+ let r = Reflect.get(n, t);
36
+ if (typeof r != "function") return;
37
+ let i = Reflect.apply(r, n, []);
38
+ return /* @__PURE__ */ e(i) && i.length === 16 ? i : void 0;
39
+ } catch {
40
+ return;
41
+ }
42
+ }
43
+ //#endregion
44
+ export { LocalUuidValue, t as UUID_VALUE_BYTES, n as UUID_VALUE_CONTEXT, uuidValueBytes };
45
+
46
+ //# sourceMappingURL=uuid-value-protocol.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"uuid-value-protocol.js","names":["UUID_VALUE_BYTES","UUID_VALUE_CONTEXT","#bytes","bytes","#maskingCodec","maskingCodec","#payloadLayout","payloadLayout","value","read"],"sources":["../src/uuid-value-protocol.ts"],"mappings":";;;;AAKA,MAAaA,IAAmB,OAAO,IAAI,wCAAwC,GACtEC,IAAqB,OAAO,IAAI,0CAA0C;AAUvF,IAAa,iBAAb,MAA4B;CAC1B;CACA;CACA;CAMA,YACE,GACA,GACA,GACA;EAGA,AAFA,KAAKC,KAASC,GACd,KAAKC,KAAgBC,GACrB,KAAKC,KAAiBC;CACxB;CAGA,OAAO,GAAG,GAAyC;EACjD,OAAO,OAAOC,KAAU,cAAYA,KAAkB,MAAUA;CAClE;CAIA,OAAO,SAAS,GAAmC;EACjD,OAAOA,EAAMN;CACf;CAEA,OAAO,gBAAgB,GAAuD;EAC5E,OAAOM,EAAMJ;CACf;CAEA,OAAO,iBAAiB,GAAwD;EAC9E,OAAOI,EAAMF;CACf;CAEA,CAACL,KAAsB;EAGrB,OAAO;GACL,cAAc,KAAKG;GACnB,eAAe,KAAKE,MAAkB,EAAE,GAAG,KAAKA,GAAe;EACjE;CACF;AACF;AAGA,SAAgB,eAAe,GAAwC;CACrE,IAAI,eAAe,GAAGE,CAAK,GAAG,OAAO,eAAe,SAASA,CAAK;CAClE,IAAI,OAAOA,KAAU,YAAYA,GACjC,IAAI;EACF,IAAMC,IAAO,QAAQ,IAAID,GAAOR,CAAgB;EAChD,IAAI,OAAOS,KAAS,YAAY;EAChC,IAAMN,IAAQ,QAAQ,MAAMM,GAAMD,GAAO,CAAC,CAAC;EAC3C,OAAO,kBAAaL,CAAK,KAAKA,EAAM,WAAW,KAAKA,IAAQ,KAAA;CAC9D,QAAQ;EACN;CACF;AACF"}
@@ -0,0 +1,17 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+ // @anizoptera/uuid-slug 0.4.0 | https://github.com/Anizoptera/uuid-slug#readme
3
+ import { UuidSlugError } from "./errors.js";
4
+ import { UuidV7MaskingCodec } from "./masking-codec-types.js";
5
+ import { KeylessUuidInput, ParsedUuidResult, UuidInput } from "./types.js";
6
+ //#region src/uuid-value.d.ts
7
+ /** Parse any keyless UUID form once; an existing UUID retains its codec and payload-layout presets. */
8
+ export declare function parseUuid<Input extends UuidInput>(uuid: KeylessUuidInput<Input>): ParsedUuidResult<Input> | UuidSlugError;
9
+ /**
10
+ * Parse through a masking codec, replacing any preset codec and retaining an existing payload layout.
11
+ * A plain UUIDv4 slug can resolve to UUIDv7 when the codec's mask check passes.
12
+ * External codec bytes are validated and copied. Malformed results return `invalid_options`;
13
+ * thrown exceptions remain available as the error's `cause`.
14
+ */
15
+ export declare function parseUuid<Input extends UuidInput>(uuid: Input, maskingCodec: UuidV7MaskingCodec): ParsedUuidResult<Input, true> | UuidSlugError;
16
+ //#endregion
17
+ //# sourceMappingURL=uuid-value.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"uuid-value.d.ts","names":[],"sources":["../src/uuid-value.ts"],"mappings":";;;;;;;wBA+QgB,UAAU,cAAc,WACtC,MAAM,iBAAiB,SACtB,iBAAiB,SAAS;;;;;;;wBAOb,UAAU,cAAc,WACtC,MAAM,OACN,cAAc,qBACb,iBAAiB,eAAe"}