@smonn/ids 0.6.0 → 0.7.0

package/README.md

@@ -70,6 +70,48 @@ const userId = r.id; // Id<"usr">, canonical
 
 `ParseError` is exported as a literal union so the switch is exhaustive at compile time.
 
+### "Handle structured errors from this library"
+
+`parse()`, `unwrap()`, the ORM adapter read paths, and the codec constructors all throw `IdsError` on failure — a single class with a stable `code` field for programmatic branching. Use `isIdsError()` to safely identify them without depending on `instanceof` across module copies:
+
+```ts
+import { isIdsError } from "@smonn/ids";
+
+try {
+  users.parse(rawInput);
+} catch (err) {
+  if (isIdsError(err)) {
+    switch (err.code) {
+      case "invalid_id": // parse failed; err.cause is the ParseError string
+        return 400;
+      case "invalid_brand": // bad codec construction — fix the brand string
+        throw err;
+      // ...
+    }
+  }
+  throw err;
+}
+```
+
+**Error codes** (`IdsErrorCode` — stable contract; `message` is non-contractual):
+
+| `code`                    | meaning                                         | thrown by                                                 | remedy                                     |
+| ------------------------- | ----------------------------------------------- | --------------------------------------------------------- | ------------------------------------------ |
+| `invalid_brand`           | brand is not three lowercase `a–z` characters   | `create*Id(brand)` construction                           | Fix the brand string                       |
+| `invalid_key_format`      | format is not `hex` or `base64url`              | `decodeOpaqueKey`, `decodeWrappingKey`                    | Pass `"hex"` or `"base64url"`              |
+| `invalid_key_encoding`    | key string is malformed for its declared format | `decodeOpaqueKey`, `decodeWrappingKey`                    | Re-encode the key with the matching format |
+| `invalid_key_length`      | raw key is not 16, 24, or 32 bytes              | `importOpaqueKey`, `importWrappingKey`, decoder functions | Use a valid AES key size                   |
+| `invalid_kind`            | wrapped kind is not `u32`/`i32`/`u64`/`i64`     | `createWrappedKeyId({ kind })`                            | Use one of the four supported kinds        |
+| `empty_keyring`           | the wrapping keyring is empty                   | `createWrappedKeyId({ keys })`                            | Supply at least one `WrappingKey`          |
+| `duplicate_keyring_entry` | two keyring entries share the same raw secret   | `createWrappedKeyId({ keys })`                            | Deduplicate the key list                   |
+| `invalid_lookup_key`      | lookup key is out of range or the wrong JS type | `wrap(lookupKey)`                                         | Check the kind's range and JS type         |
+| `verification_failed`     | no keyring entry verifies the payload tag       | `unwrap(id)`                                              | Check keyring; tamper or wrong key         |
+| `invalid_id`              | string is not a valid ID for this brand         | `parse()`, ORM adapter read paths                         | Use `safeParse()` for untrusted input      |
+
+`invalid_id` carries the originating `ParseError` string on `cause` — check `err.cause` for `"not_string"`, `"invalid_prefix"`, or `"invalid_base32"` when you need to distinguish the failure mode.
+
+`isIdsError()` uses a non-enumerable brand symbol rather than bare `instanceof`, so it works correctly even when multiple copies of `@smonn/ids` are loaded in the same process (the ESM + CJS dual-package hazard).
+
 ### "Sort and date-stamp records using just the ID"
 
 The first 6 bytes of the payload are a big-endian millisecond Unix timestamp, so `ORDER BY id` sorts by creation time without a separate `created_at` column. To extract the timestamp from an existing ID:
@@ -260,6 +302,71 @@ app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } })
 
 The 400 vs 404 defaults are identical to the Hono adapter: `reason: "brand_mismatch"` → 404, `reason: "malformed"` → 400. The canonical `Id<Brand>` is stored in `res.locals` under `paramName` and available to downstream handlers.
 
+### "Validate a route param in Fastify"
+
+`@smonn/ids/fastify` provides the same `idParam` factory for Fastify. Fastify is an **optional peer dependency**; install it separately alongside `@smonn/ids`.
+
+```bash
+pnpm add fastify
+```
+
+```ts
+import { idParam, IdParamError } from "@smonn/ids/fastify";
+import { createTimestampId } from "@smonn/ids";
+
+const usr = createTimestampId("usr");
+
+// Default: throws IdParamError → setErrorHandler renders it
+fastify.get<{ Params: { id: string } }>(
+  "/users/:id",
+  {
+    preHandler: idParam("id", usr),
+  },
+  (request, reply) => {
+    const id = request.params.id; // string; use `as Id<"usr">` if the narrowed type is needed
+    // …
+  },
+);
+
+// Error handler receives the typed error
+fastify.setErrorHandler((err, request, reply) => {
+  if (err instanceof IdParamError) {
+    reply.status(err.statusCode).send({ error: err.reason });
+    return;
+  }
+  reply.send(err);
+});
+
+// Override: consumer fully owns the error response
+fastify.get(
+  "/orgs/:id",
+  {
+    preHandler: idParam("id", org, {
+      onError: (failure, request, reply) =>
+        reply.status(failure.status).send({ error: failure.reason }),
+    }),
+  },
+  handler,
+);
+
+// Or a lightweight status remap without a full handler
+fastify.get(
+  "/things/:id",
+  {
+    preHandler: idParam("id", thing, { status: { brand_mismatch: 400 } }),
+  },
+  handler,
+);
+```
+
+**Default error-channel behavior:** on failure the adapter throws `IdParamError` carrying `statusCode` and `reason` — it does **not** write a response body itself. Fastify's `setErrorHandler` receives the error and controls rendering exactly as it would for any other error.
+
+**`options.onError`:** when provided, the hook owns the response entirely — the adapter does not throw.
+
+**`options.status`:** remaps the default HTTP status for a failure reason without requiring a full handler.
+
+The 400 vs 404 defaults are identical to the Hono and Express adapters: `reason: "brand_mismatch"` → 404, `reason: "malformed"` → 400. The canonical `Id<Brand>` is stored in `request.params` under `paramName`. Works with any codec variant's structural `safeParse`.
+
 ### "Don't leak creation time in IDs that customers can see"
 
 The Timestamp codec exposes the creation timestamp by design — that's what makes `ORDER BY id` work. If that's a leak you can't accept (invoice IDs revealing billing cadence, signup IDs revealing acquisition velocity), use the Opaque Timestamp codec at `@smonn/ids/opaque`. Same `<brand>_<26 chars>` wire shape, but the payload is AES-encrypted under a key you supply.
@@ -336,6 +443,9 @@ No key material is required. The inversion is a deterministic byte transform; `g
 
 ```ts
 import {
+  IdsError, // class — thrown by caller-reachable failures; carries a stable `code`
+  isIdsError, // (value: unknown) => value is IdsError — brand check, survives dual-package
+  type IdsErrorCode, // "invalid_brand" | "invalid_key_format" | ... (10 members)
   createTimestampId, // (brand: string, opts?: TimestampOptions) => TimestampCodec<Brand>
   type Id, // branded string type
   type TimestampCodec, // returned by createTimestampId
@@ -346,6 +456,9 @@ import {
 } from "@smonn/ids";
 
 import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
   createOpaqueTimestampId, // (brand: string, opts: OpaqueTimestampOptions) => OpaqueTimestampCodec<Brand>
   importOpaqueKey, // (bytes: Uint8Array) => Promise<OpaqueKey>
   encodeOpaqueKey, // (bytes: Uint8Array, format: OpaqueKeyFormat) => string
@@ -357,12 +470,29 @@ import {
 } from "@smonn/ids/opaque";
 
 import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
   createReverseTimestampId, // (brand: string, opts?: ReverseTimestampOptions) => ReverseTimestampCodec<Brand>
   type ReverseTimestampCodec, // returned by createReverseTimestampId
   type ReverseTimestampOptions, // { now?, rng?, allowDuplicateBrand? } constructor options
 } from "@smonn/ids/reverse";
 
 import {
+  importSigningKey, // (bytes: Uint8Array) => Promise<SigningKey>
+  encodeSigningKey, // (bytes: Uint8Array, format: SigningKeyFormat) => string
+  decodeSigningKey, // (encoded: string, format: SigningKeyFormat) => Uint8Array
+  IdsError, // re-exported from @smonn/ids/signed for convenience
+  isIdsError, // re-exported from @smonn/ids/signed for convenience
+  type SigningKey, // opaque SigningKey handle (HKDF-derived)
+  type SigningKeyFormat, // "hex" | "base64url"
+  type IdsErrorCode, // re-exported from @smonn/ids/signed for convenience
+} from "@smonn/ids/signed";
+
+import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
   createWrappedKeyId, // (brand: string, opts: { kind: "u32" | "i32" | "u64" | "i64", keys }) => WrappedKeyCodec<Brand, Kind>
   importWrappingKey, // (bytes: Uint8Array) => Promise<WrappingKey>
   encodeWrappingKey, // (bytes: Uint8Array, format: WrappingKeyFormat) => string
@@ -373,16 +503,31 @@ import {
 } from "@smonn/ids/wrapped";
 
 import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
   idColumn, // (codec: IdColumnCodec<Brand>) => PgCustomColumnBuilder (Drizzle column)
   type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
 } from "@smonn/ids/drizzle";
 
 import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
   idField, // (codec: IdColumnCodec<Brand>) => IdTransform<Brand> — read/write transforms for Prisma $extends
   type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
   type IdTransform, // { read(value: unknown): Id<Brand>; write(value: Id<Brand>): string }
 } from "@smonn/ids/prisma";
 
+import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
+  idColumn, // (codec: IdColumnCodec<Brand>) => { toDriver, fromDriver }
+  type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
+  type IdColumnType, // ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>
+} from "@smonn/ids/kysely";
+
 import {
   idParam, // (paramName: string, codec, options?) => Hono MiddlewareHandler — throws HTTPException by default; onError/status options override
   type IdParamFailure, // { reason: "brand_mismatch" | "malformed"; status: number }
@@ -395,6 +540,13 @@ import {
   type IdParamFailure, // { reason: "brand_mismatch" | "malformed"; status: number }
   type IdParamOptions, // { onError?, status? }
 } from "@smonn/ids/express";
+
+import {
+  idParam, // (paramName: string, codec, options?) => Fastify preHandler — throws IdParamError by default; onError/status options override
+  IdParamError, // Error subclass with .reason and .statusCode — thrown into setErrorHandler by default
+  type IdParamFailure, // { reason: "brand_mismatch" | "malformed"; status: number }
+  type IdParamOptions, // { onError?, status? }
+} from "@smonn/ids/fastify";
 ```
 
 `@smonn/ids/wrapped` ships the Wrapped key codec for `u32`, `i32`, `u64`, and `i64` lookup keys. `wrap(lookupKey)` returns a public ID; `unwrap(id)` verifies the payload and returns the lookup key; `safeUnwrap(input)` is the non-throwing path for untrusted input.
@@ -576,6 +728,9 @@ const id = usrCol.fromDriver(row.id as unknown as string);
 
 ```ts
 import {
+  IdsError, // re-exported for convenience — same class as "@smonn/ids"
+  isIdsError, // re-exported for convenience — same guard as "@smonn/ids"
+  type IdsErrorCode, // re-exported for convenience — same union as "@smonn/ids"
   idColumn, // (codec: IdColumnCodec<Brand>) => { toDriver, fromDriver }
   type IdColumnCodec, // { safeParse(value: unknown): ParseResult<Brand> }
   type IdColumnType, // ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>

package/dist/adapter-types-oHCCSgOO.d.mts

@@ -0,0 +1,12 @@
+//#region src/adapter-types.d.ts
+/** Discriminated failure value passed to `onError` and emitted to the framework's error handler. */
+type IdParamFailure = {
+  readonly reason: "brand_mismatch";
+  readonly status: number;
+} | {
+  readonly reason: "malformed";
+  readonly status: number;
+};
+//#endregion
+export { IdParamFailure as t };
+//# sourceMappingURL=adapter-types-oHCCSgOO.d.mts.map

package/dist/adapter-types-oHCCSgOO.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-types-oHCCSgOO.d.mts","names":[],"sources":["../src/adapter-types.ts"],"mappings":";;KACY,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA"}

package/dist/cli.mjs

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { t as createTimestampId } from "./timestamp-Bgzxx8bE.mjs";
-import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-goLnFoo7.mjs";
-import { t as createReverseTimestampId } from "./reverse--n4D2yxu.mjs";
-import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-Dw5mHQhn.mjs";
+import { n as isIdsError } from "./error-Cp5qYZcv.mjs";
+import { t as createTimestampId } from "./timestamp-B5_UCzc6.mjs";
+import { i as importOpaqueKey, n as decodeOpaqueKey, r as encodeOpaqueKey, t as createOpaqueTimestampId } from "./opaque-uvjOFY_0.mjs";
+import { t as createReverseTimestampId } from "./reverse-BgFU6JHw.mjs";
+import { i as importWrappingKey, n as decodeWrappingKey, r as encodeWrappingKey, t as createWrappedKeyId } from "./wrapped-0vL72Nje.mjs";
 //#region src/cli/codec-options.ts
 function codecOpts(opts) {
 	const o = { allowDuplicateBrand: true };
@@ -11,6 +12,65 @@ function codecOpts(opts) {
 	return o;
 }
 //#endregion
+//#region src/cli/format.ts
+function formatCliError(err) {
+	return isIdsError(err) ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
+}
+function formatWrappedInspectOutput(result) {
+	const inputLine = describeInputForm(result.input, result.canonical);
+	return [
+		`brand:      ${result.brand}`,
+		`lookup-key: ${result.lookupKey.toString()}`,
+		`canonical:  ${result.canonical}`,
+		`input:      ${inputLine}`,
+		""
+	].join("\n");
+}
+function formatInspectOutput(result) {
+	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
+	const inputLine = describeInputForm(result.input, result.canonical);
+	return [
+		`brand:     ${result.brand}`,
+		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
+		`canonical: ${result.canonical}`,
+		`input:     ${inputLine}`,
+		""
+	].join("\n");
+}
+function describeInputForm(input, canonical) {
+	if (input === canonical) return "canonical";
+	const notes = [];
+	if (input !== input.toLowerCase()) notes.push("was uppercase");
+	if (/[ilo]/i.test(input.slice(4))) notes.push("used Crockford aliases");
+	return `not canonical (${notes.join(" + ")})`;
+}
+const msPerMinute = 60 * 1e3;
+const msPerHour = 60 * msPerMinute;
+const msPerDay = 24 * msPerHour;
+const daysPerMonth = 30.44;
+const monthsPerYear = 12;
+function formatRelative(thenMs, nowMs) {
+	const diff = nowMs - thenMs;
+	const abs = Math.abs(diff);
+	const suffix = diff < 0 ? "from now" : "ago";
+	const head = headUnits(abs);
+	return head === "" ? "just now" : `${head} ${suffix}`;
+}
+function headUnits(abs) {
+	if (abs < msPerMinute) return "";
+	if (abs < msPerHour) return unit(Math.round(abs / msPerMinute), "minute");
+	if (abs < msPerDay) return unit(Math.round(abs / msPerHour), "hour");
+	if (abs < msPerDay * daysPerMonth) return unit(Math.round(abs / msPerDay), "day");
+	const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));
+	if (totalMonths < monthsPerYear) return unit(totalMonths, "month");
+	const years = Math.floor(totalMonths / monthsPerYear);
+	const months = totalMonths % monthsPerYear;
+	return months === 0 ? unit(years, "year") : `${unit(years, "year")} ${unit(months, "month")}`;
+}
+function unit(n, name) {
+	return `${n} ${n === 1 ? name : `${name}s`}`;
+}
+//#endregion
 //#region src/cli/constants.ts
 const maxGenerateCount = 1e4;
 //#endregion
@@ -215,7 +275,7 @@ function runGenerate(args, opts) {
 		try {
 			codec = createReverseTimestampId(brand ?? "", codecOpts(opts));
 		} catch (err) {
-			opts.stderr(err.message + "\n");
+			opts.stderr(formatCliError(err) + "\n");
 			return Promise.resolve(1);
 		}
 		for (let i = 0; i < count; i++) opts.stdout(codec.generate() + "\n");
@@ -225,7 +285,7 @@ function runGenerate(args, opts) {
 	try {
 		codec = createTimestampId(brand ?? "", codecOpts(opts));
 	} catch (err) {
-		opts.stderr(err.message + "\n");
+		opts.stderr(formatCliError(err) + "\n");
 		return Promise.resolve(1);
 	}
 	for (let i = 0; i < count; i++) opts.stdout(codec.generate() + "\n");
@@ -244,69 +304,13 @@ async function runOpaqueGenerate(brand, count, format, opts) {
 			...codecOpts(opts)
 		});
 	} catch (err) {
-		opts.stderr(err.message + "\n");
+		opts.stderr(formatCliError(err) + "\n");
 		return 1;
 	}
 	for (let i = 0; i < count; i++) opts.stdout(await codec.generate() + "\n");
 	return 0;
 }
 //#endregion
-//#region src/cli/format.ts
-function formatWrappedInspectOutput(result) {
-	const inputLine = describeInputForm(result.input, result.canonical);
-	return [
-		`brand:      ${result.brand}`,
-		`lookup-key: ${result.lookupKey.toString()}`,
-		`canonical:  ${result.canonical}`,
-		`input:      ${inputLine}`,
-		""
-	].join("\n");
-}
-function formatInspectOutput(result) {
-	const relative = formatRelative(result.timestamp.getTime(), result.nowMs);
-	const inputLine = describeInputForm(result.input, result.canonical);
-	return [
-		`brand:     ${result.brand}`,
-		`timestamp: ${result.timestamp.toISOString()} (${relative})`,
-		`canonical: ${result.canonical}`,
-		`input:     ${inputLine}`,
-		""
-	].join("\n");
-}
-function describeInputForm(input, canonical) {
-	if (input === canonical) return "canonical";
-	const notes = [];
-	if (input !== input.toLowerCase()) notes.push("was uppercase");
-	if (/[ilo]/i.test(input.slice(4))) notes.push("used Crockford aliases");
-	return `not canonical (${notes.join(" + ")})`;
-}
-const msPerMinute = 60 * 1e3;
-const msPerHour = 60 * msPerMinute;
-const msPerDay = 24 * msPerHour;
-const daysPerMonth = 30.44;
-const monthsPerYear = 12;
-function formatRelative(thenMs, nowMs) {
-	const diff = nowMs - thenMs;
-	const abs = Math.abs(diff);
-	const suffix = diff < 0 ? "from now" : "ago";
-	const head = headUnits(abs);
-	return head === "" ? "just now" : `${head} ${suffix}`;
-}
-function headUnits(abs) {
-	if (abs < msPerMinute) return "";
-	if (abs < msPerHour) return unit(Math.round(abs / msPerMinute), "minute");
-	if (abs < msPerDay) return unit(Math.round(abs / msPerHour), "hour");
-	if (abs < msPerDay * daysPerMonth) return unit(Math.round(abs / msPerDay), "day");
-	const totalMonths = Math.round(abs / (msPerDay * daysPerMonth));
-	if (totalMonths < monthsPerYear) return unit(totalMonths, "month");
-	const years = Math.floor(totalMonths / monthsPerYear);
-	const months = totalMonths % monthsPerYear;
-	return months === 0 ? unit(years, "year") : `${unit(years, "year")} ${unit(months, "month")}`;
-}
-function unit(n, name) {
-	return `${n} ${n === 1 ? name : `${name}s`}`;
-}
-//#endregion
 //#region src/cli/wrapping-key.ts
 function parseKeyFormatFlag(values) {
 	const fromFlag = values.get("--key-format");
@@ -434,7 +438,7 @@ function runInspect(args, opts) {
 		try {
 			reverseCodec = createReverseTimestampId(brand, codecOpts(opts));
 		} catch (err) {
-			opts.stderr(err.message + "\n");
+			opts.stderr(formatCliError(err) + "\n");
 			return Promise.resolve(1);
 		}
 		const reverseValidation = reverseCodec["~standard"].validate(input);
@@ -458,7 +462,7 @@ function runInspect(args, opts) {
 	try {
 		codec = createTimestampId(brand, codecOpts(opts));
 	} catch (err) {
-		opts.stderr(err.message + "\n");
+		opts.stderr(formatCliError(err) + "\n");
 		return Promise.resolve(1);
 	}
 	const validation = codec["~standard"].validate(input);
@@ -492,7 +496,7 @@ async function runWrappedInspect(brand, input, kind, format, opts) {
 			allowDuplicateBrand: true
 		});
 	} catch (err) {
-		opts.stderr(err.message + "\n");
+		opts.stderr(formatCliError(err) + "\n");
 		return 1;
 	}
 	const validation = codec["~standard"].validate(input);
@@ -505,7 +509,7 @@ async function runWrappedInspect(brand, input, kind, format, opts) {
 	try {
 		lookupKey = await codec.unwrap(canonical);
 	} catch (err) {
-		opts.stderr(err.message + "\n");
+		opts.stderr(formatCliError(err) + "\n");
 		return 1;
 	}
 	opts.stdout(formatWrappedInspectOutput({
@@ -529,7 +533,7 @@ async function runOpaqueInspect(brand, input, format, opts) {
 			...codecOpts(opts)
 		});
 	} catch (err) {
-		opts.stderr(err.message + "\n");
+		opts.stderr(formatCliError(err) + "\n");
 		return 1;
 	}
 	const validation = codec["~standard"].validate(input);