From 328e3d2a88f3b38457edb33cfc9cb77455588a87 Mon Sep 17 00:00:00 2001 From: David Luis <95457148+babiabeo@users.noreply.github.com> Date: Sun, 31 Dec 2023 05:40:48 +0700 Subject: [PATCH] docs(uuid): complete documentation (#4044) * chore(uuid): complete documentation * fmt * tweaks * further tweaks * tweak --------- Co-authored-by: Asher Gomez --- uuid/mod.ts | 44 +++++++++++++++++++++-------------------- uuid/v1.ts | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++++- uuid/v3.ts | 4 ++-- 3 files changed, 80 insertions(+), 24 deletions(-) diff --git a/uuid/mod.ts b/uuid/mod.ts index a329b947aafb..8bd52f54d505 100644 --- a/uuid/mod.ts +++ b/uuid/mod.ts @@ -4,9 +4,7 @@ /** * Generators and validators for UUIDs for versions v1, v3, v4 and v5. * - * Consider using the web platform - * [`crypto.randomUUID`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID) - * for v4 UUIDs instead. + * Use {@linkcode crypto.randomUUID} for v4 generating v4 UUIDs. * * Based on https://github.com/kelektiv/node-uuid -> https://www.ietf.org/rfc/rfc4122.txt * @@ -18,22 +16,26 @@ */ 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 * as v1 from "./v1.ts"; -import * as v3 from "./v3.ts"; -import * as v4 from "./v4.ts"; -import * as v5 from "./v5.ts"; - +/** + * The nil UUID is special form of UUID that is specified to have all 128 bits + * set to zero. + */ export const NIL_UUID = "00000000-0000-0000-0000-000000000000"; /** * Check if the passed UUID is the nil UUID. * - * ```js + * @example + * ```ts * import { isNil } from "https://deno.land/std@$STD_VERSION/uuid/mod.ts"; * - * isNil("00000000-0000-0000-0000-000000000000") // true - * isNil(crypto.randomUUID()) // false + * isNil("00000000-0000-0000-0000-000000000000"); // true + * isNil(crypto.randomUUID()); // false * ``` */ export function isNil(id: string): boolean { @@ -43,11 +45,12 @@ export function isNil(id: string): boolean { /** * Test a string to see if it is a valid UUID. * - * ```js - * import { validate } from "https://deno.land/std@$STD_VERSION/uuid/mod.ts" + * @example + * ```ts + * import { validate } from "https://deno.land/std@$STD_VERSION/uuid/mod.ts"; * - * validate("not a UUID") // false - * validate("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b") // true + * validate("not a UUID"); // false + * validate("6ec0bd7f-11c0-43da-975e-2a8ad9ebae0b"); // true * ``` */ export function validate(uuid: string): boolean { @@ -60,11 +63,12 @@ export function validate(uuid: string): boolean { /** * Detect RFC version of a UUID. * - * ```js - * import { version } from "https://deno.land/std@$STD_VERSION/uuid/mod.ts" + * @example + * ```ts + * import { version } from "https://deno.land/std@$STD_VERSION/uuid/mod.ts"; * - * version("d9428888-122b-11e1-b85c-61cd3cbb3210") // 1 - * version("109156be-c4fb-41ea-b1b4-efe1671c5836") // 4 + * version("d9428888-122b-11e1-b85c-61cd3cbb3210"); // 1 + * version("109156be-c4fb-41ea-b1b4-efe1671c5836"); // 4 * ``` */ export function version(uuid: string): number { @@ -74,5 +78,3 @@ export function version(uuid: string): number { return parseInt(uuid[14], 16); } - -export { v1, v3, v4, v5 }; diff --git a/uuid/v1.ts b/uuid/v1.ts index 7373661c5a5a..fd5bef860c68 100644 --- a/uuid/v1.ts +++ b/uuid/v1.ts @@ -8,6 +8,15 @@ const UUID_RE = /** * Validates the UUID v1. + * + * @example + * ```ts + * import { validate } from "https://deno.land/std@$STD_VERSION/uuid/v1.ts"; + * + * validate("ea71fc60-a713-11ee-af61-8349da24f689"); // true + * validate("fac8c1e0-ad1a-4204-a0d0-8126ae84495d"); // false + * ``` + * * @param id UUID value. */ export function validate(id: string): boolean { @@ -20,18 +29,60 @@ let _clockseq: number; let _lastMSecs = 0; let _lastNSecs = 0; -/** The options used for generating a v1 UUID. */ +/** The options used for generating a v1 UUID in {@linkcode generate}. */ export interface V1Options { + /** + * An array of 6 bytes that represents a 48-bit IEEE 802 MAC address. + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4122#section-4.1.6} + */ node?: number[]; + /** + * A 14-bit value used to avoid duplicates that could arise when the clock is + * set backwards in time or if the node ID changes (0 - 16383). + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4122#section-4.1.5} + */ clockseq?: number; + /** + * The number of milliseconds since the Unix epoch (January 1, 1970). + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4122#section-4.1.4} + */ msecs?: number; + /** + * The number of nanoseconds to add to {@linkcode V1Options.msecs} + * (0 - 10,000). + * + * @see {@link https://www.rfc-editor.org/rfc/rfc4122#section-4.1.4} + */ nsecs?: number; + /** An array of 16 random bytes (0 - 255). */ random?: number[]; + /** + * A function that returns an array of 16 random bytes (0 - 255). + * Alternative to {@linkcode V1Options.random}. + */ rng?: () => number[]; } /** * Generates a RFC4122 v1 UUID (time-based). + * + * @example + * ```ts + * import { generate } from "https://deno.land/std@$STD_VERSION/uuid/v1.ts"; + * + * const options = { + * node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab], + * clockseq: 0x1234, + * msecs: new Date("2011-11-01").getTime(), + * nsecs: 5678, + * }; + * + * generate(options); // "710b962e-041c-11e1-9234-0123456789ab" + * ``` + * * @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. @@ -89,6 +140,9 @@ export function generate( _lastNSecs = nsecs; _clockseq = clockseq; + // We have to add this value because "msecs" here is the number of + // milliseconds since January 1, 1970, not since October 15, 1582. + // This is also the milliseconds from October 15, 1582 to January 1, 1970. msecs += 12219292800000; const tl = ((msecs & 0xfffffff) * 10000 + nsecs) % 0x100000000; diff --git a/uuid/v3.ts b/uuid/v3.ts index 8d4609c3d919..b089a095b782 100644 --- a/uuid/v3.ts +++ b/uuid/v3.ts @@ -14,9 +14,9 @@ const UUID_RE = * * @example * ```ts - * import { generate as generateV3, validate } from "https://deno.land/std@$STD_VERSION/uuid/v3.ts"; + * import { generate, validate } from "https://deno.land/std@$STD_VERSION/uuid/v3.ts"; * - * validate(await generateV3("6ba7b811-9dad-11d1-80b4-00c04fd430c8", new Uint8Array())); // true + * validate(await generate("6ba7b811-9dad-11d1-80b4-00c04fd430c8", new Uint8Array())); // true * validate(crypto.randomUUID()); // false * validate("this-is-not-a-uuid"); // false * ```