@smonn/ids 0.13.1 → 0.14.1

package/README.md

@@ -8,7 +8,7 @@ Public-facing branded IDs for TypeScript apps. Type-safe, sortable, and codec-pl
 pnpm add @smonn/ids
 ```
 
-Each ID looks like `usr_01h7b3k9rqxn4cw3p9r8t2sgkw`: a three-letter brand, an underscore, then 26 Crockford base32 characters of payload. The default Timestamp codec encodes a 48-bit millisecond Unix timestamp followed by 80 random bits — the same byte layout as a [ULID](https://github.com/ulid/spec).
+Each ID looks like `usr_06f80z92d2dbsqqg28t5cy4tqg`: a three-letter brand, an underscore, then 26 Crockford base32 characters of payload. The default Timestamp codec encodes a 48-bit millisecond Unix timestamp followed by 80 random bits — the same byte layout as a [ULID](https://github.com/ulid/spec).
 
 ## Quickstart
 
@@ -18,7 +18,7 @@ import { type Id, createTimestampId } from "@smonn/ids";
 const users = createTimestampId("usr");
 
 // Generate — sortable by creation time via ORDER BY id
-const id = users.generate(); // "usr_01h7b3k9rqxn4cw3p9r8t2sgkw"
+const id = users.generate(); // "usr_06f80z92d2dbsqqg28t5cy4tqg"
 
 // Branded: Id<"usr"> and Id<"org"> are not interchangeable
 function loadUser(id: Id<"usr">) {
@@ -26,9 +26,9 @@ function loadUser(id: Id<"usr">) {
 }
 
 // Validate untrusted input — lenient in, canonical out
-const r = users.safeParse("USR_01H7B3K9RQXN1CW3P9R8T2SGKW");
+const r = users.safeParse("USR_06F80Z92D2DBSQQG28T5CY4TQG");
 if (r.ok) {
-  r.id; // "usr_01h7b3k9rqxn1cw3p9r8t2sgkw" as Id<"usr">
+  r.id; // "usr_06f80z92d2dbsqqg28t5cy4tqg" as Id<"usr">
 }
 ```
 
@@ -68,10 +68,13 @@ Framework and ORM adapters ship as optional subpath exports (each requires its o
 
 Every codec also implements [Standard Schema v1](https://standardschema.dev/), so it slots into Zod, Valibot, ArkType, tRPC, and any validator-aware library.
 
+**Native `uuid` column storage:** an `Id<Brand>` can be persisted into a native `uuid` column via `codec.toUUID(id)` and read back as a branded ID via `codec.fromUUID(value)` or `codec.safeFromUUID(value)` — a lossless round-trip useful when migrating off UUID primary keys while keeping existing column types and indexes.
+
 ## What this is **not** for
 
 - **Internal surrogate primary keys.** If nobody outside your service sees the ID, the brand prefix and lenient parsing are dead weight. Use a `bigint` sequence.
 - **Wire-compatible ULIDs.** The byte layout is ULID-shaped, but the encoding is lowercase and brand-wrapped. Stock ULID parsers will reject these.
+- **Spec-valid UUIDv7 output.** `toUUID` produces a **raw, unversioned** UUID — all 128 payload bits are preserved verbatim (lossless round-trip), which means the version/variant nibble positions hold real data, not `0x7`/`0b10`. It is **not** a spec-valid UUIDv7. Only the Timestamp codec happens to produce a UUID whose leading 48 bits are a real millisecond timestamp; only Timestamp and Reverse Timestamp produce time-sortable UUIDs. Importing a non-time-ordered UUID (e.g. a UUIDv4) into a timestamp-family codec via `fromUUID` yields a structurally valid `Id<Brand>` with a meaningless timestamp and random sort order — the same wire-indistinguishable contract that already governs codec variants.
 - **Distributed-trace / request-correlation IDs.** Use OpenTelemetry-format IDs.
 - **Hiding creation time with the Timestamp codec.** Anyone with one ID at a known creation time can compute the epoch offset. Use the Opaque Timestamp codec to hide creation time per-ID.
 
@@ -82,7 +85,7 @@ Exports from the main `@smonn/ids` entry point only. Codec-specific subpath expo
 ### Types
 
 - `Id<Brand>` — Canonical branded ID string for `Brand`; produced by `generate()` and `safeParse()`.
-- `ParseError` — Parse failure reason string (`"not_string"`, `"invalid_prefix"`, or `"invalid_base32"`) returned by `safeParse()`.
+- `ParseError` — Parse failure reason string returned by `safeParse()` (`"not_string"`, `"invalid_prefix"`, or `"invalid_base32"`) and by `safeFromUUID()` (`"not_string"` or `"invalid_uuid"`).
 - `ParseResult<Brand>` — Discriminated union returned by `safeParse()`: `{ ok: true; id: Id<Brand> }` or `{ ok: false; error: ParseError }`.
 - `JsonSchema` — Shape of the object returned by a codec's `toJsonSchema()`.
 - `IdsErrorCode` — String-literal union of the eleven stable error codes carried by `IdsError`.
@@ -99,9 +102,18 @@ Exports from the main `@smonn/ids` entry point only. Codec-specific subpath expo
 - `isIdsError(value)` — Type guard for `IdsError`; uses an internal brand to survive ESM/CJS dual-package duplication where bare `instanceof` fails.
 - `createTimestampId(brand, options?)` — Creates a Timestamp codec for `brand` (three lowercase `a–z` characters).
 
+### Shared codec methods (all variants)
+
+Every codec instance exposes the following UUID interop methods in addition to the codec-specific ones documented on the [full docs site](https://ids.smonn.se):
+
+- `toUUID(id)` — Takes a trusted `Id<Brand>`, returns the 16-byte payload reinterpreted as a canonical lowercase-hyphenated UUID `string`. Total — cannot fail. The brand is shed; the output is a plain `string`, not a branded type.
+- `fromUUID(value)` — Takes an untrusted `string`, returns `Id<Brand>`. Throws `IdsError` (`code: "invalid_id"`) with a `ParseError` on `cause` (`"invalid_uuid"`, or `"not_string"` for untyped JavaScript callers) on malformed input.
+- `safeFromUUID(value)` — Takes `unknown`, returns `ParseResult<Brand>` (`{ ok: true; id }` or `{ ok: false; error: ParseError }`). Never throws.
+
 ## Links
 
 - **[Documentation](https://ids.smonn.se)** — full guides, API reference, and playground
+- **[SPEC.md](./SPEC.md)** — descriptive wire-format specification
 - **[Design decisions](./docs/adr/)** — recorded ADRs
 - **[CONTEXT.md](./CONTEXT.md)** — glossary of the project's vocabulary
 - **[Contributing](./CONTRIBUTING.md)** · **[Security](./SECURITY.md)**

package/dist/{adapter-types-CIc-4O-P.d.mts → adapter-types-Bia_w9sg.d.mts}

@@ -1,4 +1,4 @@
-import { i as ParseResult } from "./types-wplmOgOK.mjs";
+import { i as ParseResult } from "./types-hGBnCpJj.mjs";
 
 //#region src/adapters/adapter-types.d.ts
 /** Discriminated failure value passed to `onError` and emitted to the framework's error handler. */
@@ -17,4 +17,4 @@ type IdCodec<Brand extends string> = {
 type IdColumnCodec<Brand extends string> = IdCodec<Brand>;
 //#endregion
 export { IdColumnCodec as n, IdParamFailure as r, IdCodec as t };
-//# sourceMappingURL=adapter-types-CIc-4O-P.d.mts.map
+//# sourceMappingURL=adapter-types-Bia_w9sg.d.mts.map

package/dist/{adapter-types-CIc-4O-P.d.mts.map → adapter-types-Bia_w9sg.d.mts.map}

@@ -1 +1 @@
-{"version":3,"file":"adapter-types-CIc-4O-P.d.mts","names":[],"sources":["../src/adapters/adapter-types.ts"],"mappings":";;;;KAIY,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA;;KAGjC,OAAA;EACV,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;AADzC;AAAA,KAKY,aAAA,yBAAsC,OAAA,CAAQ,KAAA"}
+{"version":3,"file":"adapter-types-Bia_w9sg.d.mts","names":[],"sources":["../src/adapters/adapter-types.ts"],"mappings":";;;;KAIY,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA;;KAGjC,OAAA;EACV,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;AADzC;AAAA,KAKY,aAAA,yBAAsC,OAAA,CAAQ,KAAA"}

package/dist/cli.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { n as isIdsError } from "./error-Cp5qYZcv.mjs";
-import { t as createTimestampId } from "./timestamp-CleAIdZI.mjs";
-import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-BW3Uzeeb.mjs";
-import { t as createReverseTimestampId } from "./reverse-BW8g_cln.mjs";
-import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-BTz3ZFYE.mjs";
-import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-DPlsv1x-.mjs";
-import { i as importDigestKey, n as decodeDigestKey, r as encodeDigestKey, t as createDigestId } from "./digest-DsGeXfk3.mjs";
+import { t as createTimestampId } from "./timestamp-RXXwHfHO.mjs";
+import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-COAcIIY4.mjs";
+import { t as createReverseTimestampId } from "./reverse-CT-El3hi.mjs";
+import { i as importSigningKey, n as decodeSigningKey, r as encodeSigningKey, t as createSignedTimestampId } from "./signed-Dkdteu1y.mjs";
+import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-Oj2hC1vB.mjs";
+import { i as importDigestKey, n as decodeDigestKey, r as encodeDigestKey, t as createDigestId } from "./digest-CLJEGBxo.mjs";
 //#region src/cli/format.ts
 const invalidIdPrefix = "invalid_id: ";
 function formatCliError(err) {
@@ -17,6 +17,7 @@ function formatWrappedInspectOutput(result) {
 		`brand:      ${result.brand}`,
 		`lookup-key: ${result.lookupKey.toString()}`,
 		`canonical:  ${result.canonical}`,
+		`uuid:       ${result.uuid}`,
 		`input:      ${inputLine}`,
 		""
 	].join("\n");
@@ -26,7 +27,7 @@ function formatSignedInspectOutput(result) {
 	const inputLine = describeInputForm(result.input, result.canonical);
 	const lines = [`brand:     ${result.brand}`, `timestamp: ${result.timestamp.toISOString()} (${relative})`];
 	lines.push(`verification: ${result.verification}`);
-	lines.push(`canonical: ${result.canonical}`, `input:     ${inputLine}`, "");
+	lines.push(`canonical: ${result.canonical}`, `uuid:      ${result.uuid}`, `input:     ${inputLine}`, "");
 	return lines.join("\n");
 }
 function formatInspectOutput(result) {
@@ -36,6 +37,7 @@ function formatInspectOutput(result) {
 		`brand:     ${result.brand}`,
 		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
 		`canonical: ${result.canonical}`,
+		`uuid:      ${result.uuid}`,
 		`input:     ${inputLine}`,
 		""
 	].join("\n");
@@ -203,7 +205,10 @@ const knownFlags = /* @__PURE__ */ new Set([
 	"--key-format",
 	"--count",
 	"-c",
-	"--bits"
+	"--bits",
+	"--uuid",
+	"--from-uuid",
+	"--brand"
 ]);
 function unsupportedFlagForCommand(command, flags, allowed) {
 	for (const flag of flags) if (!allowed.has(flag)) return knownFlags.has(flag) ? `unsupported flag for ${command}: ${flag}` : `unsupported flag: ${flag}`;
@@ -396,6 +401,7 @@ const digestVariant = {
 			});
 			return {
 				safeParse: (v) => codec.safeParse(v),
+				toUUID: (id) => codec.toUUID(id),
 				async generate() {
 					const material = await (opts.readStdin ?? (() => Promise.resolve("")))();
 					return codec.digest(material);
@@ -421,7 +427,11 @@ const generatePolicy = {
 		signedVariant,
 		digestVariant
 	],
-	intrinsicFlags: ["--count", "-c"]
+	intrinsicFlags: [
+		"--count",
+		"-c",
+		"--uuid"
+	]
 };
 const inspectPolicy = {
 	default: timestampVariant,
@@ -431,7 +441,7 @@ const inspectPolicy = {
 		opaqueVariant,
 		signedVariant
 	],
-	intrinsicFlags: []
+	intrinsicFlags: ["--from-uuid", "--brand"]
 };
 const keygenPolicy = {
 	default: opaqueVariant,
@@ -493,8 +503,9 @@ async function buildCodec(variant, brand, values, opts) {
 function usageInspect() {
 	return [
 		"Usage: ids inspect, i <id> [--opaque] [--wrapped --kind u32|i32|u64|i64] [--reverse] [--signed] [--key-format hex|base64url]",
+		"       ids inspect --from-uuid <uuid> --brand <brand>",
 		"",
-		"  Decode an ID and print brand, timestamp (or lookup key), and canonical form.",
+		"  Decode an ID and print brand, timestamp (or lookup key), canonical form, and UUID.",
 		"  --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
 		"  --wrapped reads the wrapping key from IDS_WRAPPING_KEY (hex by default; IDS_WRAPPING_KEY_FORMAT or --key-format).",
 		"  --kind is required with --wrapped: u32, i32, u64, or i64.",
@@ -502,12 +513,14 @@ function usageInspect() {
 		"  --signed decodes a Signed Timestamp ID; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
 		"  Without IDS_SIGNING_KEY, --signed prints the timestamp only (no verification). With IDS_SIGNING_KEY, prints verification: ok or failed.",
 		"  Note: --digest is not supported for inspect (Digest IDs are one-way; there is no reverse path).",
+		"  --from-uuid <uuid> converts a UUID back to a canonical Id<Brand>. Requires --brand <brand>.",
+		"  --brand <brand> specifies the entity type brand for --from-uuid (e.g. usr).",
 		""
 	].join("\n");
 }
 function usageGenerate() {
 	return [
-		`Usage: ids generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--key-format hex|base64url]`,
+		`Usage: ids generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--uuid] [--key-format hex|base64url]`,
 		"",
 		`  Mint 1..${maxGenerateCount} canonical IDs for the given brand.`,
 		"  --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
@@ -518,6 +531,7 @@ function usageGenerate() {
 		"    Reads the digest key from IDS_DIGEST_KEY (hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
 		"    Same material + ns + key always produces the same ID. Digest IDs are one-way.",
 		"    --count N > 1 is rejected: same material always produces the same ID.",
+		"  --uuid emits the raw UUID form of each generated ID instead of the canonical ID.",
 		""
 	].join("\n");
 }
@@ -538,7 +552,8 @@ function usage() {
 		"",
 		"Subcommands:",
 		"  inspect, i <id> [--opaque] [--wrapped --kind u32|i32|u64|i64] [--reverse] [--signed] [--key-format hex|base64url]",
-		"    Decode an ID and print brand, timestamp (or lookup key), and canonical form.",
+		"  inspect, i --from-uuid <uuid> --brand <brand>",
+		"    Decode an ID and print brand, timestamp (or lookup key), canonical form, and UUID.",
 		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
 		"    --wrapped reads the wrapping key from IDS_WRAPPING_KEY (hex by default; IDS_WRAPPING_KEY_FORMAT or --key-format).",
 		"    --kind is required with --wrapped: u32, i32, u64, or i64.",
@@ -546,7 +561,9 @@ function usage() {
 		"    --signed decodes a Signed Timestamp ID; reads signing key from IDS_SIGNING_KEY (hex by default; IDS_SIGNING_KEY_FORMAT or --key-format).",
 		"    Without IDS_SIGNING_KEY, --signed prints the timestamp only (no verification). With IDS_SIGNING_KEY, prints verification: ok or failed.",
 		"    Note: --digest is not supported for inspect (Digest IDs are one-way; there is no reverse path).",
-		"  generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--key-format hex|base64url]",
+		"    --from-uuid <uuid> converts a UUID back to a canonical Id<Brand>. Requires --brand <brand>.",
+		"    --brand <brand> specifies the entity type brand for --from-uuid (e.g. usr).",
+		"  generate, g <brand> [--count, -c N] [--opaque] [--reverse] [--signed] [--digest --ns <ns>] [--uuid] [--key-format hex|base64url]",
 		`    Mint 1..${maxGenerateCount} canonical IDs for the given brand.`,
 		"    --opaque reads the AES key from IDS_KEY (hex by default; IDS_KEY_FORMAT or --key-format).",
 		"    --reverse mints Reverse Timestamp IDs (newest-first sort order).",
@@ -556,6 +573,7 @@ function usage() {
 		"      Reads the digest key from IDS_DIGEST_KEY (hex by default; IDS_DIGEST_KEY_FORMAT or --key-format).",
 		"      Same material + ns + key always produces the same ID. Digest IDs are one-way.",
 		"      --count N > 1 is rejected: same material always produces the same ID.",
+		"    --uuid emits the raw UUID form of each generated ID instead of the canonical ID.",
 		"  keygen, k [--wrapped] [--signed] [--digest] [--bits 128|192|256] [--key-format hex|base64url]",
 		"    Emit a random key for importOpaqueKey, importWrappingKey, importSigningKey, or importDigestKey (key on stdout; warning on stderr).",
 		"    Safe handling: redirect stdout to a 0600 file (e.g. ids keygen > key.hex && chmod 0600 key.hex);",
@@ -635,7 +653,14 @@ async function runGenerate(args, opts) {
 		opts.stderr(codec.message + "\n");
 		return codec.kind === "usage" ? 2 : 1;
 	}
-	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
+	const emitUuid = flags.has("--uuid");
+	for (let i = 0; i < count; i++) {
+		const id = await codec.generate();
+		if (emitUuid) {
+			const uuid = codec.toUUID(id);
+			opts.stdout(uuid + "\n");
+		} else opts.stdout(id + "\n");
+	}
 	return 0;
 }
 //#endregion
@@ -657,6 +682,32 @@ async function runInspect(args, opts) {
 		opts.stderr(errors[0] + "\n");
 		return 2;
 	}
+	const fromUuidValue = values.get("--from-uuid");
+	if (fromUuidValue !== void 0) {
+		if (fromUuidValue === "") {
+			opts.stderr("--from-uuid requires a value\n");
+			return 2;
+		}
+		const brandValue = values.get("--brand");
+		if (brandValue === void 0 || brandValue === "") {
+			opts.stderr("--from-uuid requires --brand\n");
+			return 2;
+		}
+		let tsCodec;
+		try {
+			tsCodec = createTimestampId(brandValue, codecOpts(opts));
+		} catch (err) {
+			opts.stderr(formatCliError(err) + "\n");
+			return 1;
+		}
+		const result = tsCodec.safeFromUUID(fromUuidValue);
+		if (!result.ok) {
+			opts.stderr("invalid_uuid: not a valid RFC 9562 UUID\n");
+			return 1;
+		}
+		opts.stdout(result.id + "\n");
+		return 0;
+	}
 	const [input] = positionals;
 	if (input === void 0) {
 		opts.stderr(usageInspect());
@@ -681,6 +732,7 @@ async function runInspect(args, opts) {
 	let verifyTimestamp;
 	let verifyCanonical;
 	let verifyNowMs;
+	let verifyTsCodec;
 	if (cap.mode === "verify") {
 		const fmtCheck = parseKeyFormat(values, opts, variant.key);
 		if (isKeyFormatError(fmtCheck)) {
@@ -699,6 +751,7 @@ async function runInspect(args, opts) {
 			opts.stderr(invalidIdPrefix + structValidation.issues[0].message + "\n");
 			return 1;
 		}
+		verifyTsCodec = tsCodec;
 		verifyCanonical = structValidation.value;
 		verifyTimestamp = tsCodec.extractTimestamp(verifyCanonical);
 		verifyNowMs = (opts.now ?? Date.now)();
@@ -706,10 +759,12 @@ async function runInspect(args, opts) {
 	const codecOrError = await buildCodec(variant, brand, values, opts);
 	if (isCodecError(codecOrError)) {
 		if (cap.mode === "verify") {
+			const uuid = verifyTsCodec.toUUID(verifyCanonical);
 			opts.stdout(formatSignedInspectOutput({
 				brand,
 				timestamp: verifyTimestamp,
 				canonical: verifyCanonical,
+				uuid,
 				input,
 				nowMs: verifyNowMs,
 				verification: "unavailable"
@@ -729,15 +784,20 @@ async function runInspect(args, opts) {
 		}
 		canonical = parsed.value;
 	}
+	function codecToUUID(id) {
+		return codecOrError.toUUID(id);
+	}
 	switch (cap.mode) {
 		case "readable": {
 			const timestamp = cap.extractTimestamp(codecOrError, canonical);
 			const nowMs = (opts.now ?? Date.now)();
+			const uuid = codecToUUID(canonical);
 			opts.stderr(cap.note + "\n");
 			opts.stdout(formatInspectOutput({
 				brand,
 				timestamp,
 				canonical,
+				uuid,
 				input,
 				nowMs
 			}));
@@ -746,11 +806,13 @@ async function runInspect(args, opts) {
 		case "keyed-readable": {
 			const timestamp = await cap.extractTimestamp(codecOrError, canonical);
 			const nowMs = (opts.now ?? Date.now)();
+			const uuid = codecToUUID(canonical);
 			opts.stderr(cap.note + "\n");
 			opts.stdout(formatInspectOutput({
 				brand,
 				timestamp,
 				canonical,
+				uuid,
 				input,
 				nowMs
 			}));
@@ -764,15 +826,18 @@ async function runInspect(args, opts) {
 				opts.stderr(formatCliError(err) + "\n");
 				return 1;
 			}
+			const uuid = codecToUUID(canonical);
 			opts.stdout(formatWrappedInspectOutput({
 				brand,
 				lookupKey,
 				canonical,
+				uuid,
 				input
 			}));
 			return 0;
 		}
 		case "verify": {
+			const uuid = verifyTsCodec.toUUID(verifyCanonical);
 			const verifyResult = await cap.safeVerify(codecOrError, input);
 			if (!verifyResult.ok) {
 				/* v8 ignore next 4 -- defensive: both codecs share the same wire parse so ParseError
@@ -785,6 +850,7 @@ async function runInspect(args, opts) {
 					brand,
 					timestamp: verifyTimestamp,
 					canonical: verifyCanonical,
+					uuid,
 					input,
 					nowMs: verifyNowMs,
 					verification: "failed"
@@ -796,6 +862,7 @@ async function runInspect(args, opts) {
 				brand,
 				timestamp: verifyTimestamp,
 				canonical: verifyResult.id,
+				uuid,
 				input,
 				nowMs: verifyNowMs,
 				verification: "ok"