@smonn/ids 0.4.0 → 0.6.0

package/dist/drizzle.mjs

@@ -0,0 +1,42 @@
+import { customType } from "drizzle-orm/pg-core";
+//#region src/drizzle.ts
+/**
+* Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value.
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`, not strict
+* `is()`. Data at rest should already be canonical per ADR-0003, but `safeParse`
+* is a safe boundary in case stale non-canonical values exist. Throws if the
+* value from the database does not parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumn } from "@smonn/ids/drizzle";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* export const users = pgTable("users", { id: idColumn(usr).primaryKey() });
+* // users.id is Id<"usr"> end-to-end
+* ```
+*/
+function idColumn(codec) {
+	return customType({
+		dataType() {
+			return "text";
+		},
+		toDriver(value) {
+			return value;
+		},
+		fromDriver(value) {
+			const result = codec.safeParse(value);
+			if (!result.ok) throw new Error(`[ids] invalid ID from database: ${result.error}`);
+			return result.id;
+		}
+	})();
+}
+//#endregion
+export { idColumn };
+
+//# sourceMappingURL=drizzle.mjs.map

package/dist/drizzle.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"drizzle.mjs","names":[],"sources":["../src/drizzle.ts"],"sourcesContent":["import {\n  customType,\n  type ConvertCustomConfig,\n  type PgCustomColumnBuilder,\n} from \"drizzle-orm/pg-core\";\nimport type { Id, ParseResult } from \"./types.js\";\n\n/**\n * Minimum codec interface required by the Drizzle adapter.\n *\n * Any codec variant satisfies this type — TimestampCodec, OpaqueTimestampCodec,\n * and WrappedKeyCodec all expose `safeParse`. The adapter never calls\n * `extractTimestamp`, `wrap`/`unwrap`, or any key-dependent method.\n *\n * Kysely and Prisma adapter issues should use this same codec contract shape.\n */\nexport type IdColumnCodec<Brand extends string> = {\n  safeParse(value: unknown): ParseResult<Brand>;\n};\n\n/**\n * Drizzle custom column type that stores an `Id<Brand>` as a canonical `text` value.\n *\n * **Write path:** passes the `Id<Brand>` directly to the driver — it is already\n * the canonical string form.\n *\n * **Read path:** normalises the raw DB string via `codec.safeParse()`, not strict\n * `is()`. Data at rest should already be canonical per ADR-0003, but `safeParse`\n * is a safe boundary in case stale non-canonical values exist. Throws if the\n * value from the database does not parse as a valid `Id<Brand>`.\n *\n * @example\n * ```ts\n * import { idColumn } from \"@smonn/ids/drizzle\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * export const users = pgTable(\"users\", { id: idColumn(usr).primaryKey() });\n * // users.id is Id<\"usr\"> end-to-end\n * ```\n */\nexport function idColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): PgCustomColumnBuilder<ConvertCustomConfig<\"\", { data: Id<Brand>; driverData: string }>> {\n  return customType<{ data: Id<Brand>; driverData: string }>({\n    dataType() {\n      return \"text\";\n    },\n    toDriver(value: Id<Brand>): string {\n      return value;\n    },\n    fromDriver(value: string): Id<Brand> {\n      const result = codec.safeParse(value);\n      if (!result.ok) {\n        throw new Error(`[ids] invalid ID from database: ${result.error}`);\n      }\n      return result.id;\n    },\n  })();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,SACd,OACyF;CACzF,OAAO,WAAoD;EACzD,WAAW;GACT,OAAO;EACT;EACA,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,MAAM,SAAS,MAAM,UAAU,KAAK;GACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,MAAM,mCAAmC,OAAO,OAAO;GAEnE,OAAO,OAAO;EAChB;CACF,CAAC,CAAC,CAAC;AACL"}

package/dist/express.d.mts

@@ -0,0 +1,92 @@
+import { i as ParseResult, t as Id } from "./types-g7CiQDyE.mjs";
+import { NextFunction, Request, Response } from "express";
+
+//#region src/express.d.ts
+type IdCodec<Brand extends string> = {
+  safeParse(value: unknown): ParseResult<Brand>;
+};
+/** Discriminated failure value passed to `onError` and emitted to Express error pipeline via `next(err)`. */
+type IdParamFailure = {
+  readonly reason: "brand_mismatch";
+  readonly status: number;
+} | {
+  readonly reason: "malformed";
+  readonly status: number;
+};
+/**
+* Typed error forwarded to Express's error pipeline (`next(err)`) on validation failure.
+* Inspect `err.reason` and `err.status` in error-handling middleware.
+*/
+declare class IdParamError extends Error {
+  readonly status: number;
+  readonly reason: "brand_mismatch" | "malformed";
+  constructor(reason: "brand_mismatch" | "malformed", status: number);
+}
+/** Options for `idParam`. All fields are optional. */
+type IdParamOptions = {
+  /**
+  * Called instead of forwarding to `next(err)` when provided. The hook owns the response
+  * entirely — the adapter does not call `next(err)` itself.
+  */
+  onError?: (failure: IdParamFailure, req: Request, res: Response, next: NextFunction) => void;
+  /**
+  * Remap the default HTTP status for a failure reason without a full handler.
+  * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.
+  */
+  status?: {
+    brand_mismatch?: number;
+    malformed?: number;
+  };
+};
+/**
+* Express middleware that validates a named route param against a codec via `safeParse`.
+*
+* **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and `reason`,
+* so the app's existing error-handling middleware controls rendering. The adapter does not write
+* a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter does
+* not call `next(err)`.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing ID → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in `res.locals` under `paramName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idParam, IdParamError } from "@smonn/ids/express";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: forwards error to app error-handling middleware
+* app.get("/users/:id", idParam("id", usr), (req, res) => {
+*   const id = res.locals.id; // Id<"usr">, canonical
+* });
+*
+* // Error-handling middleware receives the typed error
+* app.use((err, req, res, next) => {
+*   if (err instanceof IdParamError) {
+*     res.status(err.status).json({ error: err.reason });
+*     return;
+*   }
+*   next(err);
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/orgs/:id", idParam("id", org, {
+*   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),
+* }), handler);
+*
+* // Or a lightweight status remap without a full handler
+* app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } }), handler);
+* ```
+*/
+declare function idParam<ParamKey extends string, Brand extends string>(paramName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): (req: Request, res: Response<unknown, Record<ParamKey, Id<Brand>>>, next: NextFunction) => void;
+//#endregion
+export { IdParamError, IdParamFailure, IdParamOptions, idParam };
+//# sourceMappingURL=express.d.mts.map

package/dist/express.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.mts","names":[],"sources":["../src/express.ts"],"mappings":";;;;KAGK,OAAA;EACH,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;;KAI7B,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA;;AANJ;AAIzC;;cAQa,YAAA,SAAqB,KAAA;EAAA,SACvB,MAAA;EAAA,SACA,MAAA;EAET,WAAA,CAAY,MAAA,kCAAwC,MAAA;AAAA;;KAS1C,cAAA;EAnBiC;AAM7C;;;EAkBE,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,EAAU,IAAA,EAAM,YAAA;;;;;EAKvE,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;AAAA;AAmDtC;;;;;;;;;;;;;;;;;;;;;;;;;;iBAAgB,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IACR,GAAA,EAAK,OAAA,EAAS,GAAA,EAAK,QAAA,UAAkB,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA,KAAU,IAAA,EAAM,YAAA"}

package/dist/express.mjs

@@ -0,0 +1,90 @@
+//#region src/express.ts
+/**
+* Typed error forwarded to Express's error pipeline (`next(err)`) on validation failure.
+* Inspect `err.reason` and `err.status` in error-handling middleware.
+*/
+var IdParamError = class extends Error {
+	status;
+	reason;
+	constructor(reason, status) {
+		super(`ID validation failed: ${reason}`);
+		this.name = "IdParamError";
+		this.reason = reason;
+		this.status = status;
+	}
+};
+/**
+* Express middleware that validates a named route param against a codec via `safeParse`.
+*
+* **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and `reason`,
+* so the app's existing error-handling middleware controls rendering. The adapter does not write
+* a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter does
+* not call `next(err)`.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing ID → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in `res.locals` under `paramName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idParam, IdParamError } from "@smonn/ids/express";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: forwards error to app error-handling middleware
+* app.get("/users/:id", idParam("id", usr), (req, res) => {
+*   const id = res.locals.id; // Id<"usr">, canonical
+* });
+*
+* // Error-handling middleware receives the typed error
+* app.use((err, req, res, next) => {
+*   if (err instanceof IdParamError) {
+*     res.status(err.status).json({ error: err.reason });
+*     return;
+*   }
+*   next(err);
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/orgs/:id", idParam("id", org, {
+*   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),
+* }), handler);
+*
+* // Or a lightweight status remap without a full handler
+* app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } }), handler);
+* ```
+*/
+function idParam(paramName, codec, options) {
+	return (req, res, next) => {
+		const raw = req.params[paramName];
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const reason = result.error === "invalid_prefix" ? "brand_mismatch" : "malformed";
+			const defaultStatus = reason === "brand_mismatch" ? 404 : 400;
+			const status = options?.status?.[reason] ?? defaultStatus;
+			const failure = {
+				reason,
+				status
+			};
+			if (options?.onError) {
+				options.onError(failure, req, res, next);
+				return;
+			}
+			next(new IdParamError(reason, status));
+			return;
+		}
+		res.locals[paramName] = result.id;
+		next();
+	};
+}
+//#endregion
+export { IdParamError, idParam };
+
+//# sourceMappingURL=express.mjs.map

package/dist/express.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.mjs","names":[],"sources":["../src/express.ts"],"sourcesContent":["import type { NextFunction, Request, Response } from \"express\";\nimport type { Id, ParseResult } from \"./types.js\";\n\ntype IdCodec<Brand extends string> = {\n  safeParse(value: unknown): ParseResult<Brand>;\n};\n\n/** Discriminated failure value passed to `onError` and emitted to Express error pipeline via `next(err)`. */\nexport type IdParamFailure =\n  | { readonly reason: \"brand_mismatch\"; readonly status: number }\n  | { readonly reason: \"malformed\"; readonly status: number };\n\n/**\n * Typed error forwarded to Express's error pipeline (`next(err)`) on validation failure.\n * Inspect `err.reason` and `err.status` in error-handling middleware.\n */\nexport class IdParamError extends Error {\n  readonly status: number;\n  readonly reason: \"brand_mismatch\" | \"malformed\";\n\n  constructor(reason: \"brand_mismatch\" | \"malformed\", status: number) {\n    super(`ID validation failed: ${reason}`);\n    this.name = \"IdParamError\";\n    this.reason = reason;\n    this.status = status;\n  }\n}\n\n/** Options for `idParam`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of forwarding to `next(err)` when provided. The hook owns the response\n   * entirely — the adapter does not call `next(err)` itself.\n   */\n  onError?: (failure: IdParamFailure, req: Request, res: Response, next: NextFunction) => void;\n  /**\n   * Remap the default HTTP status for a failure reason without a full handler.\n   * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.\n   */\n  status?: { brand_mismatch?: number; malformed?: number };\n};\n\n/**\n * Express middleware that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and `reason`,\n * so the app's existing error-handling middleware controls rendering. The adapter does not write\n * a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter does\n * not call `next(err)`.\n *\n * **`options.status`:** remaps the default HTTP status for a reason without a full handler.\n *\n * - **Brand mismatch (`invalid_prefix`) → `reason: \"brand_mismatch\"`, default 404**\n * - **Malformed or missing ID → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in `res.locals` under `paramName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idParam, IdParamError } from \"@smonn/ids/express\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: forwards error to app error-handling middleware\n * app.get(\"/users/:id\", idParam(\"id\", usr), (req, res) => {\n *   const id = res.locals.id; // Id<\"usr\">, canonical\n * });\n *\n * // Error-handling middleware receives the typed error\n * app.use((err, req, res, next) => {\n *   if (err instanceof IdParamError) {\n *     res.status(err.status).json({ error: err.reason });\n *     return;\n *   }\n *   next(err);\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/orgs/:id\", idParam(\"id\", org, {\n *   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),\n * }), handler);\n *\n * // Or a lightweight status remap without a full handler\n * app.get(\"/things/:id\", idParam(\"id\", thing, { status: { brand_mismatch: 400 } }), handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (req: Request, res: Response<unknown, Record<ParamKey, Id<Brand>>>, next: NextFunction) => void {\n  return (req, res, next): void => {\n    const raw = req.params[paramName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const reason =\n        result.error === \"invalid_prefix\" ? (\"brand_mismatch\" as const) : (\"malformed\" as const);\n      const defaultStatus = reason === \"brand_mismatch\" ? 404 : 400;\n      const status = options?.status?.[reason] ?? defaultStatus;\n      const failure: IdParamFailure = { reason, status };\n      if (options?.onError) {\n        options.onError(failure, req, res, next);\n        return;\n      }\n      next(new IdParamError(reason, status));\n      return;\n    }\n    (res.locals as Record<string, unknown>)[paramName] = result.id;\n    next();\n  };\n}\n"],"mappings":";;;;;AAgBA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CAEA,YAAY,QAAwC,QAAgB;EAClE,MAAM,yBAAyB,QAAQ;EACvC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,SAAS;CAChB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgEA,SAAgB,QACd,WACA,OACA,SACiG;CACjG,QAAQ,KAAK,KAAK,SAAe;EAC/B,MAAM,MAAM,IAAI,OAAO;EACvB,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,SACJ,OAAO,UAAU,mBAAoB,mBAA8B;GACrE,MAAM,gBAAgB,WAAW,mBAAmB,MAAM;GAC1D,MAAM,SAAS,SAAS,SAAS,WAAW;GAC5C,MAAM,UAA0B;IAAE;IAAQ;GAAO;GACjD,IAAI,SAAS,SAAS;IACpB,QAAQ,QAAQ,SAAS,KAAK,KAAK,IAAI;IACvC;GACF;GACA,KAAK,IAAI,aAAa,QAAQ,MAAM,CAAC;GACrC;EACF;EACA,IAAK,OAAmC,aAAa,OAAO;EAC5D,KAAK;CACP;AACF"}

package/dist/hono.d.mts

@@ -0,0 +1,75 @@
+import { i as ParseResult, t as Id } from "./types-g7CiQDyE.mjs";
+import { Context, MiddlewareHandler } from "hono";
+
+//#region src/hono.d.ts
+type IdCodec<Brand extends string> = {
+  safeParse(value: unknown): ParseResult<Brand>;
+};
+/** Discriminated failure value passed to `onError` and emitted to `app.onError` via HTTPException. */
+type IdParamFailure = {
+  readonly reason: "brand_mismatch";
+  readonly status: number;
+} | {
+  readonly reason: "malformed";
+  readonly status: number;
+};
+/** Options for `idParam`. All fields are optional. */
+type IdParamOptions = {
+  /**
+  * Called instead of throwing when provided. The hook owns the response entirely —
+  * the adapter neither throws nor writes a body.
+  */
+  onError?: (failure: IdParamFailure, c: Context) => Response | Promise<Response>;
+  /**
+  * Remap the default HTTP status for a failure reason without a full handler.
+  * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.
+  */
+  status?: {
+    brand_mismatch?: number;
+    malformed?: number;
+  };
+};
+/**
+* Hono middleware that validates a named route param against a codec via `safeParse`.
+*
+* **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler
+* controls rendering and content negotiation. The adapter does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither
+* throws nor writes a response.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing ID → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in the Hono context under `paramName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idParam } from "@smonn/ids/hono";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws HTTPException → app.onError renders it
+* app.get("/users/:id", idParam("id", usr), (c) => {
+*   const id = c.get("id"); // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/orgs/:id", idParam("id", org, {
+*   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+* }), handler);
+*
+* // Or a lightweight status remap without a full handler
+* app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } }), handler);
+* ```
+*/
+declare function idParam<ParamKey extends string, Brand extends string>(paramName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): MiddlewareHandler<{
+  Variables: Record<ParamKey, Id<Brand>>;
+}>;
+//#endregion
+export { IdParamFailure, IdParamOptions, idParam };
+//# sourceMappingURL=hono.d.mts.map

package/dist/hono.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.d.mts","names":[],"sources":["../src/hono.ts"],"mappings":";;;;KAIK,OAAA;EACH,SAAA,CAAU,KAAA,YAAiB,WAAA,CAAY,KAAA;AAAA;;KAI7B,cAAA;EAAA,SACG,MAAA;EAAA,SAAmC,MAAA;AAAA;EAAA,SACnC,MAAA;EAAA,SAA8B,MAAA;AAAA;;KAGjC,cAAA;EALZ;;;;EAUE,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,CAAA,EAAG,OAAA,KAAY,QAAA,GAAW,OAAA,CAAQ,QAAA;;;;;EAKtE,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;;;;;;;;;;AAAA;AAyCtC;;;;;;;;;;;;;;;;;;;iBAAgB,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,GACT,iBAAA;EAAoB,SAAA,EAAW,MAAA,CAAO,QAAA,EAAU,EAAA,CAAG,KAAA;AAAA"}

package/dist/hono.mjs

@@ -0,0 +1,63 @@
+import { HTTPException } from "hono/http-exception";
+//#region src/hono.ts
+/**
+* Hono middleware that validates a named route param against a codec via `safeParse`.
+*
+* **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler
+* controls rendering and content negotiation. The adapter does not write a response body itself.
+*
+* **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither
+* throws nor writes a response.
+*
+* **`options.status`:** remaps the default HTTP status for a reason without a full handler.
+*
+* - **Brand mismatch (`invalid_prefix`) → `reason: "brand_mismatch"`, default 404**
+* - **Malformed or missing ID → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in the Hono context under `paramName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idParam } from "@smonn/ids/hono";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws HTTPException → app.onError renders it
+* app.get("/users/:id", idParam("id", usr), (c) => {
+*   const id = c.get("id"); // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/orgs/:id", idParam("id", org, {
+*   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+* }), handler);
+*
+* // Or a lightweight status remap without a full handler
+* app.get("/things/:id", idParam("id", thing, { status: { brand_mismatch: 400 } }), handler);
+* ```
+*/
+function idParam(paramName, codec, options) {
+	return async (c, next) => {
+		const raw = c.req.param(paramName);
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const reason = result.error === "invalid_prefix" ? "brand_mismatch" : "malformed";
+			const defaultStatus = reason === "brand_mismatch" ? 404 : 400;
+			const status = options?.status?.[reason] ?? defaultStatus;
+			const failure = {
+				reason,
+				status
+			};
+			if (options?.onError) return options.onError(failure, c);
+			throw new HTTPException(status);
+		}
+		c.set(paramName, result.id);
+		await next();
+	};
+}
+//#endregion
+export { idParam };
+
+//# sourceMappingURL=hono.mjs.map

package/dist/hono.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono.mjs","names":[],"sources":["../src/hono.ts"],"sourcesContent":["import { HTTPException } from \"hono/http-exception\";\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport type { Id, ParseResult } from \"./types.js\";\n\ntype IdCodec<Brand extends string> = {\n  safeParse(value: unknown): ParseResult<Brand>;\n};\n\n/** Discriminated failure value passed to `onError` and emitted to `app.onError` via HTTPException. */\nexport type IdParamFailure =\n  | { readonly reason: \"brand_mismatch\"; readonly status: number }\n  | { readonly reason: \"malformed\"; readonly status: number };\n\n/** Options for `idParam`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of throwing when provided. The hook owns the response entirely —\n   * the adapter neither throws nor writes a body.\n   */\n  onError?: (failure: IdParamFailure, c: Context) => Response | Promise<Response>;\n  /**\n   * Remap the default HTTP status for a failure reason without a full handler.\n   * e.g. `{ brand_mismatch: 400 }` treats both failure kinds as 400.\n   */\n  status?: { brand_mismatch?: number; malformed?: number };\n};\n\n/**\n * Hono middleware that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `HTTPException(status)` so the app's existing `onError` handler\n * controls rendering and content negotiation. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook owns the response entirely — the adapter neither\n * throws nor writes a response.\n *\n * **`options.status`:** remaps the default HTTP status for a reason without a full handler.\n *\n * - **Brand mismatch (`invalid_prefix`) → `reason: \"brand_mismatch\"`, default 404**\n * - **Malformed or missing ID → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in the Hono context under `paramName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idParam } from \"@smonn/ids/hono\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws HTTPException → app.onError renders it\n * app.get(\"/users/:id\", idParam(\"id\", usr), (c) => {\n *   const id = c.get(\"id\"); // Id<\"usr\">, canonical\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/orgs/:id\", idParam(\"id\", org, {\n *   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),\n * }), handler);\n *\n * // Or a lightweight status remap without a full handler\n * app.get(\"/things/:id\", idParam(\"id\", thing, { status: { brand_mismatch: 400 } }), handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): MiddlewareHandler<{ Variables: Record<ParamKey, Id<Brand>> }> {\n  return async (c, next) => {\n    const raw = c.req.param(paramName);\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const reason =\n        result.error === \"invalid_prefix\" ? (\"brand_mismatch\" as const) : (\"malformed\" as const);\n      const defaultStatus = reason === \"brand_mismatch\" ? 404 : 400;\n      const status = options?.status?.[reason] ?? defaultStatus;\n      const failure: IdParamFailure = { reason, status };\n      if (options?.onError) {\n        return options.onError(failure, c);\n      }\n      throw new HTTPException(status as ConstructorParameters<typeof HTTPException>[0]);\n    }\n    c.set(paramName, result.id);\n    await next();\n    return;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,SAAgB,QACd,WACA,OACA,SAC+D;CAC/D,OAAO,OAAO,GAAG,SAAS;EACxB,MAAM,MAAM,EAAE,IAAI,MAAM,SAAS;EACjC,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,SACJ,OAAO,UAAU,mBAAoB,mBAA8B;GACrE,MAAM,gBAAgB,WAAW,mBAAmB,MAAM;GAC1D,MAAM,SAAS,SAAS,SAAS,WAAW;GAC5C,MAAM,UAA0B;IAAE;IAAQ;GAAO;GACjD,IAAI,SAAS,SACX,OAAO,QAAQ,QAAQ,SAAS,CAAC;GAEnC,MAAM,IAAI,cAAc,MAAwD;EAClF;EACA,EAAE,IAAI,WAAW,OAAO,EAAE;EAC1B,MAAM,KAAK;CAEb;AACF"}

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { t as createTimestampId } from "./timestamp-BjdAetut.mjs";
+import { t as createTimestampId } from "./timestamp-Bgzxx8bE.mjs";
 export { createTimestampId };

package/dist/kysely.d.mts

@@ -0,0 +1,55 @@
+import { t as Id } from "./types-g7CiQDyE.mjs";
+import { t as IdColumnCodec } from "./drizzle-CeSni5PB.mjs";
+import { ColumnType } from "kysely";
+
+//#region src/kysely.d.ts
+/**
+* Kysely column type mapping for `Id<Brand>`.
+*
+* Use this in your Kysely `Database` interface to type a column as `Id<Brand>` at
+* the TypeScript level. Pair it with `idColumn(codec)` for runtime read/write
+* transformation.
+*
+* @example
+* ```ts
+* import type { IdColumnType } from "@smonn/ids/kysely";
+* import type { Id } from "@smonn/ids";
+*
+* interface Database {
+*   users: { id: IdColumnType<"usr"> };
+* }
+* ```
+*/
+type IdColumnType<Brand extends string> = ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>;
+/**
+* Kysely column adapter bound to a codec.
+*
+* Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write
+* contract of the Drizzle adapter — same error message, same strictness (safeParse on
+* read, identity on write).
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`. Throws if
+* the value does not parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumn } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const usrCol = idColumn(usr);
+*
+* // In a query result handler:
+* const id = usrCol.fromDriver(row.id);
+* ```
+*/
+declare function idColumn<Brand extends string>(codec: IdColumnCodec<Brand>): {
+  toDriver(value: Id<Brand>): string;
+  fromDriver(value: string): Id<Brand>;
+};
+//#endregion
+export { type IdColumnCodec, IdColumnType, idColumn };
+//# sourceMappingURL=kysely.d.mts.map

package/dist/kysely.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.d.mts","names":[],"sources":["../src/kysely.ts"],"mappings":";;;;;;AAuBA;;;;;;;;;;;;;;;;KAAY,YAAA,yBAAqC,UAAA,CAAW,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA;;;;;AAAA;AA2BrF;;;;;;;;;;;;;;;;;;;;iBAAgB,QAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA;EAErB,QAAA,CAAS,KAAA,EAAO,EAAA,CAAG,KAAA;EACnB,UAAA,CAAW,KAAA,WAAgB,EAAA,CAAG,KAAA;AAAA"}

package/dist/kysely.mjs

@@ -0,0 +1,42 @@
+//#region src/kysely.ts
+/**
+* Kysely column adapter bound to a codec.
+*
+* Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write
+* contract of the Drizzle adapter — same error message, same strictness (safeParse on
+* read, identity on write).
+*
+* **Write path:** passes the `Id<Brand>` directly to the driver — it is already
+* the canonical string form.
+*
+* **Read path:** normalises the raw DB string via `codec.safeParse()`. Throws if
+* the value does not parse as a valid `Id<Brand>`.
+*
+* @example
+* ```ts
+* import { idColumn } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const usrCol = idColumn(usr);
+*
+* // In a query result handler:
+* const id = usrCol.fromDriver(row.id);
+* ```
+*/
+function idColumn(codec) {
+	return {
+		toDriver(value) {
+			return value;
+		},
+		fromDriver(value) {
+			const result = codec.safeParse(value);
+			if (!result.ok) throw new Error(`[ids] invalid ID from database: ${result.error}`);
+			return result.id;
+		}
+	};
+}
+//#endregion
+export { idColumn };
+
+//# sourceMappingURL=kysely.mjs.map

package/dist/kysely.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kysely.mjs","names":[],"sources":["../src/kysely.ts"],"sourcesContent":["import type { ColumnType } from \"kysely\";\nimport type { IdColumnCodec } from \"./drizzle.js\";\nimport type { Id } from \"./types.js\";\n\nexport type { IdColumnCodec } from \"./drizzle.js\";\n\n/**\n * Kysely column type mapping for `Id<Brand>`.\n *\n * Use this in your Kysely `Database` interface to type a column as `Id<Brand>` at\n * the TypeScript level. Pair it with `idColumn(codec)` for runtime read/write\n * transformation.\n *\n * @example\n * ```ts\n * import type { IdColumnType } from \"@smonn/ids/kysely\";\n * import type { Id } from \"@smonn/ids\";\n *\n * interface Database {\n *   users: { id: IdColumnType<\"usr\"> };\n * }\n * ```\n */\nexport type IdColumnType<Brand extends string> = ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>;\n\n/**\n * Kysely column adapter bound to a codec.\n *\n * Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write\n * contract of the Drizzle adapter — same error message, same strictness (safeParse on\n * read, identity on write).\n *\n * **Write path:** passes the `Id<Brand>` directly to the driver — it is already\n * the canonical string form.\n *\n * **Read path:** normalises the raw DB string via `codec.safeParse()`. Throws if\n * the value does not parse as a valid `Id<Brand>`.\n *\n * @example\n * ```ts\n * import { idColumn } from \"@smonn/ids/kysely\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n * const usrCol = idColumn(usr);\n *\n * // In a query result handler:\n * const id = usrCol.fromDriver(row.id);\n * ```\n */\nexport function idColumn<Brand extends string>(\n  codec: IdColumnCodec<Brand>,\n): {\n  toDriver(value: Id<Brand>): string;\n  fromDriver(value: string): Id<Brand>;\n} {\n  return {\n    toDriver(value: Id<Brand>): string {\n      return value;\n    },\n    fromDriver(value: string): Id<Brand> {\n      const result = codec.safeParse(value);\n      if (!result.ok) {\n        throw new Error(`[ids] invalid ID from database: ${result.error}`);\n      }\n      return result.id;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,SACd,OAIA;CACA,OAAO;EACL,SAAS,OAA0B;GACjC,OAAO;EACT;EACA,WAAW,OAA0B;GACnC,MAAM,SAAS,MAAM,UAAU,KAAK;GACpC,IAAI,CAAC,OAAO,IACV,MAAM,IAAI,MAAM,mCAAmC,OAAO,OAAO;GAEnE,OAAO,OAAO;EAChB;CACF;AACF"}

package/dist/{opaque-CX-Lc5B9.mjs → opaque-goLnFoo7.mjs}

@@ -1,4 +1,6 @@
-import { a as writeTimestamp, c as toWireId, l as validateBrand, n as registerBrand, o as payloadBase32Length, r as readTimestampMs, s as payloadBytesFromId, t as wireMethods } from "./codec-shell-C0arqqX3.mjs";
+import { a as toWireId, i as payloadBytesFromId, n as registerBrand, r as payloadBase32Length, s as validateBrand, t as wireMethods } from "./codec-shell-dWpxoFmy.mjs";
+import { r as writeTimestamp, t as readTimestampMs } from "./timestamp-bytes-B57RM7Ho.mjs";
+import { i as encodeHex, n as decodeHex, r as encodeBase64Url, t as decodeBase64Url } from "./bytes-lhzKVaBV.mjs";
 //#region src/layouts/opaque.ts
 const zeroIv = new Uint8Array(16);
 const pkcsPad = 16;
@@ -51,62 +53,35 @@ function createOpaqueLayoutOps(prefix, key, rng) {
 	};
 }
 //#endregion
-//#region src/bytes.ts
-const hexDigits = "0123456789abcdef";
-const invalidNibble = 255;
-const hexCharCodeToNibble = new Uint8Array(128).fill(invalidNibble);
-for (let i = 0; i < 10; i++) hexCharCodeToNibble[48 + i] = i;
-for (let i = 0; i < 6; i++) {
-	hexCharCodeToNibble[97 + i] = 10 + i;
-	hexCharCodeToNibble[65 + i] = 10 + i;
-}
-/** Lowercase hex encoding of raw bytes. */
-function encodeHex(bytes) {
-	const codes = new Array(bytes.length * 2);
-	for (let i = 0; i < bytes.length; i++) {
-		const b = bytes[i];
-		codes[i * 2] = hexDigits.charCodeAt(b >>> 4);
-		codes[i * 2 + 1] = hexDigits.charCodeAt(b & 15);
-	}
-	return String.fromCharCode(...codes);
-}
-/** Decodes a hex string to raw bytes. Throws on non-hex input. */
-function decodeHex(encoded) {
-	if (encoded.length % 2 !== 0) throw new Error("invalid hex");
-	const out = new Uint8Array(encoded.length / 2);
-	for (let i = 0; i < out.length; i++) {
-		const hiCode = encoded.charCodeAt(i * 2);
-		const loCode = encoded.charCodeAt(i * 2 + 1);
-		if (hiCode >= hexCharCodeToNibble.length || loCode >= hexCharCodeToNibble.length) throw new Error("invalid hex");
-		const hi = hexCharCodeToNibble[hiCode];
-		const lo = hexCharCodeToNibble[loCode];
-		if (hi === invalidNibble || lo === invalidNibble) throw new Error("invalid hex");
-		out[i] = hi << 4 | lo;
-	}
-	return out;
-}
-/** Base64url encoding without padding. */
-function encodeBase64Url(bytes) {
-	let binary = "";
-	for (let i = 0; i < bytes.length; i++) binary += String.fromCharCode(bytes[i]);
-	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-/** Decodes a base64url string to raw bytes. Throws on invalid input. */
-function decodeBase64Url(encoded) {
-	const base64 = encoded.replace(/-/g, "+").replace(/_/g, "/");
-	const pad = (4 - base64.length % 4) % 4;
-	const binary = atob(base64 + "=".repeat(pad));
-	const out = new Uint8Array(binary.length);
-	for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
-	return out;
-}
-//#endregion
 //#region src/opaque-key.ts
 const validAesKeyByteLengths = new Set([
 	16,
 	24,
 	32
 ]);
+const opaqueKeyInternals = /* @__PURE__ */ new WeakMap();
+/**
+* Imports raw AES key bytes into an {@link OpaqueKey} handle for the Opaque
+* Timestamp codec.
+*
+* Accepts 16, 24, or 32 bytes (AES-128 / AES-192 / AES-256 strength).
+* To store or transport key material, use {@link encodeOpaqueKey} /
+* {@link decodeOpaqueKey} (`"hex"` or `"base64url"` — not Crockford base32).
+*
+* @param bytes - 16, 24, or 32 raw key bytes.
+*/
+async function importOpaqueKey(bytes) {
+	assertValidAesKeyByteLength(bytes.length);
+	const cryptoKey = await crypto.subtle.importKey("raw", bytes, "AES-CBC", false, ["encrypt", "decrypt"]);
+	const key = Object.freeze({});
+	opaqueKeyInternals.set(key, cryptoKey);
+	return key;
+}
+function getOpaqueKeyCryptoKey(key) {
+	const cryptoKey = opaqueKeyInternals.get(key);
+	if (cryptoKey === void 0) throw new Error("invalid opaque key");
+	return cryptoKey;
+}
 /**
 * Encodes raw AES key bytes for storage in env vars or secret managers.
 *
@@ -159,28 +134,21 @@ function defaultRng(target) {
 	crypto.getRandomValues(target);
 }
 /**
-* Imports a raw AES key for use with the Opaque Timestamp codec.
-*
-* @param bytes - Raw key bytes (16, 24, or 32 bytes for AES-128/192/256).
-*/
-function importOpaqueKey(bytes) {
-	return crypto.subtle.importKey("raw", bytes, "AES-CBC", false, ["encrypt", "decrypt"]);
-}
-/**
 * Creates an Opaque Timestamp codec for `brand` (three lowercase a–z characters).
 *
 * @param brand - Entity type brand validated once at construction.
-* @param opts - Required `key` plus optional `now`, `rng`, and `allowDuplicateBrand` overrides.
+* @param opts - Required `key` (an {@link OpaqueKey} from {@link importOpaqueKey}) plus
+*   optional `now`, `rng`, and `allowDuplicateBrand` overrides.
 */
 function createOpaqueTimestampId(brand, opts) {
 	validateBrand(brand);
 	registerBrand(brand, opts.allowDuplicateBrand);
-	const key = opts.key;
+	const cryptoKey = getOpaqueKeyCryptoKey(opts.key);
 	const now = opts.now ?? Date.now;
 	const rng = opts.rng ?? defaultRng;
 	const prefix = `${brand}_`;
 	const wire = wireMethods(prefix);
-	const layout = createOpaqueLayoutOps(prefix, key, rng);
+	const layout = createOpaqueLayoutOps(prefix, cryptoKey, rng);
 	return {
 		generate: () => layout.generateAt(now()),
 		generateAt: (date) => layout.generateAt(date.getTime()),
@@ -193,6 +161,6 @@ function createOpaqueTimestampId(brand, opts) {
 	};
 }
 //#endregion
-export { encodeOpaqueKey as i, importOpaqueKey as n, decodeOpaqueKey as r, createOpaqueTimestampId as t };
+export { importOpaqueKey as i, decodeOpaqueKey as n, encodeOpaqueKey as r, createOpaqueTimestampId as t };
 
-//# sourceMappingURL=opaque-CX-Lc5B9.mjs.map
+//# sourceMappingURL=opaque-goLnFoo7.mjs.map