@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/uuid.ts
CHANGED
|
@@ -18,6 +18,7 @@ import type { Latin1Scratch } from "./runtime/types.ts";
|
|
|
18
18
|
import { UUID_TEXT_LOWERCASE, UUID_TEXT_UPPERCASE } from "./types.ts";
|
|
19
19
|
import type {
|
|
20
20
|
PreserveUuidVersion,
|
|
21
|
+
UnmaskedUuidInput,
|
|
21
22
|
UuidBytes,
|
|
22
23
|
UuidByteInput,
|
|
23
24
|
UuidV4Bytes,
|
|
@@ -36,11 +37,6 @@ import type {
|
|
|
36
37
|
UuidVersion,
|
|
37
38
|
} from "./types.ts";
|
|
38
39
|
|
|
39
|
-
export { isUuidSlugError } from "./errors.ts";
|
|
40
|
-
export { UuidSlugError };
|
|
41
|
-
export type { UuidSlugErrorCode } from "./errors.ts";
|
|
42
|
-
export type { UuidBytes, UuidString } from "./types.ts";
|
|
43
|
-
|
|
44
40
|
/** Report byte input that does not hold exactly one 16-byte UUID. */
|
|
45
41
|
export const invalidUuidBytes = /* @__NO_SIDE_EFFECTS__ */ (): UuidSlugError =>
|
|
46
42
|
new UuidSlugError(INVALID_BUFFER, "UUID byte input must contain exactly 16 bytes.");
|
|
@@ -70,16 +66,12 @@ export const isUuidTextCase = (value: unknown): value is UuidTextCase =>
|
|
|
70
66
|
export function resolveUuidTextCase(value: unknown): UuidTextCase | UuidSlugError {
|
|
71
67
|
if (value === UUID_TEXT_LOWERCASE || value === UUID_TEXT_UPPERCASE) return value;
|
|
72
68
|
const textCase = stringInput(value);
|
|
73
|
-
return isUuidTextCase(textCase)
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
return new UuidSlugError(INVALID_OPTIONS, "UUID text case must be lowercase or uppercase.");
|
|
69
|
+
return isUuidTextCase(textCase)
|
|
70
|
+
? textCase
|
|
71
|
+
: new UuidSlugError(INVALID_OPTIONS, "UUID text case must be lowercase or uppercase.");
|
|
77
72
|
}
|
|
78
73
|
const createLatin1Scratch = runtime.latin1Scratch;
|
|
79
74
|
const nativeToHex = runtime.uuidHex;
|
|
80
|
-
const HEX_DECODE = new Int8Array(128).fill(-1);
|
|
81
|
-
for (let i = 0; i < 10; i += 1) HEX_DECODE[48 + i] = i;
|
|
82
|
-
for (let i = 0; i < 6; i += 1) HEX_DECODE[97 + i] = 10 + i;
|
|
83
75
|
// Nibbles of both hex cases; 0x100 marks every other ASCII character so OR-ed pairs expose it.
|
|
84
76
|
const HEX_NIBBLES = new Uint16Array(128).fill(0x100);
|
|
85
77
|
for (let i = 0; i < 16; i += 1) {
|
|
@@ -87,7 +79,7 @@ for (let i = 0; i < 16; i += 1) {
|
|
|
87
79
|
HEX_NIBBLES[UPPERCASE_HEX.charCodeAt(i)] = i;
|
|
88
80
|
}
|
|
89
81
|
// Bun's Latin-1 writer and the fixed writer share lazily built case tables; native hex needs none.
|
|
90
|
-
// bench/
|
|
82
|
+
// bench/decisions.md owns the comparison and recheck conditions. Tables are built on first use.
|
|
91
83
|
let uuidTextScratch: Latin1Scratch | undefined;
|
|
92
84
|
let lowercaseHexCodes: Uint8Array | undefined;
|
|
93
85
|
let uppercaseHexCodes: Uint8Array | undefined;
|
|
@@ -123,7 +115,7 @@ function formatUuidBytesLatin1(
|
|
|
123
115
|
: (lowercaseHexCodes ??= hexCodes(HEX));
|
|
124
116
|
const text = scratch.bytes;
|
|
125
117
|
// Fixed positions remove the loop and offset-table reads on Bun's selected writer.
|
|
126
|
-
// The indexed loop loses repeated complete text calls; bench/
|
|
118
|
+
// The indexed loop loses repeated complete text calls; bench/decisions.md owns the evidence.
|
|
127
119
|
// Keep native string construction and shared storage; remeasure after JSC or writer changes.
|
|
128
120
|
const code0 = (bytes[offset + 0] as number) * 2;
|
|
129
121
|
text[0] = codes[code0] as number;
|
|
@@ -202,14 +194,11 @@ function uuidTextStart(value: string): number {
|
|
|
202
194
|
return INVALID_UUID_TEXT_START;
|
|
203
195
|
}
|
|
204
196
|
|
|
197
|
+
// Either hex case; above 15 means not a digit. `charCodeAt` past the end gives NaN and non-ASCII
|
|
198
|
+
// codes index past the table; both read undefined, hence the fallback.
|
|
205
199
|
/*#__NO_SIDE_EFFECTS__*/
|
|
206
|
-
function
|
|
207
|
-
return
|
|
208
|
-
}
|
|
209
|
-
|
|
210
|
-
/*#__NO_SIDE_EFFECTS__*/
|
|
211
|
-
function parsedHexValue(code: number) {
|
|
212
|
-
return code >= 65 && code <= 70 ? code - 55 : lowercaseHexValue(code);
|
|
200
|
+
function hexNibble(code: number) {
|
|
201
|
+
return HEX_NIBBLES[code] ?? 0x100;
|
|
213
202
|
}
|
|
214
203
|
|
|
215
204
|
/**
|
|
@@ -267,7 +256,7 @@ export function uuidStringToBytes(
|
|
|
267
256
|
|
|
268
257
|
// One pass decodes and validates: OR-ing every character code and every decoded pair exposes a
|
|
269
258
|
// non-ASCII or non-hex character after the loop. Validating before a second decoding pass cost
|
|
270
|
-
// about twice as much on Node and three times on Bun (bench/
|
|
259
|
+
// about twice as much on Node and three times on Bun (bench/decisions.md). Only failing text
|
|
271
260
|
// pays a second scan, which locates the offset for the message.
|
|
272
261
|
const target = out === undefined ? new Uint8Array(16) : decodedUuidScratch;
|
|
273
262
|
let codes = 0;
|
|
@@ -286,7 +275,7 @@ export function uuidStringToBytes(
|
|
|
286
275
|
if (codes < 128 && pairs < 256) {
|
|
287
276
|
if (out === undefined) return target;
|
|
288
277
|
// A byte loop rather than `set`: the native call made Bun text-to-slug conversion slower
|
|
289
|
-
// (bench/
|
|
278
|
+
// (bench/decisions.md).
|
|
290
279
|
for (let byteIndex = 0; byteIndex < 16; byteIndex += 1)
|
|
291
280
|
out[offset + byteIndex] = target[byteIndex] as number;
|
|
292
281
|
return out;
|
|
@@ -316,6 +305,7 @@ export function uuidStringToBytes(
|
|
|
316
305
|
* `ArrayBuffer` uses its whole contents; a `DataView` uses its declared range. Only `Uint8Array`
|
|
317
306
|
* input accepts an explicit offset. Invalid input returns `invalid_buffer`, and a preceding
|
|
318
307
|
* `UuidSlugError` is returned unchanged.
|
|
308
|
+
* TypeScript rejects known masked bytes; decode them with their masking codec first.
|
|
319
309
|
*
|
|
320
310
|
* @param bytes - One supported UUID byte source.
|
|
321
311
|
* @param textCase - Built-in output spelling. Omit for lowercase.
|
|
@@ -323,11 +313,11 @@ export function uuidStringToBytes(
|
|
|
323
313
|
* @param byteOffset - Zero-based index where the UUID starts. Omit for a standalone UUID.
|
|
324
314
|
*/
|
|
325
315
|
export function bytesToUuidString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
326
|
-
bytes: UuidByteInput | UuidSlugError
|
|
316
|
+
bytes: UnmaskedUuidInput<Readonly<UuidByteInput> | UuidSlugError>,
|
|
327
317
|
...textCase: UuidTextCaseArguments<Case>
|
|
328
318
|
): UuidStringFor<Case> | UuidSlugError;
|
|
329
319
|
export function bytesToUuidString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
330
|
-
bytes: Uint8Array | UuidSlugError
|
|
320
|
+
bytes: UnmaskedUuidInput<Readonly<Uint8Array> | UuidSlugError>,
|
|
331
321
|
byteOffset: number,
|
|
332
322
|
...textCase: UuidTextCaseArguments<Case>
|
|
333
323
|
): UuidStringFor<Case> | UuidSlugError;
|
|
@@ -350,6 +340,7 @@ export function bytesToUuidString(
|
|
|
350
340
|
if (badRange) return badRange;
|
|
351
341
|
if (nativeToHex) {
|
|
352
342
|
// A small existing view avoids another view; a larger buffer must not encode unrelated bytes.
|
|
343
|
+
// Keep range selection here: unchecked fixed-size callers should not pay this branch.
|
|
353
344
|
const hex =
|
|
354
345
|
view.length <= 32
|
|
355
346
|
? nativeToHex(view)
|
|
@@ -374,7 +365,7 @@ export function formatUuidBytesUnchecked<Case extends UuidTextCase = typeof UUID
|
|
|
374
365
|
// Bun retains its Latin-1 writer. A fixed argument list makes one flat string without
|
|
375
366
|
// temporary bytes, intermediate hex or concatenation. WebKit selects native hex to avoid
|
|
376
367
|
// repeated mixed-workload losses; remeasure both paths after engine changes
|
|
377
|
-
// (bench/
|
|
368
|
+
// (bench/decisions.md). Keep case selection and fixed writing together to avoid another call.
|
|
378
369
|
if (createLatin1Scratch)
|
|
379
370
|
return formatUuidBytesLatin1(
|
|
380
371
|
createLatin1Scratch,
|
|
@@ -474,20 +465,17 @@ export function isUuidText(value: unknown): value is UuidText {
|
|
|
474
465
|
return false;
|
|
475
466
|
for (let i = 0; i < UUID_BYTE_OFFSETS.length; i += 1) {
|
|
476
467
|
const offset = hyphenated ? textStart + (UUID_BYTE_OFFSETS[i] as number) : i * 2;
|
|
477
|
-
if (
|
|
478
|
-
parsedHexValue(value.charCodeAt(offset)) < 0 ||
|
|
479
|
-
parsedHexValue(value.charCodeAt(offset + 1)) < 0
|
|
480
|
-
)
|
|
468
|
+
if (hexNibble(value.charCodeAt(offset)) > 15 || hexNibble(value.charCodeAt(offset + 1)) > 15)
|
|
481
469
|
return false;
|
|
482
470
|
}
|
|
483
471
|
return true;
|
|
484
472
|
}
|
|
485
473
|
|
|
486
474
|
// Canonical guards stay regular expressions: a character loop measured slower on Node and Bun
|
|
487
|
-
// (bench/
|
|
475
|
+
// (bench/decisions.md, Canonical UUID text).
|
|
488
476
|
// Pair repetition improves canonical calls, but slows Bun's successful base32 normalization.
|
|
489
477
|
// Reuse its existing Latin-1 selection once; neither pattern needs a builder or per-call dispatch.
|
|
490
|
-
// Remeasure normalization if this capability moves to another adapter (bench/
|
|
478
|
+
// Remeasure normalization if this capability moves to another adapter (bench/decisions.md).
|
|
491
479
|
const UUID_RE = createLatin1Scratch
|
|
492
480
|
? /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
|
|
493
481
|
: /^(?:[0-9a-f][0-9a-f]){4}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){2}-(?:[0-9a-f][0-9a-f]){6}$/;
|
|
@@ -500,13 +488,12 @@ const UUID_V7_TEXT_RE = /*#__PURE__*/ new RegExp(UUID_V7_RE.source, "i");
|
|
|
500
488
|
export function isUuidV4Text(value: unknown): value is UuidV4Text {
|
|
501
489
|
if (!isUuidText(value)) return false;
|
|
502
490
|
const textStart = uuidTextStart(value);
|
|
503
|
-
const variant =
|
|
491
|
+
const variant = hexNibble(
|
|
504
492
|
value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 16 : textStart + 19),
|
|
505
493
|
);
|
|
506
494
|
return (
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
) === 4 &&
|
|
495
|
+
hexNibble(value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 12 : textStart + 14)) ===
|
|
496
|
+
4 &&
|
|
510
497
|
variant >= 8 &&
|
|
511
498
|
variant <= 11
|
|
512
499
|
);
|
|
@@ -517,17 +504,16 @@ export function isUuidV4Text(value: unknown): value is UuidV4Text {
|
|
|
517
504
|
export function isUuidV7Text(value: unknown): value is UuidV7Text {
|
|
518
505
|
// Canonical text uses the same syntax with either case, avoiding the full digit loop before
|
|
519
506
|
// timestamp parsing. Other spellings retain their existing checks; remeasure after engine or
|
|
520
|
-
// accepted-syntax changes (bench/
|
|
507
|
+
// accepted-syntax changes (bench/decisions.md).
|
|
521
508
|
if (typeof value === "string" && value.length === UUID_LENGTH) return UUID_V7_TEXT_RE.test(value);
|
|
522
509
|
if (!isUuidText(value)) return false;
|
|
523
510
|
const textStart = uuidTextStart(value);
|
|
524
|
-
const variant =
|
|
511
|
+
const variant = hexNibble(
|
|
525
512
|
value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 16 : textStart + 19),
|
|
526
513
|
);
|
|
527
514
|
return (
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
) === 7 &&
|
|
515
|
+
hexNibble(value.charCodeAt(textStart === COMPACT_UUID_TEXT_START ? 12 : textStart + 14)) ===
|
|
516
|
+
7 &&
|
|
531
517
|
variant >= 8 &&
|
|
532
518
|
variant <= 11
|
|
533
519
|
);
|
package/src/v4.ts
CHANGED
|
@@ -13,6 +13,8 @@ import {
|
|
|
13
13
|
} from "./errors.ts";
|
|
14
14
|
import { UUID_TEXT_LOWERCASE, UUID_TEXT_UPPERCASE } from "./types.ts";
|
|
15
15
|
import type {
|
|
16
|
+
UuidGenerationBytes,
|
|
17
|
+
UuidGenerationFailure,
|
|
16
18
|
UuidRandomFill,
|
|
17
19
|
UuidOutput,
|
|
18
20
|
UuidTextCase,
|
|
@@ -27,9 +29,6 @@ import {
|
|
|
27
29
|
resolveUuidTextCase,
|
|
28
30
|
} from "./uuid.ts";
|
|
29
31
|
|
|
30
|
-
export { isUuidSlugError } from "./errors.ts";
|
|
31
|
-
export { UuidSlugError };
|
|
32
|
-
export type { UuidSlugErrorCode } from "./errors.ts";
|
|
33
32
|
export type { UuidV4Bytes, UuidV4String } from "./types.ts";
|
|
34
33
|
export { isUuidV4Bytes, isUuidV4String, isUuidV4Text } from "./uuid.ts";
|
|
35
34
|
|
|
@@ -62,6 +61,13 @@ export function generateUuidV4Bytes<Output extends Uint8Array>(
|
|
|
62
61
|
output: Output,
|
|
63
62
|
outputOffset?: number,
|
|
64
63
|
): UuidOutput<Output> | UuidSlugError;
|
|
64
|
+
/**
|
|
65
|
+
* Use caller storage when supplied; otherwise allocate UUIDv4 bytes.
|
|
66
|
+
* @throws `UuidSlugError` with code `rng_unavailable` when storage is omitted and secure randomness is unavailable.
|
|
67
|
+
*/
|
|
68
|
+
export function generateUuidV4Bytes<const Input extends Uint8Array | undefined>(
|
|
69
|
+
output: Input,
|
|
70
|
+
): UuidGenerationBytes<Input, UuidV4Bytes> | UuidGenerationFailure<Input>;
|
|
65
71
|
export function generateUuidV4Bytes(
|
|
66
72
|
output?: Uint8Array,
|
|
67
73
|
outputOffset = 0,
|
|
@@ -91,7 +97,7 @@ export function generateUuidV4Bytes(
|
|
|
91
97
|
// Keep owned output separate so it can draw directly into its result without adding a post-draw
|
|
92
98
|
// ownership branch to caller-buffer writes. Merge the paths if either primary runtime loses this win.
|
|
93
99
|
// Failures are returned so slug and text callers can decide at their own public seam.
|
|
94
|
-
|
|
100
|
+
function generateOwnedUuidV4Bytes(): UuidV4Bytes | UuidSlugError {
|
|
95
101
|
if (generating) return new UuidSlugError(RNG_UNAVAILABLE, REENTRANT_GENERATION_MESSAGE);
|
|
96
102
|
const output = new Uint8Array(16);
|
|
97
103
|
generating = true;
|
|
@@ -109,15 +115,12 @@ export function generateOwnedUuidV4Bytes(): UuidV4Bytes | UuidSlugError {
|
|
|
109
115
|
/**
|
|
110
116
|
* Generate UUIDv4 text through the portable implementation, even on native-capable hosts.
|
|
111
117
|
* Failures are returned so the native path can aggregate them with its own cause.
|
|
118
|
+
* `textCase` must already be resolved: `generateUuidV4` resolves it before calling, and the native
|
|
119
|
+
* fallback passes lowercase, so a second check here would only slow every portable call.
|
|
112
120
|
*/
|
|
113
121
|
export function generatePortableUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
114
122
|
textCase: Case = UUID_TEXT_LOWERCASE as Case,
|
|
115
123
|
): UuidV4StringFor<Case> | UuidSlugError {
|
|
116
|
-
if (!isUuidTextCase(textCase)) {
|
|
117
|
-
const selectedCase = resolveUuidTextCase(textCase);
|
|
118
|
-
if (selectedCase instanceof Error) return selectedCase;
|
|
119
|
-
textCase = selectedCase as Case;
|
|
120
|
-
}
|
|
121
124
|
const bytes = drawUuidV4Scratch();
|
|
122
125
|
return bytes instanceof Error
|
|
123
126
|
? bytes
|
|
@@ -127,7 +130,7 @@ export function generatePortableUuidV4<Case extends UuidTextCase = typeof UUID_T
|
|
|
127
130
|
/**
|
|
128
131
|
* Fill the module scratch with UUIDv4 bytes for a writer that reads them before its next draw. Text
|
|
129
132
|
* and slug writers never expose the scratch, so they skip a new array and the public converters'
|
|
130
|
-
* input checks, which cost about a third of Node's portable text call (bench/
|
|
133
|
+
* input checks, which cost about a third of Node's portable text call (bench/decisions.md).
|
|
131
134
|
* Encoding cannot draw entropy, so the scratch cannot change between this return and the read.
|
|
132
135
|
*/
|
|
133
136
|
export function drawUuidV4Scratch(): Uint8Array | UuidSlugError {
|
|
@@ -172,7 +175,7 @@ export function generateUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWE
|
|
|
172
175
|
// Trust proper native output directly: validation and identity tracking impose guarantees
|
|
173
176
|
// beyond the default native baseline. Configured entropy still validates at its caller seam.
|
|
174
177
|
// Remeasure each output form if case normalization, host APIs or engine inlining
|
|
175
|
-
// changes; bench/
|
|
178
|
+
// changes; bench/decisions.md owns the evidence.
|
|
176
179
|
const native = runtime.uuidV4;
|
|
177
180
|
if (!native) return generatedOrThrow(generatePortableUuidV4(textCase));
|
|
178
181
|
let uuid: string | UuidSlugError;
|
package/src/v7-bounds.ts
CHANGED
|
@@ -27,6 +27,8 @@ function intervalEnd(startUnixMs: number, endUnixMs: number): number | UuidSlugE
|
|
|
27
27
|
function endpoint(unixMs: number, upper: boolean): UuidV7Bytes {
|
|
28
28
|
const bytes = new Uint8Array(16);
|
|
29
29
|
if (upper) bytes.fill(0xff);
|
|
30
|
+
// Keep this fixed write local: sharing the generator's word writer slows JITless bounds calls.
|
|
31
|
+
// Reconsider extraction only with complete-call evidence across the supported engines.
|
|
30
32
|
const high = Math.floor(unixMs / 0x1_0000_0000);
|
|
31
33
|
bytes[0] = high >>> 8;
|
|
32
34
|
bytes[1] = high;
|
|
@@ -70,7 +72,7 @@ function fixedTextEndpoint<Case extends UuidTextCase>(
|
|
|
70
72
|
): UuidV7StringFor<Case> {
|
|
71
73
|
// Fixed character arguments reduce consumed bounds costs on V8 with the JIT. Byte pairs remain
|
|
72
74
|
// faster on Bun and JITless Node; selection is outside per-ID calls. Remeasure engine changes
|
|
73
|
-
// against bench/
|
|
75
|
+
// against bench/decisions.md, including both endpoint reads and lazy table construction.
|
|
74
76
|
const hex = (hexCodes ??= Uint8Array.from("0123456789abcdef", (digit) => digit.charCodeAt(0)));
|
|
75
77
|
// Validated timestamps have 48 bits; splitting avoids truncating their upper 16 bits.
|
|
76
78
|
const high = Math.floor(unixMs / 0x1_0000_0000);
|
|
@@ -102,7 +104,7 @@ function textEndpoint<Case extends UuidTextCase>(
|
|
|
102
104
|
): UuidV7StringFor<Case> {
|
|
103
105
|
// Byte pairs avoid radix formatting and beat fixed character arguments on Bun and JITless Node.
|
|
104
106
|
// Build the table on first use so imports that never request bounds pay no table construction.
|
|
105
|
-
// Remeasure radix formatting and fixed arguments after engine changes (bench/
|
|
107
|
+
// Remeasure radix formatting and fixed arguments after engine changes (bench/decisions.md).
|
|
106
108
|
const hex = (hexBytes ??= Array.from({ length: 256 }, (_, byte) =>
|
|
107
109
|
byte.toString(16).padStart(2, "0"),
|
|
108
110
|
));
|
|
@@ -143,13 +145,13 @@ export function uuidV7StringBounds<Case extends UuidTextCase = typeof UUID_TEXT_
|
|
|
143
145
|
* interval. The comparison must preserve UUID byte order.
|
|
144
146
|
*
|
|
145
147
|
* @param startUnixMs - First whole Unix millisecond, inclusive.
|
|
146
|
-
* @param endUnixMs - Last whole Unix millisecond, inclusive.
|
|
148
|
+
* @param endUnixMs - Last whole Unix millisecond, inclusive. Use `undefined` for `startUnixMs`.
|
|
147
149
|
* @param textCase - Built-in output spelling. Omit for lowercase.
|
|
148
150
|
* @returns Canonical UUIDv7 endpoints, or `invalid_timestamp` for an invalid interval.
|
|
149
151
|
*/
|
|
150
152
|
export function uuidV7StringBounds<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
151
153
|
startUnixMs: number,
|
|
152
|
-
endUnixMs: number,
|
|
154
|
+
endUnixMs: number | undefined,
|
|
153
155
|
...textCase: UuidTextCaseArguments<Case>
|
|
154
156
|
): UuidV7Bounds<UuidV7StringFor<Case>> | UuidSlugError;
|
|
155
157
|
export function uuidV7StringBounds(
|
|
@@ -163,7 +165,7 @@ export function uuidV7StringBounds(
|
|
|
163
165
|
const end = intervalEnd(startUnixMs, endUnixMs);
|
|
164
166
|
if (typeof end !== "number") return end;
|
|
165
167
|
// Direct formatting avoids two temporary byte arrays. Keep the byte writer independent unless
|
|
166
|
-
// repeated public-route measurements reverse this result; bench/
|
|
168
|
+
// repeated public-route measurements reverse this result; bench/decisions.md owns that trigger.
|
|
167
169
|
return {
|
|
168
170
|
startInclusive: selectedTextEndpoint(startUnixMs, false, textCase),
|
|
169
171
|
endInclusive: selectedTextEndpoint(end, true, textCase),
|
|
@@ -9,6 +9,7 @@ import {
|
|
|
9
9
|
UuidSlugError,
|
|
10
10
|
} from "./errors.ts";
|
|
11
11
|
import type { UuidV7Generator, UuidV7Instant, UuidV7PayloadLayout } from "./types.ts";
|
|
12
|
+
import type { GenerationOptionValues } from "./generation-options.ts";
|
|
12
13
|
import type { PortableUuidV7Generator } from "./v7.ts";
|
|
13
14
|
import { readUuidV7Instant } from "./instant.ts";
|
|
14
15
|
import { readUuidV7PayloadLayout, uuidV7PayloadFromBytesUnchecked } from "./v7-payload.ts";
|
|
@@ -17,11 +18,7 @@ import { isUuidV7Bytes, uuidTimestampFromBytesUnchecked } from "./uuid.ts";
|
|
|
17
18
|
const AT_OPTION = "at";
|
|
18
19
|
const UUID_V7_GENERATOR_REQUIRED = "generator must be a UUIDv7 generator.";
|
|
19
20
|
|
|
20
|
-
export
|
|
21
|
-
readonly at?: unknown;
|
|
22
|
-
readonly output?: unknown;
|
|
23
|
-
readonly outputOffset?: unknown;
|
|
24
|
-
}
|
|
21
|
+
export type UuidV7GenerationValues = Pick<GenerationOptionValues, "at" | "output" | "outputOffset">;
|
|
25
22
|
|
|
26
23
|
export interface ValidatedUuidV7Generator {
|
|
27
24
|
readonly generateUuidV7Bytes: UuidV7Generator["generateUuidV7Bytes"];
|
|
@@ -48,7 +45,7 @@ class ReturnObject {
|
|
|
48
45
|
*
|
|
49
46
|
* Structural validation allocated a validated object and rescanned the layout keys on every call
|
|
50
47
|
* that passed `generator`, and the untrusted-generator call then needed a scratch buffer, byte
|
|
51
|
-
* validation, an `at` check, and a copy (bench/
|
|
48
|
+
* validation, an `at` check, and a copy (bench/decisions.md). The stamp adds a private field
|
|
52
49
|
* instead of a class prototype, so the public object stays plain. A module `WeakMap` is the rejected
|
|
53
50
|
* alternative: registration made default generator creation 1.6 times slower. Remeasure if engines
|
|
54
51
|
* change how they store private fields or weak collections.
|
|
@@ -106,7 +103,7 @@ export function readUuidV7Generator(
|
|
|
106
103
|
*
|
|
107
104
|
* The generator receives the result buffer and may keep a reference to it, so a result the caller
|
|
108
105
|
* keeps is a copy. Pass `borrowed` only when the package consumes the bytes before returning and
|
|
109
|
-
* never returns them: text, slug, and masked-slug writers skip that copy (bench/
|
|
106
|
+
* never returns them: text, slug, and masked-slug writers skip that copy (bench/decisions.md).
|
|
110
107
|
*/
|
|
111
108
|
export function generateUuidV7BytesWithGenerator(
|
|
112
109
|
generator: ValidatedUuidV7Generator,
|
package/src/v7-generator.ts
CHANGED
|
@@ -180,8 +180,8 @@ function buildGenerator(
|
|
|
180
180
|
return instant instanceof Error ? instant : generator.drawUuidV7Bytes(instant);
|
|
181
181
|
};
|
|
182
182
|
// Omission cannot prove a retained codec; the configured overload requires its runtime options.
|
|
183
|
-
function generateUuidV7Value(
|
|
184
|
-
function generateUuidV7Value<const Options extends UuidV7GeneratorValueOptions>(
|
|
183
|
+
function generateUuidV7Value(): Uuid<7, false, true> | UuidSlugError;
|
|
184
|
+
function generateUuidV7Value<const Options extends UuidV7GeneratorValueOptions | undefined>(
|
|
185
185
|
valueOptions: Options,
|
|
186
186
|
):
|
|
187
187
|
| Uuid<7, Options extends { readonly maskingCodec: UuidV7MaskingCodec } ? true : false, true>
|
package/src/v7-keyless.ts
CHANGED
|
@@ -19,6 +19,10 @@ import type {
|
|
|
19
19
|
GenerateUuidV7BytesIntoOptions,
|
|
20
20
|
GenerateUuidV7BytesOptions,
|
|
21
21
|
UuidOutput,
|
|
22
|
+
UuidGenerationBytes,
|
|
23
|
+
UuidGenerationFailure,
|
|
24
|
+
UuidGenerationInput,
|
|
25
|
+
UuidGenerationTextCase,
|
|
22
26
|
UuidTextCase,
|
|
23
27
|
UuidTextCaseArguments,
|
|
24
28
|
UuidV7Bytes,
|
|
@@ -48,7 +52,7 @@ const UUID_V7_BYTE_OPTIONS = {
|
|
|
48
52
|
/**
|
|
49
53
|
* Text and bytes keep independent lazy state so neither output form pays cross-form coordination.
|
|
50
54
|
* Native defaults avoid constructing this generator. Explicit time, configured generators and
|
|
51
|
-
* native failure still need portable state; bench/
|
|
55
|
+
* native failure still need portable state; bench/decisions.md owns the selection evidence.
|
|
52
56
|
*/
|
|
53
57
|
let textGenerator: PortableUuidV7Generator | undefined;
|
|
54
58
|
let byteGenerator: PortableUuidV7Generator | undefined;
|
|
@@ -69,7 +73,7 @@ const keylessTextBytes = new Uint8Array(16);
|
|
|
69
73
|
|
|
70
74
|
/**
|
|
71
75
|
* Draw with options this module already read. Rebuilding an options object for the generator's
|
|
72
|
-
* public method allocated it and read every option a second time (bench/
|
|
76
|
+
* public method allocated it and read every option a second time (bench/decisions.md).
|
|
73
77
|
*/
|
|
74
78
|
function drawFromReadOptions(
|
|
75
79
|
generator: PortableUuidV7Generator,
|
|
@@ -101,10 +105,10 @@ export const uuidV7BytesAt = (at: unknown): Uint8Array | UuidSlugError => drawAt
|
|
|
101
105
|
* Slug and pair writers encode their bytes before returning and draw nothing in between, so they
|
|
102
106
|
* borrow the generator's private text scratch instead of validating a second module buffer as
|
|
103
107
|
* caller output. Text keeps cached generator delegation; replacing it with a direct module
|
|
104
|
-
* formatter has not earned its cost on the primary calls (bench/
|
|
108
|
+
* formatter has not earned its cost on the primary calls (bench/decisions.md).
|
|
105
109
|
* Keep configured output validation and the generator's reentrancy guard; a borrowed buffer
|
|
106
110
|
* must never escape or survive another draw. Remeasure complete calls when either writer changes
|
|
107
|
-
* (bench/
|
|
111
|
+
* (bench/decisions.md), rather than assuming fewer checks improve every runtime.
|
|
108
112
|
*/
|
|
109
113
|
export const currentUuidV7Scratch = (): Uint8Array | UuidSlugError =>
|
|
110
114
|
v7Text().drawUuidV7Bytes(undefined, keylessTextBytes);
|
|
@@ -123,7 +127,7 @@ const portableUuidV7Text = (textCase: UuidTextCase): string | UuidSlugError =>
|
|
|
123
127
|
|
|
124
128
|
// Trust proper native results directly; validation and identity tracking add guarantees beyond
|
|
125
129
|
// the default native baseline. Keep exception fallback separate from configured calls, and
|
|
126
|
-
// remeasure complete calls when host capabilities change; bench/
|
|
130
|
+
// remeasure complete calls when host capabilities change; bench/decisions.md owns evidence.
|
|
127
131
|
function generateNativeDefaultUuidV7<Case extends UuidTextCase>(
|
|
128
132
|
selectedCase: Case,
|
|
129
133
|
): UuidV7StringFor<Case> | UuidSlugError {
|
|
@@ -174,6 +178,15 @@ export function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWE
|
|
|
174
178
|
export function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
175
179
|
options: GenerateUuidV7Options<Case>,
|
|
176
180
|
): UuidV7StringFor<Case> | UuidSlugError;
|
|
181
|
+
/**
|
|
182
|
+
* Forward a spelling preset or optional settings without branching.
|
|
183
|
+
* @throws `UuidSlugError` with code `rng_unavailable` on a preset or undefined branch when secure randomness is unavailable.
|
|
184
|
+
*/
|
|
185
|
+
export function generateUuidV7<
|
|
186
|
+
const Input extends UuidTextCase | GenerateUuidV7Options<UuidTextCase> | undefined,
|
|
187
|
+
>(
|
|
188
|
+
textCaseOrOptions: UuidGenerationInput<Input, GenerateUuidV7Options<UuidTextCase>>,
|
|
189
|
+
): UuidV7StringFor<UuidGenerationTextCase<Input>> | UuidGenerationFailure<Input>;
|
|
177
190
|
export function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
178
191
|
textCaseOrOptions?: Case | GenerateUuidV7Options<Case>,
|
|
179
192
|
): UuidV7StringFor<Case> | UuidSlugError {
|
|
@@ -261,6 +274,22 @@ export function generateUuidV7Bytes(
|
|
|
261
274
|
export function generateUuidV7Bytes<Output extends Uint8Array>(
|
|
262
275
|
options: GenerateUuidV7BytesIntoOptions<Output>,
|
|
263
276
|
): UuidOutput<Output> | UuidSlugError;
|
|
277
|
+
/**
|
|
278
|
+
* Forward optional storage or generation settings; caller storage keeps its own array type.
|
|
279
|
+
* @throws `UuidSlugError` with code `rng_unavailable` on an undefined branch when secure randomness is unavailable.
|
|
280
|
+
*/
|
|
281
|
+
export function generateUuidV7Bytes<
|
|
282
|
+
const Input extends
|
|
283
|
+
| Uint8Array
|
|
284
|
+
| GenerateUuidV7BytesOptions
|
|
285
|
+
| GenerateUuidV7BytesIntoOptions<Uint8Array>
|
|
286
|
+
| undefined,
|
|
287
|
+
>(
|
|
288
|
+
outOrOptions: UuidGenerationInput<
|
|
289
|
+
Input,
|
|
290
|
+
GenerateUuidV7BytesOptions & GenerateUuidV7BytesIntoOptions<Uint8Array>
|
|
291
|
+
>,
|
|
292
|
+
): UuidGenerationBytes<Input, UuidV7Bytes> | UuidGenerationFailure<Input>;
|
|
264
293
|
export function generateUuidV7Bytes(
|
|
265
294
|
outOrOptions?:
|
|
266
295
|
| Uint8Array
|
|
@@ -281,7 +310,7 @@ export const currentUuidV7Bytes = (): UuidV7Bytes | UuidSlugError =>
|
|
|
281
310
|
// Independent draws remove unrequested sequence work from owned defaults. Keep JITless on its
|
|
282
311
|
// measured generator path; configured calls and immutable values retain their declared layout.
|
|
283
312
|
// Remeasure complete calls if entropy, timestamp writing or runtime selection changes;
|
|
284
|
-
// bench/
|
|
313
|
+
// bench/decisions.md owns runtime comparisons rather than this selection comment.
|
|
285
314
|
const generateSelectedDefaultUuidV7Bytes = runtime.jitless
|
|
286
315
|
? currentUuidV7Bytes
|
|
287
316
|
: generateDefaultOwnedUuidV7Bytes;
|
package/src/v7-payload.ts
CHANGED
|
@@ -68,7 +68,7 @@ export function readUuidV7PayloadLayout(
|
|
|
68
68
|
* Join `rand_a` and `rand_b`; version and variant bits are separators, not payload.
|
|
69
69
|
*
|
|
70
70
|
* The upper 34 and lower 40 payload bits are assembled as exact numbers and joined once, because a
|
|
71
|
-
* BigInt conversion and shift per byte cost more than twice as much (bench/
|
|
71
|
+
* BigInt conversion and shift per byte cost more than twice as much (bench/decisions.md).
|
|
72
72
|
*/
|
|
73
73
|
export function uuidV7PayloadFromBytesUnchecked(bytes: Uint8Array, offset: number): bigint {
|
|
74
74
|
const upper =
|
package/src/v7-slug.ts
CHANGED
|
@@ -14,6 +14,9 @@ import type {
|
|
|
14
14
|
UuidTextCase,
|
|
15
15
|
UuidV7Generator,
|
|
16
16
|
UuidV7StringFor,
|
|
17
|
+
UuidGenerationFailure,
|
|
18
|
+
UuidGenerationInput,
|
|
19
|
+
UuidGenerationTextCase,
|
|
17
20
|
} from "./types.ts";
|
|
18
21
|
import { currentUuidV7Scratch, uuidV7ScratchAt } from "./v7-keyless.ts";
|
|
19
22
|
import { generateUuidV7BytesWithGenerator, readUuidV7Generator } from "./v7-generator-input.ts";
|
|
@@ -56,7 +59,7 @@ const portableUuidV7Slug = (): string | UuidSlugError => {
|
|
|
56
59
|
|
|
57
60
|
// Direct native output removes clock, entropy, byte writing and encoding from ordinary calls.
|
|
58
61
|
// Configured calls and base32hex remain portable. Remeasure complete calls and resources if this
|
|
59
|
-
// boundary changes; bench/
|
|
62
|
+
// boundary changes; bench/decisions.md owns evidence. Trust proper native results directly;
|
|
60
63
|
// result validation and identity tracking would impose stronger default guarantees.
|
|
61
64
|
function nativeUuidV7Slug(): string | UuidSlugError {
|
|
62
65
|
const native = runtime.uuidV7Slug;
|
|
@@ -250,7 +253,7 @@ export function generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
|
|
|
250
253
|
textCase: Case,
|
|
251
254
|
): GeneratedUuidV7<PlainUuidV7Slug, Case>;
|
|
252
255
|
export function generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
|
|
253
|
-
alphabet: SlugAlphabet,
|
|
256
|
+
alphabet: SlugAlphabet | undefined,
|
|
254
257
|
textCase: Case,
|
|
255
258
|
): GeneratedUuidV7<PlainUuidV7Slug, Case>;
|
|
256
259
|
/**
|
|
@@ -261,6 +264,22 @@ export function generateUuidV7WithPlainSlug<Case extends UuidTextCase>(
|
|
|
261
264
|
export function generateUuidV7WithPlainSlug<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
262
265
|
options: GenerateUuidV7WithPlainSlugOptions<Case>,
|
|
263
266
|
): GeneratedUuidV7<PlainUuidV7Slug, Case> | UuidSlugError;
|
|
267
|
+
/**
|
|
268
|
+
* Forward presets or optional settings, retaining their UUID text case and default branches.
|
|
269
|
+
* @throws `UuidSlugError` with code `rng_unavailable` on a preset or undefined branch when secure randomness is unavailable.
|
|
270
|
+
*/
|
|
271
|
+
export function generateUuidV7WithPlainSlug<
|
|
272
|
+
const Input extends
|
|
273
|
+
| SlugAlphabet
|
|
274
|
+
| UuidTextCase
|
|
275
|
+
| GenerateUuidV7WithPlainSlugOptions<UuidTextCase>
|
|
276
|
+
| undefined,
|
|
277
|
+
>(
|
|
278
|
+
alphabetOrCaseOrOptions: UuidGenerationInput<
|
|
279
|
+
Input,
|
|
280
|
+
GenerateUuidV7WithPlainSlugOptions<UuidTextCase>
|
|
281
|
+
>,
|
|
282
|
+
): GeneratedUuidV7<PlainUuidV7Slug, UuidGenerationTextCase<Input>> | UuidGenerationFailure<Input>;
|
|
264
283
|
export function generateUuidV7WithPlainSlug(
|
|
265
284
|
alphabetOrCaseOrOptions:
|
|
266
285
|
| SlugAlphabet
|
package/src/v7-value.ts
CHANGED
|
@@ -1,6 +1,11 @@
|
|
|
1
1
|
// SPDX-License-Identifier: Apache-2.0
|
|
2
2
|
|
|
3
|
-
import type {
|
|
3
|
+
import type {
|
|
4
|
+
Uuid,
|
|
5
|
+
UuidGenerationFailure,
|
|
6
|
+
UuidV7MaskingCodec,
|
|
7
|
+
UuidV7ValueOptions,
|
|
8
|
+
} from "./types.ts";
|
|
4
9
|
import { UuidSlugError } from "./errors.ts";
|
|
5
10
|
import { createUuidValue } from "./uuid-value.ts";
|
|
6
11
|
import { currentUuidV7Bytes, uuidV7BytesAt, uuidV7DefaultPayloadLayout } from "./v7-keyless.ts";
|
|
@@ -23,17 +28,17 @@ const UUID_V7_VALUE_OPTIONS = {
|
|
|
23
28
|
* @throws `UuidSlugError` with code `rng_unavailable` when generation cannot obtain
|
|
24
29
|
* secure randomness.
|
|
25
30
|
*/
|
|
26
|
-
export function generateUuidV7Value(
|
|
31
|
+
export function generateUuidV7Value(): Uuid<7, false, true>;
|
|
27
32
|
/**
|
|
28
33
|
* Generate an immutable UUIDv7 with optional time, generator, and retained masking codec.
|
|
29
34
|
* Only a supplied codec is retained; an undefined options branch uses default generation.
|
|
30
35
|
* @throws `UuidSlugError` with code `rng_unavailable` if options are undefined and secure randomness is unavailable.
|
|
31
36
|
*/
|
|
32
|
-
export function generateUuidV7Value<const Options extends UuidV7ValueOptions | undefined
|
|
37
|
+
export function generateUuidV7Value<const Options extends UuidV7ValueOptions | undefined>(
|
|
33
38
|
options: Options,
|
|
34
39
|
):
|
|
35
40
|
| Uuid<7, Options extends { readonly maskingCodec: UuidV7MaskingCodec } ? true : false, true>
|
|
36
|
-
|
|
|
41
|
+
| UuidGenerationFailure<Options>;
|
|
37
42
|
export function generateUuidV7Value(
|
|
38
43
|
options?: UuidV7ValueOptions,
|
|
39
44
|
): Uuid<7, boolean, true> | UuidSlugError {
|
package/src/v7.ts
CHANGED
|
@@ -21,6 +21,9 @@ import type {
|
|
|
21
21
|
GenerateUuidV7BytesIntoOptions,
|
|
22
22
|
GenerateUuidV7BytesOptions,
|
|
23
23
|
GenerateUuidV7Options,
|
|
24
|
+
UuidGenerationBytes,
|
|
25
|
+
UuidGenerationTextCase,
|
|
26
|
+
UuidGenerationInput,
|
|
24
27
|
UuidOutput,
|
|
25
28
|
UuidTextCase,
|
|
26
29
|
UuidTextCaseArguments,
|
|
@@ -105,7 +108,7 @@ function writeTimestampLoop(bytes: Uint8Array, ms: number, offset: number) {
|
|
|
105
108
|
}
|
|
106
109
|
|
|
107
110
|
// Measured Bun favors the loop while Node and Chromium favor fixed writes; select once so generation
|
|
108
|
-
// pays no per-call branch. bench/
|
|
111
|
+
// pays no per-call branch. bench/decisions.md owns the measurements and replacement condition.
|
|
109
112
|
const writeTimestamp = (globalThis as { Bun?: object }).Bun
|
|
110
113
|
? writeTimestampLoop
|
|
111
114
|
: writeTimestampWords;
|
|
@@ -368,6 +371,18 @@ export function createPortableUuidV7Generator(
|
|
|
368
371
|
function generateUuidV7Bytes<Output extends Uint8Array>(
|
|
369
372
|
options: Omit<GenerateUuidV7BytesIntoOptions<Output>, "generator">,
|
|
370
373
|
): UuidOutput<Output> | UuidSlugError;
|
|
374
|
+
function generateUuidV7Bytes<
|
|
375
|
+
const Input extends
|
|
376
|
+
| Uint8Array
|
|
377
|
+
| Omit<GenerateUuidV7BytesOptions, "generator">
|
|
378
|
+
| Omit<GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
|
|
379
|
+
| undefined,
|
|
380
|
+
>(
|
|
381
|
+
outOrOptions: UuidGenerationInput<
|
|
382
|
+
Input,
|
|
383
|
+
Omit<GenerateUuidV7BytesOptions & GenerateUuidV7BytesIntoOptions<Uint8Array>, "generator">
|
|
384
|
+
>,
|
|
385
|
+
): UuidGenerationBytes<Input, UuidV7Bytes> | UuidSlugError;
|
|
371
386
|
function generateUuidV7Bytes(
|
|
372
387
|
outOrOptions?:
|
|
373
388
|
| Uint8Array
|
|
@@ -408,6 +423,17 @@ export function createPortableUuidV7Generator(
|
|
|
408
423
|
function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
409
424
|
options: Omit<GenerateUuidV7Options<Case>, "generator">,
|
|
410
425
|
): UuidV7StringFor<Case> | UuidSlugError;
|
|
426
|
+
function generateUuidV7<
|
|
427
|
+
const Input extends
|
|
428
|
+
| UuidTextCase
|
|
429
|
+
| Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
|
|
430
|
+
| undefined,
|
|
431
|
+
>(
|
|
432
|
+
textCaseOrOptions: UuidGenerationInput<
|
|
433
|
+
Input,
|
|
434
|
+
Omit<GenerateUuidV7Options<UuidTextCase>, "generator">
|
|
435
|
+
>,
|
|
436
|
+
): UuidV7StringFor<UuidGenerationTextCase<Input>> | UuidSlugError;
|
|
411
437
|
function generateUuidV7<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
412
438
|
textCaseOrOptions:
|
|
413
439
|
| Case
|