@sdxc/uuid 2026.10.2 → 2026.10.11

package/README.md

@@ -1,6 +1,6 @@
 # @sdxc/uuid
 
-Validate, assert and generate UUIDs behind a branded UUID type.
+Validate and assert UUIDs behind a branded UUID type, and generate v4 or v7 values.
 
 A UUID reaches your code as a `string`, and every layer below re-checks it because the type
 says nothing. This package checks once and hands back a `UUID`: the same string, carrying
@@ -13,24 +13,38 @@ raw path segment it came from.
 npm add @sdxc/uuid
 ```
 
-`generateUUID` calls the platform's
-[`crypto.randomUUID()`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/randomUUID).
-[`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) installs alongside it when you
+The generators use the platform's Web Crypto API, available in browsers, Node, Bun, Deno and
+Cloudflare Workers. [`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) installs alongside it when you
 want prefixed identifiers built on these values.
 
 ## Usage
 
 ### Generate An Identifier
 
+Each UUID version is its own entry point, and each exports the same `generateUUID()`. The
+import path picks the version, so switching an identifier to the other one changes only that
+line.
+
+```typescript
+import { generateUUID } from "@sdxc/uuid/v7";
+
+let id = generateUUID();
+// "019a6f3e-5c21-7a4b-9d3e-8f1a2b3c4d5e" as UUID
+```
+
+A v7 value starts with the millisecond it was created, so identifiers sort in creation order
+and new database rows append to the end of their primary-key index. Import from
+`@sdxc/uuid/v4` instead when the identifier must not reveal when it was created:
+
 ```typescript
-import { generateUUID } from "@sdxc/uuid";
+import { generateUUID } from "@sdxc/uuid/v4";
 
 let id = generateUUID();
 // "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" as UUID
 ```
 
-The longhand is `crypto.randomUUID()` followed by the check that brands its result, which is
-what lets the value flow into anything typed as `UUID` without a cast.
+Either way the result is already branded, so it flows into anything typed as `UUID` without a
+cast.
 
 ### Narrow A String You Received
 
@@ -112,21 +126,23 @@ Narrows a string to `UUID` for the rest of the enclosing scope, throwing when it
 `InvalidUUIDTypeError` for a non-string, `InvalidUUIDLengthError` for a string that is not 36
 characters, and `InvalidUUIDFormatError` for 36 characters in the wrong shape.
 
-### `generateUUID(): UUID`
+### `generateUUID(): UUID` from `@sdxc/uuid/v7`
+
+Returns a new version 7 UUID as defined by [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562):
+a 48-bit millisecond timestamp, a 12-bit counter and 62 random bits. Values sort in the order
+they were generated, including several created in the same millisecond, which matters on
+runtimes such as Cloudflare Workers where `Date.now()` holds still until the next I/O. The
+guarantee holds within one process or isolate; values from two processes in the same
+millisecond are unique and share no defined order.
 
-Returns a new random UUID from `crypto.randomUUID()`, already narrowed to `UUID`. That is a
-version 4 UUID as defined by [RFC 9562](https://www.rfc-editor.org/rfc/rfc9562), random in
-every position the format leaves free — including when it was created, so two values carry
-no ordering.
+The timestamp is readable by anyone holding the value, including through a
+[`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) prefix. Use it for identifiers
+whose creation time is fine to expose, and keep secrets on random values.
 
-### `generateUUIDv7(): UUID`
+### `generateUUID(): UUID` from `@sdxc/uuid/v4`
 
-Returns a new version 7 UUID: a 48-bit millisecond timestamp followed by 74 random bits, so
-values sort the way they were created. Use this one where
-[`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) is going to prefix the result
-and something reads that prefixed id's order — a paginated listing, a table with no separate
-`created_at` to sort by. Reach for `generateUUID` instead when the id must not reveal when it
-was minted, such as a value handed to someone outside the system.
+Returns a new version 4 UUID from `crypto.randomUUID()`: 122 random bits, so two values carry
+no ordering and none reveals when it was created.
 
 ### Errors
 
@@ -198,7 +214,7 @@ takes a `UUID` and a prefix and encodes them as one sortable, self-describing st
 
 ```typescript
 import { TypeID } from "@sdxc/typeid";
-import { generateUUID } from "@sdxc/uuid";
+import { generateUUID } from "@sdxc/uuid/v7";
 
 let accountId = TypeID.fromUUID("account", generateUUID());
 
@@ -207,7 +223,8 @@ accountId.toString();
 ```
 
 It asks for a `UUID` rather than a `string`, so the value you generate here is accepted and a
-random 36 characters is not.
+random 36 characters is not. TypeID keeps the UUID's sort order, so a v7 identifier stays
+time-ordered once it is prefixed.
 
 ## Versioning
 

package/dist/index.d.ts

@@ -9,16 +9,4 @@ export type UUID = BaseUUID & {
 };
 export declare function isUUID(value: string): value is UUID;
 export declare function assertUUID(value: string): asserts value is UUID;
-export declare function generateUUID(): UUID;
-/**
- * Generates a UUID version 7: a 48-bit big-endian Unix millisecond timestamp
- * followed by 74 random bits, so values sort the way they were created without
- * a separate ordering column.
- *
- * @returns A UUIDv7, narrowed to {@link UUID}.
- * @example
- * let id = generateUUIDv7();
- * // "018f4d2e-...": sorts after a UUIDv7 minted a millisecond earlier
- */
-export declare function generateUUIDv7(): UUID;
 export { InvalidUUIDFormatError, InvalidUUIDLengthError, InvalidUUIDTypeError };

package/dist/index.js

@@ -21,38 +21,4 @@ export function assertUUID(value) {
         throw new InvalidUUIDFormatError(value);
     }
 }
-export function generateUUID() {
-    let id = crypto.randomUUID();
-    assertUUID(id);
-    return id;
-}
-/**
- * Generates a UUID version 7: a 48-bit big-endian Unix millisecond timestamp
- * followed by 74 random bits, so values sort the way they were created without
- * a separate ordering column.
- *
- * @returns A UUIDv7, narrowed to {@link UUID}.
- * @example
- * let id = generateUUIDv7();
- * // "018f4d2e-...": sorts after a UUIDv7 minted a millisecond earlier
- */
-export function generateUUIDv7() {
-    let timestamp = BigInt(Date.now());
-    let random = crypto.getRandomValues(new Uint8Array(10));
-    let bytes = new Uint8Array(16);
-    bytes[0] = Number((timestamp >> 40n) & 0xffn);
-    bytes[1] = Number((timestamp >> 32n) & 0xffn);
-    bytes[2] = Number((timestamp >> 24n) & 0xffn);
-    bytes[3] = Number((timestamp >> 16n) & 0xffn);
-    bytes[4] = Number((timestamp >> 8n) & 0xffn);
-    bytes[5] = Number(timestamp & 0xffn);
-    bytes[6] = 0x70 | (random[0] & 0x0f);
-    bytes[7] = random[1];
-    bytes[8] = 0x80 | (random[2] & 0x3f);
-    bytes.set(random.subarray(3), 9);
-    let hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
-    let id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-    assertUUID(id);
-    return id;
-}
 export { InvalidUUIDFormatError, InvalidUUIDLengthError, InvalidUUIDTypeError };

package/dist/v4.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Random UUID generation: version 4 values from the platform's `crypto.randomUUID()`,
+ * narrowed to the branded `UUID` type. Every free bit is random, so a value reveals nothing,
+ * including when it was created.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { UUID } from "./index.js";
+/**
+ * Generates a version 4 UUID: 122 random bits, so values carry no ordering and expose no
+ * creation time.
+ *
+ * @returns A UUIDv4, narrowed to {@link UUID}.
+ * @example
+ * let id = generateUUID();
+ * // "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ */
+export declare function generateUUID(): UUID;

package/dist/v4.js

@@ -0,0 +1,23 @@
+/**
+ * Random UUID generation: version 4 values from the platform's `crypto.randomUUID()`,
+ * narrowed to the branded `UUID` type. Every free bit is random, so a value reveals nothing,
+ * including when it was created.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { assertUUID } from "./index.js";
+/**
+ * Generates a version 4 UUID: 122 random bits, so values carry no ordering and expose no
+ * creation time.
+ *
+ * @returns A UUIDv4, narrowed to {@link UUID}.
+ * @example
+ * let id = generateUUID();
+ * // "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ */
+export function generateUUID() {
+    let id = crypto.randomUUID();
+    assertUUID(id);
+    return id;
+}

package/dist/v7.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Time-ordered UUID generation: version 7 values whose string order follows the order they
+ * were generated in, including several in the same millisecond, so primary keys append to
+ * their index and an id alone can page a listing.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import type { UUID } from "./index.js";
+/**
+ * Generates a version 7 UUID (RFC 9562): a 48-bit Unix millisecond timestamp, a 12-bit
+ * counter that increments within a millisecond, and 62 random bits. Each value sorts after
+ * the previous one from the same isolate, even while `Date.now()` stays put.
+ *
+ * @returns A UUIDv7, narrowed to {@link UUID}.
+ * @example
+ * let first = generateUUID();
+ * let second = generateUUID();
+ * first < second; // true
+ */
+export declare function generateUUID(): UUID;

package/dist/v7.js

@@ -0,0 +1,83 @@
+/**
+ * Time-ordered UUID generation: version 7 values whose string order follows the order they
+ * were generated in, including several in the same millisecond, so primary keys append to
+ * their index and an id alone can page a listing.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { assertUUID } from "./index.js";
+/** Largest value the 12-bit `rand_a` counter holds before the timestamp has to advance. */
+const COUNTER_MAX = 0xfff;
+/**
+ * The last timestamp written and the counter beside it, shared by every call in the isolate.
+ * Keeping the timestamp from going backwards is what makes each value sort after the last.
+ */
+const CLOCK = { timestamp: -1, counter: 0 };
+/**
+ * Generates a version 7 UUID (RFC 9562): a 48-bit Unix millisecond timestamp, a 12-bit
+ * counter that increments within a millisecond, and 62 random bits. Each value sorts after
+ * the previous one from the same isolate, even while `Date.now()` stays put.
+ *
+ * @returns A UUIDv7, narrowed to {@link UUID}.
+ * @example
+ * let first = generateUUID();
+ * let second = generateUUID();
+ * first < second; // true
+ */
+export function generateUUID() {
+    advance(Date.now());
+    let random = crypto.getRandomValues(new Uint8Array(8));
+    let bytes = new Uint8Array(16);
+    let timestamp = CLOCK.timestamp;
+    for (let index = 5; index >= 0; index--) {
+        bytes[index] = timestamp % 256;
+        timestamp = Math.floor(timestamp / 256);
+    }
+    bytes[6] = 0x70 | (CLOCK.counter >> 8);
+    bytes[7] = CLOCK.counter & 0xff;
+    bytes[8] = 0x80 | (random[0] & 0x3f);
+    bytes.set(random.subarray(1), 9);
+    let id = format(bytes);
+    assertUUID(id);
+    return id;
+}
+/**
+ * Moves the clock to `now`, or past the last timestamp when `now` is not later than it.
+ * A new millisecond seeds the counter randomly below its midpoint, leaving at least 2048
+ * increments; exhausting them moves the timestamp one millisecond ahead, as RFC 9562 allows.
+ *
+ * @param now Current Unix time in milliseconds.
+ */
+function advance(now) {
+    if (now > CLOCK.timestamp) {
+        CLOCK.timestamp = now;
+        CLOCK.counter = seed();
+        return;
+    }
+    CLOCK.counter++;
+    if (CLOCK.counter <= COUNTER_MAX)
+        return;
+    CLOCK.timestamp++;
+    CLOCK.counter = seed();
+}
+/**
+ * Picks a random starting counter with its top bit clear, so the first value of a
+ * millisecond is unpredictable and still leaves half the counter's range to increment into.
+ *
+ * @returns An integer in `[0, 0x7ff]`.
+ */
+function seed() {
+    let [value] = crypto.getRandomValues(new Uint16Array(1));
+    return value & 0x7ff;
+}
+/**
+ * Writes 16 bytes as the canonical lowercase `8-4-4-4-12` UUID string.
+ *
+ * @param bytes The UUID's bytes in network order.
+ * @returns The hyphenated hex form.
+ */
+function format(bytes) {
+    let hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}

package/package.json

@@ -1,13 +1,15 @@
 {
 	"name": "@sdxc/uuid",
-	"version": "2026.10.2",
-	"description": "Validate, assert and generate UUIDs behind a branded UUID type",
+	"version": "2026.10.11",
+	"description": "Validate and assert UUIDs behind a branded UUID type, and generate v4 or v7 values",
 	"license": "MIT",
 	"type": "module",
 	"exports": {
-		".": "./dist/index.js"
+		".": "./dist/index.js",
+		"./v4": "./dist/v4.js",
+		"./v7": "./dist/v7.js"
 	},
-	"gitHead": "7582e46f150b052ba145945661ac9937f5f26f27",
+	"gitHead": "6ac77f0839a66981ca666a16f5cf37a5473df2b1",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -15,5 +17,14 @@
 		"type": "git",
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/uuid"
+	},
+	"homepage": "https://sdxc.sergiodxa.com/api/uuid",
+	"author": {
+		"name": "Sergio Xalambrí",
+		"url": "https://sergiodxa.com"
+	},
+	"funding": {
+		"type": "github",
+		"url": "https://github.com/sponsors/sergiodxa"
 	}
 }