@sdxc/uuid 2026.10.13 → 2026.11.3

package/README.md

@@ -79,6 +79,24 @@ try {
 }
 ```
 
+## Command line
+
+`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.
+
+`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.
+
+```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`
@@ -91,6 +109,10 @@ Accepts exactly the values `assertUUID` accepts.
 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 version 7 UUID ([RFC 9562](https://www.rfc-editor.org/rfc/rfc9562)): a 48-bit
@@ -98,6 +120,10 @@ millisecond timestamp, a 12-bit counter and 62 random bits. Each value sorts aft
 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`
+
+Returns the Unix millisecond timestamp a v7 UUID was generated at.
+
 ### `generateUUID(): UUID` from `@sdxc/uuid/v4`
 
 Returns a version 4 UUID from `crypto.randomUUID()`: 122 random bits, with no ordering and no

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.13",
+	"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": "5ff758a57e35480a8db7abd24f1d9527b81bfb51",
+	"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"