@sdxc/uuid 2026.9.14 → 2026.9.23

package/README.md

@@ -116,7 +116,17 @@ characters, and `InvalidUUIDFormatError` for 36 characters in the wrong shape.
 
 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.
+every position the format leaves free — including when it was created, so two values carry
+no ordering.
+
+### `generateUUIDv7(): UUID`
+
+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.
 
 ### Errors
 

package/dist/index.d.ts

@@ -10,4 +10,15 @@ 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

@@ -26,4 +26,33 @@ export function generateUUID() {
     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/package.json

@@ -1,13 +1,13 @@
 {
 	"name": "@sdxc/uuid",
-	"version": "2026.9.14",
+	"version": "2026.9.23",
 	"description": "Validate, assert and generate UUIDs behind a branded UUID type",
 	"license": "MIT",
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js"
 	},
-	"gitHead": "069de2cb44985d682e160f9f4e72b06394b9a239",
+	"gitHead": "00c5691b2e444a348956d1879ab676b07d3f9c8f",
 	"publishConfig": {
 		"access": "public"
 	},