mirror of
https://github.com/denoland/std.git
synced 2024-11-21 20:50:22 +00:00
docs(uuid): complete documentation (#4044)
* chore(uuid): complete documentation * fmt * tweaks * further tweaks * tweak --------- Co-authored-by: Asher Gomez <ashersaupingomez@gmail.com>
This commit is contained in:
David Luis
GitHub
parent
58e6675467
commit
328e3d2a88
44
uuid/mod.ts
44
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 };
|
||||
|
||||
56
uuid/v1.ts
56
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;
|
||||
|
||||
@ -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
|
||||
* ```
|
||||
|
||||
Loading…
Reference in New Issue
Block a user