feat(uuid): implement support for UUID V6 - refs #6414

Author: ancoron

_tools/check_mod_exports.ts

@@ -50,9 +50,11 @@ for await (
         /uuid(\/|\\)v3\.ts$/,
         /uuid(\/|\\)v4\.ts$/,
         /uuid(\/|\\)v5\.ts$/,
+        /uuid(\/|\\)v6\.ts$/,
         /uuid(\/|\\)v7\.ts$/,
         /yaml(\/|\\)schema\.ts$/,
         /test\.ts$/,
+        /_bench\.ts$/,
         /\.d\.ts$/,
         /(\/|\\)_/,
         /mod\.ts$/,

uuid/common.ts

@@ -41,7 +41,7 @@ export function isNil(id: string): boolean {
  * ```
  */
 export function validate(uuid: string): boolean {
-  return /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i
+  return /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-6][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000)$/i
     .test(
       uuid,
     );

uuid/common_test.ts

@@ -23,6 +23,7 @@ Deno.test("version() detects the RFC version of a UUID", () => {
   assertEquals(version("109156be-c4fb-41ea-b1b4-efe1671c5836"), 4);
   assertEquals(version("a981a0c2-68b1-35dc-bcfc-296e52ab01ec"), 3);
   assertEquals(version("90123e1c-7512-523e-bb28-76fab9f2f73d"), 5);
+  assertEquals(version("1efed817-4119-6c50-974a-e638d7b30e9e"), 6);
   assertThrows(() => version(""));
   assertThrows(() => version("not a UUID"));
   assertThrows(() => version("00000000000000000000000000000000"));

uuid/deno.json

@@ -9,6 +9,7 @@
     "./v3": "./v3.ts",
     "./v4": "./v4.ts",
     "./v5": "./v5.ts",
+    "./unstable-v6": "./unstable_v6.ts",
     "./unstable-v7": "./unstable_v7.ts"
   }
 }

uuid/mod.ts

@@ -4,7 +4,7 @@
 /**
  * Generators and validators for
  * {@link https://www.rfc-editor.org/rfc/rfc9562.html | RFC 9562} UUIDs for
- * versions v1, v3, v4 and v5.
+ * versions v1, v3, v4, v5 and v6.
  *
  * Use the built-in
  * {@linkcode https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID | crypto.randomUUID()}

uuid/unstable_v6.ts

@@ -0,0 +1,178 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+// This module is browser compatible.
+
+import { bytesToUuid } from "./_common.ts";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-6[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/**
+ * Determines whether a string is a valid
+ * {@link https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-6 | UUIDv6}.
+ *
+ * @param id UUID value.
+ *
+ * @returns `true` if the string is a valid UUIDv6, otherwise `false`.
+ *
+ * @example Usage
+ * ```ts
+ * import { validate } from "@std/uuid/unstable-v6";
+ * import { assert, assertFalse } from "@std/assert";
+ *
+ * assert(validate("1efed67d-d966-6490-8b9a-755015853480"));
+ * assertFalse(validate("1efed67d-d966-1490-8b9a-755015853480"));
+ * ```
+ */
+export function validate(id: string): boolean {
+  return UUID_RE.test(id);
+}
+
+let _nodeId: number[];
+let _clockseq: number;
+
+let _lastMSecs = 0;
+let _lastNSecs = 0;
+
+/** Options for {@linkcode generate}. */
+export interface GenerateOptions {
+  /**
+   * 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 GenerateOptions.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 GenerateOptions.random}.
+   */
+  rng?: () => number[];
+}
+
+/**
+ * Generates a
+ * {@link https://www.rfc-editor.org/rfc/rfc9562.html#name-uuid-version-6 | UUIDv6}.
+ *
+ * @param options Can use RFC time sequence values as overwrites.
+ *
+ * @returns Returns a UUIDv6 string.
+ *
+ * @example Usage
+ * ```ts
+ * import { generate, validate } from "@std/uuid/unstable-v6";
+ * import { assert } from "@std/assert";
+ *
+ * const options = {
+ *   node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
+ *   clockseq: 0x1234,
+ *   msecs: new Date("2011-11-01").getTime(),
+ *   nsecs: 5678,
+ * };
+ *
+ * const uuid = generate(options);
+ * assert(validate(uuid as string));
+ * ```
+ */
+export function generate(options: GenerateOptions = {}): string {
+  let i = 0;
+  const b: number[] = [];
+
+  let { node = _nodeId, clockseq = _clockseq } = options;
+
+  if (node === undefined || clockseq === undefined) {
+    // deno-lint-ignore no-explicit-any
+    const seedBytes: any = options.random ??
+      options.rng ??
+      crypto.getRandomValues(new Uint8Array(16));
+
+    if (node === undefined) {
+      node = _nodeId = [
+        seedBytes[0] | 0x01,
+        seedBytes[1],
+        seedBytes[2],
+        seedBytes[3],
+        seedBytes[4],
+        seedBytes[5],
+      ];
+    }
+
+    if (clockseq === undefined) {
+      clockseq = _clockseq = ((seedBytes[6] << 8) | seedBytes[7]) & 0x3fff;
+    }
+  }
+
+  let { msecs = new Date().getTime(), nsecs = _lastNSecs + 1 } = options;
+
+  const dt = msecs - _lastMSecs + (nsecs - _lastNSecs) / 10000;
+
+  if (dt < 0 && options.clockseq === undefined) {
+    clockseq = (clockseq + 1) & 0x3fff;
+  }
+
+  if ((dt < 0 || msecs > _lastMSecs) && options.nsecs === undefined) {
+    nsecs = 0;
+  }
+
+  if (nsecs > 10000) {
+    throw new Error("Can't create more than 10M uuids/sec");
+  }
+
+  if (node.length !== 6) {
+    throw new Error(
+      "Cannot create UUID: the node option must be an array of 6 bytes",
+    );
+  }
+
+  _lastMSecs = msecs;
+  _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 th = ((msecs / 0x10000000) * 10000) & 0xffffffff;
+  b[i++] = (th >>> 24) & 0xff;
+  b[i++] = (th >>> 16) & 0xff;
+  b[i++] = (th >>> 8) & 0xff;
+  b[i++] = th & 0xff;
+
+  const tml = ((msecs & 0xfffffff) * 10000 + nsecs) % 0x10000000;
+  b[i++] = (tml >>> 20) & 0xff;
+  b[i++] = (tml >>> 12) & 0xff;
+
+  b[i++] = (tml >>> 8) & 0xf | 0x60;
+  b[i++] = tml & 0xff;
+
+  b[i++] = (clockseq >>> 8) | 0x80;
+
+  b[i++] = clockseq & 0xff;
+
+  for (let n = 0; n < 6; ++n) {
+    b[i + n] = node[n]!;
+  }
+
+  return bytesToUuid(b);
+}

uuid/unstable_v6_test.ts

@@ -0,0 +1,74 @@
+// Copyright 2018-2025 the Deno authors. MIT license.
+import { assert, assertEquals, assertThrows } from "@std/assert";
+import { generate, validate } from "./unstable_v6.ts";
+
+Deno.test("validate() checks if a string is a valid v6 UUID", () => {
+  const u = generate();
+  const t = "1efed67d-d966-6490-8b9a-755015853480";
+  const n = "1efed67d-d966-1490-8b9a-755015853480";
+
+  assert(validate(u as string), `generated ${u} should be valid`);
+  assert(validate(t), `${t} should be valid`);
+  assert(!validate(n), `${n} should not be valid`);
+});
+
+Deno.test("generate() generates a non-empty string", () => {
+  const u1 = generate();
+  const u2 = generate({
+    msecs: new Date("2011-11-01").getTime(),
+    nsecs: 10000,
+  });
+
+  assertEquals(typeof u1, "string", "returns a string");
+  assert(u1 !== "", "return string is not empty");
+  assertEquals(typeof u2, "string", "returns a string");
+  assert(u2 !== "", "return string is not empty");
+});
+
+Deno.test("generate() generates UUIDs in version 6 format", () => {
+  for (let i = 0; i < 10000; i++) {
+    const u = generate() as string;
+    assert(validate(u), `${u} is not a valid uuid v6`);
+  }
+});
+
+Deno.test("generate() can generate a static v6 UUID", () => {
+  const v6options = {
+    node: [0x01, 0x23, 0x45, 0x67, 0x89, 0xab],
+    clockseq: 0x385c,
+    msecs: new Date("2011-11-18T21:25:33.573+00:00").getTime(),
+    nsecs: 5442,
+  };
+  const u = generate(v6options);
+  assertEquals(u, "1e1122bd-9428-6892-b85c-0123456789ab");
+});
+
+Deno.test("generate() throws when node is passed with less than 6 numbers", () => {
+  assertThrows(
+    () => {
+      generate({ node: [0x01, 0x23, 0x45, 0x67, 0x89] });
+    },
+    Error,
+    "Cannot create UUID: the node option must be an array of 6 bytes",
+  );
+});
+
+Deno.test("generate() throws when node is passed with more than 6 numbers", () => {
+  assertThrows(
+    () => {
+      generate({ node: [0x01, 0x23, 0x45, 0x67, 0x89, 0x89, 0x89] });
+    },
+    Error,
+    "Cannot create UUID: the node option must be an array of 6 bytes",
+  );
+});
+
+Deno.test("generate() throws when create more than 10M uuids/sec", () => {
+  assertThrows(
+    () => {
+      generate({ nsecs: 10001 });
+    },
+    Error,
+    "Can't create more than 10M uuids/sec",
+  );
+});