@anizoptera/uuid-slug 0.3.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.
- package/LICENSE +54 -31
- package/README.md +1052 -261
- package/dist/alphabet.d.ts +5 -17
- package/dist/alphabet.d.ts.map +1 -1
- package/dist/alphabet.js +146 -112
- package/dist/alphabet.js.map +1 -1
- package/dist/base64url-name.d.ts +7 -0
- package/dist/base64url-name.d.ts.map +1 -0
- package/dist/base64url-name.js +8 -0
- package/dist/base64url-name.js.map +1 -0
- package/dist/errors.d.ts +50 -9
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +145 -63
- package/dist/errors.js.map +1 -1
- package/dist/feistel.js +29 -95
- package/dist/feistel.js.map +1 -1
- package/dist/generation-options.js +20 -0
- package/dist/generation-options.js.map +1 -0
- package/dist/index.d.ts +22 -10
- package/dist/index.js +21 -9
- package/dist/instant.js +83 -0
- package/dist/instant.js.map +1 -0
- package/dist/mask-handle.d.ts +16 -0
- package/dist/mask-handle.d.ts.map +1 -0
- package/dist/mask-handle.js +60 -0
- package/dist/mask-handle.js.map +1 -0
- package/dist/mask.d.ts +27 -0
- package/dist/mask.d.ts.map +1 -0
- package/dist/mask.js +151 -95
- package/dist/mask.js.map +1 -1
- package/dist/masking-codec-protocol.js +23 -0
- package/dist/masking-codec-protocol.js.map +1 -0
- package/dist/masking-codec-types.d.ts +245 -0
- package/dist/masking-codec-types.d.ts.map +1 -0
- package/dist/masking-codec.d.ts +19 -0
- package/dist/masking-codec.d.ts.map +1 -0
- package/dist/masking-codec.js +391 -0
- package/dist/masking-codec.js.map +1 -0
- package/dist/migration.js +114 -51
- package/dist/migration.js.map +1 -1
- package/dist/node/runtime.js +39 -0
- package/dist/node/runtime.js.map +1 -0
- package/dist/payload.d.ts +7 -0
- package/dist/payload.d.ts.map +1 -0
- package/dist/payload.js +118 -0
- package/dist/payload.js.map +1 -0
- package/dist/runtime/pool.js +21 -46
- package/dist/runtime/pool.js.map +1 -1
- package/dist/runtime/portable.js +27 -0
- package/dist/runtime/portable.js.map +1 -0
- package/dist/sentinel.js +10 -0
- package/dist/sentinel.js.map +1 -0
- package/dist/siphash.js +20 -99
- package/dist/siphash.js.map +1 -1
- package/dist/slug.d.ts +169 -0
- package/dist/slug.d.ts.map +1 -0
- package/dist/slug.js +268 -0
- package/dist/slug.js.map +1 -0
- package/dist/timestamp.d.ts +19 -0
- package/dist/timestamp.d.ts.map +1 -0
- package/dist/timestamp.js +44 -0
- package/dist/timestamp.js.map +1 -0
- package/dist/types.d.ts +480 -200
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +8 -0
- package/dist/types.js.map +1 -0
- package/dist/uuid-value-protocol.js +46 -0
- package/dist/uuid-value-protocol.js.map +1 -0
- package/dist/uuid-value.d.ts +17 -0
- package/dist/uuid-value.d.ts.map +1 -0
- package/dist/uuid-value.js +127 -0
- package/dist/uuid-value.js.map +1 -0
- package/dist/uuid.d.ts +51 -64
- package/dist/uuid.d.ts.map +1 -1
- package/dist/uuid.js +203 -199
- package/dist/uuid.js.map +1 -1
- package/dist/v4-slug.d.ts +16 -0
- package/dist/v4-slug.d.ts.map +1 -0
- package/dist/v4-slug.js +16 -0
- package/dist/v4-slug.js.map +1 -0
- package/dist/v4.d.ts +42 -0
- package/dist/v4.d.ts.map +1 -0
- package/dist/v4.js +85 -0
- package/dist/v4.js.map +1 -0
- package/dist/v7-bounds.d.ts +36 -0
- package/dist/v7-bounds.d.ts.map +1 -0
- package/dist/v7-bounds.js +49 -0
- package/dist/v7-bounds.js.map +1 -0
- package/dist/v7-generator-input.js +75 -0
- package/dist/v7-generator-input.js.map +1 -0
- package/dist/v7-generator.d.ts +43 -0
- package/dist/v7-generator.d.ts.map +1 -0
- package/dist/v7-generator.js +105 -0
- package/dist/v7-generator.js.map +1 -0
- package/dist/v7-keyless.d.ts +46 -0
- package/dist/v7-keyless.d.ts.map +1 -0
- package/dist/v7-keyless.js +106 -0
- package/dist/v7-keyless.js.map +1 -0
- package/dist/v7-payload.js +54 -0
- package/dist/v7-payload.js.map +1 -0
- package/dist/v7-slug.d.ts +46 -0
- package/dist/v7-slug.d.ts.map +1 -0
- package/dist/v7-slug.js +127 -0
- package/dist/v7-slug.js.map +1 -0
- package/dist/v7-timestamp.js +9 -0
- package/dist/v7-timestamp.js.map +1 -0
- package/dist/v7-value-options.js +28 -0
- package/dist/v7-value-options.js.map +1 -0
- package/dist/v7-value.d.ts +23 -0
- package/dist/v7-value.d.ts.map +1 -0
- package/dist/v7-value.js +31 -0
- package/dist/v7-value.js.map +1 -0
- package/dist/v7.js +127 -171
- package/dist/v7.js.map +1 -1
- package/package.json +14 -9
- package/src/alphabet.ts +456 -27
- package/src/base64url-name.ts +5 -0
- package/src/errors.ts +373 -37
- package/src/feistel.ts +69 -56
- package/src/generation-options.ts +48 -0
- package/src/index.ts +134 -80
- package/src/instant.ts +196 -0
- package/src/keyless.ts +7 -134
- package/src/mask-handle.ts +141 -0
- package/src/mask.ts +354 -129
- package/src/masking-codec-protocol.ts +29 -0
- package/src/masking-codec-types.ts +380 -0
- package/src/masking-codec.ts +923 -0
- package/src/migration.ts +195 -42
- package/src/payload.ts +321 -0
- package/src/runtime/bun.ts +30 -49
- package/src/runtime/node.ts +43 -24
- package/src/runtime/pool.ts +49 -21
- package/src/runtime/portable.ts +68 -0
- package/src/runtime/types.ts +23 -35
- package/src/sentinel.ts +13 -0
- package/src/siphash.ts +5 -4
- package/src/slug.ts +884 -0
- package/src/timestamp.ts +122 -0
- package/src/types.ts +759 -205
- package/src/uuid-value-protocol.ts +77 -0
- package/src/uuid-value.ts +341 -0
- package/src/uuid.ts +514 -234
- package/src/v4-slug.ts +27 -0
- package/src/v4.ts +234 -0
- package/src/v7-bounds.ts +171 -0
- package/src/v7-generator-input.ts +169 -0
- package/src/v7-generator.ts +245 -0
- package/src/v7-keyless.ts +354 -0
- package/src/v7-payload.ts +121 -0
- package/src/v7-slug.ts +293 -0
- package/src/v7-timestamp.ts +21 -0
- package/src/v7-value-options.ts +62 -0
- package/src/v7-value.ts +54 -0
- package/src/v7.ts +377 -200
- package/dist/base64url.d.ts +0 -20
- package/dist/base64url.d.ts.map +0 -1
- package/dist/base64url.js +0 -33
- package/dist/base64url.js.map +0 -1
- package/dist/codec.d.ts +0 -17
- package/dist/codec.d.ts.map +0 -1
- package/dist/codec.js +0 -192
- package/dist/codec.js.map +0 -1
- package/dist/keyless.d.ts +0 -31
- package/dist/keyless.d.ts.map +0 -1
- package/dist/keyless.js +0 -93
- package/dist/keyless.js.map +0 -1
- package/dist/legacy-mask.js +0 -55
- package/dist/legacy-mask.js.map +0 -1
- package/dist/node/alphabet.js +0 -130
- package/dist/node/base64url.js +0 -31
- package/dist/node/codec.js +0 -190
- package/dist/node/errors.js +0 -78
- package/dist/node/feistel.js +0 -103
- package/dist/node/index.js +0 -10
- package/dist/node/keyless.js +0 -91
- package/dist/node/legacy-mask.js +0 -53
- package/dist/node/mask.js +0 -106
- package/dist/node/migration.js +0 -64
- package/dist/node/runtime/node.js +0 -33
- package/dist/node/runtime/pool.js +0 -53
- package/dist/node/schema.js +0 -214
- package/dist/node/siphash.js +0 -106
- package/dist/node/uuid.js +0 -226
- package/dist/node/v7.js +0 -185
- package/dist/node/yield.js +0 -20
- package/dist/runtime/web.js +0 -39
- package/dist/runtime/web.js.map +0 -1
- package/dist/schema.d.ts +0 -20
- package/dist/schema.d.ts.map +0 -1
- package/dist/schema.js +0 -216
- package/dist/schema.js.map +0 -1
- package/dist/v7.d.ts +0 -12
- package/dist/v7.d.ts.map +0 -1
- package/dist/yield.js +0 -22
- package/dist/yield.js.map +0 -1
- package/src/base64url.ts +0 -41
- package/src/codec.ts +0 -320
- package/src/legacy-mask.ts +0 -25
- package/src/runtime/web.ts +0 -48
- package/src/schema.ts +0 -300
- package/src/yield.ts +0 -22
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
// Only this package's frozen codecs may borrow private UUID storage. Structural callbacks can
|
|
4
|
+
// retain or mutate their input; public shape checks cannot establish ownership.
|
|
5
|
+
// A private stamp follows the generator ownership protocol without a WeakSet registration or lookup;
|
|
6
|
+
// construction and conversion measurements are owned by bench/PERFORMANCE.md.
|
|
7
|
+
// Remeasure construction and parsed conversions if engines change private-field storage.
|
|
8
|
+
// eslint-disable-next-line typescript/no-extraneous-class -- returning the codec lets the subclass stamp the existing plain object
|
|
9
|
+
class ReturnCodec {
|
|
10
|
+
constructor(codec: object) {
|
|
11
|
+
return codec;
|
|
12
|
+
}
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
class PackageMaskingCodec extends ReturnCodec {
|
|
16
|
+
readonly #local = true;
|
|
17
|
+
|
|
18
|
+
static is(codec: object): boolean {
|
|
19
|
+
return typeof codec === "object" && codec !== null && #local in codec && codec.#local;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export function registerMaskingCodec<Codec extends object>(codec: Codec): Codec {
|
|
24
|
+
return new PackageMaskingCodec(codec) as object as Codec;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export function isLocalMaskingCodec(codec: object): boolean {
|
|
28
|
+
return PackageMaskingCodec.is(codec);
|
|
29
|
+
}
|
|
@@ -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
|
+
}
|