@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/timestamp.ts
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
+
|
|
3
|
+
import {
|
|
4
|
+
findUnknownOption,
|
|
5
|
+
INVALID_TIMESTAMP,
|
|
6
|
+
INVALID_UUID_VERSION,
|
|
7
|
+
TIMESTAMP_OUTSIDE_WINDOW,
|
|
8
|
+
normalizeUuidStringInput,
|
|
9
|
+
UuidSlugError,
|
|
10
|
+
} from "./errors.ts";
|
|
11
|
+
import { UUID_TEXT_LOWERCASE } from "./types.ts";
|
|
12
|
+
import type {
|
|
13
|
+
UuidTextCase,
|
|
14
|
+
UuidTextCaseArguments,
|
|
15
|
+
UuidV7StringFor,
|
|
16
|
+
UuidV7StringInput,
|
|
17
|
+
UuidV7TimestampWindow,
|
|
18
|
+
} from "./types.ts";
|
|
19
|
+
import {
|
|
20
|
+
formatUuidBytesUnchecked,
|
|
21
|
+
resolveUuidTextCase,
|
|
22
|
+
isUuidV7Bytes,
|
|
23
|
+
uuidTimestampFromBytesUnchecked,
|
|
24
|
+
uuidStringToBytes,
|
|
25
|
+
} from "./uuid.ts";
|
|
26
|
+
|
|
27
|
+
const TIMESTAMP_WINDOW_OPTIONS = {
|
|
28
|
+
maxTimestampDeltaMs: true,
|
|
29
|
+
referenceUnixMs: true,
|
|
30
|
+
} as const satisfies Record<keyof UuidV7TimestampWindow, true>;
|
|
31
|
+
|
|
32
|
+
/** Decode before reading the reference time so validation performs one clock observation. */
|
|
33
|
+
export function validateTimestampBytes(
|
|
34
|
+
bytes: Uint8Array,
|
|
35
|
+
window: UuidV7TimestampWindow,
|
|
36
|
+
): undefined | UuidSlugError {
|
|
37
|
+
if (!isUuidV7Bytes(bytes))
|
|
38
|
+
return new UuidSlugError(
|
|
39
|
+
INVALID_UUID_VERSION,
|
|
40
|
+
"Timestamp validation requires an RFC-variant UUIDv7.",
|
|
41
|
+
);
|
|
42
|
+
const timestamp = uuidTimestampFromBytesUnchecked(bytes, 0);
|
|
43
|
+
let maxTimestampDeltaMs: number;
|
|
44
|
+
let referenceUnixMs: number;
|
|
45
|
+
try {
|
|
46
|
+
if (typeof window !== "object" || window === null || Array.isArray(window))
|
|
47
|
+
return new UuidSlugError(INVALID_TIMESTAMP, "Timestamp window must be an object.");
|
|
48
|
+
const unknown = findUnknownOption(window, TIMESTAMP_WINDOW_OPTIONS);
|
|
49
|
+
if (unknown !== undefined)
|
|
50
|
+
return new UuidSlugError(INVALID_TIMESTAMP, `Unknown timestamp window option: ${unknown}.`);
|
|
51
|
+
maxTimestampDeltaMs = window.maxTimestampDeltaMs;
|
|
52
|
+
referenceUnixMs = window.referenceUnixMs ?? Date.now();
|
|
53
|
+
} catch (cause) {
|
|
54
|
+
return new UuidSlugError(INVALID_TIMESTAMP, "Timestamp window could not be read.", { cause });
|
|
55
|
+
}
|
|
56
|
+
if (!Number.isFinite(maxTimestampDeltaMs) || maxTimestampDeltaMs < 0)
|
|
57
|
+
return new UuidSlugError(
|
|
58
|
+
INVALID_TIMESTAMP,
|
|
59
|
+
"maxTimestampDeltaMs must be a finite, nonnegative number of milliseconds.",
|
|
60
|
+
);
|
|
61
|
+
if (!Number.isFinite(referenceUnixMs))
|
|
62
|
+
return new UuidSlugError(
|
|
63
|
+
INVALID_TIMESTAMP,
|
|
64
|
+
"referenceUnixMs must be a finite number of Unix milliseconds.",
|
|
65
|
+
);
|
|
66
|
+
if (
|
|
67
|
+
timestamp < referenceUnixMs - maxTimestampDeltaMs ||
|
|
68
|
+
timestamp > referenceUnixMs + maxTimestampDeltaMs
|
|
69
|
+
)
|
|
70
|
+
return new UuidSlugError(
|
|
71
|
+
TIMESTAMP_OUTSIDE_WINDOW,
|
|
72
|
+
`UUIDv7 timestamp ${timestamp} is outside ${referenceUnixMs - maxTimestampDeltaMs}..${referenceUnixMs + maxTimestampDeltaMs} Unix milliseconds.`,
|
|
73
|
+
);
|
|
74
|
+
return undefined;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* Validate accepted UUIDv7 text and return its normalized hyphenated spelling when its timestamp is
|
|
79
|
+
* inside the inclusive symmetric window. Return `timestamp_outside_window` when it is not. This checks clock plausibility, not
|
|
80
|
+
* expiry, authentication, replay, or issuance. TypeScript rejects known slug and UUIDv4 values. A
|
|
81
|
+
* preceding `UuidSlugError` is returned unchanged.
|
|
82
|
+
*
|
|
83
|
+
* @param uuid - UUIDv7 text in an accepted spelling to validate and normalize. JavaScript also
|
|
84
|
+
* accepts a genuine `String` object.
|
|
85
|
+
* @param window - Inclusive maximum distance from an explicit or current reference time.
|
|
86
|
+
* @param textCase - Built-in output spelling. Omit for lowercase.
|
|
87
|
+
*/
|
|
88
|
+
export function validateUuidV7StringUnixMs<
|
|
89
|
+
Input extends string | UuidSlugError,
|
|
90
|
+
Case extends UuidTextCase = typeof UUID_TEXT_LOWERCASE,
|
|
91
|
+
>(
|
|
92
|
+
uuid: UuidV7StringInput<Input>,
|
|
93
|
+
window: UuidV7TimestampWindow,
|
|
94
|
+
...textCase: UuidTextCaseArguments<Case>
|
|
95
|
+
): UuidV7StringFor<Case> | UuidSlugError;
|
|
96
|
+
export function validateUuidV7StringUnixMs(
|
|
97
|
+
uuid: unknown,
|
|
98
|
+
window: UuidV7TimestampWindow,
|
|
99
|
+
textCase: UuidTextCase = UUID_TEXT_LOWERCASE,
|
|
100
|
+
): string | UuidSlugError {
|
|
101
|
+
let uuidText: string;
|
|
102
|
+
if (typeof uuid === "string") {
|
|
103
|
+
uuidText = uuid;
|
|
104
|
+
} else {
|
|
105
|
+
const normalized = normalizeUuidStringInput(uuid);
|
|
106
|
+
if (typeof normalized !== "string") return normalized;
|
|
107
|
+
uuidText = normalized;
|
|
108
|
+
}
|
|
109
|
+
const selectedCase = resolveUuidTextCase(textCase);
|
|
110
|
+
if (selectedCase instanceof Error) return selectedCase;
|
|
111
|
+
const bytes = uuidStringToBytes(uuidText);
|
|
112
|
+
if (bytes instanceof Error) return bytes;
|
|
113
|
+
const valid = validateTimestampBytes(bytes, window);
|
|
114
|
+
if (valid instanceof Error) return valid;
|
|
115
|
+
const alreadySelected =
|
|
116
|
+
uuidText.length === 36 &&
|
|
117
|
+
(selectedCase === UUID_TEXT_LOWERCASE
|
|
118
|
+
? uuidText === uuidText.toLowerCase()
|
|
119
|
+
: uuidText === uuidText.toUpperCase());
|
|
120
|
+
if (alreadySelected) return uuidText;
|
|
121
|
+
return formatUuidBytesUnchecked(bytes, 0, selectedCase);
|
|
122
|
+
}
|