@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,380 @@
1
+ // SPDX-License-Identifier: Apache-2.0
2
+
3
+ import type { UuidSlugError } from "./errors.ts";
4
+ import type { SlugAlphabet } from "./slug.ts";
5
+ import type {
6
+ UUID_TEXT_LOWERCASE,
7
+ SEEDED_MASK_FORMAT,
8
+ EnabledMigrationFormat,
9
+ GeneratedUuidV7,
10
+ GenerateUuidV7WithMaskedSlugOptions,
11
+ MaskingCodecUuidInput,
12
+ MaskedOrSentinelUuidV7Slug,
13
+ PlainUuidSlug,
14
+ PlainUuidSlugResult,
15
+ PlainUuidV7Slug,
16
+ PlainUuidV7SlugInput,
17
+ ParsedUuidResult,
18
+ SlugStringInput,
19
+ Uuid,
20
+ UuidBytesResult,
21
+ UuidInput,
22
+ UuidSlugMigrationDecoder,
23
+ UuidSlugMigrationOptions,
24
+ UuidStringResult,
25
+ UuidOutput,
26
+ UuidTextCase,
27
+ UuidTextCaseArguments,
28
+ UuidV7Bytes,
29
+ UuidV7Mask,
30
+ UuidV7MaskOptions,
31
+ UuidV7MaskingCodecValueOptions,
32
+ UuidV7Payload,
33
+ UuidV7PayloadLayout,
34
+ UuidV7Sentinel,
35
+ UuidV7SentinelConfig,
36
+ UuidV7StringFor,
37
+ UuidV7TimestampWindow,
38
+ UuidV7ValueInput,
39
+ } from "./types.ts";
40
+
41
+ /** Key rotation, sentinel, and output options shared by both ways of supplying the writer mask. */
42
+ export interface UuidV7MaskingCodecSharedOptions {
43
+ /**
44
+ * First Unix millisecond accepted by masking. The inclusive end is this value plus
45
+ * `MAX_MASKED_UUID_V7_TIMESTAMP_OFFSET_MS`. Changing it changes masked slugs, so retain the old
46
+ * value with its mask in `previousMasks` while stored slugs still use it.
47
+ *
48
+ * @defaultValue `0`
49
+ */
50
+ readonly timestampRangeStartUnixMs?: number;
51
+ /**
52
+ * Decode-only masks tried after the writer mask, in caller order. Each item accepts a mask or its
53
+ * derivation options. A returned `UuidSlugError` passes through unchanged. Keep the list short:
54
+ * every mask adds decoding work and another chance for a random input to pass its 16-bit check.
55
+ *
56
+ * @defaultValue No previous masks.
57
+ */
58
+ readonly previousMasks?: readonly (
59
+ | UuidV7Mask
60
+ | UuidV7MaskOptions
61
+ | UuidV7PreviousMask
62
+ | UuidSlugError
63
+ )[];
64
+ /**
65
+ * Named UUIDv7 values emitted as raw plain slugs instead of masked payloads.
66
+ *
67
+ * @defaultValue No sentinels.
68
+ */
69
+ readonly sentinels?: readonly UuidV7SentinelConfig[];
70
+ /**
71
+ * Output spelling for masked UUID slugs and plain sentinel UUID slugs.
72
+ * `"base32hex"` preserves the full masked payload in 27 lowercase characters (26 for raw
73
+ * sentinels), suitable for case-insensitive filesystems. Masked output has no sort-order promise.
74
+ * Readers accept both spellings regardless of this writer selection.
75
+ *
76
+ * @defaultValue `"base64url"`
77
+ */
78
+ readonly maskedSlugAlphabet?: SlugAlphabet;
79
+ }
80
+
81
+ /**
82
+ * Configure one immutable UUIDv7 masking codec for writing, key rotation, and sentinels. Supply the
83
+ * writer mask exactly one way: `maskSeed` for private key material, or `mask` for a shared derived
84
+ * mask, `UUID_V7_TEST_MASK`, or seed material that also needs a label or a key-derivation work factor.
85
+ */
86
+ export type UuidV7MaskingCodecOptions =
87
+ | (UuidV7MaskingCodecSharedOptions & {
88
+ /**
89
+ * The writer mask and first reader. Supply a derived mask, its derivation options, or
90
+ * explicitly choose `UUID_V7_TEST_MASK` for public test data. A returned `UuidSlugError`
91
+ * passes through unchanged.
92
+ */
93
+ readonly mask: UuidV7Mask | UuidV7MaskOptions | UuidSlugError;
94
+ readonly maskSeed?: never;
95
+ })
96
+ | (UuidV7MaskingCodecSharedOptions & {
97
+ readonly mask?: never;
98
+ /**
99
+ * Stable secret key material for the writer mask, derived with the default work factor.
100
+ * Generate at least 16 bytes, keep it outside source control, and retain old values in
101
+ * `previousMasks`; a known UUID/slug pair permits offline guesses. JavaScript also accepts a
102
+ * genuine `String` object.
103
+ */
104
+ readonly maskSeed: string | Uint8Array;
105
+ });
106
+
107
+ /** A retained mask and the timestamp-range start used to create its stored slugs. */
108
+ export interface UuidV7PreviousMask {
109
+ /** Retained decode-only mask or its derivation options. */
110
+ readonly mask: UuidV7Mask | UuidV7MaskOptions | UuidSlugError;
111
+ /** First Unix millisecond accepted by this retained mask. Omit for `0`. */
112
+ readonly timestampRangeStartUnixMs?: number;
113
+ }
114
+
115
+ /**
116
+ * An immutable UUIDv7 masking codec that owns its masks, sentinels, output alphabet, and byte source.
117
+ * Methods may be detached. Decoding proves format integrity, not issuance or authorization.
118
+ * JavaScript UUID and slug text inputs normalize genuine `String` objects; TypeScript uses primitives.
119
+ */
120
+ export interface UuidV7MaskingCodec {
121
+ /** Frozen sentinel metadata in the masking codec's configured masked-slug alphabet. */
122
+ readonly sentinels: readonly UuidV7Sentinel[];
123
+ /** Generate an immutable UUIDv7 with this masking codec retained. */
124
+ generateUuidV7Value(
125
+ this: void,
126
+ options?: UuidV7MaskingCodecValueOptions,
127
+ ): Uuid<7, true, true> | UuidSlugError;
128
+ /** Parse any accepted UUID form, retain this codec and preserve an existing payload layout. A plain-v4 slug brand cannot exclude a masked-v7 reading. */
129
+ parseUuid<Input extends UuidInput>(
130
+ this: void,
131
+ uuid: Input,
132
+ ): ParsedUuidResult<Input, true> | UuidSlugError;
133
+ /**
134
+ * Convert any accepted UUID form to normalized UUID text. A 22-character slug is read as masked
135
+ * when it passes this codec's check and as plain otherwise.
136
+ * A plain UUIDv4 slug can therefore return UUIDv4 or UUIDv7 text.
137
+ */
138
+ uuidToString<Input extends UuidInput, Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
139
+ this: void,
140
+ uuid: Input,
141
+ ...textCase: UuidTextCaseArguments<Case>
142
+ ): UuidStringResult<MaskingCodecUuidInput<Input>, Case>;
143
+ /**
144
+ * Read one UUID out of a larger array as normalized UUID text. Bytes carry no masked spelling.
145
+ *
146
+ * @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
147
+ */
148
+ uuidToString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
149
+ this: void,
150
+ uuid: Uint8Array,
151
+ byteOffset: number,
152
+ ...textCase: UuidTextCaseArguments<Case>
153
+ ): UuidStringResult<Uint8Array, Case>;
154
+ /**
155
+ * Convert any accepted UUID form to a new plain 16-byte array. A 22-character slug is read as
156
+ * masked when it passes this codec's check and as plain otherwise.
157
+ * A plain UUIDv4 slug can therefore return UUIDv4 or UUIDv7 bytes.
158
+ */
159
+ uuidToBytes<Input extends UuidInput>(
160
+ this: void,
161
+ uuid: Input,
162
+ ): UuidBytesResult<MaskingCodecUuidInput<Input>>;
163
+ /** Convert any accepted UUID form into caller-owned storage after complete validation. */
164
+ uuidToBytes<Output extends Uint8Array>(
165
+ this: void,
166
+ uuid: UuidInput,
167
+ output: Output,
168
+ outputOffset?: number,
169
+ ): UuidOutput<Output> | UuidSlugError;
170
+ /**
171
+ * Copy one UUID out of a larger array. Bytes carry no masked spelling.
172
+ *
173
+ * @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
174
+ */
175
+ uuidToBytes(this: void, uuid: Uint8Array, byteOffset: number): UuidBytesResult<Uint8Array>;
176
+ /** Copy one UUID out of a larger array into caller-owned storage. */
177
+ uuidToBytes<Output extends Uint8Array>(
178
+ this: void,
179
+ uuid: Uint8Array,
180
+ byteOffset: number,
181
+ output: Output,
182
+ outputOffset?: number,
183
+ ): UuidOutput<Output> | UuidSlugError;
184
+ /**
185
+ * Convert any accepted UUID form to a plain UUID slug. A 22-character slug is read as masked
186
+ * when it passes this codec's check and as plain otherwise.
187
+ * A plain UUIDv4 slug can therefore return a plain UUIDv4 or UUIDv7 slug.
188
+ */
189
+ uuidToPlainSlug<Input extends UuidInput>(
190
+ this: void,
191
+ uuid: Input,
192
+ alphabet?: SlugAlphabet,
193
+ ): PlainUuidSlugResult<MaskingCodecUuidInput<Input>>;
194
+ /**
195
+ * Read one UUID out of a larger array as a plain UUID slug. Bytes carry no masked spelling.
196
+ *
197
+ * @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
198
+ */
199
+ uuidToPlainSlug(
200
+ this: void,
201
+ uuid: Uint8Array,
202
+ byteOffset: number,
203
+ alphabet?: SlugAlphabet,
204
+ ): PlainUuidSlugResult<Uint8Array>;
205
+ /**
206
+ * Create a reader for current and explicitly enabled old formats without changing this codec.
207
+ * Omitted options return the reader directly. Configured construction returns `invalid_options`
208
+ * for unknown keys, nonboolean settings or inaccessible properties. Check construction once
209
+ * before reusing the reader; decode failures return `UuidSlugError` from the reader.
210
+ *
211
+ * @param options - Old formats this application has actually issued. Omit for current formats only.
212
+ */
213
+ createUuidSlugMigrationDecoder(
214
+ this: void,
215
+ options?: undefined,
216
+ ): UuidSlugMigrationDecoder<typeof SEEDED_MASK_FORMAT>;
217
+ /** Create a reusable reader with explicitly enabled old formats; check configuration failure once. */
218
+ createUuidSlugMigrationDecoder<const Options extends UuidSlugMigrationOptions>(
219
+ this: void,
220
+ options: Options | undefined,
221
+ ): UuidSlugMigrationDecoder<EnabledMigrationFormat<Options>> | UuidSlugError;
222
+ /**
223
+ * Generate and encode a UUIDv7 as a masked slug or its registered raw sentinel slug.
224
+ * Options may select an explicit time and a generator whose sequence this call joins.
225
+ * Returns `invalid_timestamp` outside the codec's inclusive configured timestamp range unless
226
+ * the generated UUID is a registered sentinel, which
227
+ * is returned as a plain slug without masking.
228
+ */
229
+ generateMaskedUuidV7Slug(
230
+ this: void,
231
+ options?: UuidV7MaskingCodecValueOptions,
232
+ ): MaskedOrSentinelUuidV7Slug | UuidSlugError;
233
+ /**
234
+ * Generate UUIDv7 text and its masked or sentinel slug from one random byte draw. UUID text is
235
+ * lowercase unless `textCase` selects uppercase. Options may select an explicit time and a
236
+ * generator whose sequence this call joins.
237
+ * Returns `invalid_timestamp` outside the codec's inclusive configured timestamp range unless
238
+ * the generated UUID is a registered sentinel, which
239
+ * is returned as a plain slug without masking.
240
+ *
241
+ * @param textCase - Built-in UUID text spelling. Omit for lowercase.
242
+ */
243
+ generateUuidV7WithMaskedSlug<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
244
+ this: void,
245
+ ...textCase: UuidTextCaseArguments<Case>
246
+ ): GeneratedUuidV7<MaskedOrSentinelUuidV7Slug, Case> | UuidSlugError;
247
+ /** Generate the pair through selected sequence state at an explicit time or the current clock. */
248
+ generateUuidV7WithMaskedSlug<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
249
+ this: void,
250
+ options: GenerateUuidV7WithMaskedSlugOptions<Case>,
251
+ ): GeneratedUuidV7<MaskedOrSentinelUuidV7Slug, Case> | UuidSlugError;
252
+ /**
253
+ * Convert UUID text, 16 UUID bytes, a plain slug, or a masked slug to this masking codec's
254
+ * current masked spelling. A 22-character slug is read as masked when it passes this codec's
255
+ * check and as plain otherwise. Other UUID versions
256
+ * return `invalid_uuid_version`. TypeScript rejects known non-v7 values; unbranded external
257
+ * values are validated when called. Timestamps outside the codec's inclusive configured range
258
+ * return `invalid_timestamp`; sentinels are
259
+ * returned as plain slugs without masking and retain the full UUIDv7 timestamp range. A preceding
260
+ * `UuidSlugError` is returned unchanged.
261
+ *
262
+ * @param uuid - Any supported UUIDv7 text, bytes, plain slug, masked slug, or sentinel.
263
+ */
264
+ uuidToMaskedSlug<Input extends UuidInput>(
265
+ this: void,
266
+ uuid: UuidV7ValueInput<Input>,
267
+ ): MaskedOrSentinelUuidV7Slug | UuidSlugError;
268
+ /**
269
+ * Convert either plain UUIDv7 slug spelling to this codec's current masked or sentinel spelling.
270
+ * TypeScript rejects known UUIDv4 slugs. Other UUIDv4 input returns `invalid_uuid_version`;
271
+ * an out-of-range UUIDv7 returns `invalid_timestamp`; a
272
+ * preceding `UuidSlugError` is returned unchanged.
273
+ *
274
+ * @param plainUuidSlug - Plain UUID slug whose source representation is known by the caller.
275
+ */
276
+ plainToMaskedUuidSlug<Input extends string | UuidSlugError>(
277
+ this: void,
278
+ plainUuidSlug: PlainUuidV7SlugInput<Input>,
279
+ ): MaskedOrSentinelUuidV7Slug | UuidSlugError;
280
+ /**
281
+ * Convert a masked slug or registered sentinel to a plain UUIDv7 slug. The codec selects the
282
+ * first passing current or previous mask; output defaults to base64url. A preceding
283
+ * `UuidSlugError` is returned unchanged.
284
+ *
285
+ * @param maskedUuidSlug - Masked UUIDv7 slug or registered sentinel.
286
+ * @param alphabet - Plain output spelling. Omit for base64url.
287
+ */
288
+ maskedToPlainUuidSlug<Input extends string | UuidSlugError>(
289
+ this: void,
290
+ maskedUuidSlug: SlugStringInput<Input>,
291
+ alphabet?: SlugAlphabet,
292
+ ): PlainUuidV7Slug | UuidSlugError;
293
+ /**
294
+ * Decode the first passing sentinel or mask in configured order to UUIDv7 text in the selected
295
+ * case, lowercase by default.
296
+ * Success proves format integrity, not issuance. TypeScript rejects known UUID text; slug values
297
+ * remain accepted because plain and masked spellings can overlap. A preceding `UuidSlugError`
298
+ * is returned unchanged.
299
+ *
300
+ * @param maskedUuidSlug - Masked UUIDv7 slug or registered sentinel accepted by this masking codec.
301
+ * @param textCase - Built-in UUID text spelling. Omit for lowercase.
302
+ */
303
+ maskedSlugToUuidString<
304
+ Input extends string | UuidSlugError,
305
+ Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE,
306
+ >(
307
+ this: void,
308
+ maskedUuidSlug: SlugStringInput<Input>,
309
+ ...textCase: UuidTextCaseArguments<Case>
310
+ ): UuidV7StringFor<Case> | UuidSlugError;
311
+ /**
312
+ * Decode to a new plain 16-byte `Uint8Array`. Use this when the caller needs binary output. A
313
+ * preceding `UuidSlugError` is returned unchanged.
314
+ *
315
+ * @param maskedUuidSlug - Masked UUIDv7 slug or registered sentinel accepted by this masking codec.
316
+ */
317
+ maskedSlugToUuidBytes<Input extends string | UuidSlugError>(
318
+ this: void,
319
+ maskedUuidSlug: SlugStringInput<Input>,
320
+ ): UuidV7Bytes | UuidSlugError;
321
+ /**
322
+ * Decode and validate before writing 16 bytes. Return the exact supplied array; errors leave it
323
+ * unchanged. A preceding `UuidSlugError` is returned unchanged without writing.
324
+ *
325
+ * @param maskedUuidSlug - Masked UUIDv7 slug or registered sentinel accepted by this masking codec.
326
+ * @param output - Caller-owned array that receives the 16 UUID bytes.
327
+ * @param outputOffset - Zero-based index where writing starts. Omit to start at index 0. Bytes
328
+ * outside the written range stay unchanged.
329
+ */
330
+ maskedSlugToUuidBytes<Input extends string | UuidSlugError, Output extends Uint8Array>(
331
+ this: void,
332
+ maskedUuidSlug: SlugStringInput<Input>,
333
+ output: Output,
334
+ outputOffset?: number,
335
+ ): UuidOutput<Output> | UuidSlugError;
336
+ /**
337
+ * Decode a masked slug or registered sentinel with this codec and return its UUIDv7 Unix
338
+ * timestamp in milliseconds. Success proves format integrity, not issuance or authorization. A
339
+ * preceding `UuidSlugError` is returned unchanged.
340
+ *
341
+ * @param maskedUuidSlug - Masked slug or registered sentinel accepted by this masking codec.
342
+ */
343
+ extractMaskedUuidV7UnixMs<Input extends string | UuidSlugError>(
344
+ this: void,
345
+ maskedUuidSlug: SlugStringInput<Input>,
346
+ ): number | UuidSlugError;
347
+ /**
348
+ * Decode with this codec, then interpret the UUIDv7 payload under the layout the caller supplies.
349
+ * The slug cannot identify its generator or layout, so this method never guesses.
350
+ *
351
+ * @param maskedUuidSlug - Masked slug or registered sentinel accepted by this masking codec.
352
+ * @param layout - Known leading fraction and fixed-counter widths.
353
+ * @returns The decoded millisecond timestamp, declared fields, and undeclared low payload bits;
354
+ * or a `UuidSlugError` when the slug, mask match, UUID, or layout is invalid.
355
+ */
356
+ extractMaskedUuidV7Payload<Input extends string | UuidSlugError>(
357
+ this: void,
358
+ maskedUuidSlug: SlugStringInput<Input>,
359
+ layout: UuidV7PayloadLayout,
360
+ ): UuidV7Payload | UuidSlugError;
361
+ /**
362
+ * Decode with this codec, check the symmetric timestamp window, and return a canonical slug.
363
+ * Base32hex output is lowercase; case-sensitive base64url is unchanged.
364
+ * This checks clock plausibility, not expiry, authentication, replay, or issuance. TypeScript
365
+ * rejects known UUID text because only this codec can resolve overlapping slug spellings. A
366
+ * preceding `UuidSlugError` is returned unchanged.
367
+ *
368
+ * @param maskedUuidSlug - Masked slug or registered sentinel accepted by this masking codec.
369
+ * @param window - Inclusive maximum distance from an explicit or current reference time.
370
+ */
371
+ validateMaskedUuidV7SlugUnixMs<Input extends string | UuidSlugError>(
372
+ this: void,
373
+ maskedUuidSlug: SlugStringInput<Input>,
374
+ window: UuidV7TimestampWindow,
375
+ ):
376
+ | (Input extends PlainUuidSlug | MaskedOrSentinelUuidV7Slug
377
+ ? Input & MaskedOrSentinelUuidV7Slug
378
+ : MaskedOrSentinelUuidV7Slug)
379
+ | UuidSlugError;
380
+ }