Deno/std
1
0
Fork 0
mirror of https://github.com/denoland/std.git synced 2024-11-21 20:50:22 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Marvin Hagemeister 2024-05-29 07:47:42 +02:00 committed by GitHub
parent bce7d8e38b
commit 999e5e7a97
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
10 changed files with 230 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
_tools/check_docs.ts
View File

@ -47,6 +47,7 @@ const ENTRY_POINTS = [
"../streams/mod.ts",
"../text/mod.ts",
"../ulid/mod.ts",
"../uuid/mod.ts",
"../webgpu/mod.ts",
] as const;

4
_tools/check_mod_exports.ts
View File

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

2
deno.json
View File

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

38
uuid/common.ts
View File

@ -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 {

20
uuid/constants.ts
View File

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

104
uuid/mod.ts
View File

@ -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,
};

45
uuid/v1.ts
View File

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

44
uuid/v3.ts
View File

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

16
uuid/v4.ts
View File

@ -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(

44
uuid/v5.ts
View File

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