From 999e5e7a97c78f7c6ee6d15aecd245c44cb5b273 Mon Sep 17 00:00:00 2001 From: Marvin Hagemeister Date: Wed, 29 May 2024 07:47:42 +0200 Subject: [PATCH] docs(uuid): update module docs (#4790) --- _tools/check_docs.ts | 1 + _tools/check_mod_exports.ts | 4 ++ deno.json | 2 +- uuid/common.ts | 38 +++++++++---- uuid/constants.ts | 20 ++++--- uuid/mod.ts | 104 ++++++++++++++++++++++++++++++++---- uuid/v1.ts | 45 +++++++++------- uuid/v3.ts | 44 +++++++++------ uuid/v4.ts | 16 +++--- uuid/v5.ts | 44 +++++++++------ 10 files changed, 230 insertions(+), 88 deletions(-) diff --git a/_tools/check_docs.ts b/_tools/check_docs.ts index 67cbddb1f..5d16e8af4 100644 --- a/_tools/check_docs.ts +++ b/_tools/check_docs.ts @@ -47,6 +47,7 @@ const ENTRY_POINTS = [ "../streams/mod.ts", "../text/mod.ts", "../ulid/mod.ts", + "../uuid/mod.ts", "../webgpu/mod.ts", ] as const; diff --git a/_tools/check_mod_exports.ts b/_tools/check_mod_exports.ts index 2ffefa9b6..5c23835fc 100644 --- a/_tools/check_mod_exports.ts +++ b/_tools/check_mod_exports.ts @@ -44,6 +44,10 @@ for await ( /front_matter(\/|\\)json\.ts$/, /front_matter(\/|\\)toml\.ts$/, /front_matter(\/|\\)any\.ts$/, + /uuid(\/|\\)v1\.ts$/, + /uuid(\/|\\)v3\.ts$/, + /uuid(\/|\\)v4\.ts$/, + /uuid(\/|\\)v5\.ts$/, /yaml(\/|\\)schema\.ts$/, /test\.ts$/, /\.d\.ts$/, diff --git a/deno.json b/deno.json index d36df1b65..c97e5eee3 100644 --- a/deno.json +++ b/deno.json @@ -7,7 +7,7 @@ }, "imports": { "@deno/graph": "jsr:@deno/graph@^0.74", - "@deno/doc": "jsr:@deno/doc@0.134", + "@deno/doc": "jsr:@deno/doc@0.137", "npm:/typescript": "npm:typescript@5.4.4", "automation/": "https://raw.githubusercontent.com/denoland/automation/0.10.0/", "graphviz": "npm:node-graphviz@^0.1.1", diff --git a/uuid/common.ts b/uuid/common.ts index 20f194763..42991517d 100644 --- a/uuid/common.ts +++ b/uuid/common.ts @@ -4,14 +4,20 @@ import { NIL_UUID } from "./constants.ts"; /** - * Check if the passed UUID is the nil UUID. + * Determines whether the UUID is the + * {@link https://www.rfc-editor.org/rfc/rfc4122#section-4.1.7 | nil UUID}. * - * @example + * @param id UUID value. + * + * @returns `true` if the UUID is the nil UUID, otherwise `false`. + * + * @example Usage * ```ts * import { isNil } from "@std/uuid"; + * import { assert, assertFalse } from "@std/assert"; * - * isNil("00000000-0000-0000-0000-000000000000"); // true - * isNil(crypto.randomUUID()); // false + * assert(isNil("00000000-0000-0000-0000-000000000000")); + * assertFalse(isNil(crypto.randomUUID())); * ``` */ export function isNil(id: string): boolean { @@ -19,14 +25,19 @@ export function isNil(id: string): boolean { } /** - * Test a string to see if it is a valid UUID. + * Determines whether a string is a valid UUID. * - * @example + * @param uuid UUID value. + * + * @returns `true` if the string is a valid UUID, otherwise `false`. + * + * @example Usage * ```ts * import { validate } from "@std/uuid"; + * import { assert, assertFalse } from "@std/assert"; * - * validate("not a UUID"); // false - * validate("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"); // true + * assert(validate("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b")); + * assertFalse(validate("not a UUID")); * ``` */ export function validate(uuid: string): boolean { @@ -39,12 +50,17 @@ export function validate(uuid: string): boolean { /** * Detect RFC version of a UUID. * - * @example + * @param uuid UUID value. + * + * @returns The RFC version of the UUID. + * + * @example Usage * ```ts * import { version } from "@std/uuid"; + * import { assertEquals } from "@std/assert/assert-equals"; * - * version("d9428888-122b-11e1-b85c-61cd3cbb3210"); // 1 - * version("109156be-c4fb-41ea-b1b4-efe1671c5836"); // 4 + * assertEquals(version("d9428888-122b-11e1-b85c-61cd3cbb3210"), 1); + * assertEquals(version("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"), 4); * ``` */ export function version(uuid: string): number { diff --git a/uuid/constants.ts b/uuid/constants.ts index 94a78f2dd..6fdb6cb59 100644 --- a/uuid/constants.ts +++ b/uuid/constants.ts @@ -4,44 +4,48 @@ /** * Name string is a fully-qualified domain name. * - * @example + * @example Usage * ```ts * import { NAMESPACE_DNS } from "@std/uuid/constants"; + * import { generate } from "@std/uuid/v5"; * - * console.log(NAMESPACE_DNS); // => 6ba7b810-9dad-11d1-80b4-00c04fd430c8 + * await generate(NAMESPACE_DNS, new TextEncoder().encode("deno.land")); * ``` */ export const NAMESPACE_DNS = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"; /** * Name string is a URL. * - * @example + * @example Usage * ```ts * import { NAMESPACE_URL } from "@std/uuid/constants"; + * import { generate } from "@std/uuid/v3"; * - * console.log(NAMESPACE_URL); // => 6ba7b811-9dad-11d1-80b4-00c04fd430c8 + * await generate(NAMESPACE_URL, new TextEncoder().encode("https://deno.land")); * ``` */ export const NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"; /** * Name string is an ISO OID. * - * @example + * @example Usage * ```ts * import { NAMESPACE_OID } from "@std/uuid/constants"; + * import { generate } from "@std/uuid/v5"; * - * console.log(NAMESPACE_OID); // => 6ba7b812-9dad-11d1-80b4-00c04fd430c8 + * await generate(NAMESPACE_OID, new TextEncoder().encode("1.3.6.1.2.1.1.1")); * ``` */ export const NAMESPACE_OID = "6ba7b812-9dad-11d1-80b4-00c04fd430c8"; /** * Name string is an X.500 DN (in DER or a text output format). * - * @example + * @example Usage * ```ts * import { NAMESPACE_X500 } from "@std/uuid/constants"; + * import { generate } from "@std/uuid/v3"; * - * console.log(NAMESPACE_X500); // => 6ba7b814-9dad-11d1-80b4-00c04fd430c8 + * await generate(NAMESPACE_X500, new TextEncoder().encode("CN=John Doe, OU=People, O=Example.com")); * ``` */ export const NAMESPACE_X500 = "6ba7b814-9dad-11d1-80b4-00c04fd430c8"; diff --git a/uuid/mod.ts b/uuid/mod.ts index de4940a0f..84c61db47 100644 --- a/uuid/mod.ts +++ b/uuid/mod.ts @@ -2,23 +2,107 @@ // This module is browser compatible. /** - * Generators and validators for UUIDs for versions v1, v3, v4 and v5. + * Generators and validators for + * {@link https://www.rfc-editor.org/rfc/rfc9562.html | RFC 9562} UUIDs for + * versions v1, v3, v4 and v5. * - * Use {@linkcode crypto.randomUUID} for v4 generating v4 UUIDs. + * Use the built-in + * {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID | crypto.randomUUID()} + * function instead of this package, if you only need to generate v4 UUIDs. * - * Based on {@linkcode https://www.npmjs.com/package/uuid | npm:uuid}, which is - * based on {@link https://www.rfc-editor.org/rfc/rfc4122.html | RFC 4122}. + * Based on {@linkcode https://www.npmjs.com/package/uuid | npm:uuid}. * - * Support for RFC4122 version 1, 3, 4, and 5 UUIDs + * ```ts + * import { v5, NAMESPACE_DNS, NIL_UUID } from "@std/uuid"; + * import { assert, assertFalse } from "@std/assert"; * - * This module is browser compatible. + * const data = new TextEncoder().encode("deno.land"); + * const uuid = await v5.generate(NAMESPACE_DNS, data); + * + * assert(v5.validate(uuid)); + * assertFalse(v5.validate(NIL_UUID)); + * ``` * * @module */ export * from "./common.ts"; export * from "./constants.ts"; -export * as v1 from "./v1.ts"; -export * as v3 from "./v3.ts"; -export * as v4 from "./v4.ts"; -export * as v5 from "./v5.ts"; + +import { generate as generateV1, validate as validateV1 } from "./v1.ts"; +import { generate as generateV3, validate as validateV3 } from "./v3.ts"; +import { validate as validateV4 } from "./v4.ts"; +import { generate as generateV5, validate as validateV5 } from "./v5.ts"; + +/** + * Generator and validator for + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.1 | UUIDv1}. + * + * @example Usage + * ```ts + * import { v1 } from "@std/uuid"; + * import { assert } from "@std/assert/assert"; + * + * const uuid = v1.generate(); + * assert(v1.validate(uuid as string)); + * ``` + */ +export const v1 = { + generate: generateV1, + validate: validateV1, +}; + +/** + * Generator and validator for + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.3 | UUIDv3}. + * + * @example Usage + * ```ts + * import { v3, NAMESPACE_DNS } from "@std/uuid"; + * import { assert } from "@std/assert/assert"; + * + * const data = new TextEncoder().encode("deno.land"); + * const uuid = await v3.generate(NAMESPACE_DNS, data); + * assert(v3.validate(uuid)); + * ``` + */ +export const v3 = { + generate: generateV3, + validate: validateV3, +}; + +/** + * Validator for + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.4 | UUIDv4}. + * + * @example Usage + * ```ts + * import { v4 } from "@std/uuid"; + * import { assert } from "@std/assert/assert"; + * + * const uuid = crypto.randomUUID(); + * assert(v4.validate(uuid)); + * ``` + */ +export const v4 = { + validate: validateV4, +}; + +/** + * Generator and validator for + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.5 | UUIDv5}. + * + * @example Usage + * ```ts + * import { v5, NAMESPACE_DNS } from "@std/uuid"; + * import { assert } from "@std/assert/assert"; + * + * const data = new TextEncoder().encode("deno.land"); + * const uuid = await v5.generate(NAMESPACE_DNS, data); + * assert(v5.validate(uuid)); + * ``` + */ +export const v5 = { + generate: generateV5, + validate: validateV5, +}; diff --git a/uuid/v1.ts b/uuid/v1.ts index 12e6220f5..46e7d9878 100644 --- a/uuid/v1.ts +++ b/uuid/v1.ts @@ -7,17 +7,21 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-1[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; /** - * Validates the UUID v1. - * - * @example - * ```ts - * import { validate } from "@std/uuid/v1"; - * - * validate("ea71fc60-a713-11ee-af61-8349da24f689"); // true - * validate("fac8c1e0-ad1a-4204-a0d0-8126ae84495d"); // false - * ``` + * Determines whether a string is a valid + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.1 | UUIDv1}. * * @param id UUID value. + * + * @returns `true` if the string is a valid UUIDv1, otherwise `false`. + * + * @example Usage + * ```ts + * import { validate } from "@std/uuid/v1"; + * import { assert, assertFalse } from "@std/assert"; + * + * assert(validate("ea71fc60-a713-11ee-af61-8349da24f689")); + * assertFalse(validate("fac8c1e0-ad1a-4204-a0d0-8126ae84495d")); + * ``` */ export function validate(id: string): boolean { return UUID_RE.test(id); @@ -29,7 +33,7 @@ let _clockseq: number; let _lastMSecs = 0; let _lastNSecs = 0; -/** The options used for generating a v1 UUID in {@linkcode generate}. */ +/** Options for {@linkcode generate}. */ export interface V1Options { /** * An array of 6 bytes that represents a 48-bit IEEE 802 MAC address. @@ -67,11 +71,19 @@ export interface V1Options { } /** - * Generates a RFC4122 v1 UUID (time-based). + * Generates a + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.1 | UUIDv1}. * - * @example + * @param options Can use RFC time sequence values as overwrites. + * @param buf Can allow the UUID to be written in byte-form starting at the offset. + * @param offset Index to start writing on the UUID bytes in buffer. + * + * @returns Returns a UUIDv1 string or an array of 16 bytes. + * + * @example Usage * ```ts - * import { generate } from "@std/uuid/v1"; + * import { generate, validate } from "@std/uuid/v1"; + * import { assert } from "@std/assert/assert"; * * const options = { * node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab], @@ -80,12 +92,9 @@ export interface V1Options { * nsecs: 5678, * }; * - * generate(options); // "710b962e-041c-11e1-9234-0123456789ab" + * const uuid = generate(options) as string; + * assert(validate(uuid)); * ``` - * - * @param options Can use RFC time sequence values as overwrites. - * @param buf Can allow the UUID to be written in byte-form starting at the offset. - * @param offset Index to start writing on the UUID bytes in buffer. */ export function generate( options?: V1Options | null, diff --git a/uuid/v3.ts b/uuid/v3.ts index 19860d414..e80356c0c 100644 --- a/uuid/v3.ts +++ b/uuid/v3.ts @@ -10,15 +10,20 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[3][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; /** - * Validate that the passed UUID is an RFC4122 v3 UUID. + * Determines whether a string is a valid + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.3 | UUIDv3}. * - * @example + * @param id UUID value. + * + * @returns `true` if the string is a valid UUIDv3, otherwise `false`. + * + * @example Usage * ```ts - * import { generate, validate } from "@std/uuid/v3"; + * import { validate } from "@std/uuid/v3"; + * import { assert, assertFalse } from "@std/assert"; * - * validate(await generate("6ba7b811-9dad-11d1-80b4-00c04fd430c8", new Uint8Array())); // true - * validate(crypto.randomUUID()); // false - * validate("this-is-not-a-uuid"); // false + * assert(validate("22fe6191-c161-3d86-a432-a81f343eda08")); + * assertFalse(validate("this-is-not-a-uuid")); * ``` */ export function validate(id: string): boolean { @@ -26,20 +31,25 @@ export function validate(id: string): boolean { } /** - * Generate a RFC4122 v3 UUID (MD5 namespace). - * - * @example - * ```js - * import { generate } from "@std/uuid/v3"; - * - * const NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"; - * - * const uuid = await generate(NAMESPACE_URL, new TextEncoder().encode("python.org")); - * uuid === "22fe6191-c161-3d86-a432-a81f343eda08" // true - * ``` + * Generates a + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.3 | UUIDv3}. * * @param namespace The namespace to use, encoded as a UUID. * @param data The data to hash to calculate the MD5 digest for the UUID. + * + * @returns A UUIDv3 string. + * + * @example Usage + * ```ts + * import { NAMESPACE_URL } from "@std/uuid/constants"; + * import { generate, validate } from "@std/uuid/v3"; + * import { assert } from "@std/assert"; + * + * const data = new TextEncoder().encode("python.org"); + * const uuid = await generate(NAMESPACE_URL, data); + * + * assert(validate(uuid)); + * ``` */ export async function generate( namespace: string, diff --git a/uuid/v4.ts b/uuid/v4.ts index 8dc98a29a..d5bd46411 100644 --- a/uuid/v4.ts +++ b/uuid/v4.ts @@ -5,16 +5,20 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; /** - * Validate that the passed UUID is an RFC4122 v4 UUID. + * Determines whether a string is a valid + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.4 | UUIDv4}. * - * @example + * @param id UUID value. + * + * @returns `true` if the UUID is valid UUIDv4, otherwise `false`. + * + * @example Usage * ```ts * import { validate } from "@std/uuid/v4"; - * import { generate as generateV1 } from "@std/uuid/v1"; + * import { assert, assertFalse } from "@std/assert"; * - * validate(crypto.randomUUID()); // true - * validate(generateV1() as string); // false - * validate("this-is-not-a-uuid"); // false + * assert(validate(crypto.randomUUID())); + * assertFalse(validate("this-is-not-a-uuid")); * ``` */ export function validate( diff --git a/uuid/v5.ts b/uuid/v5.ts index d91a2efb5..45b0d167b 100644 --- a/uuid/v5.ts +++ b/uuid/v5.ts @@ -9,15 +9,20 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i; /** - * Validate that the passed UUID is an RFC4122 v5 UUID. + * Determines whether a string is a valid + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.5 | UUIDv5}. * - * @example + * @param id UUID value. + * + * @returns `true` if the string is a valid UUIDv5, otherwise `false`. + * + * @example Usage * ```ts - * import { generate as generateV5, validate } from "@std/uuid/v5"; + * import { validate } from "@std/uuid/v5"; + * import { assert, assertFalse } from "@std/assert"; * - * validate(await generateV5("6ba7b811-9dad-11d1-80b4-00c04fd430c8", new Uint8Array())); // true - * validate(crypto.randomUUID()); // false - * validate("this-is-not-a-uuid"); // false + * assert(validate("7af94e2b-4dd9-50f0-9c9a-8a48519bdef0")); + * assertFalse(validate(crypto.randomUUID())); * ``` */ export function validate(id: string): boolean { @@ -25,20 +30,25 @@ export function validate(id: string): boolean { } /** - * Generate a RFC4122 v5 UUID (SHA-1 namespace). - * - * @example - * ```js - * import { generate } from "@std/uuid/v5"; - * - * const NAMESPACE_URL = "6ba7b811-9dad-11d1-80b4-00c04fd430c8"; - * - * const uuid = await generate(NAMESPACE_URL, new TextEncoder().encode("python.org")); - * uuid === "7af94e2b-4dd9-50f0-9c9a-8a48519bdef0" // true - * ``` + * Generates a + * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.5 | UUIDv5}. * * @param namespace The namespace to use, encoded as a UUID. * @param data The data to hash to calculate the SHA-1 digest for the UUID. + * + * @returns A UUIDv5 string. + * + * @example Usage + * ```ts + * import { NAMESPACE_URL } from "@std/uuid/constants"; + * import { generate, validate } from "@std/uuid/v5"; + * import { assert } from "@std/assert"; + * + * const data = new TextEncoder().encode("python.org"); + * const uuid = await generate(NAMESPACE_URL, data); + * + * assert(validate(uuid)); + * ``` */ export async function generate( namespace: string,