@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
package/src/v4-slug.ts
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import { generatedOrThrow } from "./errors.ts";
|
|
4
|
+
import type { UuidSlugError } from "./errors.ts";
|
|
5
|
+
import { BASE64URL_NAME, encode } from "./alphabet.ts";
|
|
6
|
+
import type { PlainUuidV4Slug } from "./types.ts";
|
|
7
|
+
import { drawUuidV4Scratch } from "./v4.ts";
|
|
8
|
+
import { resolveSlugAlphabet } from "./slug.ts";
|
|
9
|
+
import type { SlugAlphabet } from "./slug.ts";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Generate a plain UUIDv4 slug with platform randomness, using base64url by default. base32hex is
|
|
13
|
+
* filesystem-safe but cannot make random UUIDv4 values chronological.
|
|
14
|
+
*
|
|
15
|
+
* @param alphabet - Output spelling. Omit for the shorter 22-character base64url form.
|
|
16
|
+
* @throws `UuidSlugError` with code `rng_unavailable` when generation cannot obtain
|
|
17
|
+
* secure randomness.
|
|
18
|
+
*/
|
|
19
|
+
export function generatePlainUuidV4Slug(alphabet?: SlugAlphabet): PlainUuidV4Slug;
|
|
20
|
+
export function generatePlainUuidV4Slug(
|
|
21
|
+
alphabet: SlugAlphabet = BASE64URL_NAME,
|
|
22
|
+
): PlainUuidV4Slug | UuidSlugError {
|
|
23
|
+
// Only an untyped call reaches an unknown alphabet; that misuse stays an error value.
|
|
24
|
+
const resolved = resolveSlugAlphabet(alphabet);
|
|
25
|
+
if (resolved instanceof Error) return resolved;
|
|
26
|
+
return encode(generatedOrThrow(drawUuidV4Scratch()), resolved) as PlainUuidV4Slug;
|
|
27
|
+
}
|
package/src/v4.ts
ADDED
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import { runtime } from "#runtime";
|
|
4
|
+
import {
|
|
5
|
+
checkByteRange,
|
|
6
|
+
checkRange,
|
|
7
|
+
fillRandomBytes,
|
|
8
|
+
generatedOrThrow,
|
|
9
|
+
INVALID_OPTIONS,
|
|
10
|
+
RNG_UNAVAILABLE,
|
|
11
|
+
portableAfterNative,
|
|
12
|
+
UuidSlugError,
|
|
13
|
+
} from "./errors.ts";
|
|
14
|
+
import { UUID_TEXT_LOWERCASE, UUID_TEXT_UPPERCASE } from "./types.ts";
|
|
15
|
+
import type {
|
|
16
|
+
UuidRandomFill,
|
|
17
|
+
UuidOutput,
|
|
18
|
+
UuidTextCase,
|
|
19
|
+
UuidTextCaseArguments,
|
|
20
|
+
UuidV4Bytes,
|
|
21
|
+
UuidV4StringFor,
|
|
22
|
+
} from "./types.ts";
|
|
23
|
+
import {
|
|
24
|
+
bytesToUuidString,
|
|
25
|
+
formatUuidBytesUnchecked,
|
|
26
|
+
isUuidTextCase,
|
|
27
|
+
resolveUuidTextCase,
|
|
28
|
+
} from "./uuid.ts";
|
|
29
|
+
|
|
30
|
+
export { isUuidSlugError } from "./errors.ts";
|
|
31
|
+
export { UuidSlugError };
|
|
32
|
+
export type { UuidSlugErrorCode } from "./errors.ts";
|
|
33
|
+
export type { UuidV4Bytes, UuidV4String } from "./types.ts";
|
|
34
|
+
export { isUuidV4Bytes, isUuidV4String, isUuidV4Text } from "./uuid.ts";
|
|
35
|
+
|
|
36
|
+
const UUID_V4_GENERATION = "UUIDv4 generation";
|
|
37
|
+
const REENTRANT_GENERATION_MESSAGE =
|
|
38
|
+
"UUIDv4 generation cannot be reentered from its entropy source.";
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Randomness is drawn into private storage before copying to caller storage. Web Crypto rejects
|
|
42
|
+
* SharedArrayBuffer views, so the runtime cannot safely fill an arbitrary caller buffer directly.
|
|
43
|
+
*/
|
|
44
|
+
const random = new Uint8Array(16);
|
|
45
|
+
let generating = false;
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Generate UUIDv4 bytes with platform randomness in a new plain 16-byte `Uint8Array`.
|
|
49
|
+
*
|
|
50
|
+
* @throws `UuidSlugError` with code `rng_unavailable` when generation cannot obtain
|
|
51
|
+
* secure randomness.
|
|
52
|
+
*/
|
|
53
|
+
export function generateUuidV4Bytes(): UuidV4Bytes;
|
|
54
|
+
/**
|
|
55
|
+
* Write UUIDv4 bytes into caller-owned storage only after successful generation.
|
|
56
|
+
*
|
|
57
|
+
* @param output - Caller-owned array that receives the 16 UUID bytes.
|
|
58
|
+
* @param outputOffset - Zero-based index where writing starts. Omit to start at index 0. Bytes
|
|
59
|
+
* outside the written range stay unchanged.
|
|
60
|
+
*/
|
|
61
|
+
export function generateUuidV4Bytes<Output extends Uint8Array>(
|
|
62
|
+
output: Output,
|
|
63
|
+
outputOffset?: number,
|
|
64
|
+
): UuidOutput<Output> | UuidSlugError;
|
|
65
|
+
export function generateUuidV4Bytes(
|
|
66
|
+
output?: Uint8Array,
|
|
67
|
+
outputOffset = 0,
|
|
68
|
+
): Uint8Array | UuidSlugError {
|
|
69
|
+
if (output === undefined) {
|
|
70
|
+
// Only an untyped call reaches an offset without storage; that misuse stays an error value.
|
|
71
|
+
const badRange = outputOffset === 0 ? undefined : checkRange(16, outputOffset, 16);
|
|
72
|
+
if (badRange) return badRange;
|
|
73
|
+
return generatedOrThrow(generateOwnedUuidV4Bytes());
|
|
74
|
+
}
|
|
75
|
+
if (generating) return new UuidSlugError(RNG_UNAVAILABLE, REENTRANT_GENERATION_MESSAGE);
|
|
76
|
+
const badRange = checkByteRange(output, outputOffset, 16);
|
|
77
|
+
if (badRange) return badRange;
|
|
78
|
+
generating = true;
|
|
79
|
+
try {
|
|
80
|
+
const failed = fillRandomBytes(runtime.fillRandom, random);
|
|
81
|
+
if (failed) return failed;
|
|
82
|
+
output.set(random, outputOffset);
|
|
83
|
+
output[outputOffset + 6] = ((output[outputOffset + 6] ?? 0) & 0x0f) | 0x40;
|
|
84
|
+
output[outputOffset + 8] = ((output[outputOffset + 8] ?? 0) & 0x3f) | 0x80;
|
|
85
|
+
return output;
|
|
86
|
+
} finally {
|
|
87
|
+
generating = false;
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// Keep owned output separate so it can draw directly into its result without adding a post-draw
|
|
92
|
+
// ownership branch to caller-buffer writes. Merge the paths if either primary runtime loses this win.
|
|
93
|
+
// Failures are returned so slug and text callers can decide at their own public seam.
|
|
94
|
+
export function generateOwnedUuidV4Bytes(): UuidV4Bytes | UuidSlugError {
|
|
95
|
+
if (generating) return new UuidSlugError(RNG_UNAVAILABLE, REENTRANT_GENERATION_MESSAGE);
|
|
96
|
+
const output = new Uint8Array(16);
|
|
97
|
+
generating = true;
|
|
98
|
+
try {
|
|
99
|
+
const failed = fillRandomBytes(runtime.fillRandom, output);
|
|
100
|
+
if (failed) return failed;
|
|
101
|
+
output[6] = ((output[6] ?? 0) & 0x0f) | 0x40;
|
|
102
|
+
output[8] = ((output[8] ?? 0) & 0x3f) | 0x80;
|
|
103
|
+
return output as UuidV4Bytes;
|
|
104
|
+
} finally {
|
|
105
|
+
generating = false;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Generate UUIDv4 text through the portable implementation, even on native-capable hosts.
|
|
111
|
+
* Failures are returned so the native path can aggregate them with its own cause.
|
|
112
|
+
*/
|
|
113
|
+
export function generatePortableUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
114
|
+
textCase: Case = UUID_TEXT_LOWERCASE as Case,
|
|
115
|
+
): 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
|
+
const bytes = drawUuidV4Scratch();
|
|
122
|
+
return bytes instanceof Error
|
|
123
|
+
? bytes
|
|
124
|
+
: (formatUuidBytesUnchecked(bytes, 0, textCase) as UuidV4StringFor<Case>);
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/**
|
|
128
|
+
* Fill the module scratch with UUIDv4 bytes for a writer that reads them before its next draw. Text
|
|
129
|
+
* 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/PERFORMANCE.md).
|
|
131
|
+
* Encoding cannot draw entropy, so the scratch cannot change between this return and the read.
|
|
132
|
+
*/
|
|
133
|
+
export function drawUuidV4Scratch(): Uint8Array | UuidSlugError {
|
|
134
|
+
if (generating) return new UuidSlugError(RNG_UNAVAILABLE, REENTRANT_GENERATION_MESSAGE);
|
|
135
|
+
generating = true;
|
|
136
|
+
try {
|
|
137
|
+
const failed = fillRandomBytes(runtime.fillRandom, random);
|
|
138
|
+
if (failed) return failed;
|
|
139
|
+
random[6] = ((random[6] ?? 0) & 0x0f) | 0x40;
|
|
140
|
+
random[8] = ((random[8] ?? 0) & 0x3f) | 0x80;
|
|
141
|
+
return random;
|
|
142
|
+
} finally {
|
|
143
|
+
generating = false;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Generate UUIDv4 text with platform cryptographic randomness, lowercase by default.
|
|
149
|
+
* Native runtime results are trusted without additional output guarantees.
|
|
150
|
+
*
|
|
151
|
+
* @param textCase - Built-in output spelling. Omit for lowercase.
|
|
152
|
+
* @throws `UuidSlugError` with code `rng_unavailable` when generation cannot obtain
|
|
153
|
+
* secure randomness.
|
|
154
|
+
*/
|
|
155
|
+
export function generateUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
156
|
+
...textCase: UuidTextCaseArguments<Case>
|
|
157
|
+
): UuidV4StringFor<Case>;
|
|
158
|
+
export function generateUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
159
|
+
textCase: Case = UUID_TEXT_LOWERCASE as Case,
|
|
160
|
+
): UuidV4StringFor<Case> | UuidSlugError {
|
|
161
|
+
if (!isUuidTextCase(textCase)) {
|
|
162
|
+
// Only an untyped call reaches an unknown spelling; that misuse stays an error value.
|
|
163
|
+
const selectedCase = resolveUuidTextCase(textCase);
|
|
164
|
+
if (selectedCase instanceof Error) return selectedCase;
|
|
165
|
+
textCase = selectedCase as Case;
|
|
166
|
+
}
|
|
167
|
+
// Native generation is useful only for text, which the host returns directly. Byte and slug
|
|
168
|
+
// routes stay portable because parsing native text adds work and complicates atomic output.
|
|
169
|
+
// Keep native generation in this public function instead of another helper call; the complete
|
|
170
|
+
// Bun text call improves with this shape. Portable-first runtimes leave before native handling.
|
|
171
|
+
// A successful string needs no local Error check; only a failed result reaches the throw seam.
|
|
172
|
+
// Trust proper native output directly: validation and identity tracking impose guarantees
|
|
173
|
+
// beyond the default native baseline. Configured entropy still validates at its caller seam.
|
|
174
|
+
// Remeasure each output form if case normalization, host APIs or engine inlining
|
|
175
|
+
// changes; bench/PERFORMANCE.md owns the evidence.
|
|
176
|
+
const native = runtime.uuidV4;
|
|
177
|
+
if (!native) return generatedOrThrow(generatePortableUuidV4(textCase));
|
|
178
|
+
let uuid: string | UuidSlugError;
|
|
179
|
+
try {
|
|
180
|
+
uuid = native();
|
|
181
|
+
} catch (nativeCause) {
|
|
182
|
+
uuid = portableAfterNative<UuidTextCase>(
|
|
183
|
+
nativeCause,
|
|
184
|
+
generatePortableUuidV4,
|
|
185
|
+
UUID_TEXT_LOWERCASE,
|
|
186
|
+
UUID_V4_GENERATION,
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
if (typeof uuid !== "string") return generatedOrThrow(uuid);
|
|
190
|
+
return (textCase === UUID_TEXT_UPPERCASE ? uuid.toUpperCase() : uuid) as UuidV4StringFor<Case>;
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
/**
|
|
194
|
+
* Generate UUIDv4 text from the caller's synchronous random-byte source. The callback must fill
|
|
195
|
+
* all 16 bytes. Returned or thrown errors become generation failures; the package cannot detect a
|
|
196
|
+
* successful partial or weak fill.
|
|
197
|
+
*
|
|
198
|
+
* @param fillRandom - Fill the complete array from the caller's chosen source.
|
|
199
|
+
* @param textCase - Built-in output spelling. Omit for lowercase.
|
|
200
|
+
*/
|
|
201
|
+
export function generateUuidV4WithRandomFill<
|
|
202
|
+
Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE,
|
|
203
|
+
>(
|
|
204
|
+
fillRandom: UuidRandomFill,
|
|
205
|
+
...textCase: UuidTextCaseArguments<Case>
|
|
206
|
+
): UuidV4StringFor<Case> | UuidSlugError;
|
|
207
|
+
export function generateUuidV4WithRandomFill<
|
|
208
|
+
Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE,
|
|
209
|
+
>(
|
|
210
|
+
fillRandom: UuidRandomFill,
|
|
211
|
+
textCase: Case = UUID_TEXT_LOWERCASE as Case,
|
|
212
|
+
): UuidV4StringFor<Case> | UuidSlugError {
|
|
213
|
+
if (typeof fillRandom !== "function")
|
|
214
|
+
return new UuidSlugError(INVALID_OPTIONS, "UUIDv4 fillRandom must be a function.");
|
|
215
|
+
if (!isUuidTextCase(textCase)) {
|
|
216
|
+
const selectedCase = resolveUuidTextCase(textCase);
|
|
217
|
+
if (selectedCase instanceof Error) return selectedCase;
|
|
218
|
+
textCase = selectedCase as Case;
|
|
219
|
+
}
|
|
220
|
+
if (generating) return new UuidSlugError(RNG_UNAVAILABLE, REENTRANT_GENERATION_MESSAGE);
|
|
221
|
+
const bytes = new Uint8Array(16);
|
|
222
|
+
generating = true;
|
|
223
|
+
try {
|
|
224
|
+
// The shared draw boundary recognizes package failures before native Error identity.
|
|
225
|
+
// Filtering callback results here would discard marker-only failures and duplicate work.
|
|
226
|
+
const failed = fillRandomBytes(fillRandom, bytes);
|
|
227
|
+
if (failed) return failed;
|
|
228
|
+
bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
|
|
229
|
+
bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
|
|
230
|
+
return bytesToUuidString(bytes, textCase) as UuidV4StringFor<Case> | UuidSlugError;
|
|
231
|
+
} finally {
|
|
232
|
+
generating = false;
|
|
233
|
+
}
|
|
234
|
+
}
|
package/src/v7-bounds.ts
ADDED
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import { INVALID_TIMESTAMP, UuidSlugError } from "./errors.ts";
|
|
4
|
+
import { runtime } from "#runtime";
|
|
5
|
+
import { UUID_TEXT_LOWERCASE, UUID_TEXT_UPPERCASE } from "./types.ts";
|
|
6
|
+
import type {
|
|
7
|
+
UuidTextCase,
|
|
8
|
+
UuidTextCaseArguments,
|
|
9
|
+
UuidV7Bounds,
|
|
10
|
+
UuidV7Bytes,
|
|
11
|
+
UuidV7StringFor,
|
|
12
|
+
} from "./types.ts";
|
|
13
|
+
import { resolveUuidTextCase } from "./uuid.ts";
|
|
14
|
+
import { rejectUuidV7UnixMs } from "./v7-timestamp.ts";
|
|
15
|
+
|
|
16
|
+
function intervalEnd(startUnixMs: number, endUnixMs: number): number | UuidSlugError {
|
|
17
|
+
const invalid = rejectUuidV7UnixMs(startUnixMs) ?? rejectUuidV7UnixMs(endUnixMs);
|
|
18
|
+
if (invalid) return invalid;
|
|
19
|
+
return startUnixMs <= endUnixMs
|
|
20
|
+
? endUnixMs
|
|
21
|
+
: new UuidSlugError(
|
|
22
|
+
INVALID_TIMESTAMP,
|
|
23
|
+
"UUIDv7 range start must not be after its inclusive end.",
|
|
24
|
+
);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
function endpoint(unixMs: number, upper: boolean): UuidV7Bytes {
|
|
28
|
+
const bytes = new Uint8Array(16);
|
|
29
|
+
if (upper) bytes.fill(0xff);
|
|
30
|
+
const high = Math.floor(unixMs / 0x1_0000_0000);
|
|
31
|
+
bytes[0] = high >>> 8;
|
|
32
|
+
bytes[1] = high;
|
|
33
|
+
bytes[2] = unixMs >>> 24;
|
|
34
|
+
bytes[3] = unixMs >>> 16;
|
|
35
|
+
bytes[4] = unixMs >>> 8;
|
|
36
|
+
bytes[5] = unixMs;
|
|
37
|
+
bytes[6] = upper ? 0x7f : 0x70;
|
|
38
|
+
bytes[8] = upper ? 0xbf : 0x80;
|
|
39
|
+
return bytes as UuidV7Bytes;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Return owned byte bounds containing every RFC-variant UUIDv7 from `startUnixMs` through
|
|
44
|
+
* `endUnixMs`. Omit the end to select one millisecond. Compare the bytes in UUID wire order.
|
|
45
|
+
*
|
|
46
|
+
* @param startUnixMs - First whole Unix millisecond, inclusive.
|
|
47
|
+
* @param endUnixMs - Last whole Unix millisecond, inclusive. Defaults to `startUnixMs`.
|
|
48
|
+
* @returns Two separate plain 16-byte arrays, or `invalid_timestamp` for an invalid interval.
|
|
49
|
+
*/
|
|
50
|
+
export function uuidV7ByteBounds(
|
|
51
|
+
startUnixMs: number,
|
|
52
|
+
endUnixMs: number = startUnixMs,
|
|
53
|
+
): UuidV7Bounds<UuidV7Bytes> | UuidSlugError {
|
|
54
|
+
const end = intervalEnd(startUnixMs, endUnixMs);
|
|
55
|
+
if (typeof end !== "number") return end;
|
|
56
|
+
return {
|
|
57
|
+
startInclusive: endpoint(startUnixMs, false),
|
|
58
|
+
endInclusive: endpoint(end, true),
|
|
59
|
+
};
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const START_SUFFIX = "-7000-8000-000000000000";
|
|
63
|
+
const END_SUFFIX = "-7fff-bfff-ffffffffffff";
|
|
64
|
+
let hexCodes: Uint8Array | undefined;
|
|
65
|
+
|
|
66
|
+
function fixedTextEndpoint<Case extends UuidTextCase>(
|
|
67
|
+
unixMs: number,
|
|
68
|
+
upper: boolean,
|
|
69
|
+
textCase: Case,
|
|
70
|
+
): UuidV7StringFor<Case> {
|
|
71
|
+
// Fixed character arguments reduce consumed bounds costs on V8 with the JIT. Byte pairs remain
|
|
72
|
+
// faster on Bun and JITless Node; selection is outside per-ID calls. Remeasure engine changes
|
|
73
|
+
// against bench/PERFORMANCE.md, including both endpoint reads and lazy table construction.
|
|
74
|
+
const hex = (hexCodes ??= Uint8Array.from("0123456789abcdef", (digit) => digit.charCodeAt(0)));
|
|
75
|
+
// Validated timestamps have 48 bits; splitting avoids truncating their upper 16 bits.
|
|
76
|
+
const high = Math.floor(unixMs / 0x1_0000_0000);
|
|
77
|
+
const value =
|
|
78
|
+
String.fromCharCode(
|
|
79
|
+
hex[high >>> 12] as number,
|
|
80
|
+
hex[(high >>> 8) & 15] as number,
|
|
81
|
+
hex[(high >>> 4) & 15] as number,
|
|
82
|
+
hex[high & 15] as number,
|
|
83
|
+
hex[unixMs >>> 28] as number,
|
|
84
|
+
hex[(unixMs >>> 24) & 15] as number,
|
|
85
|
+
hex[(unixMs >>> 20) & 15] as number,
|
|
86
|
+
hex[(unixMs >>> 16) & 15] as number,
|
|
87
|
+
45,
|
|
88
|
+
hex[(unixMs >>> 12) & 15] as number,
|
|
89
|
+
hex[(unixMs >>> 8) & 15] as number,
|
|
90
|
+
hex[(unixMs >>> 4) & 15] as number,
|
|
91
|
+
hex[unixMs & 15] as number,
|
|
92
|
+
) + (upper ? END_SUFFIX : START_SUFFIX);
|
|
93
|
+
return (textCase === UUID_TEXT_UPPERCASE ? value.toUpperCase() : value) as UuidV7StringFor<Case>;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
let hexBytes: string[] | undefined;
|
|
97
|
+
|
|
98
|
+
function textEndpoint<Case extends UuidTextCase>(
|
|
99
|
+
unixMs: number,
|
|
100
|
+
upper: boolean,
|
|
101
|
+
textCase: Case,
|
|
102
|
+
): UuidV7StringFor<Case> {
|
|
103
|
+
// Byte pairs avoid radix formatting and beat fixed character arguments on Bun and JITless Node.
|
|
104
|
+
// 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/PERFORMANCE.md).
|
|
106
|
+
const hex = (hexBytes ??= Array.from({ length: 256 }, (_, byte) =>
|
|
107
|
+
byte.toString(16).padStart(2, "0"),
|
|
108
|
+
));
|
|
109
|
+
// `rejectUuidV7UnixMs` admits only whole milliseconds below 2^48, so `high` holds 16 bits and
|
|
110
|
+
// the unsigned shifts read the low 32 bits exactly.
|
|
111
|
+
const high = Math.floor(unixMs / 0x1_0000_0000);
|
|
112
|
+
const suffix = upper ? END_SUFFIX : START_SUFFIX;
|
|
113
|
+
const value =
|
|
114
|
+
(hex[high >>> 8] as string) +
|
|
115
|
+
(hex[high & 0xff] as string) +
|
|
116
|
+
(hex[unixMs >>> 24] as string) +
|
|
117
|
+
(hex[(unixMs >>> 16) & 0xff] as string) +
|
|
118
|
+
"-" +
|
|
119
|
+
(hex[(unixMs >>> 8) & 0xff] as string) +
|
|
120
|
+
(hex[unixMs & 0xff] as string) +
|
|
121
|
+
suffix;
|
|
122
|
+
return (textCase === UUID_TEXT_UPPERCASE ? value.toUpperCase() : value) as UuidV7StringFor<Case>;
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
const selectedTextEndpoint =
|
|
126
|
+
runtime.latin1Scratch || runtime.jitless ? textEndpoint : fixedTextEndpoint;
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Return canonical bounds containing every RFC-variant UUIDv7 at one Unix millisecond. The
|
|
130
|
+
* comparison must preserve UUID byte order; SQL Server `uniqueidentifier`, base64url text, and
|
|
131
|
+
* masked slugs do not.
|
|
132
|
+
*
|
|
133
|
+
* @param startUnixMs - Whole Unix millisecond to select.
|
|
134
|
+
* @param textCase - Built-in output spelling. Omit for lowercase.
|
|
135
|
+
* @returns Canonical UUIDv7 endpoints, or `invalid_timestamp` for an invalid millisecond.
|
|
136
|
+
*/
|
|
137
|
+
export function uuidV7StringBounds<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
138
|
+
startUnixMs: number,
|
|
139
|
+
...textCase: UuidTextCaseArguments<Case>
|
|
140
|
+
): UuidV7Bounds<UuidV7StringFor<Case>> | UuidSlugError;
|
|
141
|
+
/**
|
|
142
|
+
* Return canonical bounds containing every RFC-variant UUIDv7 in an inclusive Unix-millisecond
|
|
143
|
+
* interval. The comparison must preserve UUID byte order.
|
|
144
|
+
*
|
|
145
|
+
* @param startUnixMs - First whole Unix millisecond, inclusive.
|
|
146
|
+
* @param endUnixMs - Last whole Unix millisecond, inclusive.
|
|
147
|
+
* @param textCase - Built-in output spelling. Omit for lowercase.
|
|
148
|
+
* @returns Canonical UUIDv7 endpoints, or `invalid_timestamp` for an invalid interval.
|
|
149
|
+
*/
|
|
150
|
+
export function uuidV7StringBounds<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
151
|
+
startUnixMs: number,
|
|
152
|
+
endUnixMs: number,
|
|
153
|
+
...textCase: UuidTextCaseArguments<Case>
|
|
154
|
+
): UuidV7Bounds<UuidV7StringFor<Case>> | UuidSlugError;
|
|
155
|
+
export function uuidV7StringBounds(
|
|
156
|
+
startUnixMs: number,
|
|
157
|
+
endOrCase: number | UuidTextCase = startUnixMs,
|
|
158
|
+
requestedCase: UuidTextCase = UUID_TEXT_LOWERCASE,
|
|
159
|
+
): UuidV7Bounds<UuidV7StringFor<UuidTextCase>> | UuidSlugError {
|
|
160
|
+
const endUnixMs = typeof endOrCase === "number" ? endOrCase : startUnixMs;
|
|
161
|
+
const textCase = resolveUuidTextCase(typeof endOrCase === "number" ? requestedCase : endOrCase);
|
|
162
|
+
if (textCase instanceof Error) return textCase;
|
|
163
|
+
const end = intervalEnd(startUnixMs, endUnixMs);
|
|
164
|
+
if (typeof end !== "number") return end;
|
|
165
|
+
// Direct formatting avoids two temporary byte arrays. Keep the byte writer independent unless
|
|
166
|
+
// repeated public-route measurements reverse this result; bench/PERFORMANCE.md owns that trigger.
|
|
167
|
+
return {
|
|
168
|
+
startInclusive: selectedTextEndpoint(startUnixMs, false, textCase),
|
|
169
|
+
endInclusive: selectedTextEndpoint(end, true, textCase),
|
|
170
|
+
};
|
|
171
|
+
}
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
checkByteRange,
|
|
5
|
+
INVALID_OPTIONS,
|
|
6
|
+
INVALID_TIMESTAMP,
|
|
7
|
+
INVALID_UUID_VERSION,
|
|
8
|
+
isUuidSlugError,
|
|
9
|
+
UuidSlugError,
|
|
10
|
+
} from "./errors.ts";
|
|
11
|
+
import type { UuidV7Generator, UuidV7Instant, UuidV7PayloadLayout } from "./types.ts";
|
|
12
|
+
import type { PortableUuidV7Generator } from "./v7.ts";
|
|
13
|
+
import { readUuidV7Instant } from "./instant.ts";
|
|
14
|
+
import { readUuidV7PayloadLayout, uuidV7PayloadFromBytesUnchecked } from "./v7-payload.ts";
|
|
15
|
+
import { isUuidV7Bytes, uuidTimestampFromBytesUnchecked } from "./uuid.ts";
|
|
16
|
+
|
|
17
|
+
const AT_OPTION = "at";
|
|
18
|
+
const UUID_V7_GENERATOR_REQUIRED = "generator must be a UUIDv7 generator.";
|
|
19
|
+
|
|
20
|
+
export interface UuidV7GenerationValues {
|
|
21
|
+
readonly at?: unknown;
|
|
22
|
+
readonly output?: unknown;
|
|
23
|
+
readonly outputOffset?: unknown;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
export interface ValidatedUuidV7Generator {
|
|
27
|
+
readonly generateUuidV7Bytes: UuidV7Generator["generateUuidV7Bytes"];
|
|
28
|
+
readonly payloadLayout: UuidV7PayloadLayout;
|
|
29
|
+
// Only the private package sequence supplies text: structural generators retain byte validation.
|
|
30
|
+
readonly generateUuidV7?: PortableUuidV7Generator["generateUuidV7"];
|
|
31
|
+
/** Present only on package generators, whose bytes need no validation or defensive copy. */
|
|
32
|
+
readonly drawUuidV7Bytes?: PortableUuidV7Generator["drawUuidV7Bytes"];
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Return its argument so a subclass can add private fields to an existing object. */
|
|
36
|
+
// eslint-disable-next-line typescript/no-extraneous-class -- only a class constructor can hand `super` an existing object
|
|
37
|
+
class ReturnObject {
|
|
38
|
+
constructor(value: object) {
|
|
39
|
+
return value;
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/**
|
|
44
|
+
* Stamps the sequence onto a public generator this package copy created. That object is frozen and
|
|
45
|
+
* its layout was validated when it was built, so reading it again proves nothing, and its sequence
|
|
46
|
+
* writes fresh or caller-owned bytes that nothing else retains. A lookalike, a proxy, or a generator
|
|
47
|
+
* from another package copy has no stamp and takes the structural read.
|
|
48
|
+
*
|
|
49
|
+
* Structural validation allocated a validated object and rescanned the layout keys on every call
|
|
50
|
+
* that passed `generator`, and the untrusted-generator call then needed a scratch buffer, byte
|
|
51
|
+
* validation, an `at` check, and a copy (bench/PERFORMANCE.md). The stamp adds a private field
|
|
52
|
+
* instead of a class prototype, so the public object stays plain. A module `WeakMap` is the rejected
|
|
53
|
+
* alternative: registration made default generator creation 1.6 times slower. Remeasure if engines
|
|
54
|
+
* change how they store private fields or weak collections.
|
|
55
|
+
*/
|
|
56
|
+
class PackageUuidV7Generator extends ReturnObject {
|
|
57
|
+
readonly #sequence: PortableUuidV7Generator;
|
|
58
|
+
|
|
59
|
+
constructor(generator: object, sequence: PortableUuidV7Generator) {
|
|
60
|
+
super(generator);
|
|
61
|
+
this.#sequence = sequence;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
static sequenceOf(value: unknown): PortableUuidV7Generator | undefined {
|
|
65
|
+
return typeof value === "object" && value !== null && #sequence in value
|
|
66
|
+
? value.#sequence
|
|
67
|
+
: undefined;
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Stamp a not-yet-frozen public generator with the sequence behind its methods, and return it. */
|
|
72
|
+
export function stampPackageUuidV7Generator<Generator extends object>(
|
|
73
|
+
generator: Generator,
|
|
74
|
+
sequence: PortableUuidV7Generator,
|
|
75
|
+
): Generator {
|
|
76
|
+
return new PackageUuidV7Generator(generator, sequence) as object as Generator;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Narrow an untrusted generator without relying on package-copy identity. */
|
|
80
|
+
export function readUuidV7Generator(
|
|
81
|
+
value: unknown,
|
|
82
|
+
): ValidatedUuidV7Generator | UuidSlugError | undefined {
|
|
83
|
+
if (value === undefined) return undefined;
|
|
84
|
+
const packaged = PackageUuidV7Generator.sequenceOf(value);
|
|
85
|
+
if (packaged) return packaged;
|
|
86
|
+
try {
|
|
87
|
+
if (value === null || typeof value !== "object")
|
|
88
|
+
return new UuidSlugError(INVALID_OPTIONS, UUID_V7_GENERATOR_REQUIRED);
|
|
89
|
+
const source = value as {
|
|
90
|
+
readonly generateUuidV7Bytes?: unknown;
|
|
91
|
+
readonly payloadLayout?: unknown;
|
|
92
|
+
};
|
|
93
|
+
const generateUuidV7Bytes = source.generateUuidV7Bytes;
|
|
94
|
+
if (typeof generateUuidV7Bytes !== "function")
|
|
95
|
+
return new UuidSlugError(INVALID_OPTIONS, UUID_V7_GENERATOR_REQUIRED);
|
|
96
|
+
const payloadLayout = readUuidV7PayloadLayout(source.payloadLayout);
|
|
97
|
+
if (payloadLayout instanceof Error) return payloadLayout;
|
|
98
|
+
return { generateUuidV7Bytes, payloadLayout } as ValidatedUuidV7Generator;
|
|
99
|
+
} catch (cause) {
|
|
100
|
+
return new UuidSlugError(INVALID_OPTIONS, "Reading UUIDv7 generator failed.", { cause });
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* Generate bytes only after validating every option that can fail without advancing sequence state.
|
|
106
|
+
*
|
|
107
|
+
* The generator receives the result buffer and may keep a reference to it, so a result the caller
|
|
108
|
+
* 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/PERFORMANCE.md).
|
|
110
|
+
*/
|
|
111
|
+
export function generateUuidV7BytesWithGenerator(
|
|
112
|
+
generator: ValidatedUuidV7Generator,
|
|
113
|
+
options: UuidV7GenerationValues,
|
|
114
|
+
borrowed = false,
|
|
115
|
+
): Uint8Array | UuidSlugError {
|
|
116
|
+
const hasAt = Object.hasOwn(options, AT_OPTION);
|
|
117
|
+
const requested = hasAt ? readUuidV7Instant(options.at) : undefined;
|
|
118
|
+
if (requested instanceof Error) return requested;
|
|
119
|
+
const hasOutput = Object.hasOwn(options, "output");
|
|
120
|
+
const outputOffset = (options.outputOffset as number | undefined) ?? 0;
|
|
121
|
+
if (hasOutput || Object.hasOwn(options, "outputOffset")) {
|
|
122
|
+
const rangeError = checkByteRange(options.output, outputOffset, 16);
|
|
123
|
+
if (rangeError) return rangeError;
|
|
124
|
+
}
|
|
125
|
+
const drawUuidV7Bytes = generator.drawUuidV7Bytes;
|
|
126
|
+
if (drawUuidV7Bytes)
|
|
127
|
+
return drawUuidV7Bytes(
|
|
128
|
+
requested,
|
|
129
|
+
hasOutput ? (options.output as Uint8Array) : undefined,
|
|
130
|
+
outputOffset,
|
|
131
|
+
);
|
|
132
|
+
let generated: unknown;
|
|
133
|
+
const generatedOutput = new Uint8Array(16);
|
|
134
|
+
try {
|
|
135
|
+
const generateUuidV7Bytes = generator.generateUuidV7Bytes;
|
|
136
|
+
generated = hasAt
|
|
137
|
+
? generateUuidV7Bytes({ at: options.at as UuidV7Instant, output: generatedOutput })
|
|
138
|
+
: generateUuidV7Bytes(generatedOutput);
|
|
139
|
+
} catch (cause) {
|
|
140
|
+
return new UuidSlugError(INVALID_OPTIONS, "UUIDv7 generator failed.", { cause });
|
|
141
|
+
}
|
|
142
|
+
if (isUuidSlugError(generated)) return generated;
|
|
143
|
+
if (!isUuidV7Bytes(generated))
|
|
144
|
+
return new UuidSlugError(
|
|
145
|
+
INVALID_UUID_VERSION,
|
|
146
|
+
"Generator must return exactly 16 RFC-variant UUIDv7 bytes.",
|
|
147
|
+
);
|
|
148
|
+
if (generated !== generatedOutput) generatedOutput.set(generated);
|
|
149
|
+
if (requested) {
|
|
150
|
+
const generatedUnixMs = uuidTimestampFromBytesUnchecked(generatedOutput, 0);
|
|
151
|
+
const fractionBits = generator.payloadLayout.subMillisecondFractionBits;
|
|
152
|
+
const requestedFraction = requested.fractionBucket12 >> (12 - fractionBits);
|
|
153
|
+
const generatedFraction = Number(
|
|
154
|
+
uuidV7PayloadFromBytesUnchecked(generatedOutput, 0) >> BigInt(74 - fractionBits),
|
|
155
|
+
);
|
|
156
|
+
if (
|
|
157
|
+
generatedUnixMs < requested.unixMs ||
|
|
158
|
+
(generatedUnixMs === requested.unixMs && generatedFraction < requestedFraction)
|
|
159
|
+
)
|
|
160
|
+
return new UuidSlugError(
|
|
161
|
+
INVALID_TIMESTAMP,
|
|
162
|
+
"UUIDv7 generator returned an instant before at; its output must preserve or advance the requested instant.",
|
|
163
|
+
);
|
|
164
|
+
}
|
|
165
|
+
if (!hasOutput) return borrowed ? generatedOutput : new Uint8Array(generatedOutput);
|
|
166
|
+
const output = options.output as Uint8Array;
|
|
167
|
+
output.set(generatedOutput, outputOffset);
|
|
168
|
+
return output;
|
|
169
|
+
}
|