Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(uuid): complete documentation #4044

Merged
merged 5 commits into from
Dec 30, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 23 additions & 21 deletions uuid/mod.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
*
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -74,5 +78,3 @@ export function version(uuid: string): number {

return parseInt(uuid[14], 16);
}

export { v1, v3, v4, v5 };
56 changes: 55 additions & 1 deletion uuid/v1.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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.
Expand Down Expand Up @@ -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;
Expand Down
4 changes: 2 additions & 2 deletions uuid/v3.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
* ```
Expand Down