@anizoptera/uuid-slug 0.4.0 → 0.5.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 +315 -1057
- package/dist/alphabet.d.ts +1 -1
- package/dist/alphabet.js +1 -1
- package/dist/base64url-name.d.ts +1 -1
- package/dist/base64url-name.js +1 -1
- package/dist/errors.d.ts +1 -1
- package/dist/errors.js +1 -1
- package/dist/feistel.js +1 -1
- package/dist/generation-options.js +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +1 -1
- package/dist/instant.js +1 -1
- package/dist/mask-handle.d.ts +1 -1
- package/dist/mask-handle.js +1 -1
- package/dist/mask.d.ts +1 -1
- package/dist/mask.js +1 -1
- package/dist/masking-codec-protocol.js +1 -1
- package/dist/masking-codec-types.d.ts +1 -1
- package/dist/masking-codec.d.ts +1 -1
- package/dist/masking-codec.js +1 -1
- package/dist/migration.js +1 -1
- package/dist/node/runtime.js +1 -1
- package/dist/payload.d.ts +1 -1
- package/dist/payload.js +1 -1
- package/dist/runtime/pool.js +1 -1
- package/dist/runtime/portable.js +1 -1
- package/dist/sentinel.js +1 -1
- package/dist/siphash.js +1 -1
- package/dist/slug.d.ts +1 -1
- package/dist/slug.js +1 -1
- package/dist/timestamp.d.ts +1 -1
- package/dist/timestamp.js +1 -1
- package/dist/types.d.ts +1 -1
- package/dist/types.js +1 -1
- package/dist/uuid-value-protocol.js +1 -1
- package/dist/uuid-value.d.ts +1 -1
- package/dist/uuid-value.js +1 -1
- package/dist/uuid.d.ts +1 -1
- package/dist/uuid.js +1 -1
- package/dist/v4-slug.d.ts +1 -1
- package/dist/v4-slug.js +1 -1
- package/dist/v4.d.ts +1 -1
- package/dist/v4.js +1 -1
- package/dist/v7-bounds.d.ts +1 -1
- package/dist/v7-bounds.js +1 -1
- package/dist/v7-generator-input.js +1 -1
- package/dist/v7-generator.d.ts +1 -1
- package/dist/v7-generator.js +1 -1
- package/dist/v7-keyless.d.ts +1 -1
- package/dist/v7-keyless.js +1 -1
- package/dist/v7-payload.js +1 -1
- package/dist/v7-slug.d.ts +1 -1
- package/dist/v7-slug.js +1 -1
- package/dist/v7-timestamp.js +1 -1
- package/dist/v7-value-options.js +1 -1
- package/dist/v7-value.d.ts +1 -1
- package/dist/v7-value.js +1 -1
- package/dist/v7.js +1 -1
- package/package.json +5 -3
- package/src/alphabet.ts +2 -2
- package/src/errors.ts +3 -3
- package/src/feistel.ts +1 -1
- package/src/generation-options.ts +1 -1
- package/src/masking-codec-protocol.ts +1 -1
- package/src/masking-codec.ts +1 -1
- package/src/payload.ts +2 -2
- 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 +1 -1
- package/src/slug.ts +6 -6
- package/src/uuid-value-protocol.ts +1 -1
- package/src/uuid-value.ts +1 -1
- package/src/uuid.ts +8 -8
- package/src/v4.ts +2 -2
- package/src/v7-bounds.ts +3 -3
- package/src/v7-generator-input.ts +2 -2
- package/src/v7-keyless.ts +6 -6
- package/src/v7-payload.ts +1 -1
- package/src/v7-slug.ts +1 -1
- package/src/v7.ts +1 -1
package/src/masking-codec.ts
CHANGED
|
@@ -555,7 +555,7 @@ function buildUuidSlugCodec(
|
|
|
555
555
|
// function past the size JavaScriptCore inlines into a small caller, which costs Bun sentinel
|
|
556
556
|
// reads a few nanoseconds; moving it into a helper cost more because Bun did not inline the
|
|
557
557
|
// helper either. Recheck `sentinel.base32.decode` on Bun when this function changes
|
|
558
|
-
// (bench/
|
|
558
|
+
// (bench/decisions.md).
|
|
559
559
|
if (uuid.length === 36) {
|
|
560
560
|
if (selectedCase === UUID_TEXT_LOWERCASE && isUuidString(uuid))
|
|
561
561
|
return uuid as UuidStringFor<Case>;
|
package/src/payload.ts
CHANGED
|
@@ -178,7 +178,7 @@ export function ownedUuidV7BytesToMaskedSlug(
|
|
|
178
178
|
// Raw sentinels have zero outer bits. Only that tail can collide with retained base64 reads;
|
|
179
179
|
// other writes need neither a second encoding nor a lookup for a collision that cannot occur.
|
|
180
180
|
// Skipping the lookup matters: on V8 it hashed and flattened every base64url slug
|
|
181
|
-
// (bench/
|
|
181
|
+
// (bench/decisions.md).
|
|
182
182
|
const canonical =
|
|
183
183
|
alphabet === BASE64URL_NAME || (tail === 0 && reserved?.size)
|
|
184
184
|
? encode(raw, BASE64URL, tail, OUTER_TAG_BITS)
|
|
@@ -203,7 +203,7 @@ export const noMaskedSlugMatch = /* @__NO_SIDE_EFFECTS__ */ (): UuidSlugError =>
|
|
|
203
203
|
* Decode a masked slug and return `undefined` when every mask's check rejects it. Source-specific
|
|
204
204
|
* readers report that miss with `noMaskedSlugMatch`; a codec reading an ambiguous 22-character slug
|
|
205
205
|
* takes the plain reading instead, so the miss builds no error. Readers call this directly: a wrapper
|
|
206
|
-
* that built the error slowed the masked-slug text reader on Node (bench/
|
|
206
|
+
* that built the error slowed the masked-slug text reader on Node (bench/decisions.md).
|
|
207
207
|
*/
|
|
208
208
|
export function unmaskSlug(
|
|
209
209
|
slug: string,
|
package/src/runtime/bun.ts
CHANGED
|
@@ -26,7 +26,7 @@ else if (globalThis.crypto.randomUUID)
|
|
|
26
26
|
|
|
27
27
|
// Native UUIDv7 can advance logical time during counter overflow; defaults do not forbid that.
|
|
28
28
|
// Select it only when complete-call gains preserve configured-call speed and resource efficiency.
|
|
29
|
-
// Explicit generators keep their clock controls; bench/
|
|
29
|
+
// Explicit generators keep their clock controls; bench/decisions.md owns drift and cost evidence.
|
|
30
30
|
const nativeUuidV7 = (globalThis as { Bun?: { randomUUIDv7?: (encoding?: "base64url") => string } })
|
|
31
31
|
.Bun?.randomUUIDv7;
|
|
32
32
|
if (typeof nativeUuidV7 === "function") {
|
package/src/runtime/node.ts
CHANGED
|
@@ -35,7 +35,7 @@ if (nodeOptions?.includes("jitless")) {
|
|
|
35
35
|
|
|
36
36
|
/**
|
|
37
37
|
* Node's native UTF-8 encoder materially reduces string-seed construction; the portable adapter
|
|
38
|
-
* remains the compatibility boundary. bench/
|
|
38
|
+
* remains the compatibility boundary. bench/decisions.md owns the measured runtime scope.
|
|
39
39
|
*/
|
|
40
40
|
export const encodeUtf8 = /* @__NO_SIDE_EFFECTS__ */ (text: string): Uint8Array =>
|
|
41
41
|
Buffer.from(text, "utf8");
|
|
@@ -53,7 +53,7 @@ const nodeRuntime: Runtime = {
|
|
|
53
53
|
}),
|
|
54
54
|
// Pooled formatting wins with the JIT; native text wins without it. Missing native capability
|
|
55
55
|
// stays undefined so the generator uses its tested portable fallback. Remeasure both modes
|
|
56
|
-
// after Node changes; bench/
|
|
56
|
+
// after Node changes; bench/decisions.md owns the compared calls and resource limits.
|
|
57
57
|
...(jitless ? { jitless: true, uuidV4: crypto.randomUUID } : {}),
|
|
58
58
|
};
|
|
59
59
|
|
package/src/runtime/pool.ts
CHANGED
|
@@ -55,7 +55,7 @@ export function pooledFill(
|
|
|
55
55
|
// Continuation draws need four bytes. Fixed stores avoid their loop without another view
|
|
56
56
|
// or retained buffer. Owned draws use four-byte blocks, reusing each source offset rather
|
|
57
57
|
// than repeating its arithmetic. Blocks keep the body smaller than fully expanded stores;
|
|
58
|
-
// other lengths keep the indexed loop. Complete-call comparisons in bench/
|
|
58
|
+
// other lengths keep the indexed loop. Complete-call comparisons in bench/decisions.md
|
|
59
59
|
// decide this shape, not copy-only timing. Remeasure if draw widths
|
|
60
60
|
// or the runtime's typed-array handling change.
|
|
61
61
|
if (length === 4) {
|
package/src/runtime/portable.ts
CHANGED
|
@@ -29,7 +29,7 @@ const runtimeCapabilities: Runtime = {
|
|
|
29
29
|
// WebKit's fixed formatter slowed unrelated successful calls in mixed comparisons. Native hex
|
|
30
30
|
// did not reproduce a repeated loss while other engines retain their fixed writers. This identity
|
|
31
31
|
// selects cost only; absent hex support still uses the portable writer. Remeasure after browser
|
|
32
|
-
// changes (bench/
|
|
32
|
+
// changes (bench/decisions.md); the shared ASCII decoder also slowed slug output.
|
|
33
33
|
if (
|
|
34
34
|
typeof navigator !== "undefined" &&
|
|
35
35
|
navigator.vendor === "Apple Computer, Inc." &&
|
package/src/slug.ts
CHANGED
|
@@ -245,7 +245,7 @@ export function uuidBytesToPlainSlug(
|
|
|
245
245
|
if (selectedAlphabet === BASE32HEX_NAME) return encode(bytes, BASE32HEX) as PlainUuidSlug;
|
|
246
246
|
// Native encoding owns this exact plain-payload job. Offset windows and non-array forms retain
|
|
247
247
|
// general conversion; masked tails never enter here. Keep base32 controls in the comparison
|
|
248
|
-
// when changing this dispatch (bench/
|
|
248
|
+
// when changing this dispatch (bench/decisions.md).
|
|
249
249
|
if (selectedAlphabet === BASE64URL_NAME) {
|
|
250
250
|
if (nativePlainUuidBase64) {
|
|
251
251
|
try {
|
|
@@ -361,7 +361,7 @@ export function uuidStringToPlainSlug(
|
|
|
361
361
|
// Resolve caller selectors before scratch is live, then parse and encode without callbacks.
|
|
362
362
|
// Separate text-to-slug
|
|
363
363
|
// writers read hex pairs and concatenated characters, and were slower on every runtime
|
|
364
|
-
// (bench/
|
|
364
|
+
// (bench/decisions.md). Reassess scratch ownership if encoding adds caller-controlled work.
|
|
365
365
|
const bytes = uuidStringToBytes(uuidText, textSlugScratch);
|
|
366
366
|
if (bytes instanceof Error) return bytes;
|
|
367
367
|
return encode(bytes, alpha) as PlainUuidSlug;
|
|
@@ -549,7 +549,7 @@ export function uuidToString(
|
|
|
549
549
|
textCase = caseAfterOffset;
|
|
550
550
|
} else textCase = byteOffsetOrCase;
|
|
551
551
|
// 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/
|
|
552
|
+
// An inline `typeof` guard ahead of the helper slowed Node mixed-case text (bench/decisions.md).
|
|
553
553
|
if (textCase === UUID_TEXT_LOWERCASE && isUuidString(uuid)) return uuid;
|
|
554
554
|
const localBytes = exactLocalUuidBytes(uuid);
|
|
555
555
|
if (localBytes) {
|
|
@@ -570,7 +570,7 @@ export function uuidToString(
|
|
|
570
570
|
}
|
|
571
571
|
}
|
|
572
572
|
// Only text leaves this call. Reuse private scratch instead of an owned decode array;
|
|
573
|
-
// public caller-buffer decoding adds validation and copying (bench/
|
|
573
|
+
// public caller-buffer decoding adds validation and copying (bench/decisions.md).
|
|
574
574
|
const alpha = typeof input === "string" ? SLUG_ALPHABET_BY_LENGTH[input.length] : undefined;
|
|
575
575
|
const decoded =
|
|
576
576
|
typeof input === "string"
|
|
@@ -671,7 +671,7 @@ function fixedCanonicalUuidV7UnixMs(text: string): number {
|
|
|
671
671
|
// low word so timestamps above its sign bit preserve all 48 bits. Only validated canonical text
|
|
672
672
|
// reaches this helper; compact text retains its contiguous parse. Table reads slightly favor
|
|
673
673
|
// Bun but lose on Node in the source screen; remeasure complete calls after parser or engine
|
|
674
|
-
// changes (bench/
|
|
674
|
+
// changes (bench/decisions.md).
|
|
675
675
|
const high =
|
|
676
676
|
(validatedHexNibble(text, 0) << 12) |
|
|
677
677
|
(validatedHexNibble(text, 1) << 8) |
|
|
@@ -696,7 +696,7 @@ function parsedCanonicalUuidV7UnixMs(text: string): number {
|
|
|
696
696
|
}
|
|
697
697
|
|
|
698
698
|
// 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/
|
|
699
|
+
// Recheck both complete calls after engine changes against bench/decisions.md.
|
|
700
700
|
const canonicalUuidV7UnixMsUnchecked = runtime.jitless
|
|
701
701
|
? parsedCanonicalUuidV7UnixMs
|
|
702
702
|
: fixedCanonicalUuidV7UnixMs;
|
|
@@ -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
|
@@ -74,7 +74,7 @@ class ParsedUuidValue<
|
|
|
74
74
|
{
|
|
75
75
|
// Private bytes are already a complete immutable UUID; public conversion would validate them
|
|
76
76
|
// 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/
|
|
77
|
+
// Revisit if private storage becomes mutable or borrowed; measurements live in bench/decisions.md.
|
|
78
78
|
get version(): Version {
|
|
79
79
|
return uuidVersion(LocalUuidValue.ownBytes(this), 0) as Version;
|
|
80
80
|
}
|
package/src/uuid.ts
CHANGED
|
@@ -87,7 +87,7 @@ for (let i = 0; i < 16; i += 1) {
|
|
|
87
87
|
HEX_NIBBLES[UPPERCASE_HEX.charCodeAt(i)] = i;
|
|
88
88
|
}
|
|
89
89
|
// Bun's Latin-1 writer and the fixed writer share lazily built case tables; native hex needs none.
|
|
90
|
-
// bench/
|
|
90
|
+
// bench/decisions.md owns the comparison and recheck conditions. Tables are built on first use.
|
|
91
91
|
let uuidTextScratch: Latin1Scratch | undefined;
|
|
92
92
|
let lowercaseHexCodes: Uint8Array | undefined;
|
|
93
93
|
let uppercaseHexCodes: Uint8Array | undefined;
|
|
@@ -123,7 +123,7 @@ function formatUuidBytesLatin1(
|
|
|
123
123
|
: (lowercaseHexCodes ??= hexCodes(HEX));
|
|
124
124
|
const text = scratch.bytes;
|
|
125
125
|
// Fixed positions remove the loop and offset-table reads on Bun's selected writer.
|
|
126
|
-
// The indexed loop loses repeated complete text calls; bench/
|
|
126
|
+
// The indexed loop loses repeated complete text calls; bench/decisions.md owns the evidence.
|
|
127
127
|
// Keep native string construction and shared storage; remeasure after JSC or writer changes.
|
|
128
128
|
const code0 = (bytes[offset + 0] as number) * 2;
|
|
129
129
|
text[0] = codes[code0] as number;
|
|
@@ -267,7 +267,7 @@ export function uuidStringToBytes(
|
|
|
267
267
|
|
|
268
268
|
// One pass decodes and validates: OR-ing every character code and every decoded pair exposes a
|
|
269
269
|
// 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/
|
|
270
|
+
// about twice as much on Node and three times on Bun (bench/decisions.md). Only failing text
|
|
271
271
|
// pays a second scan, which locates the offset for the message.
|
|
272
272
|
const target = out === undefined ? new Uint8Array(16) : decodedUuidScratch;
|
|
273
273
|
let codes = 0;
|
|
@@ -286,7 +286,7 @@ export function uuidStringToBytes(
|
|
|
286
286
|
if (codes < 128 && pairs < 256) {
|
|
287
287
|
if (out === undefined) return target;
|
|
288
288
|
// A byte loop rather than `set`: the native call made Bun text-to-slug conversion slower
|
|
289
|
-
// (bench/
|
|
289
|
+
// (bench/decisions.md).
|
|
290
290
|
for (let byteIndex = 0; byteIndex < 16; byteIndex += 1)
|
|
291
291
|
out[offset + byteIndex] = target[byteIndex] as number;
|
|
292
292
|
return out;
|
|
@@ -374,7 +374,7 @@ export function formatUuidBytesUnchecked<Case extends UuidTextCase = typeof UUID
|
|
|
374
374
|
// Bun retains its Latin-1 writer. A fixed argument list makes one flat string without
|
|
375
375
|
// temporary bytes, intermediate hex or concatenation. WebKit selects native hex to avoid
|
|
376
376
|
// repeated mixed-workload losses; remeasure both paths after engine changes
|
|
377
|
-
// (bench/
|
|
377
|
+
// (bench/decisions.md). Keep case selection and fixed writing together to avoid another call.
|
|
378
378
|
if (createLatin1Scratch)
|
|
379
379
|
return formatUuidBytesLatin1(
|
|
380
380
|
createLatin1Scratch,
|
|
@@ -484,10 +484,10 @@ export function isUuidText(value: unknown): value is UuidText {
|
|
|
484
484
|
}
|
|
485
485
|
|
|
486
486
|
// Canonical guards stay regular expressions: a character loop measured slower on Node and Bun
|
|
487
|
-
// (bench/
|
|
487
|
+
// (bench/decisions.md, Canonical UUID text).
|
|
488
488
|
// Pair repetition improves canonical calls, but slows Bun's successful base32 normalization.
|
|
489
489
|
// 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/
|
|
490
|
+
// Remeasure normalization if this capability moves to another adapter (bench/decisions.md).
|
|
491
491
|
const UUID_RE = createLatin1Scratch
|
|
492
492
|
? /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
|
|
493
493
|
: /^(?:[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}$/;
|
|
@@ -517,7 +517,7 @@ export function isUuidV4Text(value: unknown): value is UuidV4Text {
|
|
|
517
517
|
export function isUuidV7Text(value: unknown): value is UuidV7Text {
|
|
518
518
|
// Canonical text uses the same syntax with either case, avoiding the full digit loop before
|
|
519
519
|
// timestamp parsing. Other spellings retain their existing checks; remeasure after engine or
|
|
520
|
-
// accepted-syntax changes (bench/
|
|
520
|
+
// accepted-syntax changes (bench/decisions.md).
|
|
521
521
|
if (typeof value === "string" && value.length === UUID_LENGTH) return UUID_V7_TEXT_RE.test(value);
|
|
522
522
|
if (!isUuidText(value)) return false;
|
|
523
523
|
const textStart = uuidTextStart(value);
|
package/src/v4.ts
CHANGED
|
@@ -127,7 +127,7 @@ export function generatePortableUuidV4<Case extends UuidTextCase = typeof UUID_T
|
|
|
127
127
|
/**
|
|
128
128
|
* Fill the module scratch with UUIDv4 bytes for a writer that reads them before its next draw. Text
|
|
129
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/
|
|
130
|
+
* input checks, which cost about a third of Node's portable text call (bench/decisions.md).
|
|
131
131
|
* Encoding cannot draw entropy, so the scratch cannot change between this return and the read.
|
|
132
132
|
*/
|
|
133
133
|
export function drawUuidV4Scratch(): Uint8Array | UuidSlugError {
|
|
@@ -172,7 +172,7 @@ export function generateUuidV4<Case extends UuidTextCase = typeof UUID_TEXT_LOWE
|
|
|
172
172
|
// Trust proper native output directly: validation and identity tracking impose guarantees
|
|
173
173
|
// beyond the default native baseline. Configured entropy still validates at its caller seam.
|
|
174
174
|
// Remeasure each output form if case normalization, host APIs or engine inlining
|
|
175
|
-
// changes; bench/
|
|
175
|
+
// changes; bench/decisions.md owns the evidence.
|
|
176
176
|
const native = runtime.uuidV4;
|
|
177
177
|
if (!native) return generatedOrThrow(generatePortableUuidV4(textCase));
|
|
178
178
|
let uuid: string | UuidSlugError;
|
package/src/v7-bounds.ts
CHANGED
|
@@ -70,7 +70,7 @@ function fixedTextEndpoint<Case extends UuidTextCase>(
|
|
|
70
70
|
): UuidV7StringFor<Case> {
|
|
71
71
|
// Fixed character arguments reduce consumed bounds costs on V8 with the JIT. Byte pairs remain
|
|
72
72
|
// faster on Bun and JITless Node; selection is outside per-ID calls. Remeasure engine changes
|
|
73
|
-
// against bench/
|
|
73
|
+
// against bench/decisions.md, including both endpoint reads and lazy table construction.
|
|
74
74
|
const hex = (hexCodes ??= Uint8Array.from("0123456789abcdef", (digit) => digit.charCodeAt(0)));
|
|
75
75
|
// Validated timestamps have 48 bits; splitting avoids truncating their upper 16 bits.
|
|
76
76
|
const high = Math.floor(unixMs / 0x1_0000_0000);
|
|
@@ -102,7 +102,7 @@ function textEndpoint<Case extends UuidTextCase>(
|
|
|
102
102
|
): UuidV7StringFor<Case> {
|
|
103
103
|
// Byte pairs avoid radix formatting and beat fixed character arguments on Bun and JITless Node.
|
|
104
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/
|
|
105
|
+
// Remeasure radix formatting and fixed arguments after engine changes (bench/decisions.md).
|
|
106
106
|
const hex = (hexBytes ??= Array.from({ length: 256 }, (_, byte) =>
|
|
107
107
|
byte.toString(16).padStart(2, "0"),
|
|
108
108
|
));
|
|
@@ -163,7 +163,7 @@ export function uuidV7StringBounds(
|
|
|
163
163
|
const end = intervalEnd(startUnixMs, endUnixMs);
|
|
164
164
|
if (typeof end !== "number") return end;
|
|
165
165
|
// Direct formatting avoids two temporary byte arrays. Keep the byte writer independent unless
|
|
166
|
-
// repeated public-route measurements reverse this result; bench/
|
|
166
|
+
// repeated public-route measurements reverse this result; bench/decisions.md owns that trigger.
|
|
167
167
|
return {
|
|
168
168
|
startInclusive: selectedTextEndpoint(startUnixMs, false, textCase),
|
|
169
169
|
endInclusive: selectedTextEndpoint(end, true, textCase),
|
|
@@ -48,7 +48,7 @@ class ReturnObject {
|
|
|
48
48
|
*
|
|
49
49
|
* Structural validation allocated a validated object and rescanned the layout keys on every call
|
|
50
50
|
* that passed `generator`, and the untrusted-generator call then needed a scratch buffer, byte
|
|
51
|
-
* validation, an `at` check, and a copy (bench/
|
|
51
|
+
* validation, an `at` check, and a copy (bench/decisions.md). The stamp adds a private field
|
|
52
52
|
* instead of a class prototype, so the public object stays plain. A module `WeakMap` is the rejected
|
|
53
53
|
* alternative: registration made default generator creation 1.6 times slower. Remeasure if engines
|
|
54
54
|
* change how they store private fields or weak collections.
|
|
@@ -106,7 +106,7 @@ export function readUuidV7Generator(
|
|
|
106
106
|
*
|
|
107
107
|
* The generator receives the result buffer and may keep a reference to it, so a result the caller
|
|
108
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/
|
|
109
|
+
* never returns them: text, slug, and masked-slug writers skip that copy (bench/decisions.md).
|
|
110
110
|
*/
|
|
111
111
|
export function generateUuidV7BytesWithGenerator(
|
|
112
112
|
generator: ValidatedUuidV7Generator,
|
package/src/v7-keyless.ts
CHANGED
|
@@ -48,7 +48,7 @@ const UUID_V7_BYTE_OPTIONS = {
|
|
|
48
48
|
/**
|
|
49
49
|
* Text and bytes keep independent lazy state so neither output form pays cross-form coordination.
|
|
50
50
|
* Native defaults avoid constructing this generator. Explicit time, configured generators and
|
|
51
|
-
* native failure still need portable state; bench/
|
|
51
|
+
* native failure still need portable state; bench/decisions.md owns the selection evidence.
|
|
52
52
|
*/
|
|
53
53
|
let textGenerator: PortableUuidV7Generator | undefined;
|
|
54
54
|
let byteGenerator: PortableUuidV7Generator | undefined;
|
|
@@ -69,7 +69,7 @@ const keylessTextBytes = new Uint8Array(16);
|
|
|
69
69
|
|
|
70
70
|
/**
|
|
71
71
|
* 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/
|
|
72
|
+
* public method allocated it and read every option a second time (bench/decisions.md).
|
|
73
73
|
*/
|
|
74
74
|
function drawFromReadOptions(
|
|
75
75
|
generator: PortableUuidV7Generator,
|
|
@@ -101,10 +101,10 @@ export const uuidV7BytesAt = (at: unknown): Uint8Array | UuidSlugError => drawAt
|
|
|
101
101
|
* Slug and pair writers encode their bytes before returning and draw nothing in between, so they
|
|
102
102
|
* borrow the generator's private text scratch instead of validating a second module buffer as
|
|
103
103
|
* 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/
|
|
104
|
+
* formatter has not earned its cost on the primary calls (bench/decisions.md).
|
|
105
105
|
* Keep configured output validation and the generator's reentrancy guard; a borrowed buffer
|
|
106
106
|
* must never escape or survive another draw. Remeasure complete calls when either writer changes
|
|
107
|
-
* (bench/
|
|
107
|
+
* (bench/decisions.md), rather than assuming fewer checks improve every runtime.
|
|
108
108
|
*/
|
|
109
109
|
export const currentUuidV7Scratch = (): Uint8Array | UuidSlugError =>
|
|
110
110
|
v7Text().drawUuidV7Bytes(undefined, keylessTextBytes);
|
|
@@ -123,7 +123,7 @@ const portableUuidV7Text = (textCase: UuidTextCase): string | UuidSlugError =>
|
|
|
123
123
|
|
|
124
124
|
// Trust proper native results directly; validation and identity tracking add guarantees beyond
|
|
125
125
|
// the default native baseline. Keep exception fallback separate from configured calls, and
|
|
126
|
-
// remeasure complete calls when host capabilities change; bench/
|
|
126
|
+
// remeasure complete calls when host capabilities change; bench/decisions.md owns evidence.
|
|
127
127
|
function generateNativeDefaultUuidV7<Case extends UuidTextCase>(
|
|
128
128
|
selectedCase: Case,
|
|
129
129
|
): UuidV7StringFor<Case> | UuidSlugError {
|
|
@@ -281,7 +281,7 @@ export const currentUuidV7Bytes = (): UuidV7Bytes | UuidSlugError =>
|
|
|
281
281
|
// Independent draws remove unrequested sequence work from owned defaults. Keep JITless on its
|
|
282
282
|
// measured generator path; configured calls and immutable values retain their declared layout.
|
|
283
283
|
// Remeasure complete calls if entropy, timestamp writing or runtime selection changes;
|
|
284
|
-
// bench/
|
|
284
|
+
// bench/decisions.md owns runtime comparisons rather than this selection comment.
|
|
285
285
|
const generateSelectedDefaultUuidV7Bytes = runtime.jitless
|
|
286
286
|
? currentUuidV7Bytes
|
|
287
287
|
: 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
|
@@ -56,7 +56,7 @@ const portableUuidV7Slug = (): string | UuidSlugError => {
|
|
|
56
56
|
|
|
57
57
|
// Direct native output removes clock, entropy, byte writing and encoding from ordinary calls.
|
|
58
58
|
// Configured calls and base32hex remain portable. Remeasure complete calls and resources if this
|
|
59
|
-
// boundary changes; bench/
|
|
59
|
+
// boundary changes; bench/decisions.md owns evidence. Trust proper native results directly;
|
|
60
60
|
// result validation and identity tracking would impose stronger default guarantees.
|
|
61
61
|
function nativeUuidV7Slug(): string | UuidSlugError {
|
|
62
62
|
const native = runtime.uuidV7Slug;
|
package/src/v7.ts
CHANGED
|
@@ -105,7 +105,7 @@ function writeTimestampLoop(bytes: Uint8Array, ms: number, offset: number) {
|
|
|
105
105
|
}
|
|
106
106
|
|
|
107
107
|
// Measured Bun favors the loop while Node and Chromium favor fixed writes; select once so generation
|
|
108
|
-
// pays no per-call branch. bench/
|
|
108
|
+
// pays no per-call branch. bench/decisions.md owns the measurements and replacement condition.
|
|
109
109
|
const writeTimestamp = (globalThis as { Bun?: object }).Bun
|
|
110
110
|
? writeTimestampLoop
|
|
111
111
|
: writeTimestampWords;
|