@sdxc/uuid 2026.10.12 → 2026.11.3

package/README.md

@@ -2,51 +2,43 @@
 
 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
-proof of the check in its type, so a function that asks for a `UUID` cannot be handed the
-raw path segment it came from.
+A `UUID` is the same string, carrying proof of the check in its type: validate once where the
+value enters, and every function below can ask for a `UUID` instead of re-checking a `string`.
 
 ## Installation
 
-```bash
+```sh
 npm add @sdxc/uuid
 ```
 
 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.
+Cloudflare Workers.
 
 ## Usage
 
-### Generate An Identifier
+### 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.
+Each UUID version is its own entry point exporting the same `generateUUID()`, so the import
+path picks the version.
 
 ```typescript
 import { generateUUID } from "@sdxc/uuid/v7";
 
 let id = generateUUID();
-// "019a6f3e-5c21-7a4b-9d3e-8f1a2b3c4d5e" as UUID
+// "019a6f3e-5c21-7a4b-9d3e-8f1a2b3c4d5e", typed 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:
+A v7 value starts with its creation time, so values sort in the order they were generated.
+Import from `@sdxc/uuid/v4` for a fully random value that reveals nothing:
 
 ```typescript
 import { generateUUID } from "@sdxc/uuid/v4";
 
 let id = generateUUID();
-// "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d" as UUID
+// "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d", typed UUID
 ```
 
-Either way the result is already branded, so it flows into anything typed as `UUID` without a
-cast.
-
-### Narrow A String You Received
+### Check a string you received
 
 ```typescript
 import { isUUID } from "@sdxc/uuid";
@@ -58,26 +50,12 @@ if (isUUID(value)) {
 }
 ```
 
-A value passes when it is a string of exactly 36 characters shaped `8-4-4-4-12` in lowercase
-hex. Uppercase and the brace-wrapped form both fail, so the identifiers you store and compare
-have one spelling. The version and variant digits are read as hex like any other, so the
-check is about the format rather than which UUID version produced it.
-
-### Assert At A Boundary
+A UUID is exactly 36 characters of lowercase hex shaped `8-4-4-4-12`, so stored identifiers
+have one spelling. Any version passes.
 
-```typescript
-import { assertUUID } from "@sdxc/uuid";
+### Assert and tell the failures apart
 
-function readAccountId(value: string) {
-	assertUUID(value);
-	return value; // typed UUID from here on
-}
-```
-
-`assertUUID` throws rather than returning, which suits the edge of a system: the value is an
-identifier or the request stops here.
-
-### Tell The Failures Apart
+`assertUUID` narrows the value for the rest of the scope, or throws one of three error classes.
 
 ```typescript
 import {
@@ -89,128 +67,168 @@ import {
 
 try {
 	assertUUID(value);
+	// value is UUID from here on
 } catch (error) {
 	if (error instanceof InvalidUUIDTypeError) {
-		// something other than a string arrived
-	}
-
-	if (error instanceof InvalidUUIDLengthError) {
-		// a string of the wrong length: "Invalid UUID length: 10"
-	}
-
-	if (error instanceof InvalidUUIDFormatError) {
+		// not a string: "Expected a string, got object"
+	} else if (error instanceof InvalidUUIDLengthError) {
+		// wrong length: "Invalid UUID length: 10"
+	} else if (error instanceof InvalidUUIDFormatError) {
 		// 36 characters in the wrong shape
 	}
 }
 ```
 
-Three classes rather than one message, so a truncated identifier and a mistyped one are
-distinguishable when you decide what to answer.
+## Command line
 
-## API
+`sdxc-uuid` generates and checks UUIDs from a terminal or a script, with no install step:
+
+```sh
+bunx @sdxc/uuid --help
+```
+
+With [`@sdxc/kit`](https://www.npmjs.com/package/@sdxc/kit) installed, `sdxc pkg uuid …` runs the same command line, using the version your project installs.
 
-### `UUID`
+`validate` reads the UUID from its argument, or stdin when it is `-` or absent, prints its version and, for v7, its creation time, and exits 1 when the value is invalid. `--json` prints the result as data.
 
-The UUID string type, branded. A plain `string` is not assignable to it, and a `UUID` is
-assignable anywhere a `string` is, so the brand costs nothing at the call sites that only
-read the value.
+```sh
+bunx @sdxc/uuid v4 -n 5
+bunx @sdxc/uuid v7 -n 1000 > ids.txt
+bunx @sdxc/uuid validate 019a6f3e-5c21-7a4b-9d3e-8f1a2b3c4d5e --json
+```
+
+## API
 
 ### `isUUID(value: string): value is UUID`
 
-Reports whether a string is a UUID, narrowing it to `UUID` inside the branch that takes it.
-Use it where an invalid value is an outcome you handle.
+Returns `true` when the value is a lowercase `8-4-4-4-12` hex string, narrowing it to `UUID`.
+Accepts exactly the values `assertUUID` accepts.
 
 ### `assertUUID(value: string): asserts value is UUID`
 
-Narrows a string to `UUID` for the rest of the enclosing scope, throwing when it is not one:
-`InvalidUUIDTypeError` for a non-string, `InvalidUUIDLengthError` for a string that is not 36
-characters, and `InvalidUUIDFormatError` for 36 characters in the wrong shape.
+Narrows the value to `UUID`, or throws `InvalidUUIDTypeError` for a non-string,
+`InvalidUUIDLengthError` for a length other than 36, and `InvalidUUIDFormatError` otherwise.
+
+### `getVersion(id: UUID): number`
+
+Returns the version the UUID declares, such as `4` or `7`.
 
 ### `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 version 7 UUID ([RFC 9562](https://www.rfc-editor.org/rfc/rfc9562)): a 48-bit
+millisecond timestamp, a 12-bit counter and 62 random bits. Each value sorts after the previous
+one from the same process, including within one millisecond. Anyone holding the value can read
+its creation time.
+
+### `getTimestamp(id: UUID): number` from `@sdxc/uuid/v7`
 
-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.
+Returns the Unix millisecond timestamp a v7 UUID was generated at.
 
 ### `generateUUID(): UUID` from `@sdxc/uuid/v4`
 
-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.
+Returns a version 4 UUID from `crypto.randomUUID()`: 122 random bits, with no ordering and no
+creation time.
 
-### Errors
+### `InvalidUUIDTypeError`
 
-#### `InvalidUUIDTypeError`
+Thrown for a non-string; the message names the type received.
 
-Validation received something that is not a string. The message names the runtime type that
-arrived, as in `Expected a string, got object`.
+### `InvalidUUIDLengthError`
 
-#### `InvalidUUIDLengthError`
+Thrown for a string that is not 36 characters; the message names the length.
 
-A string of the wrong length, reported as `Invalid UUID length: 10`. The check runs before
-the shape check, so a truncated identifier says so instead of reading as malformed.
+### `InvalidUUIDFormatError`
 
-#### `InvalidUUIDFormatError`
+Thrown for 36 characters that are not lowercase `8-4-4-4-12` hex; the message repeats the value.
 
-A 36-character string that is not lowercase `8-4-4-4-12` hex. The message repeats the value
-that failed, as in `Invalid UUID format: 550e8400_e29b_41d4_a716_446655440000`.
+### Types
 
-## Pattern: Narrowing Once At The Edge
+#### `UUID`
 
-An identifier arrives as text — a path segment, a query parameter, a form field — and every
-function under the handler wants it typed. Assert it where it enters, and the signatures
-below can ask for a `UUID` and be sure they have one:
+A branded UUID string. A plain `string` must pass `isUUID` or `assertUUID` to become one, and a
+`UUID` is usable anywhere a `string` is.
+
+## Pattern: Narrow Once At The Edge
+
+Assert an identifier where it enters a request handler, and the functions below take a `UUID`
+without re-validating.
 
 ```typescript
 import type { UUID } from "@sdxc/uuid";
 
-import { assertUUID } from "@sdxc/uuid";
+import { assertUUID, InvalidUUIDLengthError, InvalidUUIDFormatError } from "@sdxc/uuid";
 
-export async function GET(request: Request) {
+export async function handler(request: Request) {
 	let accountId = new URL(request.url).pathname.split("/").at(-1) ?? "";
-	assertUUID(accountId);
+
+	try {
+		assertUUID(accountId);
+	} catch (error) {
+		if (error instanceof InvalidUUIDLengthError || error instanceof InvalidUUIDFormatError) {
+			return new Response("Not Found", { status: 404 });
+		}
+		throw error;
+	}
 
 	return Response.json(await loadAccount(accountId));
 }
 
 async function loadAccount(accountId: UUID) {
-	// no re-validation: the type already carries the check
+	return { id: accountId };
 }
 ```
 
-The throw is the point: an identifier that never validated never reaches the query.
-
-## Pattern: Branching Instead Of Throwing
+## Pattern: Validate A Form Field Without Throwing
 
-A form field is a value a person can get wrong, which makes an exception the wrong shape for
-the answer. `isUUID` gives you the same narrowing in an expression you can branch on:
+A person can mistype a field, so branch on `isUUID` and answer with a result.
 
 ```typescript
 import type { UUID } from "@sdxc/uuid";
 
 import { isUUID } from "@sdxc/uuid";
 
-function readAccountId(input: FormData): { ok: true; accountId: UUID } | { ok: false } {
-	let value = input.get("accountId");
+function readAccountId(form: FormData): { ok: true; accountId: UUID } | { ok: false } {
+	let value = form.get("accountId");
 	if (typeof value !== "string" || !isUUID(value)) return { ok: false };
 	return { ok: true, accountId: value };
 }
 ```
 
-`isUUID` is `assertUUID` with the throw turned into a `false`, so the two agree on exactly
-which strings are identifiers.
+## Pattern: Time-Ordered Record Ids
+
+Use v7 for primary keys: new rows append to the end of the index, and sorting by id sorts by
+creation, so the last id of a page is enough of a cursor for the next one.
+
+```typescript
+import type { UUID } from "@sdxc/uuid";
+
+import { generateUUID } from "@sdxc/uuid/v7";
+
+interface Note {
+	id: UUID;
+	body: string;
+}
+
+let notes: Note[] = [];
+
+function createNote(body: string): Note {
+	let note = { id: generateUUID(), body };
+	notes.push(note);
+	return note;
+}
+
+function notesAfter(cursor: UUID | null, limit: number) {
+	return notes.filter((note) => cursor === null || note.id > cursor).slice(0, limit);
+}
+```
+
+Reach for `@sdxc/uuid/v4` when an identifier must not reveal when it was created, such as a
+public share id.
 
 ## Pattern: Prefixed Identifiers
 
-A UUID says nothing about what it identifies, which is why an identifier pasted into a bug
-report is so hard to place. [`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid)
-takes a `UUID` and a prefix and encodes them as one sortable, self-describing string:
+[`@sdxc/typeid`](https://www.npmjs.com/package/@sdxc/typeid) takes a `UUID` and a prefix and
+encodes them as one self-describing string that keeps the v7 sort order.
 
 ```typescript
 import { TypeID } from "@sdxc/typeid";
@@ -222,10 +240,6 @@ accountId.toString();
 // "account_01h455vb4pex5vsknk084sn02q"
 ```
 
-It asks for a `UUID` rather than a `string`, so the value you generate here is accepted and a
-random 36 characters is not. TypeID keeps the UUID's sort order, so a v7 identifier stays
-time-ordered once it is prefixed.
-
 ## Versioning
 
 Releases are dated rather than semantic. A version is the UTC date it was published,

package/dist/cli-contract.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The `sdxc-uuid` command line as a contract: `v4` and `v7` generate identifiers, `validate`
+ * checks one and reports its version. Help, usage errors and each handler's typed `ctx.flags`
+ * come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Every command `sdxc-uuid` takes. */
+export declare const UUID_COMMANDS: import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-uuid — generate and validate UUIDs";
+    readonly v4: import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+        readonly count: import("@sdxc/cli").ValueFlag<number, true, false, false>;
+    }>;
+    readonly v7: import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+        readonly count: import("@sdxc/cli").ValueFlag<number, true, false, false>;
+    }>;
+    readonly validate: import("@sdxc/cli").Command<{
+        readonly uuid: import("@sdxc/cli").Argument<string | undefined>;
+    }, {
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+}, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>;

package/dist/cli-contract.js

@@ -0,0 +1,59 @@
+/**
+ * The `sdxc-uuid` command line as a contract: `v4` and `v7` generate identifiers, `validate`
+ * checks one and reports its version. Help, usage errors and each handler's typed `ctx.flags`
+ * come from this one declaration.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { argument, command, commands, flag } from "@sdxc/cli";
+import * as s from "remix/data-schema";
+/** The most identifiers one run prints, so a typo in `-n` cannot flood a terminal. */
+const MAX_COUNT = 100_000;
+/**
+ * A count from 1 to {@link MAX_COUNT}, written as digits only, so `+8`, `8.0` and `0x8` are
+ * usage errors.
+ */
+function count() {
+    return s.createSchema(function validate(value, context) {
+        if (typeof value === "string" && /^\d+$/.test(value)) {
+            let parsed = Number(value);
+            if (parsed >= 1 && parsed <= MAX_COUNT)
+                return { value: parsed };
+        }
+        return s.fail(`expects an integer from 1 to ${MAX_COUNT}; got ${JSON.stringify(value)}`, context.path);
+    });
+}
+/** The `-n` flag both generators take: how many identifiers to print, one per line. */
+const COUNT = flag.string("count", {
+    short: "n",
+    valueName: "N",
+    default: 1,
+    schema: count(),
+    description: "How many to print, one per line",
+});
+/** Every command `sdxc-uuid` takes. */
+export const UUID_COMMANDS = commands({
+    description: "sdxc-uuid — generate and validate UUIDs",
+    v4: command({
+        description: "Print random version 4 UUIDs, which reveal nothing about when they were made.",
+        flags: { count: COUNT },
+        examples: ["v4", "v4 -n 5"],
+    }),
+    v7: command({
+        description: "Print time-ordered version 7 UUIDs; each sorts after the one before, within a millisecond too.",
+        flags: { count: COUNT },
+        examples: ["v7", "v7 -n 1000 > ids.txt"],
+    }),
+    validate: command({
+        description: "Check a UUID is lowercase 8-4-4-4-12 hex and print its version, plus its creation time for v7. Exits 1 when it is invalid.",
+        arguments: {
+            uuid: argument(s.string(), {
+                optional: true,
+                description: "The UUID to check; stdin when it is - or absent",
+            }),
+        },
+        flags: { json: flag.boolean("json", { description: "Print the result as JSON" }) },
+        examples: ["validate 019a6f3e-5c21-7a4b-9d3e-8f1a2b3c4d5e", "validate --json < id.txt"],
+    }),
+});

package/dist/cli-v4.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `sdxc-uuid v4` handler: prints random version 4 UUIDs from the package's own generator,
+ * one per line, for ids that must not reveal when they were created.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Prints `--count` values, each on its own line. */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+    readonly count: import("@sdxc/cli").ValueFlag<number, true, false, false>;
+}>, []>;
+export default _default;

package/dist/cli-v4.js

@@ -0,0 +1,16 @@
+/**
+ * The `sdxc-uuid v4` handler: prints random version 4 UUIDs from the package's own generator,
+ * one per line, for ids that must not reveal when they were created.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, success } from "@sdxc/cli";
+import { UUID_COMMANDS } from "./cli-contract.js";
+import { generateUUID } from "./v4.js";
+/** Prints `--count` values, each on its own line. */
+export default createCommand(UUID_COMMANDS.v4, (ctx) => {
+    let ids = Array.from({ length: ctx.flags.count }, () => generateUUID());
+    ctx.stdout(`${ids.join("\n")}\n`);
+    return success();
+});

package/dist/cli-v7.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `sdxc-uuid v7` handler: prints time-ordered version 7 UUIDs, one per line, in the order
+ * they sort, so a batch can seed a table or fixture already in index order.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** Prints `--count` values, each on its own line and each sorting after the line above. */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+    readonly count: import("@sdxc/cli").ValueFlag<number, true, false, false>;
+}>, []>;
+export default _default;

package/dist/cli-v7.js

@@ -0,0 +1,16 @@
+/**
+ * The `sdxc-uuid v7` handler: prints time-ordered version 7 UUIDs, one per line, in the order
+ * they sort, so a batch can seed a table or fixture already in index order.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, success } from "@sdxc/cli";
+import { UUID_COMMANDS } from "./cli-contract.js";
+import { generateUUID } from "./v7.js";
+/** Prints `--count` values, each on its own line and each sorting after the line above. */
+export default createCommand(UUID_COMMANDS.v7, (ctx) => {
+    let ids = Array.from({ length: ctx.flags.count }, () => generateUUID());
+    ctx.stdout(`${ids.join("\n")}\n`);
+    return success();
+});

package/dist/cli-validate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The `sdxc-uuid validate` handler: checks one UUID from an argument or stdin with the
+ * package's `assertUUID`, and reports its version and, for v7, the time it was generated.
+ * An invalid value exits 1 with the reason, so a script can branch on the exit code.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/**
+ * Prints `valid`, the version and the v7 creation time, or `invalid` and the reason; `--json`
+ * prints `{ valid, uuid, version, timestamp? }` or `{ valid, uuid, error }`. Stdin loses one
+ * trailing line ending, so `echo $ID |` checks the id itself.
+ */
+declare const _default: import("@sdxc/cli").CommandAction<import("@sdxc/cli").Command<{
+    readonly uuid: import("@sdxc/cli").Argument<string | undefined>;
+}, {
+    readonly json: import("@sdxc/cli").Flag<boolean>;
+}>, []>;
+export default _default;

package/dist/cli-validate.js

@@ -0,0 +1,48 @@
+/**
+ * The `sdxc-uuid validate` handler: checks one UUID from an argument or stdin with the
+ * package's `assertUUID`, and reports its version and, for v7, the time it was generated.
+ * An invalid value exits 1 with the reason, so a script can branch on the exit code.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCommand, exit, success, usage } from "@sdxc/cli";
+import { isFailure, wrap } from "@sdxc/result";
+import { UUID_COMMANDS } from "./cli-contract.js";
+import { getTimestamp } from "./v7.js";
+import { assertUUID, getVersion } from "./index.js";
+/**
+ * Prints `valid`, the version and the v7 creation time, or `invalid` and the reason; `--json`
+ * prints `{ valid, uuid, version, timestamp? }` or `{ valid, uuid, error }`. Stdin loses one
+ * trailing line ending, so `echo $ID |` checks the id itself.
+ */
+export default createCommand(UUID_COMMANDS.validate, async (ctx) => {
+    let value = ctx.arguments.uuid ?? "-";
+    if (value === "-") {
+        if (ctx.stdin.isTTY)
+            return usage("Pass a UUID, or pipe one on stdin");
+        value = (await ctx.stdin.text()).replace(/\r?\n$/, "");
+    }
+    let checked = wrap(() => {
+        assertUUID(value);
+        return value;
+    });
+    if (isFailure(checked)) {
+        ctx.stdout(ctx.flags.json
+            ? `${JSON.stringify({ valid: false, uuid: value, error: checked.error.message })}\n`
+            : `invalid: ${checked.error.message}\n`);
+        return exit(1);
+    }
+    let uuid = checked.data;
+    let version = getVersion(uuid);
+    let timestamp = version === 7 ? new Date(getTimestamp(uuid)).toISOString() : undefined;
+    if (ctx.flags.json) {
+        ctx.stdout(`${JSON.stringify({ valid: true, uuid, version, timestamp })}\n`);
+        return success();
+    }
+    let lines = ["valid", `version ${version}`];
+    if (timestamp !== undefined)
+        lines.push(`timestamp ${timestamp}`);
+    ctx.stdout(`${lines.join("\n")}\n`);
+    return success();
+});

package/dist/cli.d.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-uuid` command-line program: the contract in `cli-contract.ts` with each command
+ * mapped onto its handler, loaded only when that command runs. Exit codes: 0 done, 1 the UUID
+ * is invalid, 2 usage or unreadable input.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+/** The `sdxc-uuid` program, run by the bin entry below and by tests through `invoke()`. */
+export declare const cli: import("@sdxc/cli").CLI<import("@sdxc/cli").Group<Omit<{
+    readonly description: "sdxc-uuid — generate and validate UUIDs";
+    readonly v4: import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+        readonly count: import("@sdxc/cli").ValueFlag<number, true, false, false>;
+    }>;
+    readonly v7: import("@sdxc/cli").Command<Readonly<Record<string, import("@sdxc/cli").Argument<unknown>>>, {
+        readonly count: import("@sdxc/cli").ValueFlag<number, true, false, false>;
+    }>;
+    readonly validate: import("@sdxc/cli").Command<{
+        readonly uuid: import("@sdxc/cli").Argument<string | undefined>;
+    }, {
+        readonly json: import("@sdxc/cli").Flag<boolean>;
+    }>;
+}, "description" | "hidden" | "arguments" | "flags" | "tasks">, Record<never, never>, Record<never, never>>, []>;

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * The `sdxc-uuid` command-line program: the contract in `cli-contract.ts` with each command
+ * mapped onto its handler, loaded only when that command runs. Exit codes: 0 done, 1 the UUID
+ * is invalid, 2 usage or unreadable input.
+ *
+ * @author [Sergio Xalambrí](https://sergiodxa.com)
+ * @copyright Sergio Xalambrí 2026
+ */
+import { createCLI, lazy } from "@sdxc/cli";
+import { UUID_COMMANDS } from "./cli-contract.js";
+/** The `sdxc-uuid` program, run by the bin entry below and by tests through `invoke()`. */
+export const cli = createCLI({ name: "sdxc-uuid", commands: UUID_COMMANDS });
+cli.map(UUID_COMMANDS.v4, lazy(() => import("./cli-v4.js")));
+cli.map(UUID_COMMANDS.v7, lazy(() => import("./cli-v7.js")));
+cli.map(UUID_COMMANDS.validate, lazy(() => import("./cli-validate.js")));
+if (import.meta.main) {
+    process.exit(await cli.run(process.argv.slice(2)));
+}

package/dist/index.d.ts

@@ -9,4 +9,14 @@ export type UUID = BaseUUID & {
 };
 export declare function isUUID(value: string): value is UUID;
 export declare function assertUUID(value: string): asserts value is UUID;
+/**
+ * The version a UUID declares in its 13th hex digit, so a caller can tell a time-ordered v7
+ * from a random v4 before reading any version-specific field.
+ *
+ * @param id - A validated UUID
+ * @returns The version number, 0 to 15.
+ * @example
+ * getVersion(generateUUID()); // 7, from "@sdxc/uuid/v7"
+ */
+export declare function getVersion(id: UUID): number;
 export { InvalidUUIDFormatError, InvalidUUIDLengthError, InvalidUUIDTypeError };

package/dist/index.js

@@ -21,4 +21,16 @@ export function assertUUID(value) {
         throw new InvalidUUIDFormatError(value);
     }
 }
+/**
+ * The version a UUID declares in its 13th hex digit, so a caller can tell a time-ordered v7
+ * from a random v4 before reading any version-specific field.
+ *
+ * @param id - A validated UUID
+ * @returns The version number, 0 to 15.
+ * @example
+ * getVersion(generateUUID()); // 7, from "@sdxc/uuid/v7"
+ */
+export function getVersion(id) {
+    return Number.parseInt(id[14], 16);
+}
 export { InvalidUUIDFormatError, InvalidUUIDLengthError, InvalidUUIDTypeError };

package/dist/v7.d.ts

@@ -19,3 +19,14 @@ import type { UUID } from "./index.js";
  * first < second; // true
  */
 export declare function generateUUID(): UUID;
+/**
+ * The Unix millisecond timestamp a version 7 UUID starts with: the moment it was generated.
+ * The first 48 bits carry it for v7 only, so check `getVersion` first for a UUID of
+ * unknown origin.
+ *
+ * @param id - A version 7 UUID
+ * @returns Milliseconds since the Unix epoch.
+ * @example
+ * new Date(getTimestamp(generateUUID())); // now
+ */
+export declare function getTimestamp(id: UUID): number;

package/dist/v7.js

@@ -42,6 +42,19 @@ export function generateUUID() {
     assertUUID(id);
     return id;
 }
+/**
+ * The Unix millisecond timestamp a version 7 UUID starts with: the moment it was generated.
+ * The first 48 bits carry it for v7 only, so check `getVersion` first for a UUID of
+ * unknown origin.
+ *
+ * @param id - A version 7 UUID
+ * @returns Milliseconds since the Unix epoch.
+ * @example
+ * new Date(getTimestamp(generateUUID())); // now
+ */
+export function getTimestamp(id) {
+    return Number.parseInt(id.slice(0, 8) + id.slice(9, 13), 16);
+}
 /**
  * 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

package/package.json

@@ -1,15 +1,23 @@
 {
 	"name": "@sdxc/uuid",
-	"version": "2026.10.12",
+	"version": "2026.11.3",
 	"description": "Validate and assert UUIDs behind a branded UUID type, and generate v4 or v7 values",
 	"license": "MIT",
+	"bin": {
+		"sdxc-uuid": "dist/cli.js"
+	},
 	"type": "module",
 	"exports": {
 		".": "./dist/index.js",
 		"./v4": "./dist/v4.js",
 		"./v7": "./dist/v7.js"
 	},
-	"gitHead": "857ef87ddb0b2484e28b46431d0740fcc80e5f33",
+	"dependencies": {
+		"@sdxc/cli": "2026.11.3",
+		"@sdxc/result": "2026.10.13",
+		"remix": "3.1.0"
+	},
+	"gitHead": "d1dd4030f8df68b8a170940a3f790ea8654d3676",
 	"publishConfig": {
 		"access": "public"
 	},
@@ -18,7 +26,7 @@
 		"url": "git+https://github.com/sergiodxa/monorepo.git",
 		"directory": "packages/uuid"
 	},
-	"homepage": "https://sdxc.sergiodxa.com/api/uuid",
+	"homepage": "https://sdxc.dev/api/uuid",
 	"author": {
 		"name": "Sergio Xalambrí",
 		"url": "https://sergiodxa.com"