@anizoptera/uuid-slug 0.3.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/LICENSE +54 -31
- package/README.md +373 -324
- 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 +15 -8
- 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/dist/base64url.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"base64url.d.ts","names":[],"sources":["../src/base64url.ts"],"mappings":";;;;;iBAMgB,gBAAgB,OAAO,aAAa;;;;;;;;;;iBAapC,gBACd,eACA,MAAM,YACN,kBACC,gBAAgB;iBAYH,YAAY,mCAAmC,SAAS"}
|
package/dist/base64url.js
DELETED
|
@@ -1,33 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
-
// @anizoptera/uuid-slug 0.3.0 | https://github.com/Anizoptera/uuid-slug#readme
|
|
3
|
-
import { UuidSlugError } from "./errors.js";
|
|
4
|
-
import { BASE64URL, decodeInto, encode, isEncoded } from "./alphabet.js";
|
|
5
|
-
//#region src/base64url.ts
|
|
6
|
-
function encodeBase64Url(bytes) {
|
|
7
|
-
return encode(bytes, BASE64URL);
|
|
8
|
-
}
|
|
9
|
-
/**
|
|
10
|
-
* Decodes into `out` at `offset` when given one, otherwise into a fresh array.
|
|
11
|
-
*
|
|
12
|
-
* Returns a view over EXACTLY the bytes decoded, in both cases. The two used to disagree: without
|
|
13
|
-
* `out` the result was `byteLength`-exact, with `out` it was the caller's entire buffer at its full
|
|
14
|
-
* size, with the data at `offset` and no way to learn how many bytes had been written short of
|
|
15
|
-
* recomputing `floor(value.length * 6 / 8)` by hand. One rule — "the bytes this call produced" —
|
|
16
|
-
* makes the length usable and leaves the caller's own buffer reachable, since they own it.
|
|
17
|
-
*/
|
|
18
|
-
function decodeBase64Url(value, out, offset = 0) {
|
|
19
|
-
if (value.includes("=")) return new UuidSlugError("invalid_base64url", "Base64url value must be unpadded.");
|
|
20
|
-
const byteLength = Math.floor(value.length * BASE64URL.bitsPerChar / 8);
|
|
21
|
-
const target = out ?? new Uint8Array(byteLength);
|
|
22
|
-
const result = decodeInto(value, BASE64URL, target, offset, byteLength);
|
|
23
|
-
if (result instanceof Error) return result;
|
|
24
|
-
return target.subarray(offset, offset + byteLength);
|
|
25
|
-
}
|
|
26
|
-
function isBase64Url(value) {
|
|
27
|
-
if (!value) return false;
|
|
28
|
-
return isEncoded(value, BASE64URL, Math.floor(value.length * BASE64URL.bitsPerChar / 8));
|
|
29
|
-
}
|
|
30
|
-
//#endregion
|
|
31
|
-
export { decodeBase64Url, encodeBase64Url, isBase64Url };
|
|
32
|
-
|
|
33
|
-
//# sourceMappingURL=base64url.js.map
|
package/dist/base64url.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"base64url.js","names":[],"sources":["../src/base64url.ts"],"sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\nimport { BASE64URL, decodeInto, encode, isEncoded } from \"./alphabet\";\nimport { UuidSlugError } from \"./errors\";\nimport type { Base64UrlString } from \"./types\";\n\nexport function encodeBase64Url(bytes: Uint8Array): Base64UrlString {\n return encode(bytes, BASE64URL);\n}\n\n/**\n * Decodes into `out` at `offset` when given one, otherwise into a fresh array.\n *\n * Returns a view over EXACTLY the bytes decoded, in both cases. The two used to disagree: without\n * `out` the result was `byteLength`-exact, with `out` it was the caller's entire buffer at its full\n * size, with the data at `offset` and no way to learn how many bytes had been written short of\n * recomputing `floor(value.length * 6 / 8)` by hand. One rule — \"the bytes this call produced\" —\n * makes the length usable and leaves the caller's own buffer reachable, since they own it.\n */\nexport function decodeBase64Url(\n value: string,\n out?: Uint8Array,\n offset = 0,\n): UuidSlugError | Uint8Array {\n // Padding is the most common malformed input by far, and the generic \"invalid character\"\n // message sends the reader looking for a typo instead of a stray \"=\".\n if (value.includes(\"=\"))\n return new UuidSlugError(\"invalid_base64url\", \"Base64url value must be unpadded.\");\n const byteLength = Math.floor((value.length * BASE64URL.bitsPerChar) / 8);\n const target = out ?? new Uint8Array(byteLength);\n const result = decodeInto(value, BASE64URL, target, offset, byteLength);\n if (result instanceof Error) return result;\n return target.subarray(offset, offset + byteLength);\n}\n\nexport function isBase64Url(value: null | string | undefined): value is Base64UrlString {\n // The empty string decodes to zero bytes without error, but an identifier of no characters is\n // never what a caller means by \"is this a slug\"; rejecting it keeps the guard usable as one.\n if (!value) return false;\n return isEncoded(value, BASE64URL, Math.floor((value.length * BASE64URL.bitsPerChar) / 8));\n}\n"],"mappings":";;;;;AAMA,SAAgB,gBAAgB,OAAoC;CAClE,OAAO,OAAO,OAAO,SAAS;AAChC;;;;;;;;;;AAWA,SAAgB,gBACd,OACA,KACA,SAAS,GACmB;CAG5B,IAAI,MAAM,SAAS,GAAG,GACpB,OAAO,IAAI,cAAc,qBAAqB,mCAAmC;CACnF,MAAM,aAAa,KAAK,MAAO,MAAM,SAAS,UAAU,cAAe,CAAC;CACxE,MAAM,SAAS,OAAO,IAAI,WAAW,UAAU;CAC/C,MAAM,SAAS,WAAW,OAAO,WAAW,QAAQ,QAAQ,UAAU;CACtE,IAAI,kBAAkB,OAAO,OAAO;CACpC,OAAO,OAAO,SAAS,QAAQ,SAAS,UAAU;AACpD;AAEA,SAAgB,YAAY,OAA4D;CAGtF,IAAI,CAAC,OAAO,OAAO;CACnB,OAAO,UAAU,OAAO,WAAW,KAAK,MAAO,MAAM,SAAS,UAAU,cAAe,CAAC,CAAC;AAC3F"}
|
package/dist/codec.d.ts
DELETED
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
-
// @anizoptera/uuid-slug 0.3.0 | https://github.com/Anizoptera/uuid-slug#readme
|
|
3
|
-
import { UuidSlugError } from "./errors.js";
|
|
4
|
-
import { FreshValidationOptions, UuidSlugCodec, UuidSlugCodecOptions, UuidV7SentinelDefinition, UuidV7Slug, UuidV7String } from "./types.js";
|
|
5
|
-
//#region src/codec.d.ts
|
|
6
|
-
declare const UUID_V7_SENTINEL_DEFINITIONS: readonly UuidV7SentinelDefinition[];
|
|
7
|
-
declare function createUuidSlugCodec(options?: UuidSlugCodecOptions): UuidSlugCodec;
|
|
8
|
-
/**
|
|
9
|
-
* Uses the published default seed, so anyone can decode its masked slugs.
|
|
10
|
-
* Use `createUuidSlugCodec({ mask: { seed } })` with your own seed to hide identifiers.
|
|
11
|
-
*/
|
|
12
|
-
declare const defaultCodec: UuidSlugCodec;
|
|
13
|
-
declare function validateUuidV7Fresh(uuid: string, options?: FreshValidationOptions): UuidSlugError | UuidV7String;
|
|
14
|
-
declare function validateUuidV7SlugFresh(slug: string, options?: FreshValidationOptions): UuidSlugError | UuidV7Slug;
|
|
15
|
-
//#endregion
|
|
16
|
-
export { UUID_V7_SENTINEL_DEFINITIONS, createUuidSlugCodec, defaultCodec, validateUuidV7Fresh, validateUuidV7SlugFresh };
|
|
17
|
-
//# sourceMappingURL=codec.d.ts.map
|
package/dist/codec.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"codec.d.ts","names":[],"sources":["../src/codec.ts"],"mappings":";;;;;cAoCa,uCAAuC;iBA6EpC,oBAAoB,UAAS,uBAA4B;;;;;cA4J5D,cAAc;iBAEX,oBACd,cACA,UAAS,yBACR,gBAAgB;iBAqCH,wBACd,cACA,UAAU,yBACT,gBAAgB"}
|
package/dist/codec.js
DELETED
|
@@ -1,192 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
-
// @anizoptera/uuid-slug 0.3.0 | https://github.com/Anizoptera/uuid-slug#readme
|
|
3
|
-
import { UuidSlugError, errorOrThrow, readClock } from "./errors.js";
|
|
4
|
-
import { runtime } from "./runtime/web.js";
|
|
5
|
-
import { extractUuidV7Timestamp, formatUuid, formatUuidSlug, hasUuidV7Entropy, isUuidV7Bytes, parseUuid, parseUuidSlug, resolveSlugAlphabet } from "./uuid.js";
|
|
6
|
-
import { createRuntimeGenerator } from "./v7.js";
|
|
7
|
-
import { uuidV4, uuidV4Bytes } from "./keyless.js";
|
|
8
|
-
import { decodeMaskedSlug, uuidV7BytesToMaskedSlug } from "./mask.js";
|
|
9
|
-
import { createMigration } from "./migration.js";
|
|
10
|
-
import { DEFAULT_MASK_SCHEMA, createMaskSchema, verifyInvertible } from "./schema.js";
|
|
11
|
-
//#region src/codec.ts
|
|
12
|
-
const UUID_V7_SENTINEL_DEFINITIONS = [
|
|
13
|
-
{
|
|
14
|
-
name: "nil",
|
|
15
|
-
uuid: "00000000-0000-7000-8000-000000000000"
|
|
16
|
-
},
|
|
17
|
-
{
|
|
18
|
-
name: "anonymousUser",
|
|
19
|
-
uuid: "00000000-0001-7000-8000-000000000000"
|
|
20
|
-
},
|
|
21
|
-
{
|
|
22
|
-
name: "unknownUser",
|
|
23
|
-
uuid: "00000000-0002-7000-8000-000000000000"
|
|
24
|
-
}
|
|
25
|
-
];
|
|
26
|
-
function schemaFromOption(mask) {
|
|
27
|
-
if (!mask) return DEFAULT_MASK_SCHEMA;
|
|
28
|
-
if (!("mix" in mask)) return createMaskSchema(mask);
|
|
29
|
-
return verifyInvertible(mask);
|
|
30
|
-
}
|
|
31
|
-
function createSentinels(definitions) {
|
|
32
|
-
const sentinels = [];
|
|
33
|
-
const byUuid = /* @__PURE__ */ new Set();
|
|
34
|
-
const encoded = [];
|
|
35
|
-
const bySlug = /* @__PURE__ */ new Map();
|
|
36
|
-
for (const definition of definitions) {
|
|
37
|
-
const bytes = errorOrThrow(parseUuid(definition.uuid));
|
|
38
|
-
if (!isUuidV7Bytes(bytes)) throw new UuidSlugError("invalid_uuid_version", `Sentinel "${definition.name}" must be a UUIDv7, got ${String(definition.uuid)}.`);
|
|
39
|
-
if (byUuid.has(definition.uuid)) throw new UuidSlugError("invalid_uuid", `Sentinel "${definition.name}" repeats the UUID of an earlier sentinel.`);
|
|
40
|
-
const slug = formatUuidSlug(bytes);
|
|
41
|
-
if (slug instanceof Error) throw slug;
|
|
42
|
-
const sentinel = Object.freeze({
|
|
43
|
-
name: definition.name,
|
|
44
|
-
slug,
|
|
45
|
-
uuid: definition.uuid
|
|
46
|
-
});
|
|
47
|
-
sentinels.push(sentinel);
|
|
48
|
-
byUuid.add(definition.uuid);
|
|
49
|
-
encoded.push({
|
|
50
|
-
bytes,
|
|
51
|
-
slug: sentinel.slug
|
|
52
|
-
});
|
|
53
|
-
bySlug.set(sentinel.slug, {
|
|
54
|
-
uuid: definition.uuid,
|
|
55
|
-
bytes
|
|
56
|
-
});
|
|
57
|
-
}
|
|
58
|
-
return {
|
|
59
|
-
bySlug,
|
|
60
|
-
encoded,
|
|
61
|
-
sentinels: Object.freeze(sentinels)
|
|
62
|
-
};
|
|
63
|
-
}
|
|
64
|
-
function createUuidSlugCodec(options = {}) {
|
|
65
|
-
const schema = errorOrThrow(schemaFromOption(options.mask));
|
|
66
|
-
const previousMasks = (options.previousMasks ?? []).map((mask) => errorOrThrow(schemaFromOption(mask)));
|
|
67
|
-
const generator = options.generator ?? createRuntimeGenerator(runtime);
|
|
68
|
-
const slugAlphabet = options.slugAlphabet ?? "base64url";
|
|
69
|
-
errorOrThrow(resolveSlugAlphabet(slugAlphabet));
|
|
70
|
-
const acceptUnmaskedSlugs = options.acceptUnmaskedSlugs === true;
|
|
71
|
-
const nativeSlug = options.generator === void 0 && slugAlphabet === "base64url" ? runtime.uuidV7Slug : void 0;
|
|
72
|
-
const sentinelState = createSentinels(options.sentinels ?? UUID_V7_SENTINEL_DEFINITIONS);
|
|
73
|
-
function decodeMasked(slug) {
|
|
74
|
-
const primary = decodeMaskedSlug(slug, schema, previousMasks);
|
|
75
|
-
if (!(primary instanceof Error)) return primary;
|
|
76
|
-
if (acceptUnmaskedSlugs) {
|
|
77
|
-
const unmasked = parseUuidSlug(slug);
|
|
78
|
-
if (!(unmasked instanceof Error)) return unmasked;
|
|
79
|
-
}
|
|
80
|
-
return primary;
|
|
81
|
-
}
|
|
82
|
-
function encodeMasked(bytes) {
|
|
83
|
-
if (!isUuidV7Bytes(bytes)) return new UuidSlugError("invalid_uuid_version", "Masked UUID slugs require 16 UUIDv7 bytes.");
|
|
84
|
-
for (const sentinel of sentinelState.encoded) {
|
|
85
|
-
let index = 0;
|
|
86
|
-
while (index < 16 && sentinel.bytes[index] === bytes[index]) index += 1;
|
|
87
|
-
if (index === 16) return sentinel.slug;
|
|
88
|
-
}
|
|
89
|
-
const slug = uuidV7BytesToMaskedSlug(bytes, schema);
|
|
90
|
-
if (slug instanceof Error) return slug;
|
|
91
|
-
if (sentinelState.bySlug.has(slug)) return new UuidSlugError("invalid_mask_schema", "Masked output collides with a reserved sentinel. Configure a different mask or sentinel set.");
|
|
92
|
-
return slug;
|
|
93
|
-
}
|
|
94
|
-
function uuidV7ToMaskedSlug(uuid) {
|
|
95
|
-
const bytes = parseUuid(uuid);
|
|
96
|
-
return bytes instanceof Error ? bytes : encodeMasked(bytes);
|
|
97
|
-
}
|
|
98
|
-
function maskedSlugToUuidV7(slug) {
|
|
99
|
-
const sentinel = sentinelState.bySlug.get(slug);
|
|
100
|
-
if (sentinel) return sentinel.uuid;
|
|
101
|
-
const decoded = decodeMasked(slug);
|
|
102
|
-
if (decoded instanceof Error) return decoded;
|
|
103
|
-
if (acceptUnmaskedSlugs && !isUuidV7Bytes(decoded)) return new UuidSlugError("invalid_uuid_version", "Decoded UUID is not UUIDv7.");
|
|
104
|
-
return formatUuid(decoded);
|
|
105
|
-
}
|
|
106
|
-
return {
|
|
107
|
-
sentinels: sentinelState.sentinels,
|
|
108
|
-
migration(migrationOptions) {
|
|
109
|
-
return createMigration([schema, ...previousMasks], sentinelState.bySlug, migrationOptions);
|
|
110
|
-
},
|
|
111
|
-
uuidV4,
|
|
112
|
-
uuidV7() {
|
|
113
|
-
return generator.uuidV7();
|
|
114
|
-
},
|
|
115
|
-
uuidV4Bytes,
|
|
116
|
-
uuidV7Bytes: generator.uuidV7Bytes,
|
|
117
|
-
uuidV7At: generator.uuidV7At,
|
|
118
|
-
uuidV7BytesAt: generator.uuidV7BytesAt,
|
|
119
|
-
uuidV4Slug() {
|
|
120
|
-
return errorOrThrow(formatUuidSlug(errorOrThrow(uuidV4Bytes()), 0, slugAlphabet));
|
|
121
|
-
},
|
|
122
|
-
uuidV7Slug() {
|
|
123
|
-
if (nativeSlug) return nativeSlug();
|
|
124
|
-
return errorOrThrow(formatUuidSlug(errorOrThrow(generator.uuidV7Bytes()), 0, slugAlphabet));
|
|
125
|
-
},
|
|
126
|
-
uuidV7MaskedSlug() {
|
|
127
|
-
return errorOrThrow(encodeMasked(errorOrThrow(generator.uuidV7Bytes())));
|
|
128
|
-
},
|
|
129
|
-
uuidV7ToMaskedSlug,
|
|
130
|
-
maskedSlugToUuidV7,
|
|
131
|
-
maskedSlugToUuid(slug) {
|
|
132
|
-
const sentinel = sentinelState.bySlug.get(slug);
|
|
133
|
-
if (sentinel) return sentinel.uuid;
|
|
134
|
-
const bytes = decodeMasked(slug);
|
|
135
|
-
return bytes instanceof Error ? bytes : formatUuid(bytes);
|
|
136
|
-
},
|
|
137
|
-
/**
|
|
138
|
-
* Unmask, then apply the same freshness rules as `validateUuidV7Fresh`, returning the slug.
|
|
139
|
-
*
|
|
140
|
-
* A METHOD rather than the module-level function it replaced: unmasking needs this codec's
|
|
141
|
-
* key, and the old free function reached for `defaultCodec` — so it silently answered under
|
|
142
|
-
* the seed published in this package's source and was wrong for every caller who supplied
|
|
143
|
-
* their own. Nothing about that failure was visible at the call site; it returned a confident
|
|
144
|
-
* Error for perfectly good slugs.
|
|
145
|
-
*
|
|
146
|
-
* Decode directly to bytes instead of formatting and reparsing a UUID. The method does not
|
|
147
|
-
* access `this`, so it also works when detached from the codec.
|
|
148
|
-
*/
|
|
149
|
-
validateMaskedSlugFresh(slug, freshness) {
|
|
150
|
-
const bytes = sentinelState.bySlug.get(slug)?.bytes ?? decodeMasked(slug);
|
|
151
|
-
if (bytes instanceof Error) return bytes;
|
|
152
|
-
if (!isUuidV7Bytes(bytes)) return new UuidSlugError("invalid_uuid_version", "Decoded UUID is not UUIDv7.");
|
|
153
|
-
const valid = validateFreshBytes(bytes, freshness);
|
|
154
|
-
return valid instanceof Error ? valid : slug;
|
|
155
|
-
}
|
|
156
|
-
};
|
|
157
|
-
}
|
|
158
|
-
/**
|
|
159
|
-
* Uses the published default seed, so anyone can decode its masked slugs.
|
|
160
|
-
* Use `createUuidSlugCodec({ mask: { seed } })` with your own seed to hide identifiers.
|
|
161
|
-
*/
|
|
162
|
-
const defaultCodec = /*#__PURE__*/ createUuidSlugCodec();
|
|
163
|
-
function validateUuidV7Fresh(uuid, options = {}) {
|
|
164
|
-
const bytes = parseUuid(uuid);
|
|
165
|
-
if (bytes instanceof Error) return new UuidSlugError("invalid_uuid", "Expected canonical UUIDv7 string.");
|
|
166
|
-
const valid = validateFreshBytes(bytes, options);
|
|
167
|
-
return valid instanceof Error ? valid : uuid;
|
|
168
|
-
}
|
|
169
|
-
/** Capture decoded fields before calling an external clock, which can reenter a custom schema. */
|
|
170
|
-
function validateFreshBytes(bytes, options = {}) {
|
|
171
|
-
if (!isUuidV7Bytes(bytes)) return new UuidSlugError("invalid_uuid", "Expected canonical UUIDv7 string.");
|
|
172
|
-
const timestamp = extractUuidV7Timestamp(bytes);
|
|
173
|
-
if (timestamp instanceof Error) return timestamp;
|
|
174
|
-
const hasEntropy = hasUuidV7Entropy(bytes);
|
|
175
|
-
const windowMs = options.windowMs ?? 864e5;
|
|
176
|
-
if (!Number.isFinite(windowMs) || windowMs < 0) return new UuidSlugError("invalid_timestamp", "windowMs must be a finite, nonnegative number of milliseconds.");
|
|
177
|
-
const now = readClock(options.now ?? Date.now);
|
|
178
|
-
if (now instanceof Error) return now;
|
|
179
|
-
if (!Number.isFinite(now)) return new UuidSlugError("invalid_timestamp", "now must return a finite number of Unix milliseconds.");
|
|
180
|
-
if (timestamp < now - windowMs || timestamp > now + windowMs) return new UuidSlugError("stale_uuid", "UUIDv7 timestamp is outside the accepted window.");
|
|
181
|
-
if (!hasEntropy) return new UuidSlugError("invalid_uuid", "UUIDv7 random payload is degenerate.");
|
|
182
|
-
}
|
|
183
|
-
function validateUuidV7SlugFresh(slug, options) {
|
|
184
|
-
const bytes = parseUuidSlug(slug);
|
|
185
|
-
if (bytes instanceof Error) return bytes;
|
|
186
|
-
const valid = validateFreshBytes(bytes, options);
|
|
187
|
-
return valid instanceof Error ? valid : slug;
|
|
188
|
-
}
|
|
189
|
-
//#endregion
|
|
190
|
-
export { UUID_V7_SENTINEL_DEFINITIONS, createUuidSlugCodec, defaultCodec, validateUuidV7Fresh, validateUuidV7SlugFresh };
|
|
191
|
-
|
|
192
|
-
//# sourceMappingURL=codec.js.map
|
package/dist/codec.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"codec.js","names":["generateUuidV4","generateUuidV4Bytes"],"sources":["../src/codec.ts"],"sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\nimport { runtime } from \"#runtime\";\nimport { errorOrThrow, readClock, UuidSlugError } from \"./errors\";\n// A v4 has ONE implementation however it is reached. The keyless module owns it because that is\n// the module a consumer who never masks pulls in; importing it here costs a codec consumer nothing\n// it was not already paying, whereas the reverse direction would put the codec back on the keyless\n// path and undo the whole saving that split exists for.\nimport { uuidV4Bytes as generateUuidV4Bytes, uuidV4 as generateUuidV4 } from \"./keyless\";\nimport { uuidV7BytesToMaskedSlug, decodeMaskedSlug } from \"./mask\";\nimport { createMigration } from \"./migration\";\nimport { createMaskSchema, DEFAULT_MASK_SCHEMA, verifyInvertible } from \"./schema\";\nimport type {\n MaskSchema,\n PublicUuidV7Slug,\n SentinelUuidV7Slug,\n UuidSlugCodec,\n UuidSlugCodecOptions,\n UuidV4Slug,\n UuidV7Sentinel,\n UuidV7String,\n UuidV7Slug,\n} from \"./types\";\nimport { createRuntimeGenerator } from \"./v7\";\nimport {\n formatUuidSlug,\n hasUuidV7Entropy,\n isUuidV7Bytes,\n resolveSlugAlphabet,\n parseUuid,\n formatUuid,\n parseUuidSlug,\n extractUuidV7Timestamp,\n} from \"./uuid\";\nimport type { FreshValidationOptions, UuidV7SentinelDefinition } from \"./types\";\n\nexport const UUID_V7_SENTINEL_DEFINITIONS: readonly UuidV7SentinelDefinition[] = [\n {\n name: \"nil\",\n uuid: \"00000000-0000-7000-8000-000000000000\",\n },\n {\n name: \"anonymousUser\",\n uuid: \"00000000-0001-7000-8000-000000000000\",\n },\n {\n name: \"unknownUser\",\n uuid: \"00000000-0002-7000-8000-000000000000\",\n },\n];\n\nfunction schemaFromOption(mask: UuidSlugCodecOptions[\"mask\"]): UuidSlugError | MaskSchema {\n // Omitting `mask` yields a codec that masks under a seed published in this package's source, so\n // its masked slugs are decodable by anyone. That is a real configuration — tests and demos want\n // reproducible output — but it is never the one a caller protecting ids wants, and nothing about\n // the resulting slug reveals which they got. See `defaultCodec` and `UuidSlugCodecOptions.mask`.\n if (!mask) return DEFAULT_MASK_SCHEMA;\n // A built schema carries its mixing step; an options object carries only a seed to derive one\n // from. One discriminating property beats sniffing several, which silently stops discriminating\n // when a scheme is added whose data fields differ.\n //\n // Every schema the codec will use passes through here, which is why the invertibility smoke test\n // belongs here and nowhere else: a caller-supplied `mix` is the extension point now, and an\n // unchecked one silently makes every id it encodes unreadable.\n if (!(\"mix\" in mask)) return createMaskSchema(mask);\n return verifyInvertible(mask);\n}\n\nfunction createSentinels(definitions: readonly UuidV7SentinelDefinition[]) {\n const sentinels: UuidV7Sentinel[] = [];\n const byUuid = new Set<string>();\n const encoded: { bytes: Uint8Array; slug: SentinelUuidV7Slug }[] = [];\n const bySlug = new Map<string, { uuid: UuidV7String; bytes: Uint8Array }>();\n for (const definition of definitions) {\n // `uuid` is typed `UuidV7String`, and that types NOTHING: `Brand`'s marker is optional by\n // design, so every string satisfies every brand and a v4 passed the declaration untouched.\n // It then constructed fine, masked fine, and failed on EVERY decode forever after — a\n // permanent, per-call error configured once at construction. Checked here for the same reason\n // the invertibility smoke test is checked here: this is the last point at which a bad definition is\n // still a caller's argument rather than a codec that cannot work.\n const bytes = errorOrThrow(parseUuid(definition.uuid));\n if (!isUuidV7Bytes(bytes))\n throw new UuidSlugError(\n \"invalid_uuid_version\",\n `Sentinel \"${definition.name}\" must be a UUIDv7, got ${String(definition.uuid)}.`,\n );\n // A duplicate collapses SILENTLY: both entries stay in `codec.sentinels`, while the lookup maps\n // keep only the last, so the codec reports a sentinel it will never match.\n if (byUuid.has(definition.uuid))\n throw new UuidSlugError(\n \"invalid_uuid\",\n `Sentinel \"${definition.name}\" repeats the UUID of an earlier sentinel.`,\n );\n // Always base64url, never the codec's `slugAlphabet`: a sentinel slug is matched against\n // MASKED input, which is base64url by definition, so one written in another alphabet could\n // never be recognised in the position it exists for.\n const slug = formatUuidSlug(bytes);\n if (slug instanceof Error) throw slug;\n const sentinel = Object.freeze({\n name: definition.name,\n // `formatUuidSlug` returns the version-agnostic brand; the v7-ness comes\n // from the check above.\n slug: slug as SentinelUuidV7Slug,\n uuid: definition.uuid,\n });\n sentinels.push(sentinel);\n byUuid.add(definition.uuid);\n encoded.push({ bytes, slug: sentinel.slug });\n bySlug.set(sentinel.slug, { uuid: definition.uuid, bytes });\n }\n return { bySlug, encoded, sentinels: Object.freeze(sentinels) };\n}\n\nexport function createUuidSlugCodec(options: UuidSlugCodecOptions = {}): UuidSlugCodec {\n const schema = errorOrThrow(schemaFromOption(options.mask));\n // Every schema a decode may try, and NOTHING a caller did not list. A codec once appended two\n // schemas of its own — a substitution partner derived from any seed, and the default seed's\n // pre-Feistel scheme — on the reasoning that a marker bit would select one outright. No marker\n // exists: each schema is tried in turn and the first whose check passes wins, so the codec's\n // false-accept rate is the SUM over the list and is set by its weakest member. Measured\n // 2026-08-12 over 200,000 wrong-key decodes, the auto-added 6-bit partner accepted 211 while\n // the 16-bit schema it accompanied accepted 2 — a 16x widening nobody asked for.\n const previousMasks = (options.previousMasks ?? []).map((mask) =>\n errorOrThrow(schemaFromOption(mask)),\n );\n const generator = options.generator ?? createRuntimeGenerator(runtime);\n const slugAlphabet = options.slugAlphabet ?? \"base64url\";\n errorOrThrow(resolveSlugAlphabet(slugAlphabet));\n const acceptUnmaskedSlugs = options.acceptUnmaskedSlugs === true;\n // The runtime's own slug generator emits base64url and nothing else, so it can only serve the\n // default. Resolved once here rather than per call: the branch is on configuration, which cannot\n // change after construction.\n const nativeSlug =\n options.generator === undefined && slugAlphabet === \"base64url\"\n ? runtime.uuidV7Slug\n : undefined;\n const sentinelState = createSentinels(options.sentinels ?? UUID_V7_SENTINEL_DEFINITIONS);\n\n function decodeMasked(slug: string): UuidSlugError | Uint8Array {\n const primary = decodeMaskedSlug(slug, schema, previousMasks);\n if (!(primary instanceof Error)) return primary;\n if (acceptUnmaskedSlugs) {\n const unmasked = parseUuidSlug(slug);\n if (!(unmasked instanceof Error)) return unmasked;\n }\n // The fallback's error is DROPPED, deliberately, and this returns `primary` whether or not the\n // fallback ran. It answers a different question — \"is this a plain slug?\" — and for the failure\n // that actually brings people here, a wrong or rotated key, its answer is untrue: the input is\n // perfectly good base64url whose trailing bits ARE the mask check, so it reported\n // `invalid_base64url: non-canonical trailing bits` and sent operators hunting a typo.\n // `primary` says the schema did not match, which is what happened.\n return primary;\n }\n\n function encodeMasked(bytes: Uint8Array): UuidSlugError | PublicUuidV7Slug {\n if (!isUuidV7Bytes(bytes))\n return new UuidSlugError(\n \"invalid_uuid_version\",\n \"Masked UUID slugs require 16 UUIDv7 bytes.\",\n );\n for (const sentinel of sentinelState.encoded) {\n let index = 0;\n while (index < 16 && sentinel.bytes[index] === bytes[index]) index += 1;\n if (index === 16) return sentinel.slug;\n }\n const slug = uuidV7BytesToMaskedSlug(bytes, schema);\n if (slug instanceof Error) return slug;\n // Sentinel decoding takes precedence, so returning this ciphertext would recover a different UUID.\n if (sentinelState.bySlug.has(slug))\n return new UuidSlugError(\n \"invalid_mask_schema\",\n \"Masked output collides with a reserved sentinel. Configure a different mask or sentinel set.\",\n );\n return slug;\n }\n\n function uuidV7ToMaskedSlug(uuid: string): UuidSlugError | PublicUuidV7Slug {\n const bytes = parseUuid(uuid);\n return bytes instanceof Error ? bytes : encodeMasked(bytes);\n }\n\n function maskedSlugToUuidV7(slug: string): UuidSlugError | UuidV7String {\n const sentinel = sentinelState.bySlug.get(slug);\n if (sentinel) return sentinel.uuid;\n const decoded = decodeMasked(slug);\n if (decoded instanceof Error) return decoded;\n // Mask decoding restores v7 constants; only the plain fallback can carry another version.\n if (acceptUnmaskedSlugs && !isUuidV7Bytes(decoded))\n return new UuidSlugError(\"invalid_uuid_version\", \"Decoded UUID is not UUIDv7.\");\n return formatUuid(decoded) as UuidSlugError | UuidV7String;\n }\n\n return {\n sentinels: sentinelState.sentinels,\n migration(migrationOptions) {\n return createMigration([schema, ...previousMasks], sentinelState.bySlug, migrationOptions);\n },\n uuidV4: generateUuidV4,\n uuidV7() {\n return generator.uuidV7();\n },\n uuidV4Bytes: generateUuidV4Bytes,\n uuidV7Bytes: generator.uuidV7Bytes,\n uuidV7At: generator.uuidV7At,\n uuidV7BytesAt: generator.uuidV7BytesAt,\n uuidV4Slug() {\n // The bytes came from `generateUuidV4Bytes`, which stamps version 4; the encoder sees only\n // bytes and cannot carry that through.\n return errorOrThrow(\n formatUuidSlug(errorOrThrow(generateUuidV4Bytes()), 0, slugAlphabet),\n ) as UuidV4Slug;\n },\n uuidV7Slug() {\n if (nativeSlug) return nativeSlug();\n // Same assertion `uuidV4Slug` makes for the same reason: the bytes come from a v7 generator,\n // and the encoder sees only bytes so it cannot carry the version through. Until the runtime\n // hooks were branded this cast was ABSENT and nothing complained — the native branch typed\n // the union as bare `string`, which an optional brand accepts, so the promise went unchecked.\n return errorOrThrow(\n formatUuidSlug(errorOrThrow(generator.uuidV7Bytes()), 0, slugAlphabet),\n ) as UuidV7Slug;\n },\n uuidV7MaskedSlug() {\n return errorOrThrow(encodeMasked(errorOrThrow(generator.uuidV7Bytes())));\n },\n uuidV7ToMaskedSlug,\n maskedSlugToUuidV7,\n maskedSlugToUuid(slug) {\n const sentinel = sentinelState.bySlug.get(slug);\n if (sentinel) return sentinel.uuid;\n const bytes = decodeMasked(slug);\n return bytes instanceof Error ? bytes : formatUuid(bytes);\n },\n /**\n * Unmask, then apply the same freshness rules as `validateUuidV7Fresh`, returning the slug.\n *\n * A METHOD rather than the module-level function it replaced: unmasking needs this codec's\n * key, and the old free function reached for `defaultCodec` — so it silently answered under\n * the seed published in this package's source and was wrong for every caller who supplied\n * their own. Nothing about that failure was visible at the call site; it returned a confident\n * Error for perfectly good slugs.\n *\n * Decode directly to bytes instead of formatting and reparsing a UUID. The method does not\n * access `this`, so it also works when detached from the codec.\n */\n validateMaskedSlugFresh(slug, freshness) {\n const bytes = sentinelState.bySlug.get(slug)?.bytes ?? decodeMasked(slug);\n if (bytes instanceof Error) return bytes;\n // The v7-specific decoder reports this before freshness validation does.\n if (!isUuidV7Bytes(bytes))\n return new UuidSlugError(\"invalid_uuid_version\", \"Decoded UUID is not UUIDv7.\");\n const valid = validateFreshBytes(bytes, freshness);\n return valid instanceof Error ? valid : slug;\n },\n };\n}\n\n/**\n * Uses the published default seed, so anyone can decode its masked slugs.\n * Use `createUuidSlugCodec({ mask: { seed } })` with your own seed to hide identifiers.\n */\n// Annotated PURE so a bundle that never names it can drop it: a module-scope CONSTRUCTION call is\n// otherwise a side effect no bundler may remove, and this one reaches the cipher, the mask schema\n// and the sentinel table. Sound because `createUuidSlugCodec()` with no options cannot fail — the\n// only throwing paths are caller-supplied sentinels and a caller-supplied mix — and nothing else\n// observes the construction. The annotation is worth nothing on its own: it was measured saving\n// ZERO bytes while `index.ts` bound its shortcuts as PROPERTY READS of this value, since a read at\n// module scope forces the evaluation the annotation permits skipping. Keep the shortcuts keyless\n// (see `keyless.ts`) or this goes dead again.\nexport const defaultCodec: UuidSlugCodec = /*#__PURE__*/ createUuidSlugCodec();\n\nexport function validateUuidV7Fresh(\n uuid: string,\n options: FreshValidationOptions = {},\n): UuidSlugError | UuidV7String {\n const bytes = parseUuid(uuid);\n if (bytes instanceof Error)\n return new UuidSlugError(\"invalid_uuid\", \"Expected canonical UUIDv7 string.\");\n const valid = validateFreshBytes(bytes, options);\n return valid instanceof Error ? valid : uuid;\n}\n\n/** Capture decoded fields before calling an external clock, which can reenter a custom schema. */\nfunction validateFreshBytes(\n bytes: Uint8Array,\n options: FreshValidationOptions = {},\n): UuidSlugError | undefined {\n if (!isUuidV7Bytes(bytes))\n return new UuidSlugError(\"invalid_uuid\", \"Expected canonical UUIDv7 string.\");\n const timestamp = extractUuidV7Timestamp(bytes);\n if (timestamp instanceof Error) return timestamp;\n const hasEntropy = hasUuidV7Entropy(bytes);\n const windowMs = options.windowMs ?? 86_400_000;\n if (!Number.isFinite(windowMs) || windowMs < 0)\n return new UuidSlugError(\n \"invalid_timestamp\",\n \"windowMs must be a finite, nonnegative number of milliseconds.\",\n );\n const now = readClock(options.now ?? Date.now);\n if (now instanceof Error) return now;\n if (!Number.isFinite(now))\n return new UuidSlugError(\n \"invalid_timestamp\",\n \"now must return a finite number of Unix milliseconds.\",\n );\n if (timestamp < now - windowMs || timestamp > now + windowMs)\n return new UuidSlugError(\"stale_uuid\", \"UUIDv7 timestamp is outside the accepted window.\");\n if (!hasEntropy) return new UuidSlugError(\"invalid_uuid\", \"UUIDv7 random payload is degenerate.\");\n return undefined;\n}\n\nexport function validateUuidV7SlugFresh(\n slug: string,\n options?: FreshValidationOptions,\n): UuidSlugError | UuidV7Slug {\n const bytes = parseUuidSlug(slug);\n if (bytes instanceof Error) return bytes;\n const valid = validateFreshBytes(bytes, options);\n return valid instanceof Error ? valid : slug;\n}\n"],"mappings":"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"}
|
package/dist/keyless.d.ts
DELETED
|
@@ -1,31 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
-
// @anizoptera/uuid-slug 0.3.0 | https://github.com/Anizoptera/uuid-slug#readme
|
|
3
|
-
import { UuidSlugError } from "./errors.js";
|
|
4
|
-
import { SlugAlphabet } from "./uuid.js";
|
|
5
|
-
import { UuidV4Slug, UuidV4String, UuidV7Slug, UuidV7String } from "./types.js";
|
|
6
|
-
//#region src/keyless.d.ts
|
|
7
|
-
/** Shared with `createUuidSlugCodec`, so a v4 has one implementation however it is reached. */
|
|
8
|
-
declare function uuidV4Bytes(out?: Uint8Array, offset?: number): UuidSlugError | Uint8Array;
|
|
9
|
-
declare function uuidV4(): UuidV4String;
|
|
10
|
-
/**
|
|
11
|
-
* Takes the alphabet for the same reason `uuidV7Slug` does, and NOT because a v4 slug sorts — it
|
|
12
|
-
* does not. The alphabet is a choice of representation, so a project that has standardised on the
|
|
13
|
-
* 26-character lowercase form for its public ids needs its v4 slugs in it too; the pair differing
|
|
14
|
-
* would be an asymmetry with nothing behind it.
|
|
15
|
-
*/
|
|
16
|
-
declare function uuidV4Slug(alphabet?: SlugAlphabet): UuidV4Slug;
|
|
17
|
-
declare const uuidV7: () => UuidV7String;
|
|
18
|
-
declare const uuidV7Bytes: (out?: Uint8Array, offset?: number) => UuidSlugError | Uint8Array;
|
|
19
|
-
declare const uuidV7At: (timestamp: number) => UuidSlugError | UuidV7String;
|
|
20
|
-
declare const uuidV7BytesAt: (timestamp: number, out?: Uint8Array, offset?: number) => UuidSlugError | Uint8Array;
|
|
21
|
-
/**
|
|
22
|
-
* The alphabet is an argument here, exactly as it is on `uuidToSlug(uuid, alphabet)`, because
|
|
23
|
-
* choosing it needs no key: without it the only way to GENERATE a base32hex slug was to build a
|
|
24
|
-
* codec, so the sortable form cost the whole masking machinery while the unsortable one was free.
|
|
25
|
-
* Positional and last, matching `uuidToSlug`, so the two spellings of "encode in this alphabet"
|
|
26
|
-
* do not diverge.
|
|
27
|
-
*/
|
|
28
|
-
declare function uuidV7Slug(alphabet?: SlugAlphabet): UuidV7Slug;
|
|
29
|
-
//#endregion
|
|
30
|
-
export { uuidV4, uuidV4Bytes, uuidV4Slug, uuidV7, uuidV7At, uuidV7Bytes, uuidV7BytesAt, uuidV7Slug };
|
|
31
|
-
//# sourceMappingURL=keyless.d.ts.map
|
package/dist/keyless.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"keyless.d.ts","names":[],"sources":["../src/keyless.ts"],"mappings":";;;;;;;iBAsDgB,YAAY,MAAM,YAAY,kBAAa,gBAAgB;iBAY3D,UAAU;;;;;;;iBAgBV,WAAW,WAAU,eAA6B;cAarD,cAAa;cAEb,cAAe,MAAM,YAAY,oBAAkB,gBAAgB;cAGnE,WAAY,sBAAoB,gBAAgB;cAGhD,gBACX,mBACA,MAAM,YACN,oBACC,gBAAgB;;;;;;;;iBASH,WAAW,WAAU,eAA6B"}
|
package/dist/keyless.js
DELETED
|
@@ -1,93 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
-
// @anizoptera/uuid-slug 0.3.0 | https://github.com/Anizoptera/uuid-slug#readme
|
|
3
|
-
import { UuidRuntimeError, checkRange, errorOrThrow, fillRandomBytes } from "./errors.js";
|
|
4
|
-
import { runtime } from "./runtime/web.js";
|
|
5
|
-
import { formatUuid, formatUuidSlug } from "./uuid.js";
|
|
6
|
-
import { createRuntimeGenerator } from "./v7.js";
|
|
7
|
-
//#region src/keyless.ts
|
|
8
|
-
/**
|
|
9
|
-
* The operations that need no key, built WITHOUT a codec.
|
|
10
|
-
*
|
|
11
|
-
* Generating an id and re-encoding one are keyless: the result is the same value whoever asks, so
|
|
12
|
-
* a bare function is an honest shape for them. Reaching them through a codec is what made them
|
|
13
|
-
* expensive — a codec carries a mask schema, a cipher and a sentinel table, none of which a caller
|
|
14
|
-
* who never masks will ever execute, and all of which a bundler must keep once the graph reaches
|
|
15
|
-
* them. Measured 2026-08-12 on the built package: an entry importing only `uuidV7Slug` minified to
|
|
16
|
-
* 12,735 bytes through the codec and 4,559 from a bare generator; `uuidToSlug` alone, 12,725
|
|
17
|
-
* against 2,188. `defaultCodec` still exists and still works — it is simply no longer on the path
|
|
18
|
-
* every consumer walks.
|
|
19
|
-
*
|
|
20
|
-
* NOTHING KEYED MAY BE ADDED HERE (Art's ruling, 2026-08-12). The only key a bare function could
|
|
21
|
-
* carry is `DEFAULT_MASK_SCHEMA`'s, whose seed is a string literal in this published package, so a
|
|
22
|
-
* masked operation exported this way would be the shortest spelling of the headline feature and
|
|
23
|
-
* the one that obfuscates nothing. Masking is reached through a codec built with your own seed.
|
|
24
|
-
*/
|
|
25
|
-
/**
|
|
26
|
-
* Built on first use, and the laziness is what the measurement above depends on: a module-scope
|
|
27
|
-
* CONSTRUCTION call is a side effect a bundler may not remove, so an eager one would pin the
|
|
28
|
-
* generator, the runtime adapter and the entropy pool into a bundle that only ever re-encodes a
|
|
29
|
-
* UUID. Measured the same day, the eager spelling cost 5,130 bytes for `uuidToSlug` alone against
|
|
30
|
-
* 2,188 here.
|
|
31
|
-
*
|
|
32
|
-
* It also keeps import-time work at zero, which `test/entropy.test.ts` gates for a different
|
|
33
|
-
* reason — a heap snapshot taken at module load must capture no drawn randomness.
|
|
34
|
-
*/
|
|
35
|
-
let generator;
|
|
36
|
-
const v7 = () => generator ??= createRuntimeGenerator(runtime);
|
|
37
|
-
/**
|
|
38
|
-
* Randomness is drawn into a private buffer and copied out instead of filled through a view of the
|
|
39
|
-
* caller's array: `fillRandom` requires a plain `ArrayBuffer` because Web Crypto rejects a
|
|
40
|
-
* `SharedArrayBuffer` view, and a caller-supplied `out` carries no such guarantee. Reused rather
|
|
41
|
-
* than allocated per call, matching the v7 generator, so the cost is one 16-byte copy.
|
|
42
|
-
*/
|
|
43
|
-
const v4Random = /* @__PURE__ */ new Uint8Array(16);
|
|
44
|
-
/** Shared with `createUuidSlugCodec`, so a v4 has one implementation however it is reached. */
|
|
45
|
-
function uuidV4Bytes(out, offset = 0) {
|
|
46
|
-
const target = out ?? /* @__PURE__ */ new Uint8Array(16);
|
|
47
|
-
const badRange = checkRange(target.length, offset, 16);
|
|
48
|
-
if (badRange) return badRange;
|
|
49
|
-
const failed = fillRandomBytes(runtime.fillRandom, v4Random);
|
|
50
|
-
if (failed) return failed;
|
|
51
|
-
target.set(v4Random, offset);
|
|
52
|
-
target[offset + 6] = (target[offset + 6] ?? 0) & 15 | 64;
|
|
53
|
-
target[offset + 8] = (target[offset + 8] ?? 0) & 63 | 128;
|
|
54
|
-
return target;
|
|
55
|
-
}
|
|
56
|
-
function uuidV4() {
|
|
57
|
-
try {
|
|
58
|
-
const native = runtime.uuidV4?.();
|
|
59
|
-
if (native) return native;
|
|
60
|
-
} catch (cause) {
|
|
61
|
-
throw new UuidRuntimeError("Runtime UUIDv4 generation failed.", { cause });
|
|
62
|
-
}
|
|
63
|
-
return errorOrThrow(formatUuid(errorOrThrow(uuidV4Bytes())));
|
|
64
|
-
}
|
|
65
|
-
/**
|
|
66
|
-
* Takes the alphabet for the same reason `uuidV7Slug` does, and NOT because a v4 slug sorts — it
|
|
67
|
-
* does not. The alphabet is a choice of representation, so a project that has standardised on the
|
|
68
|
-
* 26-character lowercase form for its public ids needs its v4 slugs in it too; the pair differing
|
|
69
|
-
* would be an asymmetry with nothing behind it.
|
|
70
|
-
*/
|
|
71
|
-
function uuidV4Slug(alphabet = "base64url") {
|
|
72
|
-
return errorOrThrow(formatUuidSlug(errorOrThrow(uuidV4Bytes()), 0, alphabet));
|
|
73
|
-
}
|
|
74
|
-
const uuidV7 = () => v7().uuidV7();
|
|
75
|
-
const uuidV7Bytes = (out, offset) => v7().uuidV7Bytes(out, offset);
|
|
76
|
-
const uuidV7At = (timestamp) => v7().uuidV7At(timestamp);
|
|
77
|
-
const uuidV7BytesAt = (timestamp, out, offset) => v7().uuidV7BytesAt(timestamp, out, offset);
|
|
78
|
-
/**
|
|
79
|
-
* The alphabet is an argument here, exactly as it is on `uuidToSlug(uuid, alphabet)`, because
|
|
80
|
-
* choosing it needs no key: without it the only way to GENERATE a base32hex slug was to build a
|
|
81
|
-
* codec, so the sortable form cost the whole masking machinery while the unsortable one was free.
|
|
82
|
-
* Positional and last, matching `uuidToSlug`, so the two spellings of "encode in this alphabet"
|
|
83
|
-
* do not diverge.
|
|
84
|
-
*/
|
|
85
|
-
function uuidV7Slug(alphabet = "base64url") {
|
|
86
|
-
const native = alphabet === "base64url" ? runtime.uuidV7Slug : void 0;
|
|
87
|
-
if (native) return native();
|
|
88
|
-
return errorOrThrow(formatUuidSlug(errorOrThrow(v7().uuidV7Bytes()), 0, alphabet));
|
|
89
|
-
}
|
|
90
|
-
//#endregion
|
|
91
|
-
export { uuidV4, uuidV4Bytes, uuidV4Slug, uuidV7, uuidV7At, uuidV7Bytes, uuidV7BytesAt, uuidV7Slug };
|
|
92
|
-
|
|
93
|
-
//# sourceMappingURL=keyless.js.map
|
package/dist/keyless.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"keyless.js","names":[],"sources":["../src/keyless.ts"],"sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * The operations that need no key, built WITHOUT a codec.\n *\n * Generating an id and re-encoding one are keyless: the result is the same value whoever asks, so\n * a bare function is an honest shape for them. Reaching them through a codec is what made them\n * expensive — a codec carries a mask schema, a cipher and a sentinel table, none of which a caller\n * who never masks will ever execute, and all of which a bundler must keep once the graph reaches\n * them. Measured 2026-08-12 on the built package: an entry importing only `uuidV7Slug` minified to\n * 12,735 bytes through the codec and 4,559 from a bare generator; `uuidToSlug` alone, 12,725\n * against 2,188. `defaultCodec` still exists and still works — it is simply no longer on the path\n * every consumer walks.\n *\n * NOTHING KEYED MAY BE ADDED HERE (Art's ruling, 2026-08-12). The only key a bare function could\n * carry is `DEFAULT_MASK_SCHEMA`'s, whose seed is a string literal in this published package, so a\n * masked operation exported this way would be the shortest spelling of the headline feature and\n * the one that obfuscates nothing. Masking is reached through a codec built with your own seed.\n */\nimport { runtime } from \"#runtime\";\nimport {\n checkRange,\n errorOrThrow,\n fillRandomBytes,\n UuidRuntimeError,\n UuidSlugError,\n} from \"./errors\";\nimport type { UuidV4Slug, UuidV4String, UuidV7Generator, UuidV7Slug, UuidV7String } from \"./types\";\nimport { formatUuid, formatUuidSlug } from \"./uuid\";\nimport type { SlugAlphabet } from \"./uuid\";\nimport { createRuntimeGenerator } from \"./v7\";\n\n/**\n * Built on first use, and the laziness is what the measurement above depends on: a module-scope\n * CONSTRUCTION call is a side effect a bundler may not remove, so an eager one would pin the\n * generator, the runtime adapter and the entropy pool into a bundle that only ever re-encodes a\n * UUID. Measured the same day, the eager spelling cost 5,130 bytes for `uuidToSlug` alone against\n * 2,188 here.\n *\n * It also keeps import-time work at zero, which `test/entropy.test.ts` gates for a different\n * reason — a heap snapshot taken at module load must capture no drawn randomness.\n */\nlet generator: UuidV7Generator | undefined;\nconst v7 = () => (generator ??= createRuntimeGenerator(runtime));\n\n/**\n * Randomness is drawn into a private buffer and copied out instead of filled through a view of the\n * caller's array: `fillRandom` requires a plain `ArrayBuffer` because Web Crypto rejects a\n * `SharedArrayBuffer` view, and a caller-supplied `out` carries no such guarantee. Reused rather\n * than allocated per call, matching the v7 generator, so the cost is one 16-byte copy.\n */\nconst v4Random = new Uint8Array(16);\n\n/** Shared with `createUuidSlugCodec`, so a v4 has one implementation however it is reached. */\nexport function uuidV4Bytes(out?: Uint8Array, offset = 0): UuidSlugError | Uint8Array {\n const target = out ?? new Uint8Array(16);\n const badRange = checkRange(target.length, offset, 16);\n if (badRange) return badRange;\n const failed = fillRandomBytes(runtime.fillRandom, v4Random);\n if (failed) return failed;\n target.set(v4Random, offset);\n target[offset + 6] = ((target[offset + 6] ?? 0) & 0x0f) | 0x40;\n target[offset + 8] = ((target[offset + 8] ?? 0) & 0x3f) | 0x80;\n return target;\n}\n\nexport function uuidV4(): UuidV4String {\n try {\n const native = runtime.uuidV4?.();\n if (native) return native;\n } catch (cause) {\n throw new UuidRuntimeError(\"Runtime UUIDv4 generation failed.\", { cause });\n }\n return errorOrThrow(formatUuid(errorOrThrow(uuidV4Bytes()))) as UuidV4String;\n}\n\n/**\n * Takes the alphabet for the same reason `uuidV7Slug` does, and NOT because a v4 slug sorts — it\n * does not. The alphabet is a choice of representation, so a project that has standardised on the\n * 26-character lowercase form for its public ids needs its v4 slugs in it too; the pair differing\n * would be an asymmetry with nothing behind it.\n */\nexport function uuidV4Slug(alphabet: SlugAlphabet = \"base64url\"): UuidV4Slug {\n // The bytes came from `uuidV4Bytes`, which stamps version 4; the encoder sees only bytes and\n // cannot carry that through, which is what the assertion stands in for.\n return errorOrThrow(formatUuidSlug(errorOrThrow(uuidV4Bytes()), 0, alphabet)) as UuidV4Slug;\n}\n\n/*\n * Return types are DECLARED, not inferred, on all four. Inference reads them off the generator, so\n * a widened method there silently widens the package's public surface — and this package has\n * already been bitten by exactly that: `uuidV7Slug` once inferred `string | UuidSlug`, which\n * collapses to `string` because `Brand`'s marker is optional, so a branded return was promised that\n * nothing checked. A declared type turns that into a compile error at the one site that is wrong.\n */\nexport const uuidV7 = (): UuidV7String => v7().uuidV7();\n\nexport const uuidV7Bytes = (out?: Uint8Array, offset?: number): UuidSlugError | Uint8Array =>\n v7().uuidV7Bytes(out, offset);\n\nexport const uuidV7At = (timestamp: number): UuidSlugError | UuidV7String =>\n v7().uuidV7At(timestamp);\n\nexport const uuidV7BytesAt = (\n timestamp: number,\n out?: Uint8Array,\n offset?: number,\n): UuidSlugError | Uint8Array => v7().uuidV7BytesAt(timestamp, out, offset);\n\n/**\n * The alphabet is an argument here, exactly as it is on `uuidToSlug(uuid, alphabet)`, because\n * choosing it needs no key: without it the only way to GENERATE a base32hex slug was to build a\n * codec, so the sortable form cost the whole masking machinery while the unsortable one was free.\n * Positional and last, matching `uuidToSlug`, so the two spellings of \"encode in this alphabet\"\n * do not diverge.\n */\nexport function uuidV7Slug(alphabet: SlugAlphabet = \"base64url\"): UuidV7Slug {\n // Gated on the ALPHABET, not merely on the hook's presence. The runtime's slug generator emits\n // base64url and nothing else, so an ungated branch answers a base32hex request with a 22-char\n // base64url string — and only Bun defines the hook, so vitest on Node cannot reach the branch at\n // all and the entire suite stays green. `test/runtime.bun.test.ts` is what actually covers it.\n // Probed per call rather than resolved once: resolving at module scope would reintroduce the\n // eager work the lazy cell above exists to avoid.\n //\n // The gate is also where the two alphabets stop costing the same, which is worth knowing before\n // standardising on the sortable one: measured on Bun 2026-08-12, base64url runs 17.0M/s and\n // base32hex 4.2M/s. Not an encoder deficiency -- base64url is handed straight to the engine's\n // own slug generator here, while base32hex must draw bytes and encode them in JavaScript. 4M\n // ids/sec is ample for identifier issuance; the number is recorded so the 4x is not rediscovered\n // as a mystery.\n const native = alphabet === \"base64url\" ? runtime.uuidV7Slug : undefined;\n if (native) return native();\n // Asserted for the same reason `uuidV4Slug` asserts: the bytes come from a v7 generator and the\n // encoder sees only bytes, so it returns the version-agnostic brand.\n return errorOrThrow(formatUuidSlug(errorOrThrow(v7().uuidV7Bytes()), 0, alphabet)) as UuidV7Slug;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,IAAI;AACJ,MAAM,WAAY,cAAc,uBAAuB,OAAO;;;;;;;AAQ9D,MAAM,2BAAW,IAAI,WAAW,EAAE;;AAGlC,SAAgB,YAAY,KAAkB,SAAS,GAA+B;CACpF,MAAM,SAAS,uBAAO,IAAI,WAAW,EAAE;CACvC,MAAM,WAAW,WAAW,OAAO,QAAQ,QAAQ,EAAE;CACrD,IAAI,UAAU,OAAO;CACrB,MAAM,SAAS,gBAAgB,QAAQ,YAAY,QAAQ;CAC3D,IAAI,QAAQ,OAAO;CACnB,OAAO,IAAI,UAAU,MAAM;CAC3B,OAAO,SAAS,MAAO,OAAO,SAAS,MAAM,KAAK,KAAQ;CAC1D,OAAO,SAAS,MAAO,OAAO,SAAS,MAAM,KAAK,KAAQ;CAC1D,OAAO;AACT;AAEA,SAAgB,SAAuB;CACrC,IAAI;EACF,MAAM,SAAS,QAAQ,SAAS;EAChC,IAAI,QAAQ,OAAO;CACrB,SAAS,OAAO;EACd,MAAM,IAAI,iBAAiB,qCAAqC,EAAE,MAAM,CAAC;CAC3E;CACA,OAAO,aAAa,WAAW,aAAa,YAAY,CAAC,CAAC,CAAC;AAC7D;;;;;;;AAQA,SAAgB,WAAW,WAAyB,aAAyB;CAG3E,OAAO,aAAa,eAAe,aAAa,YAAY,CAAC,GAAG,GAAG,QAAQ,CAAC;AAC9E;AASA,MAAa,eAA6B,GAAG,CAAC,CAAC,OAAO;AAEtD,MAAa,eAAe,KAAkB,WAC5C,GAAG,CAAC,CAAC,YAAY,KAAK,MAAM;AAE9B,MAAa,YAAY,cACvB,GAAG,CAAC,CAAC,SAAS,SAAS;AAEzB,MAAa,iBACX,WACA,KACA,WAC+B,GAAG,CAAC,CAAC,cAAc,WAAW,KAAK,MAAM;;;;;;;;AAS1E,SAAgB,WAAW,WAAyB,aAAyB;CAc3E,MAAM,SAAS,aAAa,cAAc,QAAQ,aAAa,KAAA;CAC/D,IAAI,QAAQ,OAAO,OAAO;CAG1B,OAAO,aAAa,eAAe,aAAa,GAAG,CAAC,CAAC,YAAY,CAAC,GAAG,GAAG,QAAQ,CAAC;AACnF"}
|
package/dist/legacy-mask.js
DELETED
|
@@ -1,55 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
-
// @anizoptera/uuid-slug 0.3.0 | https://github.com/Anizoptera/uuid-slug#readme
|
|
3
|
-
import { UuidSlugError } from "./errors.js";
|
|
4
|
-
//#region src/legacy-mask.ts
|
|
5
|
-
const PERMUTE = [
|
|
6
|
-
9,
|
|
7
|
-
13,
|
|
8
|
-
3,
|
|
9
|
-
8,
|
|
10
|
-
14,
|
|
11
|
-
0,
|
|
12
|
-
11,
|
|
13
|
-
7,
|
|
14
|
-
6,
|
|
15
|
-
1,
|
|
16
|
-
15,
|
|
17
|
-
4,
|
|
18
|
-
2,
|
|
19
|
-
5,
|
|
20
|
-
10,
|
|
21
|
-
12
|
|
22
|
-
];
|
|
23
|
-
const XOR = [
|
|
24
|
-
162,
|
|
25
|
-
112,
|
|
26
|
-
50,
|
|
27
|
-
127,
|
|
28
|
-
152,
|
|
29
|
-
184,
|
|
30
|
-
155,
|
|
31
|
-
94,
|
|
32
|
-
27,
|
|
33
|
-
38,
|
|
34
|
-
182,
|
|
35
|
-
22,
|
|
36
|
-
150,
|
|
37
|
-
249,
|
|
38
|
-
234,
|
|
39
|
-
62
|
|
40
|
-
];
|
|
41
|
-
/** Return a matching candidate or undefined; callers resolve sentinels before trying masks. */
|
|
42
|
-
function decodeOriginalMask(mixed) {
|
|
43
|
-
if (mixed.length !== 16) return new UuidSlugError("invalid_buffer", "Original masked slugs require 16 decoded bytes.");
|
|
44
|
-
const bytes = /* @__PURE__ */ new Uint8Array(16);
|
|
45
|
-
for (let i = 0; i < 16; i++) bytes[PERMUTE[i]] = mixed[i] ^ XOR[i];
|
|
46
|
-
const found = bytes[6] >>> 4;
|
|
47
|
-
bytes[6] = bytes[6] & 15 | 112;
|
|
48
|
-
let checksum = 0;
|
|
49
|
-
for (const byte of bytes) checksum ^= byte;
|
|
50
|
-
return (checksum >>> 4 ^ checksum & 15) === found ? bytes : void 0;
|
|
51
|
-
}
|
|
52
|
-
//#endregion
|
|
53
|
-
export { decodeOriginalMask };
|
|
54
|
-
|
|
55
|
-
//# sourceMappingURL=legacy-mask.js.map
|
package/dist/legacy-mask.js.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"legacy-mask.js","names":[],"sources":["../src/legacy-mask.ts"],"sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\nimport { UuidSlugError } from \"./errors\";\n\n// These tables and the four-bit checksum define the original wire format.\n// Changing them would change the UUID recovered from an existing slug.\nconst PERMUTE = [9, 13, 3, 8, 14, 0, 11, 7, 6, 1, 15, 4, 2, 5, 10, 12] as const;\nconst XOR = [\n 0xa2, 0x70, 0x32, 0x7f, 0x98, 0xb8, 0x9b, 0x5e, 0x1b, 0x26, 0xb6, 0x16, 0x96, 0xf9, 0xea, 0x3e,\n] as const;\n\n/** Return a matching candidate or undefined; callers resolve sentinels before trying masks. */\nexport function decodeOriginalMask(mixed: Uint8Array): Uint8Array | UuidSlugError | undefined {\n if (mixed.length !== 16)\n return new UuidSlugError(\"invalid_buffer\", \"Original masked slugs require 16 decoded bytes.\");\n const bytes = new Uint8Array(16);\n for (let i = 0; i < 16; i++)\n bytes[PERMUTE[i] as number] = (mixed[i] as number) ^ (XOR[i] as number);\n const found = (bytes[6] as number) >>> 4;\n bytes[6] = ((bytes[6] as number) & 15) | 0x70;\n let checksum = 0;\n for (const byte of bytes) checksum ^= byte;\n // A mismatch is expected while trying formats; allocate diagnostics only if the reader fails.\n return ((checksum >>> 4) ^ (checksum & 15)) === found ? bytes : undefined;\n}\n"],"mappings":";;;;AAMA,MAAM,UAAU;CAAC;CAAG;CAAI;CAAG;CAAG;CAAI;CAAG;CAAI;CAAG;CAAG;CAAG;CAAI;CAAG;CAAG;CAAG;CAAI;AAAE;AACrE,MAAM,MAAM;CACV;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;CAAM;AAC5F;;AAGA,SAAgB,mBAAmB,OAA2D;CAC5F,IAAI,MAAM,WAAW,IACnB,OAAO,IAAI,cAAc,kBAAkB,iDAAiD;CAC9F,MAAM,wBAAQ,IAAI,WAAW,EAAE;CAC/B,KAAK,IAAI,IAAI,GAAG,IAAI,IAAI,KACtB,MAAM,QAAQ,MAAiB,MAAM,KAAiB,IAAI;CAC5D,MAAM,QAAS,MAAM,OAAkB;CACvC,MAAM,KAAO,MAAM,KAAgB,KAAM;CACzC,IAAI,WAAW;CACf,KAAK,MAAM,QAAQ,OAAO,YAAY;CAEtC,QAAS,aAAa,IAAM,WAAW,QAAS,QAAQ,QAAQ,KAAA;AAClE"}
|
package/dist/node/alphabet.js
DELETED
|
@@ -1,130 +0,0 @@
|
|
|
1
|
-
// SPDX-License-Identifier: Apache-2.0
|
|
2
|
-
// @anizoptera/uuid-slug 0.3.0 | https://github.com/Anizoptera/uuid-slug#readme
|
|
3
|
-
import { UuidSlugError, checkRange } from "./errors.js";
|
|
4
|
-
//#region src/alphabet.ts
|
|
5
|
-
function alphabet(name, chars, code) {
|
|
6
|
-
const bitsPerChar = Math.log2(chars.length);
|
|
7
|
-
if (!Number.isInteger(bitsPerChar)) throw new Error(`${name} alphabet must be a power of two.`);
|
|
8
|
-
const decode = (/* @__PURE__ */ new Int16Array(128)).fill(-1);
|
|
9
|
-
for (let i = 0; i < chars.length; i += 1) decode[chars.charCodeAt(i)] = i;
|
|
10
|
-
return {
|
|
11
|
-
bitsPerChar,
|
|
12
|
-
chars,
|
|
13
|
-
code,
|
|
14
|
-
decode,
|
|
15
|
-
name,
|
|
16
|
-
invalidChars: new RegExp(`[^${chars.replaceAll("-", "\\-")}]`)
|
|
17
|
-
};
|
|
18
|
-
}
|
|
19
|
-
const BASE64URL = alphabet("base64url", "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_", "invalid_base64url");
|
|
20
|
-
/**
|
|
21
|
-
* The RFC 4648 §7 extended-hex digit values, not the §6 alphabet and not Crockford. Chosen because
|
|
22
|
-
* its characters are in ASCII order, so encoded values sort the same way the underlying bytes do —
|
|
23
|
-
* the one property base64url cannot offer, and the reason a second alphabet exists at all.
|
|
24
|
-
*
|
|
25
|
-
* Spelled LOWERCASE where the RFC writes `0-9A-V`, matching how this package renders UUIDs, and
|
|
26
|
-
* decoding accepts only that spelling so an id has exactly one form. The cost is interop: verified
|
|
27
|
-
* 2026-08-12 against CPython, `base64.b32hexdecode` rejects these slugs unless called with
|
|
28
|
-
* `casefold=True`. Upper-case them at the boundary if a strict RFC decoder has to read them.
|
|
29
|
-
*/
|
|
30
|
-
const BASE32HEX = alphabet("base32hex", "0123456789abcdefghijklmnopqrstuv", "invalid_base32");
|
|
31
|
-
const nativeToBase64 = Uint8Array.prototype.toBase64;
|
|
32
|
-
const BASE64_OPTIONS = {
|
|
33
|
-
alphabet: "base64url",
|
|
34
|
-
omitPadding: true
|
|
35
|
-
};
|
|
36
|
-
/**
|
|
37
|
-
* Bits left over when `byteLength` bytes are written in this alphabet. A slug rounds up to whole
|
|
38
|
-
* characters, so the final character has spare low bits that carry no data: 4 for 16 bytes in
|
|
39
|
-
* base64url (22 chars = 132 bits), 2 in base32hex (26 chars = 130 bits). Callers may spend them
|
|
40
|
-
* on a trailing value at zero cost in length — see `encode`.
|
|
41
|
-
*/
|
|
42
|
-
function spareBits(alpha, byteLength) {
|
|
43
|
-
const bits = byteLength * 8;
|
|
44
|
-
return (alpha.bitsPerChar - bits % alpha.bitsPerChar) % alpha.bitsPerChar;
|
|
45
|
-
}
|
|
46
|
-
/** Boolean validation needs no output buffer or diagnostic allocation. */
|
|
47
|
-
function isEncoded(value, alpha, byteLength) {
|
|
48
|
-
if (value.length !== Math.ceil(byteLength * 8 / alpha.bitsPerChar) || alpha.invalidChars.test(value)) return false;
|
|
49
|
-
const spare = spareBits(alpha, byteLength);
|
|
50
|
-
return spare === 0 || (alpha.decode[value.charCodeAt(value.length - 1)] & (1 << spare) - 1) === 0;
|
|
51
|
-
}
|
|
52
|
-
/**
|
|
53
|
-
* Pack bytes, optionally followed by `tailBits` low bits of `tail`, into `alpha`.
|
|
54
|
-
*
|
|
55
|
-
* `tailBits` MUST NOT exceed `spareBits`, otherwise the result grows a character. Passing
|
|
56
|
-
* `tail = 0` reproduces a plain encoding byte for byte, which is what keeps identifiers issued
|
|
57
|
-
* before the tail existed valid afterwards.
|
|
58
|
-
*/
|
|
59
|
-
function encode(bytes, alpha, tail = 0, tailBits = 0) {
|
|
60
|
-
if (nativeToBase64 && alpha === BASE64URL && tailBits >= 0 && tailBits <= spareBits(alpha, bytes.length)) {
|
|
61
|
-
const encoded = nativeToBase64.call(bytes, BASE64_OPTIONS);
|
|
62
|
-
if (tailBits === 0) return encoded;
|
|
63
|
-
const last = encoded.length - 1;
|
|
64
|
-
const digit = alpha.decode[encoded.charCodeAt(last)];
|
|
65
|
-
const trailing = (tail & (1 << tailBits) - 1) << spareBits(alpha, bytes.length) - tailBits;
|
|
66
|
-
return encoded.slice(0, last) + alpha.chars[digit | trailing];
|
|
67
|
-
}
|
|
68
|
-
const { bitsPerChar, chars } = alpha;
|
|
69
|
-
const mask = (1 << bitsPerChar) - 1;
|
|
70
|
-
let out = "";
|
|
71
|
-
let acc = 0;
|
|
72
|
-
let bits = 0;
|
|
73
|
-
for (let i = 0; i < bytes.length; i += 1) {
|
|
74
|
-
acc = acc << 8 | bytes[i];
|
|
75
|
-
bits += 8;
|
|
76
|
-
while (bits >= bitsPerChar) {
|
|
77
|
-
bits -= bitsPerChar;
|
|
78
|
-
out += chars[acc >>> bits & mask];
|
|
79
|
-
}
|
|
80
|
-
}
|
|
81
|
-
if (tailBits > 0) {
|
|
82
|
-
acc = acc << tailBits | tail & (1 << tailBits) - 1;
|
|
83
|
-
bits += tailBits;
|
|
84
|
-
while (bits >= bitsPerChar) {
|
|
85
|
-
bits -= bitsPerChar;
|
|
86
|
-
out += chars[acc >>> bits & mask];
|
|
87
|
-
}
|
|
88
|
-
}
|
|
89
|
-
if (bits > 0) out += chars[acc << bitsPerChar - bits & mask];
|
|
90
|
-
return out;
|
|
91
|
-
}
|
|
92
|
-
/**
|
|
93
|
-
* Inverse of `encode`, writing into a caller-owned buffer so the slug paths need no intermediate
|
|
94
|
-
* allocation. Returns the trailing value (0 when `tailBits` is 0), or an Error.
|
|
95
|
-
*
|
|
96
|
-
* Rejects any character outside the alphabet, and any padding bit that is not zero. Without that
|
|
97
|
-
* last check one identifier would have several valid spellings, so a corrupted slug could decode
|
|
98
|
-
* successfully instead of being refused.
|
|
99
|
-
*/
|
|
100
|
-
function decodeInto(value, alpha, out, offset, byteLength, tailBits = 0) {
|
|
101
|
-
const { bitsPerChar, decode: table, code, name } = alpha;
|
|
102
|
-
const expected = Math.ceil((byteLength * 8 + tailBits) / bitsPerChar);
|
|
103
|
-
if (value.length !== expected) return new UuidSlugError(code, `Expected ${expected} ${name} characters, got ${value.length}.`);
|
|
104
|
-
const badRange = checkRange(out.length, offset, byteLength);
|
|
105
|
-
if (badRange) return badRange;
|
|
106
|
-
let acc = 0;
|
|
107
|
-
let bits = 0;
|
|
108
|
-
let written = 0;
|
|
109
|
-
for (let i = 0; i < value.length; i += 1) {
|
|
110
|
-
const charCode = value.charCodeAt(i);
|
|
111
|
-
const digit = charCode < 128 ? table[charCode] : -1;
|
|
112
|
-
if (digit < 0) return new UuidSlugError(code, `Invalid ${name} character at offset ${i}.`);
|
|
113
|
-
acc = acc << bitsPerChar | digit;
|
|
114
|
-
bits += bitsPerChar;
|
|
115
|
-
while (bits >= 8 && written < byteLength) {
|
|
116
|
-
bits -= 8;
|
|
117
|
-
out[offset + written] = acc >>> bits & 255;
|
|
118
|
-
written += 1;
|
|
119
|
-
}
|
|
120
|
-
}
|
|
121
|
-
let tail = 0;
|
|
122
|
-
if (tailBits > 0) {
|
|
123
|
-
bits -= tailBits;
|
|
124
|
-
tail = acc >>> bits & (1 << tailBits) - 1;
|
|
125
|
-
}
|
|
126
|
-
if (bits > 0 && (acc & (1 << bits) - 1) !== 0) return new UuidSlugError(code, `${name} value has non-canonical trailing bits.`);
|
|
127
|
-
return tail;
|
|
128
|
-
}
|
|
129
|
-
//#endregion
|
|
130
|
-
export { BASE32HEX, BASE64URL, decodeInto, encode, isEncoded, spareBits };
|