@anizoptera/uuid-slug 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +54 -31
- package/README.md +1052 -261
- package/dist/alphabet.d.ts +5 -17
- package/dist/alphabet.d.ts.map +1 -1
- package/dist/alphabet.js +146 -112
- package/dist/alphabet.js.map +1 -1
- package/dist/base64url-name.d.ts +7 -0
- package/dist/base64url-name.d.ts.map +1 -0
- package/dist/base64url-name.js +8 -0
- package/dist/base64url-name.js.map +1 -0
- package/dist/errors.d.ts +50 -9
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +145 -63
- package/dist/errors.js.map +1 -1
- package/dist/feistel.js +29 -95
- package/dist/feistel.js.map +1 -1
- package/dist/generation-options.js +20 -0
- package/dist/generation-options.js.map +1 -0
- package/dist/index.d.ts +22 -10
- package/dist/index.js +21 -9
- package/dist/instant.js +83 -0
- package/dist/instant.js.map +1 -0
- package/dist/mask-handle.d.ts +16 -0
- package/dist/mask-handle.d.ts.map +1 -0
- package/dist/mask-handle.js +60 -0
- package/dist/mask-handle.js.map +1 -0
- package/dist/mask.d.ts +27 -0
- package/dist/mask.d.ts.map +1 -0
- package/dist/mask.js +151 -95
- package/dist/mask.js.map +1 -1
- package/dist/masking-codec-protocol.js +23 -0
- package/dist/masking-codec-protocol.js.map +1 -0
- package/dist/masking-codec-types.d.ts +245 -0
- package/dist/masking-codec-types.d.ts.map +1 -0
- package/dist/masking-codec.d.ts +19 -0
- package/dist/masking-codec.d.ts.map +1 -0
- package/dist/masking-codec.js +391 -0
- package/dist/masking-codec.js.map +1 -0
- package/dist/migration.js +114 -51
- package/dist/migration.js.map +1 -1
- package/dist/node/runtime.js +39 -0
- package/dist/node/runtime.js.map +1 -0
- package/dist/payload.d.ts +7 -0
- package/dist/payload.d.ts.map +1 -0
- package/dist/payload.js +118 -0
- package/dist/payload.js.map +1 -0
- package/dist/runtime/pool.js +21 -46
- package/dist/runtime/pool.js.map +1 -1
- package/dist/runtime/portable.js +27 -0
- package/dist/runtime/portable.js.map +1 -0
- package/dist/sentinel.js +10 -0
- package/dist/sentinel.js.map +1 -0
- package/dist/siphash.js +20 -99
- package/dist/siphash.js.map +1 -1
- package/dist/slug.d.ts +169 -0
- package/dist/slug.d.ts.map +1 -0
- package/dist/slug.js +268 -0
- package/dist/slug.js.map +1 -0
- package/dist/timestamp.d.ts +19 -0
- package/dist/timestamp.d.ts.map +1 -0
- package/dist/timestamp.js +44 -0
- package/dist/timestamp.js.map +1 -0
- package/dist/types.d.ts +480 -200
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +8 -0
- package/dist/types.js.map +1 -0
- package/dist/uuid-value-protocol.js +46 -0
- package/dist/uuid-value-protocol.js.map +1 -0
- package/dist/uuid-value.d.ts +17 -0
- package/dist/uuid-value.d.ts.map +1 -0
- package/dist/uuid-value.js +127 -0
- package/dist/uuid-value.js.map +1 -0
- package/dist/uuid.d.ts +51 -64
- package/dist/uuid.d.ts.map +1 -1
- package/dist/uuid.js +203 -199
- package/dist/uuid.js.map +1 -1
- package/dist/v4-slug.d.ts +16 -0
- package/dist/v4-slug.d.ts.map +1 -0
- package/dist/v4-slug.js +16 -0
- package/dist/v4-slug.js.map +1 -0
- package/dist/v4.d.ts +42 -0
- package/dist/v4.d.ts.map +1 -0
- package/dist/v4.js +85 -0
- package/dist/v4.js.map +1 -0
- package/dist/v7-bounds.d.ts +36 -0
- package/dist/v7-bounds.d.ts.map +1 -0
- package/dist/v7-bounds.js +49 -0
- package/dist/v7-bounds.js.map +1 -0
- package/dist/v7-generator-input.js +75 -0
- package/dist/v7-generator-input.js.map +1 -0
- package/dist/v7-generator.d.ts +43 -0
- package/dist/v7-generator.d.ts.map +1 -0
- package/dist/v7-generator.js +105 -0
- package/dist/v7-generator.js.map +1 -0
- package/dist/v7-keyless.d.ts +46 -0
- package/dist/v7-keyless.d.ts.map +1 -0
- package/dist/v7-keyless.js +106 -0
- package/dist/v7-keyless.js.map +1 -0
- package/dist/v7-payload.js +54 -0
- package/dist/v7-payload.js.map +1 -0
- package/dist/v7-slug.d.ts +46 -0
- package/dist/v7-slug.d.ts.map +1 -0
- package/dist/v7-slug.js +127 -0
- package/dist/v7-slug.js.map +1 -0
- package/dist/v7-timestamp.js +9 -0
- package/dist/v7-timestamp.js.map +1 -0
- package/dist/v7-value-options.js +28 -0
- package/dist/v7-value-options.js.map +1 -0
- package/dist/v7-value.d.ts +23 -0
- package/dist/v7-value.d.ts.map +1 -0
- package/dist/v7-value.js +31 -0
- package/dist/v7-value.js.map +1 -0
- package/dist/v7.js +127 -171
- package/dist/v7.js.map +1 -1
- package/package.json +14 -9
- package/src/alphabet.ts +456 -27
- package/src/base64url-name.ts +5 -0
- package/src/errors.ts +373 -37
- package/src/feistel.ts +69 -56
- package/src/generation-options.ts +48 -0
- package/src/index.ts +134 -80
- package/src/instant.ts +196 -0
- package/src/keyless.ts +7 -134
- package/src/mask-handle.ts +141 -0
- package/src/mask.ts +354 -129
- package/src/masking-codec-protocol.ts +29 -0
- package/src/masking-codec-types.ts +380 -0
- package/src/masking-codec.ts +923 -0
- package/src/migration.ts +195 -42
- package/src/payload.ts +321 -0
- package/src/runtime/bun.ts +30 -49
- package/src/runtime/node.ts +43 -24
- package/src/runtime/pool.ts +49 -21
- package/src/runtime/portable.ts +68 -0
- package/src/runtime/types.ts +23 -35
- package/src/sentinel.ts +13 -0
- package/src/siphash.ts +5 -4
- package/src/slug.ts +884 -0
- package/src/timestamp.ts +122 -0
- package/src/types.ts +759 -205
- package/src/uuid-value-protocol.ts +77 -0
- package/src/uuid-value.ts +341 -0
- package/src/uuid.ts +514 -234
- package/src/v4-slug.ts +27 -0
- package/src/v4.ts +234 -0
- package/src/v7-bounds.ts +171 -0
- package/src/v7-generator-input.ts +169 -0
- package/src/v7-generator.ts +245 -0
- package/src/v7-keyless.ts +354 -0
- package/src/v7-payload.ts +121 -0
- package/src/v7-slug.ts +293 -0
- package/src/v7-timestamp.ts +21 -0
- package/src/v7-value-options.ts +62 -0
- package/src/v7-value.ts +54 -0
- package/src/v7.ts +377 -200
- package/dist/base64url.d.ts +0 -20
- package/dist/base64url.d.ts.map +0 -1
- package/dist/base64url.js +0 -33
- package/dist/base64url.js.map +0 -1
- package/dist/codec.d.ts +0 -17
- package/dist/codec.d.ts.map +0 -1
- package/dist/codec.js +0 -192
- package/dist/codec.js.map +0 -1
- package/dist/keyless.d.ts +0 -31
- package/dist/keyless.d.ts.map +0 -1
- package/dist/keyless.js +0 -93
- package/dist/keyless.js.map +0 -1
- package/dist/legacy-mask.js +0 -55
- package/dist/legacy-mask.js.map +0 -1
- package/dist/node/alphabet.js +0 -130
- package/dist/node/base64url.js +0 -31
- package/dist/node/codec.js +0 -190
- package/dist/node/errors.js +0 -78
- package/dist/node/feistel.js +0 -103
- package/dist/node/index.js +0 -10
- package/dist/node/keyless.js +0 -91
- package/dist/node/legacy-mask.js +0 -53
- package/dist/node/mask.js +0 -106
- package/dist/node/migration.js +0 -64
- package/dist/node/runtime/node.js +0 -33
- package/dist/node/runtime/pool.js +0 -53
- package/dist/node/schema.js +0 -214
- package/dist/node/siphash.js +0 -106
- package/dist/node/uuid.js +0 -226
- package/dist/node/v7.js +0 -185
- package/dist/node/yield.js +0 -20
- package/dist/runtime/web.js +0 -39
- package/dist/runtime/web.js.map +0 -1
- package/dist/schema.d.ts +0 -20
- package/dist/schema.d.ts.map +0 -1
- package/dist/schema.js +0 -216
- package/dist/schema.js.map +0 -1
- package/dist/v7.d.ts +0 -12
- package/dist/v7.d.ts.map +0 -1
- package/dist/yield.js +0 -22
- package/dist/yield.js.map +0 -1
- package/src/base64url.ts +0 -41
- package/src/codec.ts +0 -320
- package/src/legacy-mask.ts +0 -25
- package/src/runtime/web.ts +0 -48
- package/src/schema.ts +0 -300
- package/src/yield.ts +0 -22
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import type { UuidV7MaskingCodec, UuidV7PayloadLayout } from "./types.ts";
|
|
4
|
+
import { isUint8Array } from "./errors.ts";
|
|
5
|
+
|
|
6
|
+
export const UUID_VALUE_BYTES = Symbol.for("@anizoptera/uuid-slug.uuid-value-bytes");
|
|
7
|
+
export const UUID_VALUE_CONTEXT = Symbol.for("@anizoptera/uuid-slug.uuid-value-context");
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Base of every UUID value this package copy creates. Readers recognize values through it without
|
|
11
|
+
* importing the value class, and private fields keep the state off the frozen value's own properties.
|
|
12
|
+
*
|
|
13
|
+
* A module `WeakMap` keyed by value is the rejected alternative: registering each value cost more
|
|
14
|
+
* than the rest of value creation (bench/PERFORMANCE.md). Remeasure if engines change how they
|
|
15
|
+
* store private fields or weak collections.
|
|
16
|
+
*/
|
|
17
|
+
export class LocalUuidValue {
|
|
18
|
+
readonly #bytes: Uint8Array;
|
|
19
|
+
readonly #maskingCodec: UuidV7MaskingCodec | undefined;
|
|
20
|
+
readonly #payloadLayout: UuidV7PayloadLayout | undefined;
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* @param bytes - Package-owned bytes that nothing else writes.
|
|
24
|
+
* @param payloadLayout - Package-owned layout that no caller can reach or change.
|
|
25
|
+
*/
|
|
26
|
+
constructor(
|
|
27
|
+
bytes: Uint8Array,
|
|
28
|
+
maskingCodec: UuidV7MaskingCodec | undefined,
|
|
29
|
+
payloadLayout: UuidV7PayloadLayout | undefined,
|
|
30
|
+
) {
|
|
31
|
+
this.#bytes = bytes;
|
|
32
|
+
this.#maskingCodec = maskingCodec;
|
|
33
|
+
this.#payloadLayout = payloadLayout;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Recognize a value this package copy created; a lookalike or proxy is not one. */
|
|
37
|
+
static is(value: unknown): value is LocalUuidValue {
|
|
38
|
+
return typeof value === "object" && value !== null && #bytes in value;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
// The readers below trust their argument: a detached method called on another object throws
|
|
42
|
+
// `TypeError` instead of reading state.
|
|
43
|
+
static ownBytes(value: LocalUuidValue): Uint8Array {
|
|
44
|
+
return value.#bytes;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
static ownMaskingCodec(value: LocalUuidValue): UuidV7MaskingCodec | undefined {
|
|
48
|
+
return value.#maskingCodec;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
static ownPayloadLayout(value: LocalUuidValue): UuidV7PayloadLayout | undefined {
|
|
52
|
+
return value.#payloadLayout;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
[UUID_VALUE_CONTEXT]() {
|
|
56
|
+
// Foreign readers need presets as well as bits. Copy the layout so this protocol cannot
|
|
57
|
+
// expose mutable private state; the original caller already owns the retained codec.
|
|
58
|
+
return {
|
|
59
|
+
maskingCodec: this.#maskingCodec,
|
|
60
|
+
payloadLayout: this.#payloadLayout && { ...this.#payloadLayout },
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Recognize local values without allocation and duplicate-package values through one stable protocol. */
|
|
66
|
+
export function uuidValueBytes(value: unknown): Uint8Array | undefined {
|
|
67
|
+
if (LocalUuidValue.is(value)) return LocalUuidValue.ownBytes(value);
|
|
68
|
+
if (typeof value !== "object" || value === null) return undefined;
|
|
69
|
+
try {
|
|
70
|
+
const read = Reflect.get(value, UUID_VALUE_BYTES);
|
|
71
|
+
if (typeof read !== "function") return undefined;
|
|
72
|
+
const bytes = Reflect.apply(read, value, []);
|
|
73
|
+
return isUint8Array(bytes) && bytes.length === 16 ? bytes : undefined;
|
|
74
|
+
} catch {
|
|
75
|
+
return undefined;
|
|
76
|
+
}
|
|
77
|
+
}
|
|
@@ -0,0 +1,341 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
BASE32HEX,
|
|
5
|
+
BASE64URL,
|
|
6
|
+
BASE64URL_NAME,
|
|
7
|
+
encode as encodeUuidBytes,
|
|
8
|
+
isEncoded,
|
|
9
|
+
} from "./alphabet.ts";
|
|
10
|
+
import {
|
|
11
|
+
checkByteRange,
|
|
12
|
+
INVALID_OPTIONS,
|
|
13
|
+
INVALID_UUID_VERSION,
|
|
14
|
+
isUint8Array,
|
|
15
|
+
isUuidSlugError,
|
|
16
|
+
UuidSlugError,
|
|
17
|
+
} from "./errors.ts";
|
|
18
|
+
import { isLocalMaskingCodec } from "./masking-codec-protocol.ts";
|
|
19
|
+
import type { SlugAlphabet } from "./slug.ts";
|
|
20
|
+
import { decodeKeylessUuid, extractUuidV7Payload, resolveSlugAlphabet } from "./slug.ts";
|
|
21
|
+
import {
|
|
22
|
+
UUID_TEXT_LOWERCASE,
|
|
23
|
+
UUID_VARIANT_FUTURE,
|
|
24
|
+
UUID_VARIANT_MICROSOFT,
|
|
25
|
+
UUID_VARIANT_NCS,
|
|
26
|
+
UUID_VARIANT_RFC,
|
|
27
|
+
} from "./types.ts";
|
|
28
|
+
import type {
|
|
29
|
+
KeylessUuidInput,
|
|
30
|
+
MaskedOrSentinelUuidV7Slug,
|
|
31
|
+
PlainUuidSlugForVersion,
|
|
32
|
+
ParsedUuidResult,
|
|
33
|
+
Uuid,
|
|
34
|
+
UuidBytesForVersion,
|
|
35
|
+
UuidInput,
|
|
36
|
+
UuidInspection,
|
|
37
|
+
UuidStringForVersion,
|
|
38
|
+
UuidOutput,
|
|
39
|
+
UuidTextCase,
|
|
40
|
+
UuidTextCaseArguments,
|
|
41
|
+
UuidV7MaskingCodec,
|
|
42
|
+
UuidV7Payload,
|
|
43
|
+
UuidV7PayloadLayout,
|
|
44
|
+
UuidVariant,
|
|
45
|
+
UuidVersion,
|
|
46
|
+
} from "./types.ts";
|
|
47
|
+
import {
|
|
48
|
+
formatUuidBytesUnchecked,
|
|
49
|
+
isUuidV7Bytes,
|
|
50
|
+
resolveUuidTextCase,
|
|
51
|
+
uuidTimestampFromBytesUnchecked,
|
|
52
|
+
uuidVersion,
|
|
53
|
+
} from "./uuid.ts";
|
|
54
|
+
import { LocalUuidValue, UUID_VALUE_BYTES, UUID_VALUE_CONTEXT } from "./uuid-value-protocol.ts";
|
|
55
|
+
import { readUuidV7PayloadLayout } from "./v7-payload.ts";
|
|
56
|
+
|
|
57
|
+
const MASKING_CODEC_REQUIRED = "A masking codec is required for masked UUID output.";
|
|
58
|
+
const PAYLOAD_LAYOUT_REQUIRED = "A UUIDv7 payload layout is required.";
|
|
59
|
+
|
|
60
|
+
function variantOf(bytes: Uint8Array): UuidVariant {
|
|
61
|
+
const field = bytes[8] as number;
|
|
62
|
+
if ((field & 0x80) === 0) return UUID_VARIANT_NCS;
|
|
63
|
+
if ((field & 0xc0) === 0x80) return UUID_VARIANT_RFC;
|
|
64
|
+
return (field & 0xe0) === 0xc0 ? UUID_VARIANT_MICROSOFT : UUID_VARIANT_FUTURE;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
class ParsedUuidValue<
|
|
68
|
+
Version extends UuidVersion,
|
|
69
|
+
HasMaskingCodec extends boolean,
|
|
70
|
+
HasPayloadLayout extends boolean,
|
|
71
|
+
>
|
|
72
|
+
extends LocalUuidValue
|
|
73
|
+
implements Uuid<Version, HasMaskingCodec, HasPayloadLayout>
|
|
74
|
+
{
|
|
75
|
+
// Private bytes are already a complete immutable UUID; public conversion would validate them
|
|
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/PERFORMANCE.md.
|
|
78
|
+
get version(): Version {
|
|
79
|
+
return uuidVersion(LocalUuidValue.ownBytes(this), 0) as Version;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
inspect(): UuidInspection<Version> {
|
|
83
|
+
const bytes = LocalUuidValue.ownBytes(this);
|
|
84
|
+
const version = uuidVersion(bytes, 0);
|
|
85
|
+
const variant = variantOf(bytes);
|
|
86
|
+
let isNil = true;
|
|
87
|
+
let isMax = true;
|
|
88
|
+
for (let index = 0; index < 16; index += 1) {
|
|
89
|
+
const byte = bytes[index];
|
|
90
|
+
isNil &&= byte === 0;
|
|
91
|
+
isMax &&= byte === 255;
|
|
92
|
+
}
|
|
93
|
+
return Object.freeze({
|
|
94
|
+
uuid: formatUuidBytesUnchecked(bytes) as UuidStringForVersion<
|
|
95
|
+
Version,
|
|
96
|
+
typeof UUID_TEXT_LOWERCASE
|
|
97
|
+
>,
|
|
98
|
+
version: version as Version,
|
|
99
|
+
variant,
|
|
100
|
+
unixMs:
|
|
101
|
+
version === 7 && variant === UUID_VARIANT_RFC
|
|
102
|
+
? uuidTimestampFromBytesUnchecked(bytes, 0)
|
|
103
|
+
: undefined,
|
|
104
|
+
isNil,
|
|
105
|
+
isMax,
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
toString<Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE>(
|
|
110
|
+
...textCase: UuidTextCaseArguments<Case>
|
|
111
|
+
): UuidStringForVersion<Version, Case>;
|
|
112
|
+
toString(
|
|
113
|
+
textCase: unknown = UUID_TEXT_LOWERCASE,
|
|
114
|
+
): UuidStringForVersion<Version, UuidTextCase> | UuidSlugError {
|
|
115
|
+
const selectedCase = resolveUuidTextCase(textCase);
|
|
116
|
+
if (selectedCase instanceof Error) return selectedCase;
|
|
117
|
+
return formatUuidBytesUnchecked(
|
|
118
|
+
LocalUuidValue.ownBytes(this),
|
|
119
|
+
0,
|
|
120
|
+
selectedCase,
|
|
121
|
+
) as UuidStringForVersion<Version, UuidTextCase>;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
toBytes(): UuidBytesForVersion<Version>;
|
|
125
|
+
toBytes<Output extends Uint8Array>(
|
|
126
|
+
output: Output,
|
|
127
|
+
outputOffset?: number,
|
|
128
|
+
): UuidOutput<Output> | UuidSlugError;
|
|
129
|
+
toBytes(output?: Uint8Array, outputOffset = 0): Uint8Array | UuidSlugError {
|
|
130
|
+
const bytes = LocalUuidValue.ownBytes(this);
|
|
131
|
+
if (!output) return new Uint8Array(bytes);
|
|
132
|
+
const badRange = checkByteRange(output, outputOffset, 16);
|
|
133
|
+
if (badRange) return badRange;
|
|
134
|
+
output.set(bytes, outputOffset);
|
|
135
|
+
return output;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
toPlainSlug(alphabet?: SlugAlphabet): PlainUuidSlugForVersion<Version>;
|
|
139
|
+
toPlainSlug(
|
|
140
|
+
alphabet: SlugAlphabet = BASE64URL_NAME,
|
|
141
|
+
): PlainUuidSlugForVersion<Version> | UuidSlugError {
|
|
142
|
+
const selectedAlphabet = resolveSlugAlphabet(alphabet);
|
|
143
|
+
if (selectedAlphabet instanceof Error) return selectedAlphabet;
|
|
144
|
+
return encodeUuidBytes(
|
|
145
|
+
LocalUuidValue.ownBytes(this),
|
|
146
|
+
selectedAlphabet,
|
|
147
|
+
) as PlainUuidSlugForVersion<Version>;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
toMaskedSlug(
|
|
151
|
+
...codecArgument: [HasMaskingCodec] extends [true]
|
|
152
|
+
? readonly [maskingCodec?: UuidV7MaskingCodec]
|
|
153
|
+
: readonly [maskingCodec: UuidV7MaskingCodec]
|
|
154
|
+
): MaskedOrSentinelUuidV7Slug | UuidSlugError {
|
|
155
|
+
const bytes = LocalUuidValue.ownBytes(this);
|
|
156
|
+
const codec = codecArgument[0] ?? LocalUuidValue.ownMaskingCodec(this);
|
|
157
|
+
if (!codec) return new UuidSlugError(INVALID_OPTIONS, MASKING_CODEC_REQUIRED);
|
|
158
|
+
if (isLocalMaskingCodec(codec)) return codec.uuidToMaskedSlug(bytes);
|
|
159
|
+
if (!isUuidV7Bytes(bytes))
|
|
160
|
+
return new UuidSlugError(
|
|
161
|
+
INVALID_UUID_VERSION,
|
|
162
|
+
"Masked output requires RFC-variant UUIDv7 bytes.",
|
|
163
|
+
);
|
|
164
|
+
try {
|
|
165
|
+
const encode = codec.uuidToMaskedSlug;
|
|
166
|
+
if (typeof encode !== "function")
|
|
167
|
+
return new UuidSlugError(INVALID_OPTIONS, MASKING_CODEC_REQUIRED);
|
|
168
|
+
// A callback may keep its argument beyond this call; freezing the UUID does not freeze bytes.
|
|
169
|
+
const result: unknown = Reflect.apply(encode, undefined, [new Uint8Array(bytes)]);
|
|
170
|
+
if (isUuidSlugError(result)) return result;
|
|
171
|
+
if (
|
|
172
|
+
typeof result === "string" &&
|
|
173
|
+
(isEncoded(result, BASE64URL, 16, false, 4) ||
|
|
174
|
+
isEncoded(result, BASE32HEX, 16, false, 4) ||
|
|
175
|
+
isEncoded(result, BASE32HEX, 16))
|
|
176
|
+
)
|
|
177
|
+
return result as MaskedOrSentinelUuidV7Slug;
|
|
178
|
+
return new UuidSlugError(
|
|
179
|
+
INVALID_OPTIONS,
|
|
180
|
+
"Masking codec must return a canonical masked slug or sentinel.",
|
|
181
|
+
);
|
|
182
|
+
} catch (cause) {
|
|
183
|
+
return new UuidSlugError(INVALID_OPTIONS, "Masking codec UUID encoding failed.", { cause });
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
|
|
187
|
+
extractV7Payload(
|
|
188
|
+
...layoutArgument: [HasPayloadLayout] extends [true]
|
|
189
|
+
? readonly [payloadLayout?: UuidV7PayloadLayout]
|
|
190
|
+
: readonly [payloadLayout: UuidV7PayloadLayout]
|
|
191
|
+
): UuidV7Payload | UuidSlugError {
|
|
192
|
+
const bytes = LocalUuidValue.ownBytes(this);
|
|
193
|
+
const layout = layoutArgument[0] ?? LocalUuidValue.ownPayloadLayout(this);
|
|
194
|
+
return layout
|
|
195
|
+
? extractUuidV7Payload(bytes, layout)
|
|
196
|
+
: new UuidSlugError(INVALID_OPTIONS, PAYLOAD_LAYOUT_REQUIRED);
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
toJSON(): UuidStringForVersion<Version, typeof UUID_TEXT_LOWERCASE> {
|
|
200
|
+
return formatUuidBytesUnchecked(LocalUuidValue.ownBytes(this)) as UuidStringForVersion<
|
|
201
|
+
Version,
|
|
202
|
+
typeof UUID_TEXT_LOWERCASE
|
|
203
|
+
>;
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
[UUID_VALUE_BYTES](): Uint8Array {
|
|
207
|
+
return this.toBytes();
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
Object.freeze(ParsedUuidValue.prototype);
|
|
212
|
+
Object.freeze(LocalUuidValue.prototype);
|
|
213
|
+
|
|
214
|
+
/**
|
|
215
|
+
* Build an immutable parsed UUID. The value keeps `bytes` and `payloadLayout` without copying, so
|
|
216
|
+
* both must be package-owned: nothing may write the bytes, and no caller may reach the layout.
|
|
217
|
+
*/
|
|
218
|
+
export function createUuidValue<
|
|
219
|
+
Version extends UuidVersion = UuidVersion,
|
|
220
|
+
HasMaskingCodec extends boolean = false,
|
|
221
|
+
HasPayloadLayout extends boolean = false,
|
|
222
|
+
>(
|
|
223
|
+
bytes: Uint8Array,
|
|
224
|
+
maskingCodec?: UuidV7MaskingCodec,
|
|
225
|
+
payloadLayout?: UuidV7PayloadLayout,
|
|
226
|
+
): Uuid<Version, HasMaskingCodec, HasPayloadLayout> {
|
|
227
|
+
return Object.freeze(
|
|
228
|
+
new ParsedUuidValue<Version, HasMaskingCodec, HasPayloadLayout>(
|
|
229
|
+
bytes,
|
|
230
|
+
maskingCodec,
|
|
231
|
+
payloadLayout,
|
|
232
|
+
),
|
|
233
|
+
);
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
function readForeignUuidContext(value: unknown):
|
|
237
|
+
| {
|
|
238
|
+
readonly maskingCodec: UuidV7MaskingCodec | undefined;
|
|
239
|
+
readonly payloadLayout: UuidV7PayloadLayout | undefined;
|
|
240
|
+
}
|
|
241
|
+
| UuidSlugError
|
|
242
|
+
| undefined {
|
|
243
|
+
if (typeof value !== "object" || value === null) return undefined;
|
|
244
|
+
try {
|
|
245
|
+
const read = Reflect.get(value, UUID_VALUE_CONTEXT);
|
|
246
|
+
if (typeof read !== "function") return undefined;
|
|
247
|
+
const context: unknown = Reflect.apply(read, value, []);
|
|
248
|
+
if (typeof context !== "object" || context === null)
|
|
249
|
+
return new UuidSlugError(INVALID_OPTIONS, "UUID construction context must be an object.");
|
|
250
|
+
const source = context as { readonly maskingCodec?: unknown; readonly payloadLayout?: unknown };
|
|
251
|
+
const maskingCodec = source.maskingCodec;
|
|
252
|
+
if (
|
|
253
|
+
maskingCodec !== undefined &&
|
|
254
|
+
(typeof maskingCodec !== "object" ||
|
|
255
|
+
maskingCodec === null ||
|
|
256
|
+
typeof (maskingCodec as { readonly uuidToMaskedSlug?: unknown }).uuidToMaskedSlug !==
|
|
257
|
+
"function")
|
|
258
|
+
)
|
|
259
|
+
return new UuidSlugError(INVALID_OPTIONS, MASKING_CODEC_REQUIRED);
|
|
260
|
+
const layout = source.payloadLayout;
|
|
261
|
+
const payloadLayout = layout === undefined ? undefined : readUuidV7PayloadLayout(layout);
|
|
262
|
+
if (payloadLayout instanceof Error) return payloadLayout;
|
|
263
|
+
return { maskingCodec: maskingCodec as UuidV7MaskingCodec | undefined, payloadLayout };
|
|
264
|
+
} catch (cause) {
|
|
265
|
+
return new UuidSlugError(INVALID_OPTIONS, "Reading UUID construction context failed.", {
|
|
266
|
+
cause,
|
|
267
|
+
});
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/** Parse any keyless UUID form once; an existing UUID retains its codec and payload-layout presets. */
|
|
272
|
+
export function parseUuid<Input extends UuidInput>(
|
|
273
|
+
uuid: KeylessUuidInput<Input>,
|
|
274
|
+
): ParsedUuidResult<Input> | UuidSlugError;
|
|
275
|
+
/**
|
|
276
|
+
* Parse through a masking codec, replacing any preset codec and retaining an existing payload layout.
|
|
277
|
+
* A plain UUIDv4 slug can resolve to UUIDv7 when the codec's mask check passes.
|
|
278
|
+
* External codec bytes are validated and copied. Malformed results return `invalid_options`;
|
|
279
|
+
* thrown exceptions remain available as the error's `cause`.
|
|
280
|
+
*/
|
|
281
|
+
export function parseUuid<Input extends UuidInput>(
|
|
282
|
+
uuid: Input,
|
|
283
|
+
maskingCodec: UuidV7MaskingCodec,
|
|
284
|
+
): ParsedUuidResult<Input, true> | UuidSlugError;
|
|
285
|
+
export function parseUuid(
|
|
286
|
+
uuid: unknown,
|
|
287
|
+
maskingCodec?: UuidV7MaskingCodec,
|
|
288
|
+
): Uuid<UuidVersion, boolean, boolean> | UuidSlugError {
|
|
289
|
+
const existing = LocalUuidValue.is(uuid) ? uuid : undefined;
|
|
290
|
+
if (existing && (!maskingCodec || LocalUuidValue.ownMaskingCodec(existing) === maskingCodec))
|
|
291
|
+
return uuid as Uuid<UuidVersion, boolean, boolean>;
|
|
292
|
+
let parsed: Uint8Array | UuidSlugError;
|
|
293
|
+
if (!maskingCodec) parsed = decodeKeylessUuid(uuid);
|
|
294
|
+
else {
|
|
295
|
+
const localCodec = isLocalMaskingCodec(maskingCodec);
|
|
296
|
+
if (!localCodec && isUuidSlugError(uuid)) return uuid;
|
|
297
|
+
let decode: unknown;
|
|
298
|
+
try {
|
|
299
|
+
decode = maskingCodec.uuidToBytes;
|
|
300
|
+
} catch (cause) {
|
|
301
|
+
return new UuidSlugError(INVALID_OPTIONS, "Reading masking codec failed.", { cause });
|
|
302
|
+
}
|
|
303
|
+
if (typeof decode !== "function")
|
|
304
|
+
return new UuidSlugError(INVALID_OPTIONS, "maskingCodec must be a UUIDv7 masking codec.");
|
|
305
|
+
try {
|
|
306
|
+
parsed = Reflect.apply(decode, undefined, [uuid]);
|
|
307
|
+
if (isUint8Array(parsed) && parsed.length === 16) {
|
|
308
|
+
if (!localCodec) parsed = new Uint8Array(parsed);
|
|
309
|
+
} else if (!isUuidSlugError(parsed))
|
|
310
|
+
return new UuidSlugError(
|
|
311
|
+
INVALID_OPTIONS,
|
|
312
|
+
"Masking codec must return exactly 16 UUID bytes.",
|
|
313
|
+
);
|
|
314
|
+
} catch (cause) {
|
|
315
|
+
return new UuidSlugError(INVALID_OPTIONS, "Masking codec UUID parsing failed.", { cause });
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
if (isUuidSlugError(parsed)) return parsed;
|
|
319
|
+
// Read context only after successful parsing, so preceding failures skip protocol callbacks.
|
|
320
|
+
// A borrowed array is the decoded input itself; it has no parsed-value presets. Reuse that
|
|
321
|
+
// observation instead of probing raw storage again. Foreign values need a validated snapshot.
|
|
322
|
+
const foreignContext =
|
|
323
|
+
existing || parsed === uuid || typeof uuid === "string"
|
|
324
|
+
? undefined
|
|
325
|
+
: readForeignUuidContext(uuid);
|
|
326
|
+
if (foreignContext instanceof Error) return foreignContext;
|
|
327
|
+
// Text decoders and local codecs own fresh bytes; external codec storage was isolated above.
|
|
328
|
+
return createUuidValue(
|
|
329
|
+
maskingCodec || typeof uuid === "string" ? parsed : new Uint8Array(parsed),
|
|
330
|
+
maskingCodec ?? foreignContext?.maskingCodec,
|
|
331
|
+
existing ? LocalUuidValue.ownPayloadLayout(existing) : foreignContext?.payloadLayout,
|
|
332
|
+
);
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/** Parse with the supplied masking codec preset by an owner method. */
|
|
336
|
+
export function parseUuidWithCodec<Input extends UuidInput>(
|
|
337
|
+
uuid: Input,
|
|
338
|
+
maskingCodec: UuidV7MaskingCodec,
|
|
339
|
+
): ParsedUuidResult<Input, true> | UuidSlugError {
|
|
340
|
+
return parseUuid(uuid, maskingCodec);
|
|
341
|
+
}
|