docs(uuid): update module docs (#4790)

_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;
 

_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$/,

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",

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
+ * assert(isNil("00000000-0000-0000-0000-000000000000"));
- * isNil(crypto.randomUUID()); // false
+ * 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
+ * assert(validate("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"));
- * validate("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"); // true
+ * 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
+ * assertEquals(version("d9428888-122b-11e1-b85c-61cd3cbb3210"), 1);
- * version("109156be-c4fb-41ea-b1b4-efe1671c5836"); // 4
+ * assertEquals(version("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"), 4);
  * ```
  */
 export function version(uuid: string): number {

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";

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 {@linkcode https://www.npmjs.com/package/uuid | npm:uuid}.
- * based on {@link https://www.rfc-editor.org/rfc/rfc4122.html | RFC 4122}.
  *
- * 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";
+import { generate as generateV1, validate as validateV1 } from "./v1.ts";
-export * as v4 from "./v4.ts";
+import { generate as generateV3, validate as validateV3 } from "./v3.ts";
-export * as v5 from "./v5.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,
+};

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.
+ * Determines whether a string is a valid
- *
+ * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.1 | UUIDv1}.
- * @example
- * ```ts
- * import { validate } from "@std/uuid/v1";
- *
- * validate("ea71fc60-a713-11ee-af61-8349da24f689");  // true
- * validate("fac8c1e0-ad1a-4204-a0d0-8126ae84495d");  // false
- * ```
  *
  * @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,

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
+ * assert(validate("22fe6191-c161-3d86-a432-a81f343eda08"));
- * validate(crypto.randomUUID()); // false
+ * assertFalse(validate("this-is-not-a-uuid"));
- * validate("this-is-not-a-uuid"); // false
  * ```
  */
 export function validate(id: string): boolean {
@@ -26,20 +31,25 @@ export function validate(id: string): boolean {
 }
 
 /**
- * Generate a RFC4122 v3 UUID (MD5 namespace).
+ * Generates a
- *
+ * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.3 | UUIDv3}.
- * @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
- * ```
  *
  * @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,

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
+ * assert(validate(crypto.randomUUID()));
- * validate(generateV1() as string); // false
+ * assertFalse(validate("this-is-not-a-uuid"));
- * validate("this-is-not-a-uuid"); // false
  * ```
  */
 export function validate(

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
+ * assert(validate("7af94e2b-4dd9-50f0-9c9a-8a48519bdef0"));
- * validate(crypto.randomUUID()); // false
+ * assertFalse(validate(crypto.randomUUID()));
- * validate("this-is-not-a-uuid"); // false
  * ```
  */
 export function validate(id: string): boolean {
@@ -25,20 +30,25 @@ export function validate(id: string): boolean {
 }
 
 /**
- * Generate a RFC4122 v5 UUID (SHA-1 namespace).
+ * Generates a
- *
+ * {@link https://www.rfc-editor.org/rfc/rfc9562.html#section-5.5 | UUIDv5}.
- * @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
- * ```
  *
  * @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,