@anizoptera/uuid-slug 0.2.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 +181 -0
- package/README.md +65 -0
- package/dist/index.d.ts +168 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +649 -0
- package/dist/index.js.map +1 -0
- package/dist/node/index.js +647 -0
- package/dist/web/index.js +648 -0
- package/package.json +68 -0
- package/src/base64url.ts +76 -0
- package/src/codec.ts +218 -0
- package/src/errors.ts +26 -0
- package/src/index.ts +74 -0
- package/src/mask.ts +95 -0
- package/src/runtime/bun.ts +33 -0
- package/src/runtime/node.ts +23 -0
- package/src/runtime/types.ts +12 -0
- package/src/runtime/web.ts +20 -0
- package/src/schema.ts +123 -0
- package/src/types.ts +89 -0
- package/src/uuid.ts +158 -0
- package/src/v7.ts +106 -0
package/src/schema.ts
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
import { UuidSlugError } from "./errors";
|
|
2
|
+
import type { ExplicitMaskSchema, MaskSchema, MaskSchemaOptions } from "./types";
|
|
3
|
+
|
|
4
|
+
const LEGACY_PERMUTE = Uint8Array.from([9, 13, 3, 8, 14, 0, 11, 7, 6, 1, 15, 4, 2, 5, 10, 12]);
|
|
5
|
+
const LEGACY_XOR = Uint8Array.from([
|
|
6
|
+
0xa2, 0x70, 0x32, 0x7f, 0x98, 0xb8, 0x9b, 0x5e, 0x1b, 0x26, 0xb6, 0x16, 0x96, 0xf9, 0xea, 0x3e,
|
|
7
|
+
]);
|
|
8
|
+
|
|
9
|
+
function clone16(bytes: Uint8Array, name: string): Error | Uint8Array {
|
|
10
|
+
if (bytes.length !== 16)
|
|
11
|
+
return new UuidSlugError("invalid_mask_schema", `${name} must contain exactly 16 bytes.`);
|
|
12
|
+
return new Uint8Array(bytes);
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
function inversePermutation(permute: Uint8Array): Error | Uint8Array {
|
|
16
|
+
if (permute.length !== 16)
|
|
17
|
+
return new UuidSlugError("invalid_mask_schema", "Permutation must contain exactly 16 bytes.");
|
|
18
|
+
const seen = new Uint8Array(16);
|
|
19
|
+
const inverse = new Uint8Array(16);
|
|
20
|
+
for (let i = 0; i < 16; i += 1) {
|
|
21
|
+
const value = permute[i] ?? 255;
|
|
22
|
+
if (value > 15 || seen[value] === 1)
|
|
23
|
+
return new UuidSlugError(
|
|
24
|
+
"invalid_mask_schema",
|
|
25
|
+
"Permutation must be a bijection over 0..15.",
|
|
26
|
+
);
|
|
27
|
+
seen[value] = 1;
|
|
28
|
+
inverse[value] = i;
|
|
29
|
+
}
|
|
30
|
+
return inverse;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function fnv1a64(data: Uint8Array) {
|
|
34
|
+
let hash = 0xcbf29ce484222325n;
|
|
35
|
+
for (const byte of data) {
|
|
36
|
+
hash ^= BigInt(byte);
|
|
37
|
+
hash = BigInt.asUintN(64, hash * 0x100000001b3n);
|
|
38
|
+
}
|
|
39
|
+
return hash;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function seedBytes(seed: string | Uint8Array) {
|
|
43
|
+
if (typeof seed !== "string") return new Uint8Array(seed);
|
|
44
|
+
return new TextEncoder().encode(seed);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function next64(state: { value: bigint }) {
|
|
48
|
+
state.value ^= state.value << 13n;
|
|
49
|
+
state.value ^= state.value >> 7n;
|
|
50
|
+
state.value ^= state.value << 17n;
|
|
51
|
+
state.value = BigInt.asUintN(64, state.value);
|
|
52
|
+
return state.value;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
function derivedBytes(seed: Uint8Array, purpose: number, length: number) {
|
|
56
|
+
const state = {
|
|
57
|
+
value: fnv1a64(Uint8Array.from([...seed, purpose])) || 0x9e3779b97f4a7c15n,
|
|
58
|
+
};
|
|
59
|
+
const out = new Uint8Array(length);
|
|
60
|
+
for (let i = 0; i < length; i += 1)
|
|
61
|
+
out[i] = Number((next64(state) >> BigInt((i % 8) * 8)) & 0xffn);
|
|
62
|
+
return out;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function derivedPermutation(seed: Uint8Array) {
|
|
66
|
+
const random = derivedBytes(seed, 2, 64);
|
|
67
|
+
const permute = Uint8Array.from({ length: 16 }, (_, i) => i);
|
|
68
|
+
let cursor = 0;
|
|
69
|
+
for (let i = 15; i > 0; i -= 1) {
|
|
70
|
+
const j = (random[cursor] ?? 0) % (i + 1);
|
|
71
|
+
cursor += 1;
|
|
72
|
+
const tmp = permute[i] ?? 0;
|
|
73
|
+
permute[i] = permute[j] ?? 0;
|
|
74
|
+
permute[j] = tmp;
|
|
75
|
+
}
|
|
76
|
+
return permute;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function completeSchema(
|
|
80
|
+
id: string,
|
|
81
|
+
xorInput: Uint8Array,
|
|
82
|
+
permuteInput: Uint8Array,
|
|
83
|
+
tagBits: 4 | 6,
|
|
84
|
+
): Error | MaskSchema {
|
|
85
|
+
const xor = clone16(xorInput, "XOR mask");
|
|
86
|
+
if (xor instanceof Error) return xor;
|
|
87
|
+
const permute = clone16(permuteInput, "Permutation");
|
|
88
|
+
if (permute instanceof Error) return permute;
|
|
89
|
+
const inverse = inversePermutation(permute);
|
|
90
|
+
if (inverse instanceof Error) return inverse;
|
|
91
|
+
return { id, inverse, permute, tagBits, xor };
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
export const LEGACY_MASK_SCHEMA_V1: MaskSchema = completeSchema(
|
|
95
|
+
"legacy-mask-v1",
|
|
96
|
+
LEGACY_XOR,
|
|
97
|
+
LEGACY_PERMUTE,
|
|
98
|
+
4,
|
|
99
|
+
) as MaskSchema;
|
|
100
|
+
|
|
101
|
+
export function defineMaskSchema(schema: ExplicitMaskSchema): Error | MaskSchema {
|
|
102
|
+
return completeSchema(schema.id ?? "explicit", schema.xor, schema.permute, schema.tagBits);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
export function createMaskSchema(options: MaskSchemaOptions): Error | MaskSchema {
|
|
106
|
+
const seed = seedBytes(options.seed);
|
|
107
|
+
if (seed.length === 0)
|
|
108
|
+
return new UuidSlugError("invalid_mask_schema", "Mask seed must not be empty.");
|
|
109
|
+
const tagBits = options.tagBits ?? 6;
|
|
110
|
+
if (tagBits !== 4 && tagBits !== 6)
|
|
111
|
+
return new UuidSlugError("invalid_mask_schema", "Mask tagBits must be 4 or 6.");
|
|
112
|
+
return completeSchema(
|
|
113
|
+
options.id ?? "seeded",
|
|
114
|
+
derivedBytes(seed, 1, 16),
|
|
115
|
+
derivedPermutation(seed),
|
|
116
|
+
tagBits,
|
|
117
|
+
);
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
export const DEFAULT_MASK_SCHEMA: MaskSchema = createMaskSchema({
|
|
121
|
+
id: "default",
|
|
122
|
+
seed: "anizoptera.uuid-slug.default-mask.v1",
|
|
123
|
+
}) as MaskSchema;
|
package/src/types.ts
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
declare const brand: unique symbol;
|
|
2
|
+
|
|
3
|
+
export type Brand<T, Name extends string> = T & { readonly [brand]?: Name };
|
|
4
|
+
|
|
5
|
+
export type Base64UrlString = Brand<string, "Base64UrlString">;
|
|
6
|
+
export type UuidString = Brand<string, "UuidString">;
|
|
7
|
+
export type UuidV4String = Brand<UuidString, "UuidV4String">;
|
|
8
|
+
export type UuidV7String = Brand<UuidString, "UuidV7String">;
|
|
9
|
+
export type UuidSlug = Brand<Base64UrlString, "UuidSlug">;
|
|
10
|
+
export type UuidV4Slug = Brand<UuidSlug, "UuidV4Slug">;
|
|
11
|
+
export type UuidV7Slug = Brand<UuidSlug, "UuidV7Slug">;
|
|
12
|
+
export type MaskedUuidSlug = Brand<UuidSlug, "MaskedUuidSlug">;
|
|
13
|
+
export type MaskedUuidV7Slug = Brand<MaskedUuidSlug, "MaskedUuidV7Slug">;
|
|
14
|
+
export type SentinelUuidV7Slug = Brand<UuidV7Slug, "SentinelUuidV7Slug">;
|
|
15
|
+
export type PublicUuidV7Slug = MaskedUuidV7Slug | SentinelUuidV7Slug;
|
|
16
|
+
export type UuidBytes = Brand<Uint8Array, "UuidBytes">;
|
|
17
|
+
|
|
18
|
+
export interface FreshValidationOptions {
|
|
19
|
+
now?: () => number;
|
|
20
|
+
windowMs?: number;
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export interface UuidV7Generator {
|
|
24
|
+
uuidV7(): UuidV7String;
|
|
25
|
+
uuidV7Bytes(out?: Uint8Array, offset?: number): Error | Uint8Array;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export interface MaskSchema {
|
|
29
|
+
readonly id: string;
|
|
30
|
+
readonly inverse: Uint8Array;
|
|
31
|
+
readonly permute: Uint8Array;
|
|
32
|
+
readonly tagBits: 4 | 6;
|
|
33
|
+
readonly xor: Uint8Array;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export interface MaskSchemaOptions {
|
|
37
|
+
readonly id?: string;
|
|
38
|
+
readonly seed: string | Uint8Array;
|
|
39
|
+
readonly tagBits?: 4 | 6;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export interface ExplicitMaskSchema {
|
|
43
|
+
readonly id?: string;
|
|
44
|
+
readonly permute: Uint8Array;
|
|
45
|
+
readonly tagBits: 4 | 6;
|
|
46
|
+
readonly xor: Uint8Array;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export interface UuidV7SentinelDefinition {
|
|
50
|
+
readonly name: string;
|
|
51
|
+
readonly uuid: UuidV7String;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
export interface UuidV7Sentinel {
|
|
55
|
+
readonly name: string;
|
|
56
|
+
readonly slug: SentinelUuidV7Slug;
|
|
57
|
+
readonly uuid: UuidV7String;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export interface UuidSlugCodecOptions {
|
|
61
|
+
readonly generator?: UuidV7Generator;
|
|
62
|
+
readonly legacy?: {
|
|
63
|
+
readonly directDecode?: boolean;
|
|
64
|
+
readonly masks?: readonly MaskSchema[];
|
|
65
|
+
};
|
|
66
|
+
readonly mask?: MaskSchema | MaskSchemaOptions;
|
|
67
|
+
readonly sentinels?: readonly UuidV7SentinelDefinition[];
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export interface UuidSlugCodec {
|
|
71
|
+
readonly sentinels: readonly UuidV7Sentinel[];
|
|
72
|
+
uuidV4(): UuidV4String;
|
|
73
|
+
uuidV7(): UuidV7String;
|
|
74
|
+
uuidV4Bytes(out?: Uint8Array, offset?: number): Error | Uint8Array;
|
|
75
|
+
uuidV7Bytes(out?: Uint8Array, offset?: number): Error | Uint8Array;
|
|
76
|
+
uuidV4Slug(): UuidV4Slug;
|
|
77
|
+
uuidV7Slug(): UuidV7Slug;
|
|
78
|
+
uuidV7MaskedSlug(): MaskedUuidV7Slug;
|
|
79
|
+
uuidToSlug(uuid: string): Error | UuidSlug;
|
|
80
|
+
slugToUuid(slug: string): Error | UuidString;
|
|
81
|
+
uuidToMaskedSlug(uuid: string): Error | MaskedUuidSlug;
|
|
82
|
+
maskedSlugToUuid(slug: string): Error | UuidString;
|
|
83
|
+
uuidV7ToMaskedSlug(uuid: string): Error | PublicUuidV7Slug;
|
|
84
|
+
maskedSlugToUuidV7(slug: string): Error | UuidV7String;
|
|
85
|
+
parseUuid(uuid: string, out?: Uint8Array, offset?: number): Error | Uint8Array;
|
|
86
|
+
formatUuid(bytes: Uint8Array, offset?: number): Error | UuidString;
|
|
87
|
+
parseUuidSlug(slug: string, out?: Uint8Array, offset?: number): Error | Uint8Array;
|
|
88
|
+
formatUuidSlug(bytes: Uint8Array, offset?: number): Error | UuidSlug;
|
|
89
|
+
}
|
package/src/uuid.ts
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
import { decodeBase64Url, encodeBase64Url } from "./base64url";
|
|
2
|
+
import { UuidSlugError } from "./errors";
|
|
3
|
+
import type {
|
|
4
|
+
UuidSlug,
|
|
5
|
+
UuidString,
|
|
6
|
+
UuidV4Slug,
|
|
7
|
+
UuidV4String,
|
|
8
|
+
UuidV7Slug,
|
|
9
|
+
UuidV7String,
|
|
10
|
+
} from "./types";
|
|
11
|
+
|
|
12
|
+
const HEX = "0123456789abcdef";
|
|
13
|
+
const HEX_DECODE = new Int8Array(128).fill(-1);
|
|
14
|
+
for (let i = 0; i < 10; i += 1) HEX_DECODE[48 + i] = i;
|
|
15
|
+
for (let i = 0; i < 6; i += 1) HEX_DECODE[97 + i] = 10 + i;
|
|
16
|
+
|
|
17
|
+
const UUID_LENGTH = 36;
|
|
18
|
+
const SLUG_LENGTH = 22;
|
|
19
|
+
const UUID_BYTE_OFFSETS = [0, 2, 4, 6, 9, 11, 14, 16, 19, 21, 24, 26, 28, 30, 32, 34] as const;
|
|
20
|
+
|
|
21
|
+
function hexValue(code: number) {
|
|
22
|
+
return code < HEX_DECODE.length ? HEX_DECODE[code] : -1;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export function parseUuid(uuid: string, out?: Uint8Array, offset = 0): Error | Uint8Array {
|
|
26
|
+
if (uuid.length !== UUID_LENGTH)
|
|
27
|
+
return new UuidSlugError("invalid_uuid", "UUID must be 36 characters.");
|
|
28
|
+
if (uuid[8] !== "-" || uuid[13] !== "-" || uuid[18] !== "-" || uuid[23] !== "-") {
|
|
29
|
+
return new UuidSlugError("invalid_uuid", "UUID hyphen positions are invalid.");
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const target = out ?? new Uint8Array(16);
|
|
33
|
+
if (offset < 0 || offset + 16 > target.length)
|
|
34
|
+
return new UuidSlugError("invalid_buffer", "Output buffer is too small.");
|
|
35
|
+
|
|
36
|
+
for (let byteIndex = 0; byteIndex < UUID_BYTE_OFFSETS.length; byteIndex += 1) {
|
|
37
|
+
const textOffset = UUID_BYTE_OFFSETS[byteIndex] ?? 0;
|
|
38
|
+
const high = hexValue(uuid.charCodeAt(textOffset)) ?? -1;
|
|
39
|
+
const low = hexValue(uuid.charCodeAt(textOffset + 1)) ?? -1;
|
|
40
|
+
if (high < 0 || low < 0)
|
|
41
|
+
return new UuidSlugError("invalid_uuid", `Invalid UUID hex at offset ${textOffset}.`);
|
|
42
|
+
target[offset + byteIndex] = (high << 4) | low;
|
|
43
|
+
}
|
|
44
|
+
return target;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export function formatUuid(bytes: Uint8Array, offset = 0): Error | UuidString {
|
|
48
|
+
if (offset < 0 || offset + 16 > bytes.length)
|
|
49
|
+
return new UuidSlugError("invalid_buffer", "UUID byte buffer is too small.");
|
|
50
|
+
let out = "";
|
|
51
|
+
for (let i = 0; i < 16; i += 1) {
|
|
52
|
+
if (i === 4 || i === 6 || i === 8 || i === 10) out += "-";
|
|
53
|
+
const byte = bytes[offset + i] ?? 0;
|
|
54
|
+
out += HEX[byte >>> 4];
|
|
55
|
+
out += HEX[byte & 0x0f];
|
|
56
|
+
}
|
|
57
|
+
return out as UuidString;
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export function uuidVersion(bytes: Uint8Array, offset = 0): number {
|
|
61
|
+
return (bytes[offset + 6] ?? 0) >>> 4;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
export function isRfcVariant(bytes: Uint8Array, offset = 0): boolean {
|
|
65
|
+
return (bytes[offset + 8] ?? 0) >>> 6 === 0b10;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export function isUuidString(uuid: null | string | undefined): uuid is UuidString {
|
|
69
|
+
if (!uuid) return false;
|
|
70
|
+
return parseUuid(uuid) instanceof Error ? false : true;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
export function isUuidV4String(uuid: null | string | undefined): uuid is UuidV4String {
|
|
74
|
+
if (!uuid) return false;
|
|
75
|
+
const bytes = parseUuid(uuid);
|
|
76
|
+
return bytes instanceof Error ? false : uuidVersion(bytes) === 4 && isRfcVariant(bytes);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
export function isUuidV7String(uuid: null | string | undefined): uuid is UuidV7String {
|
|
80
|
+
if (!uuid) return false;
|
|
81
|
+
const bytes = parseUuid(uuid);
|
|
82
|
+
return bytes instanceof Error ? false : uuidVersion(bytes) === 7 && isRfcVariant(bytes);
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
export function isUuidV7Bytes(bytes: Uint8Array): boolean {
|
|
86
|
+
return bytes.length === 16 && uuidVersion(bytes) === 7 && isRfcVariant(bytes);
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
export function uuidBytesToSlug(bytes: Uint8Array, offset = 0): Error | UuidSlug {
|
|
90
|
+
if (offset < 0 || offset + 16 > bytes.length)
|
|
91
|
+
return new UuidSlugError("invalid_buffer", "UUID byte buffer is too small.");
|
|
92
|
+
return encodeBase64Url(bytes.subarray(offset, offset + 16)) as UuidSlug;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
export function slugToUuidBytes(slug: string, out?: Uint8Array, offset = 0): Error | Uint8Array {
|
|
96
|
+
if (slug.length !== SLUG_LENGTH)
|
|
97
|
+
return new UuidSlugError("invalid_uuid_slug", "UUID slug must be 22 characters.");
|
|
98
|
+
return decodeBase64Url(slug, out, offset);
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export function uuidToSlug(uuid: string): Error | UuidSlug {
|
|
102
|
+
const bytes = parseUuid(uuid);
|
|
103
|
+
if (bytes instanceof Error) return bytes;
|
|
104
|
+
return uuidBytesToSlug(bytes);
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export function slugToUuid(slug: string): Error | UuidString {
|
|
108
|
+
const bytes = slugToUuidBytes(slug);
|
|
109
|
+
if (bytes instanceof Error) return bytes;
|
|
110
|
+
return formatUuid(bytes);
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
export function formatUuidSlug(bytes: Uint8Array, offset = 0): Error | UuidSlug {
|
|
114
|
+
return uuidBytesToSlug(bytes, offset);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export function parseUuidSlug(slug: string, out?: Uint8Array, offset = 0): Error | Uint8Array {
|
|
118
|
+
return slugToUuidBytes(slug, out, offset);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
export function isUuidSlug(slug: null | string | undefined): slug is UuidSlug {
|
|
122
|
+
if (!slug || slug.length !== SLUG_LENGTH) return false;
|
|
123
|
+
return slugToUuidBytes(slug) instanceof Error ? false : true;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export function isUuidV4Slug(slug: null | string | undefined): slug is UuidV4Slug {
|
|
127
|
+
if (!slug) return false;
|
|
128
|
+
const bytes = slugToUuidBytes(slug);
|
|
129
|
+
return bytes instanceof Error ? false : uuidVersion(bytes) === 4 && isRfcVariant(bytes);
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
export function isUuidV7Slug(slug: null | string | undefined): slug is UuidV7Slug {
|
|
133
|
+
if (!slug) return false;
|
|
134
|
+
const bytes = slugToUuidBytes(slug);
|
|
135
|
+
return bytes instanceof Error ? false : uuidVersion(bytes) === 7 && isRfcVariant(bytes);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
export function extractUuidV7Timestamp(bytes: Uint8Array, offset = 0): number {
|
|
139
|
+
let timestamp = 0;
|
|
140
|
+
for (let i = 0; i < 6; i += 1) timestamp = timestamp * 256 + (bytes[offset + i] ?? 0);
|
|
141
|
+
return timestamp;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
export function hasUuidV7Entropy(bytes: Uint8Array, offset = 0): boolean {
|
|
145
|
+
const randA = (((bytes[offset + 6] ?? 0) & 0x0f) << 8) | (bytes[offset + 7] ?? 0);
|
|
146
|
+
const randBFirst = (bytes[offset + 8] ?? 0) & 0x3f;
|
|
147
|
+
let restZero = true;
|
|
148
|
+
let restMax = true;
|
|
149
|
+
for (let i = 9; i < 16; i += 1) {
|
|
150
|
+
const byte = bytes[offset + i] ?? 0;
|
|
151
|
+
if (byte !== 0x00) restZero = false;
|
|
152
|
+
if (byte !== 0xff) restMax = false;
|
|
153
|
+
}
|
|
154
|
+
return (
|
|
155
|
+
!(randA === 0 && randBFirst === 0 && restZero) &&
|
|
156
|
+
!(randA === 0x0fff && randBFirst === 0x3f && restMax)
|
|
157
|
+
);
|
|
158
|
+
}
|
package/src/v7.ts
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { UuidSlugError } from "./errors";
|
|
2
|
+
import type { UuidV7Generator, UuidV7String } from "./types";
|
|
3
|
+
import { formatUuid } from "./uuid";
|
|
4
|
+
import type { Runtime } from "./runtime/types";
|
|
5
|
+
|
|
6
|
+
export interface UuidV7GeneratorOptions {
|
|
7
|
+
readonly clock?: () => number;
|
|
8
|
+
readonly fillRandom: (bytes: Uint8Array<ArrayBuffer>) => void;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
function writeTimestamp(bytes: Uint8Array, ms: number) {
|
|
12
|
+
let value = Math.trunc(ms);
|
|
13
|
+
for (let i = 5; i >= 0; i -= 1) {
|
|
14
|
+
bytes[i] = value & 0xff;
|
|
15
|
+
value = Math.floor(value / 256);
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
function writeCounter(bytes: Uint8Array, counter: bigint) {
|
|
20
|
+
bytes[6] = 0x70 | Number((counter >> 38n) & 0x0fn);
|
|
21
|
+
bytes[7] = Number((counter >> 30n) & 0xffn);
|
|
22
|
+
bytes[8] = 0x80 | Number((counter >> 24n) & 0x3fn);
|
|
23
|
+
bytes[9] = Number((counter >> 16n) & 0xffn);
|
|
24
|
+
bytes[10] = Number((counter >> 8n) & 0xffn);
|
|
25
|
+
bytes[11] = Number(counter & 0xffn);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function readCounterSeed(bytes: Uint8Array) {
|
|
29
|
+
return (
|
|
30
|
+
(BigInt(bytes[0] ?? 0) << 34n) |
|
|
31
|
+
(BigInt(bytes[1] ?? 0) << 26n) |
|
|
32
|
+
(BigInt(bytes[2] ?? 0) << 18n) |
|
|
33
|
+
(BigInt(bytes[3] ?? 0) << 10n) |
|
|
34
|
+
(BigInt(bytes[4] ?? 0) << 2n) |
|
|
35
|
+
(BigInt(bytes[5] ?? 0) & 0x03n)
|
|
36
|
+
);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export function createUuidV7Generator(options: UuidV7GeneratorOptions): UuidV7Generator {
|
|
40
|
+
const clock = options.clock ?? Date.now;
|
|
41
|
+
const random = new Uint8Array(16);
|
|
42
|
+
let lastMs = -1;
|
|
43
|
+
let counter = 0n;
|
|
44
|
+
|
|
45
|
+
function reseed(ms: number) {
|
|
46
|
+
options.fillRandom(random);
|
|
47
|
+
lastMs = ms;
|
|
48
|
+
counter = readCounterSeed(random);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
function bytes(out?: Uint8Array, offset = 0): Error | Uint8Array {
|
|
52
|
+
const target = out ?? new Uint8Array(16);
|
|
53
|
+
if (offset < 0 || offset + 16 > target.length)
|
|
54
|
+
return new UuidSlugError("invalid_buffer", "Output buffer is too small.");
|
|
55
|
+
const now = Math.trunc(clock());
|
|
56
|
+
if (lastMs < 0 || now > lastMs) reseed(now);
|
|
57
|
+
else {
|
|
58
|
+
counter += 1n;
|
|
59
|
+
if (counter > 0x3ffffffffffn) reseed(lastMs + 1);
|
|
60
|
+
else options.fillRandom(random);
|
|
61
|
+
}
|
|
62
|
+
const uuid = target.subarray(offset, offset + 16);
|
|
63
|
+
writeTimestamp(uuid, lastMs);
|
|
64
|
+
writeCounter(uuid, counter);
|
|
65
|
+
target[offset + 12] = random[12] ?? 0;
|
|
66
|
+
target[offset + 13] = random[13] ?? 0;
|
|
67
|
+
target[offset + 14] = random[14] ?? 0;
|
|
68
|
+
target[offset + 15] = random[15] ?? 0;
|
|
69
|
+
return target;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
return {
|
|
73
|
+
uuidV7() {
|
|
74
|
+
const result = bytes();
|
|
75
|
+
if (result instanceof Error) throw result;
|
|
76
|
+
const formatted = formatUuid(result);
|
|
77
|
+
if (formatted instanceof Error) throw formatted;
|
|
78
|
+
return formatted as UuidV7String;
|
|
79
|
+
},
|
|
80
|
+
uuidV7Bytes: bytes,
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
export function createRuntimeGenerator(runtime: Runtime): UuidV7Generator {
|
|
85
|
+
const fallback = createUuidV7Generator({ fillRandom: runtime.fillRandom });
|
|
86
|
+
return {
|
|
87
|
+
uuidV7() {
|
|
88
|
+
if (!runtime.uuidV7) return fallback.uuidV7();
|
|
89
|
+
try {
|
|
90
|
+
return runtime.uuidV7() as UuidV7String;
|
|
91
|
+
} catch {
|
|
92
|
+
return fallback.uuidV7();
|
|
93
|
+
}
|
|
94
|
+
},
|
|
95
|
+
uuidV7Bytes(out?: Uint8Array, offset = 0) {
|
|
96
|
+
if (!runtime.uuidV7Bytes) return fallback.uuidV7Bytes(out, offset);
|
|
97
|
+
try {
|
|
98
|
+
return runtime.uuidV7Bytes(out, offset);
|
|
99
|
+
} catch (cause) {
|
|
100
|
+
return new UuidSlugError("rng_unavailable", "Runtime UUIDv7 byte generation failed.", {
|
|
101
|
+
cause,
|
|
102
|
+
});
|
|
103
|
+
}
|
|
104
|
+
},
|
|
105
|
+
};
|
|
106
|
+
}
|