@anizoptera/uuid-slug 0.4.0 → 0.6.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/README.md +232 -1062
- package/dist/alphabet.d.ts +1 -3
- package/dist/alphabet.d.ts.map +1 -1
- package/dist/alphabet.js +32 -90
- package/dist/alphabet.js.map +1 -1
- package/dist/base64url-name.d.ts +1 -3
- package/dist/base64url-name.d.ts.map +1 -1
- package/dist/base64url-name.js +2 -3
- package/dist/errors.d.ts +1 -3
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +7 -24
- package/dist/errors.js.map +1 -1
- package/dist/feistel.js +1 -2
- package/dist/generation-options.js +2 -3
- package/dist/index.d.ts +10 -10
- package/dist/index.js +21 -21
- package/dist/instant.js +2 -3
- package/dist/mask-handle.d.ts +1 -3
- package/dist/mask-handle.d.ts.map +1 -1
- package/dist/mask-handle.js +19 -17
- package/dist/mask-handle.js.map +1 -1
- package/dist/mask.d.ts +1 -3
- package/dist/mask.d.ts.map +1 -1
- package/dist/mask.js +23 -24
- package/dist/mask.js.map +1 -1
- package/dist/masked-bytes.js +74 -0
- package/dist/masked-bytes.js.map +1 -0
- package/dist/masking-codec-protocol.js +2 -3
- package/dist/masking-codec-types.d.ts +60 -19
- package/dist/masking-codec-types.d.ts.map +1 -1
- package/dist/masking-codec.d.ts +1 -3
- package/dist/masking-codec.d.ts.map +1 -1
- package/dist/masking-codec.js +115 -111
- package/dist/masking-codec.js.map +1 -1
- package/dist/migration.js +39 -40
- package/dist/migration.js.map +1 -1
- package/dist/node/runtime.js +2 -3
- package/dist/payload.d.ts +1 -3
- package/dist/payload.d.ts.map +1 -1
- package/dist/payload.js +65 -64
- package/dist/payload.js.map +1 -1
- package/dist/runtime/pool.js +2 -3
- package/dist/runtime/portable.js +2 -3
- package/dist/runtime/portable.js.map +1 -1
- package/dist/sentinel.js +2 -3
- package/dist/siphash.js +1 -2
- package/dist/slug.d.ts +14 -13
- package/dist/slug.d.ts.map +1 -1
- package/dist/slug.js +144 -152
- package/dist/slug.js.map +1 -1
- package/dist/timestamp.d.ts +1 -3
- package/dist/timestamp.d.ts.map +1 -1
- package/dist/timestamp.js +2 -3
- package/dist/types.d.ts +38 -16
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +2 -3
- package/dist/types.js.map +1 -1
- package/dist/uuid-value-protocol.js +2 -3
- package/dist/uuid-value.d.ts +3 -5
- package/dist/uuid-value.d.ts.map +1 -1
- package/dist/uuid-value.js +74 -78
- package/dist/uuid-value.js.map +1 -1
- package/dist/uuid.d.ts +6 -8
- package/dist/uuid.d.ts.map +1 -1
- package/dist/uuid.js +34 -45
- package/dist/uuid.js.map +1 -1
- package/dist/v4-slug.d.ts +2 -4
- package/dist/v4-slug.d.ts.map +1 -1
- package/dist/v4-slug.js +6 -7
- package/dist/v4.d.ts +8 -6
- package/dist/v4.d.ts.map +1 -1
- package/dist/v4.js +3 -9
- package/dist/v4.js.map +1 -1
- package/dist/v7-bounds.d.ts +3 -5
- package/dist/v7-bounds.d.ts.map +1 -1
- package/dist/v7-bounds.js +8 -9
- package/dist/v7-bounds.js.map +1 -1
- package/dist/v7-generator-input.js +10 -11
- package/dist/v7-generator-input.js.map +1 -1
- package/dist/v7-generator.d.ts +1 -3
- package/dist/v7-generator.d.ts.map +1 -1
- package/dist/v7-generator.js +13 -14
- package/dist/v7-keyless.d.ts +12 -4
- package/dist/v7-keyless.d.ts.map +1 -1
- package/dist/v7-keyless.js +2 -3
- package/dist/v7-keyless.js.map +1 -1
- package/dist/v7-payload.js +2 -3
- package/dist/v7-slug.d.ts +8 -5
- package/dist/v7-slug.d.ts.map +1 -1
- package/dist/v7-slug.js +28 -29
- package/dist/v7-slug.js.map +1 -1
- package/dist/v7-timestamp.js +2 -3
- package/dist/v7-value-options.js +2 -3
- package/dist/v7-value.d.ts +5 -8
- package/dist/v7-value.d.ts.map +1 -1
- package/dist/v7-value.js +10 -11
- package/dist/v7-value.js.map +1 -1
- package/dist/v7.js +16 -17
- package/dist/v7.js.map +1 -1
- package/package.json +6 -4
- package/src/alphabet.ts +84 -239
- package/src/errors.ts +30 -43
- package/src/feistel.ts +4 -4
- package/src/generation-options.ts +1 -1
- package/src/index.ts +3 -0
- package/src/mask-handle.ts +7 -11
- package/src/mask.ts +16 -14
- package/src/masked-bytes.ts +203 -0
- package/src/masking-codec-protocol.ts +1 -1
- package/src/masking-codec-types.ts +124 -24
- package/src/masking-codec.ts +44 -43
- package/src/migration.ts +8 -7
- package/src/payload.ts +71 -53
- package/src/runtime/bun.ts +1 -1
- package/src/runtime/node.ts +2 -2
- package/src/runtime/pool.ts +1 -1
- package/src/runtime/portable.ts +3 -3
- package/src/runtime/types.ts +2 -4
- package/src/slug.ts +45 -54
- package/src/types.ts +108 -17
- package/src/uuid-value-protocol.ts +1 -1
- package/src/uuid-value.ts +3 -10
- package/src/uuid.ts +27 -41
- package/src/v4.ts +14 -11
- package/src/v7-bounds.ts +7 -5
- package/src/v7-generator-input.ts +4 -7
- package/src/v7-generator.ts +2 -2
- package/src/v7-keyless.ts +35 -6
- package/src/v7-payload.ts +1 -1
- package/src/v7-slug.ts +21 -2
- package/src/v7-value.ts +9 -4
- package/src/v7.ts +27 -1
package/src/slug.ts
CHANGED
|
@@ -55,6 +55,7 @@ import type {
|
|
|
55
55
|
UuidV7StringFor,
|
|
56
56
|
UuidVersion,
|
|
57
57
|
KeylessUuidInput,
|
|
58
|
+
UnmaskedUuidInput,
|
|
58
59
|
} from "./types.ts";
|
|
59
60
|
import { UUID_TEXT_LOWERCASE } from "./types.ts";
|
|
60
61
|
import { uuidValueBytes } from "./uuid-value-protocol.ts";
|
|
@@ -76,9 +77,6 @@ import {
|
|
|
76
77
|
uuidVersion,
|
|
77
78
|
} from "./uuid.ts";
|
|
78
79
|
|
|
79
|
-
export { isUuidSlugError } from "./errors.ts";
|
|
80
|
-
export { UuidSlugError };
|
|
81
|
-
export type { UuidSlugErrorCode } from "./errors.ts";
|
|
82
80
|
export type { PlainUuidSlug, PlainUuidV4Slug, PlainUuidV7Slug } from "./types.ts";
|
|
83
81
|
|
|
84
82
|
const UUID_V7_TIMESTAMP_ONLY = "Timestamp is only defined for UUIDv7.";
|
|
@@ -160,17 +158,12 @@ const BYTE_OFFSET_NEEDS_BYTES =
|
|
|
160
158
|
*/
|
|
161
159
|
export type SlugAlphabet = typeof BASE64URL_NAME | typeof BASE32HEX_NAME;
|
|
162
160
|
|
|
163
|
-
const SLUG_ALPHABET_CODECS = {
|
|
164
|
-
base32hex: BASE32HEX,
|
|
165
|
-
base64url: BASE64URL,
|
|
166
|
-
} as const satisfies Record<SlugAlphabet, Alphabet>;
|
|
167
|
-
|
|
168
161
|
/** Reject values outside the public alphabet union when untyped JavaScript bypasses TypeScript. */
|
|
169
162
|
/*#__NO_SIDE_EFFECTS__*/
|
|
170
163
|
export function resolveSlugAlphabet(alphabet: SlugAlphabet): Alphabet | UuidSlugError {
|
|
171
164
|
const name = typeof alphabet === "string" ? alphabet : stringInput(alphabet);
|
|
172
165
|
// Fixed comparisons avoid an own-property call and keyed lookup on every conversion.
|
|
173
|
-
// Packed complete-call comparisons favor this over
|
|
166
|
+
// Packed complete-call comparisons favor this over a name-keyed lookup object; remeasure if
|
|
174
167
|
// the supported alphabet vocabulary grows. Wrapper normalization remains shared.
|
|
175
168
|
if (name === BASE64URL_NAME) return BASE64URL;
|
|
176
169
|
if (name === BASE32HEX_NAME) return BASE32HEX;
|
|
@@ -180,38 +173,33 @@ export function resolveSlugAlphabet(alphabet: SlugAlphabet): Alphabet | UuidSlug
|
|
|
180
173
|
);
|
|
181
174
|
}
|
|
182
175
|
|
|
183
|
-
/** Characters needed for 16 bytes: 22 in base64url, 26 in base32hex. */
|
|
184
|
-
/*#__NO_SIDE_EFFECTS__*/
|
|
185
|
-
function slugLength(alpha: Alphabet) {
|
|
186
|
-
return Math.ceil(128 / alpha.bitsPerChar);
|
|
187
|
-
}
|
|
188
|
-
|
|
189
176
|
/**
|
|
190
177
|
* Length -> alphabet, which is why decoding takes no alphabet argument: the two lengths are
|
|
191
178
|
* disjoint, so a slug names its own encoding and a caller cannot pick the wrong one. Indexed
|
|
192
179
|
* rather than searched because every decode and every type guard pays this lookup.
|
|
180
|
+
* The index is the characters 16 bytes need: ceil(128 / 6) = 22 in base64url, ceil(128 / 5) = 26
|
|
181
|
+
* in base32hex.
|
|
193
182
|
*/
|
|
194
|
-
const SLUG_ALPHABET_BY_LENGTH: readonly (Alphabet | undefined)[] = /*#__PURE__*/
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
table[
|
|
183
|
+
const SLUG_ALPHABET_BY_LENGTH: readonly (Alphabet | undefined)[] = /*#__PURE__*/ (() => {
|
|
184
|
+
const table: (Alphabet | undefined)[] = [];
|
|
185
|
+
table[22] = BASE64URL;
|
|
186
|
+
table[26] = BASE32HEX;
|
|
198
187
|
return table;
|
|
199
|
-
}
|
|
188
|
+
})();
|
|
200
189
|
|
|
201
|
-
const SLUG_LENGTHS =
|
|
202
|
-
.map((alpha) => `${slugLength(alpha)} (${alpha.name})`)
|
|
203
|
-
.join(ALTERNATIVE_SEPARATOR);
|
|
190
|
+
const SLUG_LENGTHS = `26 (${BASE32HEX_NAME})${ALTERNATIVE_SEPARATOR}22 (${BASE64URL_NAME})`;
|
|
204
191
|
|
|
205
192
|
/**
|
|
206
193
|
* Encode a standalone 16-byte UUID as a plain slug, using base64url by default. An `ArrayBuffer`
|
|
207
194
|
* uses its whole contents; a `DataView` uses its declared range. Invalid input or alphabet returns
|
|
208
195
|
* `UuidSlugError`. A preceding `UuidSlugError` is returned unchanged.
|
|
196
|
+
* TypeScript rejects known masked bytes; decode them with their masking codec first.
|
|
209
197
|
*
|
|
210
198
|
* @param bytes - One exact 16-byte UUID source.
|
|
211
199
|
* @param alphabet - Output spelling. Omit for the shorter 22-character base64url form.
|
|
212
200
|
*/
|
|
213
201
|
export function uuidBytesToPlainSlug(
|
|
214
|
-
bytes: UuidByteInput | UuidSlugError
|
|
202
|
+
bytes: UnmaskedUuidInput<Readonly<UuidByteInput> | UuidSlugError>,
|
|
215
203
|
alphabet?: SlugAlphabet,
|
|
216
204
|
): PlainUuidSlug | UuidSlugError;
|
|
217
205
|
/**
|
|
@@ -223,7 +211,7 @@ export function uuidBytesToPlainSlug(
|
|
|
223
211
|
* @param alphabet - Output spelling. Omit for the shorter 22-character base64url form.
|
|
224
212
|
*/
|
|
225
213
|
export function uuidBytesToPlainSlug(
|
|
226
|
-
bytes: Uint8Array | UuidSlugError
|
|
214
|
+
bytes: UnmaskedUuidInput<Readonly<Uint8Array> | UuidSlugError>,
|
|
227
215
|
byteOffset: number,
|
|
228
216
|
alphabet?: SlugAlphabet,
|
|
229
217
|
): PlainUuidSlug | UuidSlugError;
|
|
@@ -245,7 +233,7 @@ export function uuidBytesToPlainSlug(
|
|
|
245
233
|
if (selectedAlphabet === BASE32HEX_NAME) return encode(bytes, BASE32HEX) as PlainUuidSlug;
|
|
246
234
|
// Native encoding owns this exact plain-payload job. Offset windows and non-array forms retain
|
|
247
235
|
// general conversion; masked tails never enter here. Keep base32 controls in the comparison
|
|
248
|
-
// when changing this dispatch (bench/
|
|
236
|
+
// when changing this dispatch (bench/decisions.md).
|
|
249
237
|
if (selectedAlphabet === BASE64URL_NAME) {
|
|
250
238
|
if (nativePlainUuidBase64) {
|
|
251
239
|
try {
|
|
@@ -318,18 +306,13 @@ export function plainSlugToUuidBytes(
|
|
|
318
306
|
? checkRange(16, outputOffset, 16)
|
|
319
307
|
: checkByteRange(output, outputOffset, 16);
|
|
320
308
|
if (badRange) return badRange;
|
|
309
|
+
// A caller buffer must stay unchanged on failure, so invalid input is decoded into a throwaway
|
|
310
|
+
// array only to get the same diagnostic the no-buffer path returns. Valid input never allocates.
|
|
321
311
|
if (output && !isEncoded(slug, alpha, 16, true)) {
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
if (code >= 128 || (alpha.decode[code] as number) < 0)
|
|
325
|
-
return new UuidSlugError(
|
|
326
|
-
alpha.code,
|
|
327
|
-
`Invalid ${alpha.name} character ${JSON.stringify(slug[i])} at offset ${i}.`,
|
|
328
|
-
);
|
|
329
|
-
}
|
|
330
|
-
return new UuidSlugError(alpha.code, `${alpha.name} value has non-canonical trailing bits.`);
|
|
312
|
+
const failed = decodeInto(slug, alpha, new Uint8Array(16), 0);
|
|
313
|
+
if (failed instanceof Error) return failed;
|
|
331
314
|
}
|
|
332
|
-
const result = decodeInto(slug, alpha, target, outputOffset
|
|
315
|
+
const result = decodeInto(slug, alpha, target, outputOffset);
|
|
333
316
|
return result instanceof Error ? result : target;
|
|
334
317
|
}
|
|
335
318
|
|
|
@@ -361,7 +344,7 @@ export function uuidStringToPlainSlug(
|
|
|
361
344
|
// Resolve caller selectors before scratch is live, then parse and encode without callbacks.
|
|
362
345
|
// Separate text-to-slug
|
|
363
346
|
// writers read hex pairs and concatenated characters, and were slower on every runtime
|
|
364
|
-
// (bench/
|
|
347
|
+
// (bench/decisions.md). Reassess scratch ownership if encoding adds caller-controlled work.
|
|
365
348
|
const bytes = uuidStringToBytes(uuidText, textSlugScratch);
|
|
366
349
|
if (bytes instanceof Error) return bytes;
|
|
367
350
|
return encode(bytes, alpha) as PlainUuidSlug;
|
|
@@ -403,9 +386,7 @@ export function plainSlugToUuidString(
|
|
|
403
386
|
// Normalize before scratch is live, then decode and format without caller callbacks. Revisit
|
|
404
387
|
// reuse if either operation gains callbacks; failed writes cannot escape this private buffer.
|
|
405
388
|
// The public byte decoder owns invalid-length diagnostics, so keep that exceptional path shared.
|
|
406
|
-
const decoded = alpha
|
|
407
|
-
? decodeInto(slug, alpha, textSlugScratch, 0, 16)
|
|
408
|
-
: plainSlugToUuidBytes(slug);
|
|
389
|
+
const decoded = alpha ? decodeInto(slug, alpha, textSlugScratch, 0) : plainSlugToUuidBytes(slug);
|
|
409
390
|
if (decoded instanceof Error) return decoded;
|
|
410
391
|
// A successful decode yields exactly 16 bytes, so the checked formatter would repeat work.
|
|
411
392
|
return formatUuidBytesUnchecked(textSlugScratch, 0, selectedCase);
|
|
@@ -450,7 +431,8 @@ export function readObjectUuidInput(uuid: unknown): Uint8Array | string | UuidSl
|
|
|
450
431
|
*/
|
|
451
432
|
export function extractUuidVersion<Input extends UuidInput>(
|
|
452
433
|
uuid: KeylessUuidInput<Input>,
|
|
453
|
-
): UuidVersion | UuidSlugError
|
|
434
|
+
): UuidVersion | UuidSlugError;
|
|
435
|
+
export function extractUuidVersion(uuid: unknown): UuidVersion | UuidSlugError {
|
|
454
436
|
const localBytes = exactLocalUuidBytes(uuid);
|
|
455
437
|
if (localBytes) return uuidVersion(localBytes, 0);
|
|
456
438
|
const bytes = decodeKeylessUuid(uuid);
|
|
@@ -460,6 +442,7 @@ export function extractUuidVersion<Input extends UuidInput>(
|
|
|
460
442
|
|
|
461
443
|
/**
|
|
462
444
|
* Convert UUID text, bytes, or a plain UUID slug to new or caller-owned UUID bytes.
|
|
445
|
+
* Decode masked bytes with their masking codec before calling this reader.
|
|
463
446
|
* Only `Uint8Array` input accepts a non-zero offset; `0` means the same as omitting it.
|
|
464
447
|
*
|
|
465
448
|
* @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
|
|
@@ -472,9 +455,12 @@ export function uuidToBytes<Input extends UuidInput, Output extends Uint8Array>(
|
|
|
472
455
|
output: Output,
|
|
473
456
|
outputOffset?: number,
|
|
474
457
|
): UuidOutput<Output> | UuidSlugError;
|
|
475
|
-
export function uuidToBytes
|
|
476
|
-
|
|
477
|
-
|
|
458
|
+
export function uuidToBytes<Input extends Uint8Array>(
|
|
459
|
+
uuid: KeylessUuidInput<Input>,
|
|
460
|
+
byteOffset: number,
|
|
461
|
+
): UuidBytesResult<Uint8Array>;
|
|
462
|
+
export function uuidToBytes<Output extends Uint8Array, Input extends Uint8Array = Uint8Array>(
|
|
463
|
+
uuid: KeylessUuidInput<Input>,
|
|
478
464
|
byteOffset: number,
|
|
479
465
|
output: Output,
|
|
480
466
|
outputOffset?: number,
|
|
@@ -521,6 +507,7 @@ export function uuidToBytes(
|
|
|
521
507
|
|
|
522
508
|
/**
|
|
523
509
|
* Convert UUID text, bytes, or a plain UUID slug to normalized UUID text.
|
|
510
|
+
* Decode masked bytes with their masking codec before calling this reader.
|
|
524
511
|
* Only `Uint8Array` input accepts a non-zero offset; `0` means the same as omitting it.
|
|
525
512
|
*
|
|
526
513
|
* @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
|
|
@@ -532,8 +519,11 @@ export function uuidToString<
|
|
|
532
519
|
uuid: KeylessUuidInput<Input>,
|
|
533
520
|
...textCase: UuidTextCaseArguments<Case>
|
|
534
521
|
): UuidStringResult<Input, Case>;
|
|
535
|
-
export function uuidToString<
|
|
536
|
-
|
|
522
|
+
export function uuidToString<
|
|
523
|
+
Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE,
|
|
524
|
+
Input extends Uint8Array = Uint8Array,
|
|
525
|
+
>(
|
|
526
|
+
uuid: KeylessUuidInput<Input>,
|
|
537
527
|
byteOffset: number,
|
|
538
528
|
...textCase: UuidTextCaseArguments<Case>
|
|
539
529
|
): UuidStringResult<Uint8Array, Case>;
|
|
@@ -549,7 +539,7 @@ export function uuidToString(
|
|
|
549
539
|
textCase = caseAfterOffset;
|
|
550
540
|
} else textCase = byteOffsetOrCase;
|
|
551
541
|
// Canonical lowercase text is already the default output, so it is returned without decoding.
|
|
552
|
-
// An inline `typeof` guard ahead of the helper slowed Node mixed-case text (bench/
|
|
542
|
+
// An inline `typeof` guard ahead of the helper slowed Node mixed-case text (bench/decisions.md).
|
|
553
543
|
if (textCase === UUID_TEXT_LOWERCASE && isUuidString(uuid)) return uuid;
|
|
554
544
|
const localBytes = exactLocalUuidBytes(uuid);
|
|
555
545
|
if (localBytes) {
|
|
@@ -570,12 +560,12 @@ export function uuidToString(
|
|
|
570
560
|
}
|
|
571
561
|
}
|
|
572
562
|
// Only text leaves this call. Reuse private scratch instead of an owned decode array;
|
|
573
|
-
// public caller-buffer decoding adds validation and copying (bench/
|
|
563
|
+
// public caller-buffer decoding adds validation and copying (bench/decisions.md).
|
|
574
564
|
const alpha = typeof input === "string" ? SLUG_ALPHABET_BY_LENGTH[input.length] : undefined;
|
|
575
565
|
const decoded =
|
|
576
566
|
typeof input === "string"
|
|
577
567
|
? alpha
|
|
578
|
-
? decodeInto(input, alpha, textSlugScratch, 0
|
|
568
|
+
? decodeInto(input, alpha, textSlugScratch, 0)
|
|
579
569
|
: uuidStringToBytes(input)
|
|
580
570
|
: input;
|
|
581
571
|
const bytes = typeof decoded === "number" ? textSlugScratch : decoded;
|
|
@@ -589,6 +579,7 @@ export function uuidToString(
|
|
|
589
579
|
|
|
590
580
|
/**
|
|
591
581
|
* Convert UUID text, bytes, or a plain UUID slug to a plain slug.
|
|
582
|
+
* Decode masked bytes with their masking codec before calling this reader.
|
|
592
583
|
* Only `Uint8Array` input accepts a non-zero offset; `0` means the same as omitting it.
|
|
593
584
|
*
|
|
594
585
|
* @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
|
|
@@ -597,8 +588,8 @@ export function uuidToPlainSlug<Input extends UuidInput>(
|
|
|
597
588
|
uuid: KeylessUuidInput<Input>,
|
|
598
589
|
alphabet?: SlugAlphabet,
|
|
599
590
|
): PlainUuidSlugResult<Input>;
|
|
600
|
-
export function uuidToPlainSlug(
|
|
601
|
-
uuid:
|
|
591
|
+
export function uuidToPlainSlug<Input extends Uint8Array>(
|
|
592
|
+
uuid: KeylessUuidInput<Input>,
|
|
602
593
|
byteOffset: number,
|
|
603
594
|
alphabet?: SlugAlphabet,
|
|
604
595
|
): PlainUuidSlugResult<Uint8Array>;
|
|
@@ -671,7 +662,7 @@ function fixedCanonicalUuidV7UnixMs(text: string): number {
|
|
|
671
662
|
// low word so timestamps above its sign bit preserve all 48 bits. Only validated canonical text
|
|
672
663
|
// reaches this helper; compact text retains its contiguous parse. Table reads slightly favor
|
|
673
664
|
// Bun but lose on Node in the source screen; remeasure complete calls after parser or engine
|
|
674
|
-
// changes (bench/
|
|
665
|
+
// changes (bench/decisions.md).
|
|
675
666
|
const high =
|
|
676
667
|
(validatedHexNibble(text, 0) << 12) |
|
|
677
668
|
(validatedHexNibble(text, 1) << 8) |
|
|
@@ -696,7 +687,7 @@ function parsedCanonicalUuidV7UnixMs(text: string): number {
|
|
|
696
687
|
}
|
|
697
688
|
|
|
698
689
|
// Reuse the runtime's settled JIT selection; no flag parsing or table construction belongs here.
|
|
699
|
-
// Recheck both complete calls after engine changes against bench/
|
|
690
|
+
// Recheck both complete calls after engine changes against bench/decisions.md.
|
|
700
691
|
const canonicalUuidV7UnixMsUnchecked = runtime.jitless
|
|
701
692
|
? parsedCanonicalUuidV7UnixMs
|
|
702
693
|
: fixedCanonicalUuidV7UnixMs;
|
|
@@ -873,7 +864,7 @@ export function validatePlainUuidV7SlugUnixMs(
|
|
|
873
864
|
// validator captures all byte fields before caller-owned window accessors can reenter.
|
|
874
865
|
const alpha = SLUG_ALPHABET_BY_LENGTH[plainSlug.length];
|
|
875
866
|
const decoded = alpha
|
|
876
|
-
? decodeInto(plainSlug, alpha, textSlugScratch, 0
|
|
867
|
+
? decodeInto(plainSlug, alpha, textSlugScratch, 0)
|
|
877
868
|
: plainSlugToUuidBytes(plainSlug);
|
|
878
869
|
if (decoded instanceof Error) return decoded;
|
|
879
870
|
const bytes = typeof decoded === "number" ? textSlugScratch : decoded;
|
package/src/types.ts
CHANGED
|
@@ -33,6 +33,31 @@ export type UuidTextCase = typeof UUID_TEXT_LOWERCASE | typeof UUID_TEXT_UPPERCA
|
|
|
33
33
|
export type UuidTextCaseArguments<Case extends UuidTextCase> =
|
|
34
34
|
typeof UUID_TEXT_LOWERCASE extends Case ? [textCase?: Case] : [textCase: Case];
|
|
35
35
|
|
|
36
|
+
// Forwarded unions must keep the lowercase branch when the selector or its property is absent.
|
|
37
|
+
// Capturing the argument avoids claiming uppercase from an explicit generic alone.
|
|
38
|
+
export type UuidGenerationTextCase<Input> = Input extends UuidTextCase
|
|
39
|
+
? Input
|
|
40
|
+
: Input extends object
|
|
41
|
+
? "textCase" extends keyof Input
|
|
42
|
+
?
|
|
43
|
+
| Extract<Input["textCase"], UuidTextCase>
|
|
44
|
+
| (undefined extends Input["textCase"] ? typeof UUID_TEXT_LOWERCASE : never)
|
|
45
|
+
: typeof UUID_TEXT_LOWERCASE
|
|
46
|
+
: typeof UUID_TEXT_LOWERCASE;
|
|
47
|
+
|
|
48
|
+
// Module presets and omission throw entropy failures; configured calls return error values.
|
|
49
|
+
export type UuidGenerationFailure<Input> = Input extends object ? UuidSlugError : never;
|
|
50
|
+
|
|
51
|
+
// Capturing an argument suppresses excess-property checks; keep misspelled options rejected.
|
|
52
|
+
// Byte destinations are caller-owned arrays, so their own additional properties remain valid.
|
|
53
|
+
export type UuidGenerationInput<Input, Options> = Input extends Uint8Array
|
|
54
|
+
? Input
|
|
55
|
+
: Input extends object
|
|
56
|
+
? Exclude<keyof Input, keyof Options> extends never
|
|
57
|
+
? Input
|
|
58
|
+
: Input & { [Key in Exclude<keyof Input, keyof Options>]: never }
|
|
59
|
+
: Input;
|
|
60
|
+
|
|
36
61
|
// Keep selector inference at the property while requiring a non-default selector in reusable options.
|
|
37
62
|
type UuidTextCaseOptions<Case extends UuidTextCase> = typeof UUID_TEXT_LOWERCASE extends Case
|
|
38
63
|
? { readonly textCase?: Case }
|
|
@@ -133,7 +158,7 @@ export type PreserveUuidVersion<Input, UnknownVersion, Version4, Version7> =
|
|
|
133
158
|
? Version7
|
|
134
159
|
: UnknownVersion;
|
|
135
160
|
/** Infer a version from immutable input; mutable bytes retain the complete version-field range. */
|
|
136
|
-
|
|
161
|
+
type UuidVersionOf<Input> = Input extends UuidSlugError
|
|
137
162
|
? never
|
|
138
163
|
: Input extends Uuid<infer Version, boolean, boolean>
|
|
139
164
|
? Version
|
|
@@ -162,6 +187,13 @@ export type SentinelUuidV7Slug = Brand<PlainUuidV7Slug, "SentinelUuidV7Slug">;
|
|
|
162
187
|
/** A masking result: either a masked UUIDv7 or a registered plain sentinel. */
|
|
163
188
|
export type MaskedOrSentinelUuidV7Slug = MaskedUuidV7Slug | SentinelUuidV7Slug;
|
|
164
189
|
|
|
190
|
+
/** An owned 16-byte mixed UUIDv7 block with its 12-bit inner check; not raw UUID bytes. */
|
|
191
|
+
export type MaskedUuidV7Bytes = Brand<Uint8Array, "MaskedUuidV7Bytes">;
|
|
192
|
+
/** A registered sentinel's unmasked UUIDv7 bytes. */
|
|
193
|
+
export type SentinelUuidV7Bytes = Brand<UuidV7Bytes, "SentinelUuidV7Bytes">;
|
|
194
|
+
/** Binary masking output: a mixed block or a registered sentinel's raw UUID bytes. */
|
|
195
|
+
export type MaskedOrSentinelUuidV7Bytes = MaskedUuidV7Bytes | SentinelUuidV7Bytes;
|
|
196
|
+
|
|
165
197
|
/** One generated UUIDv7 in the selected text case and one selected slug made from the same bytes. */
|
|
166
198
|
export interface GeneratedUuidV7<
|
|
167
199
|
Slug extends PlainUuidV7Slug | MaskedOrSentinelUuidV7Slug,
|
|
@@ -333,6 +365,14 @@ type RejectKnownInput<Input, Invalid> = [Extract<Exclude<Input, UuidSlugError>,
|
|
|
333
365
|
? Input
|
|
334
366
|
: never;
|
|
335
367
|
|
|
368
|
+
/** Raw UUID readers cannot infer masked provenance from the identical 16-byte shape. */
|
|
369
|
+
// Keep the exclusion on the parameter: explicit case/output generics can default an inferred
|
|
370
|
+
// input to unbranded bytes. The object intersection accepts unrelated UUID brands too.
|
|
371
|
+
// Fixed byte-source unions use Readonly first so methods returning `this` do not revive a
|
|
372
|
+
// destination's previous brand after a writer returns its unbranded view.
|
|
373
|
+
export type UnmaskedUuidInput<Input> = Input & {
|
|
374
|
+
readonly [brand]?: object & { readonly MaskedUuidV7Bytes?: never };
|
|
375
|
+
};
|
|
336
376
|
/** Reject a known slug; the operation parses UUID text. A bare string is validated at runtime. */
|
|
337
377
|
export type UuidStringInput<Input extends string | UuidSlugError> = RejectKnownInput<
|
|
338
378
|
Input,
|
|
@@ -358,18 +398,25 @@ export type PlainUuidV7SlugInput<Input extends string | UuidSlugError> = RejectK
|
|
|
358
398
|
Input,
|
|
359
399
|
UuidText | MaskedUuidSlug | PlainUuidV4Slug
|
|
360
400
|
>;
|
|
361
|
-
/** Reject masked slugs and known UUIDv4 values across
|
|
401
|
+
/** Reject masked slugs, mixed bytes and known UUIDv4 values across timestamp inputs. */
|
|
362
402
|
export type UuidV7TimestampInput<Input extends string | UuidByteInput | UuidSlugError> =
|
|
363
|
-
RejectKnownInput<
|
|
364
|
-
|
|
403
|
+
RejectKnownInput<
|
|
404
|
+
Input,
|
|
405
|
+
MaskedUuidSlug | MaskedUuidV7Bytes | UuidV4Text | PlainUuidV4Slug | UuidV4Bytes
|
|
406
|
+
>;
|
|
407
|
+
/** Reject mixed and known UUIDv4 bytes; the operation needs raw UUIDv7 bytes. */
|
|
365
408
|
export type UuidV7BytesInput<Input extends UuidByteInput | UuidSlugError> = RejectKnownInput<
|
|
366
409
|
Input,
|
|
367
|
-
UuidV4Bytes
|
|
410
|
+
UuidV4Bytes | MaskedUuidV7Bytes
|
|
368
411
|
>;
|
|
369
412
|
/** Reject known non-v7 values; a masking codec accepts every UUIDv7 form. */
|
|
370
413
|
export type UuidV7ValueInput<Input extends UuidInput> = RejectKnownInput<
|
|
371
414
|
Input,
|
|
372
|
-
|
|
415
|
+
| UuidV4Text
|
|
416
|
+
| UuidV4Bytes
|
|
417
|
+
| PlainUuidV4Slug
|
|
418
|
+
| MaskedUuidV7Bytes
|
|
419
|
+
| AnyUuidForVersion<Exclude<UuidVersion, 7>>
|
|
373
420
|
>;
|
|
374
421
|
/** Exactly 16 validated UUID bytes. Package-owned values are plain `Uint8Array`. */
|
|
375
422
|
export type UuidBytes = Brand<Uint8Array, "UuidBytes">;
|
|
@@ -380,10 +427,17 @@ export type UuidV7Bytes = Brand<UuidBytes, "UuidV7Bytes">;
|
|
|
380
427
|
|
|
381
428
|
// Writers preserve the array and its methods, but prior UUID facts describe the replaced bytes.
|
|
382
429
|
// Strip only the package brand; erasing every subtype would also discard useful caller storage APIs.
|
|
383
|
-
export type UuidOutput<Output extends Uint8Array> = Output extends UuidBytes
|
|
430
|
+
export type UuidOutput<Output extends Uint8Array> = Output extends UuidBytes | MaskedUuidV7Bytes
|
|
384
431
|
? Omit<Output, typeof brand>
|
|
385
432
|
: Output;
|
|
386
433
|
|
|
434
|
+
// Storage remains a caller choice even when a wrapper forwards several generation forms.
|
|
435
|
+
export type UuidGenerationBytes<Input, Owned extends UuidBytes> = Input extends Uint8Array
|
|
436
|
+
? UuidOutput<Input>
|
|
437
|
+
: Input extends { readonly output: infer Output extends Uint8Array }
|
|
438
|
+
? UuidOutput<Output>
|
|
439
|
+
: Owned;
|
|
440
|
+
|
|
387
441
|
/** A UUID byte source: a `Uint8Array`, a complete `ArrayBuffer`, or a `DataView`'s declared range. */
|
|
388
442
|
export type UuidByteInput = Uint8Array | ArrayBuffer | DataView;
|
|
389
443
|
type AnyUuidForVersion<Version extends UuidVersion> = Uuid<Version, boolean, boolean>;
|
|
@@ -409,12 +463,8 @@ export type ParsedUuidResult<Input, WithCodec extends boolean = false> = Uuid<
|
|
|
409
463
|
* implementations also normalize genuine `String` objects; TypeScript uses primitive strings.
|
|
410
464
|
*/
|
|
411
465
|
export type UuidInput = string | UuidByteInput | AnyUuid | UuidSlugError;
|
|
412
|
-
/** Reject
|
|
413
|
-
export type KeylessUuidInput<Input> =
|
|
414
|
-
Extract<Exclude<Input, UuidSlugError>, MaskedUuidV7Slug>,
|
|
415
|
-
] extends [never]
|
|
416
|
-
? Input
|
|
417
|
-
: never;
|
|
466
|
+
/** Reject branded masked slugs or bytes where no masking codec is available. */
|
|
467
|
+
export type KeylessUuidInput<Input> = UnmaskedUuidInput<RejectKnownInput<Input, MaskedUuidV7Slug>>;
|
|
418
468
|
/** UUID text or the error returned while converting the captured input. */
|
|
419
469
|
export type UuidStringResult<Input, Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE> =
|
|
420
470
|
| PreserveUuidVersion<Input, UuidStringFor<Case>, UuidV4StringFor<Case>, UuidV7StringFor<Case>>
|
|
@@ -453,7 +503,7 @@ export interface UuidV7Generator {
|
|
|
453
503
|
/** Payload layout emitted by this generator; pass it to UUIDv7 payload extraction. */
|
|
454
504
|
readonly payloadLayout: UuidV7PayloadLayout;
|
|
455
505
|
/** Generate an immutable UUIDv7 that remembers this generator's payload layout. */
|
|
456
|
-
generateUuidV7Value(this: void
|
|
506
|
+
generateUuidV7Value(this: void): Uuid<7, false, true> | UuidSlugError;
|
|
457
507
|
/** Generate with supplied time or masking options; only a supplied codec is retained. */
|
|
458
508
|
generateUuidV7Value<const Options extends UuidV7GeneratorValueOptions | undefined>(
|
|
459
509
|
this: void,
|
|
@@ -471,6 +521,19 @@ export interface UuidV7Generator {
|
|
|
471
521
|
this: void,
|
|
472
522
|
options: Omit<GenerateUuidV7Options<Case>, "generator">,
|
|
473
523
|
): UuidV7StringFor<Case> | UuidSlugError;
|
|
524
|
+
/** Forward a spelling preset or optional settings through this generator's sequence. */
|
|
525
|
+
generateUuidV7<
|
|
526
|
+
const Input extends
|
|
527
|
+
| UuidTextCase
|
|
528
|
+
| Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
|
|
529
|
+
| undefined,
|
|
530
|
+
>(
|
|
531
|
+
this: void,
|
|
532
|
+
textCaseOrOptions: UuidGenerationInput<
|
|
533
|
+
Input,
|
|
534
|
+
Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
|
|
535
|
+
>,
|
|
536
|
+
): UuidV7StringFor<UuidGenerationTextCase<Input>> | UuidSlugError;
|
|
474
537
|
/** Generate a new plain 16-byte `Uint8Array` for the current clock reading. */
|
|
475
538
|
generateUuidV7Bytes(this: void): UuidV7Bytes | UuidSlugError;
|
|
476
539
|
/**
|
|
@@ -495,6 +558,20 @@ export interface UuidV7Generator {
|
|
|
495
558
|
this: void,
|
|
496
559
|
options: Omit<GenerateUuidV7BytesIntoOptions<Output>, "generator">,
|
|
497
560
|
): UuidOutput<Output> | UuidSlugError;
|
|
561
|
+
/** Forward optional storage or settings, preserving caller-array types and sequence state. */
|
|
562
|
+
generateUuidV7Bytes<
|
|
563
|
+
const Input extends
|
|
564
|
+
| Uint8Array
|
|
565
|
+
| Omit<GenerateUuidV7BytesOptions, "generator">
|
|
566
|
+
| Omit<GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
|
|
567
|
+
| undefined,
|
|
568
|
+
>(
|
|
569
|
+
this: void,
|
|
570
|
+
outOrOptions: UuidGenerationInput<
|
|
571
|
+
Input,
|
|
572
|
+
Omit<GenerateUuidV7BytesOptions & GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
|
|
573
|
+
>,
|
|
574
|
+
): UuidGenerationBytes<Input, UuidV7Bytes> | UuidSlugError;
|
|
498
575
|
/**
|
|
499
576
|
* Generate a plain UUIDv7 slug in this sequence. Lowercase base32hex preserves UUID byte order;
|
|
500
577
|
* base64url does not preserve that order under text comparison.
|
|
@@ -523,7 +600,7 @@ export interface UuidV7Generator {
|
|
|
523
600
|
): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
|
|
524
601
|
generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
|
|
525
602
|
this: void,
|
|
526
|
-
alphabet: SlugAlphabet,
|
|
603
|
+
alphabet: SlugAlphabet | undefined,
|
|
527
604
|
textCase: Case,
|
|
528
605
|
): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
|
|
529
606
|
/** Generate the pair at an explicit time or the current clock reading, in the selected spellings. */
|
|
@@ -531,6 +608,20 @@ export interface UuidV7Generator {
|
|
|
531
608
|
this: void,
|
|
532
609
|
options: Omit<GenerateUuidV7WithPlainSlugOptions<Case>, "generator">,
|
|
533
610
|
): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
|
|
611
|
+
/** Forward presets or optional settings through this sequence, retaining the UUID text case. */
|
|
612
|
+
generateUuidV7WithPlainSlug<
|
|
613
|
+
const Input extends
|
|
614
|
+
| SlugAlphabet
|
|
615
|
+
| UuidTextCase
|
|
616
|
+
| Omit<GenerateUuidV7WithPlainSlugOptions<UuidTextCase>, "generator">
|
|
617
|
+
| undefined,
|
|
618
|
+
>(
|
|
619
|
+
this: void,
|
|
620
|
+
alphabetOrCaseOrOptions: UuidGenerationInput<
|
|
621
|
+
Input,
|
|
622
|
+
Omit<GenerateUuidV7WithPlainSlugOptions<UuidTextCase>, "generator">
|
|
623
|
+
>,
|
|
624
|
+
): GeneratedUuidV7<PlainUuidV7Slug, UuidGenerationTextCase<Input>> | UuidSlugError;
|
|
534
625
|
}
|
|
535
626
|
|
|
536
627
|
/**
|
|
@@ -792,7 +883,7 @@ export interface UuidSlugMigrationDecoder<
|
|
|
792
883
|
uuidSlugToUuidString<Input extends string | UuidSlugError, Case extends UuidTextCase>(
|
|
793
884
|
this: void,
|
|
794
885
|
uuidSlug: SlugStringInput<Input>,
|
|
795
|
-
format: Format,
|
|
886
|
+
format: Format | undefined,
|
|
796
887
|
textCase: Case,
|
|
797
888
|
): UuidStringFor<Case> | UuidSlugError;
|
|
798
889
|
/**
|
|
@@ -821,7 +912,7 @@ export interface UuidSlugMigrationDecoder<
|
|
|
821
912
|
uuidSlugToUuidStringCandidates<Input extends string | UuidSlugError, Case extends UuidTextCase>(
|
|
822
913
|
this: void,
|
|
823
914
|
uuidSlug: SlugStringInput<Input>,
|
|
824
|
-
format: Format,
|
|
915
|
+
format: Format | undefined,
|
|
825
916
|
textCase: Case,
|
|
826
917
|
): readonly UuidStringFor<Case>[] | UuidSlugError;
|
|
827
918
|
}
|
|
@@ -11,7 +11,7 @@ export const UUID_VALUE_CONTEXT = Symbol.for("@anizoptera/uuid-slug.uuid-value-c
|
|
|
11
11
|
* importing the value class, and private fields keep the state off the frozen value's own properties.
|
|
12
12
|
*
|
|
13
13
|
* A module `WeakMap` keyed by value is the rejected alternative: registering each value cost more
|
|
14
|
-
* than the rest of value creation (bench/
|
|
14
|
+
* than the rest of value creation (bench/decisions.md). Remeasure if engines change how they
|
|
15
15
|
* store private fields or weak collections.
|
|
16
16
|
*/
|
|
17
17
|
export class LocalUuidValue {
|
package/src/uuid-value.ts
CHANGED
|
@@ -27,6 +27,7 @@ import {
|
|
|
27
27
|
} from "./types.ts";
|
|
28
28
|
import type {
|
|
29
29
|
KeylessUuidInput,
|
|
30
|
+
UnmaskedUuidInput,
|
|
30
31
|
MaskedOrSentinelUuidV7Slug,
|
|
31
32
|
PlainUuidSlugForVersion,
|
|
32
33
|
ParsedUuidResult,
|
|
@@ -74,7 +75,7 @@ class ParsedUuidValue<
|
|
|
74
75
|
{
|
|
75
76
|
// Private bytes are already a complete immutable UUID; public conversion would validate them
|
|
76
77
|
// again. Resolve caller selectors, then use the same writers directly without caching spellings.
|
|
77
|
-
// Revisit if private storage becomes mutable or borrowed; measurements live in bench/
|
|
78
|
+
// Revisit if private storage becomes mutable or borrowed; measurements live in bench/decisions.md.
|
|
78
79
|
get version(): Version {
|
|
79
80
|
return uuidVersion(LocalUuidValue.ownBytes(this), 0) as Version;
|
|
80
81
|
}
|
|
@@ -279,7 +280,7 @@ export function parseUuid<Input extends UuidInput>(
|
|
|
279
280
|
* thrown exceptions remain available as the error's `cause`.
|
|
280
281
|
*/
|
|
281
282
|
export function parseUuid<Input extends UuidInput>(
|
|
282
|
-
uuid: Input
|
|
283
|
+
uuid: UnmaskedUuidInput<Input>,
|
|
283
284
|
maskingCodec: UuidV7MaskingCodec,
|
|
284
285
|
): ParsedUuidResult<Input, true> | UuidSlugError;
|
|
285
286
|
export function parseUuid(
|
|
@@ -331,11 +332,3 @@ export function parseUuid(
|
|
|
331
332
|
existing ? LocalUuidValue.ownPayloadLayout(existing) : foreignContext?.payloadLayout,
|
|
332
333
|
);
|
|
333
334
|
}
|
|
334
|
-
|
|
335
|
-
/** Parse with the supplied masking codec preset by an owner method. */
|
|
336
|
-
export function parseUuidWithCodec<Input extends UuidInput>(
|
|
337
|
-
uuid: Input,
|
|
338
|
-
maskingCodec: UuidV7MaskingCodec,
|
|
339
|
-
): ParsedUuidResult<Input, true> | UuidSlugError {
|
|
340
|
-
return parseUuid(uuid, maskingCodec);
|
|
341
|
-
}
|