@smonn/ids 0.15.0 → 1.0.0-rc.1

package/dist/express.mjs

@@ -1,4 +1,4 @@
-import { n as resolveIdParamFailure } from "./adapter-types-7wWdELSh.mjs";
+import { r as resolveIdParamFailure } from "./adapter-types-CjzFNDcJ.mjs";
 //#region src/adapters/express.ts
 /**
 * Typed error forwarded to Express's error pipeline (`next(err)`) on validation failure.
@@ -79,7 +79,65 @@ function idParam(paramName, codec, options) {
 		next();
 	};
 }
+/**
+* Express middleware that validates a named query-string param against a codec via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same
+* `IdParamError` forwarded to `next(err)` — but reads `req.query[queryName]` instead of
+* `req.params[queryName]`.
+*
+* **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 query param → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in `res.locals` under `queryName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idQuery, IdParamError } from "@smonn/ids/express";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: forwards error to app error-handling middleware
+* // GET /users?userId=usr_...
+* app.get("/users", idQuery("userId", usr), (req, res) => {
+*   const userId = res.locals.userId; // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/search", idQuery("cursor", usr, {
+*   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),
+* }), handler);
+* ```
+*/
+function idQuery(queryName, codec, options) {
+	return (req, res, next) => {
+		const raw = req.query[queryName];
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const failure = resolveIdParamFailure(result.error, options);
+			if (options?.onError) {
+				options.onError(failure, req, res, next);
+				return;
+			}
+			next(new IdParamError(failure.reason, failure.status));
+			return;
+		}
+		res.locals[queryName] = result.id;
+		next();
+	};
+}
 //#endregion
-export { IdParamError, idParam };
+export { IdParamError, idParam, idQuery };
 
 //# sourceMappingURL=express.mjs.map

package/dist/express.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"express.mjs","names":[],"sources":["../src/adapters/express.ts"],"sourcesContent":["import type { NextFunction, Request, Response } from \"express\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\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 failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        options.onError(failure, req, res, next);\n        return;\n      }\n      next(new IdParamError(failure.reason, failure.status));\n      return;\n    }\n    (res.locals as Record<string, unknown>)[paramName] = result.id;\n    next();\n  };\n}\n"],"mappings":";;;;;;AAUA,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,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,QAAQ,QAAQ,SAAS,KAAK,KAAK,IAAI;IACvC;GACF;GACA,KAAK,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM,CAAC;GACrD;EACF;EACA,IAAK,OAAmC,aAAa,OAAO;EAC5D,KAAK;CACP;AACF"}
+{"version":3,"file":"express.mjs","names":[],"sources":["../src/adapters/express.ts"],"sourcesContent":["import type { NextFunction, Request, Response } from \"express\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\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` and `idQuery`. 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 failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        options.onError(failure, req, res, next);\n        return;\n      }\n      next(new IdParamError(failure.reason, failure.status));\n      return;\n    }\n    (res.locals as Record<string, unknown>)[paramName] = result.id;\n    next();\n  };\n}\n\n/**\n * Express middleware that validates a named query-string param against a codec via `safeParse`.\n *\n * Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same\n * `IdParamError` forwarded to `next(err)` — but reads `req.query[queryName]` instead of\n * `req.params[queryName]`.\n *\n * **Default (no options):** calls `next(err)` with an `IdParamError` carrying `status` and\n * `reason`, so the app's existing error-handling middleware controls rendering. The adapter\n * does not write 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 query param → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in `res.locals` under `queryName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idQuery, 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 * // GET /users?userId=usr_...\n * app.get(\"/users\", idQuery(\"userId\", usr), (req, res) => {\n *   const userId = res.locals.userId; // Id<\"usr\">, canonical\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/search\", idQuery(\"cursor\", usr, {\n *   onError: (failure, req, res) => res.status(failure.status).json({ error: failure.reason }),\n * }), handler);\n * ```\n */\nexport function idQuery<ParamKey extends string, Brand extends string>(\n  queryName: 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.query[queryName] as string | undefined;\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        options.onError(failure, req, res, next);\n        return;\n      }\n      next(new IdParamError(failure.reason, failure.status));\n      return;\n    }\n    (res.locals as Record<string, unknown>)[queryName] = result.id;\n    next();\n  };\n}\n"],"mappings":";;;;;;AAUA,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,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,QAAQ,QAAQ,SAAS,KAAK,KAAK,IAAI;IACvC;GACF;GACA,KAAK,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM,CAAC;GACrD;EACF;EACA,IAAK,OAAmC,aAAa,OAAO;EAC5D,KAAK;CACP;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,SAAgB,QACd,WACA,OACA,SACiG;CACjG,QAAQ,KAAK,KAAK,SAAe;EAC/B,MAAM,MAAM,IAAI,MAAM;EACtB,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,QAAQ,QAAQ,SAAS,KAAK,KAAK,IAAI;IACvC;GACF;GACA,KAAK,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM,CAAC;GACrD;EACF;EACA,IAAK,OAAmC,aAAa,OAAO;EAC5D,KAAK;CACP;AACF"}

package/dist/fastify.d.mts

@@ -12,7 +12,7 @@ declare class IdParamError extends Error {
   readonly reason: "brand_mismatch" | "malformed";
   constructor(reason: "brand_mismatch" | "malformed", statusCode: number);
 }
-/** Options for `idParam`. All fields are optional. */
+/** Options for `idParam` and `idQuery`. All fields are optional. */
 type IdParamOptions = {
   /**
   * Called instead of throwing when provided. The hook owns the response entirely —
@@ -89,6 +89,53 @@ type IdParamOptions = {
 declare function idParam<ParamKey extends string, Brand extends string>(paramName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): (request: FastifyRequest<{
   Params: Record<string, Id<Brand>>;
 }>, reply: FastifyReply) => Promise<void>;
+/**
+* Fastify `preHandler` hook factory that validates a named query-string param against a codec
+* via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same
+* `IdParamError` thrown into `setErrorHandler` — but reads `request.query[queryName]` instead of
+* `request.params`.
+*
+* **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the
+* app's existing `setErrorHandler` controls rendering. The adapter does not write a response
+* body itself.
+*
+* **`options.onError`:** when provided, the hook calls `onError` and does not throw; the
+* consumer fully owns the response via `reply`.
+*
+* **`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 query param → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in `request.query` under `queryName`.
+*
+* @example
+* ```ts
+* import { idQuery, IdParamError } from "@smonn/ids/fastify";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws IdParamError → setErrorHandler renders it
+* // GET /users?userId=usr_...
+* fastify.get("/users", { preHandler: idQuery("userId", usr) }, (request, reply) => {
+*   const userId = request.query.userId; // string (compile-time); Id<"usr"> at runtime
+* });
+*
+* // Override: consumer fully owns the error response
+* fastify.get("/search", {
+*   preHandler: idQuery("cursor", usr, {
+*     onError: (failure, request, reply) =>
+*       reply.status(failure.status).send({ error: failure.reason }),
+*   }),
+* }, handler);
+* ```
+*/
+declare function idQuery<ParamKey extends string, Brand extends string>(queryName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): (request: FastifyRequest<{
+  Querystring: Record<string, Id<Brand>>;
+}>, reply: FastifyReply) => Promise<void>;
 //#endregion
-export { IdParamError, type IdParamFailure, IdParamOptions, idParam };
+export { IdParamError, type IdParamFailure, IdParamOptions, idParam, idQuery };
 //# sourceMappingURL=fastify.d.mts.map

package/dist/fastify.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"fastify.d.mts","names":[],"sources":["../src/adapters/fastify.ts"],"mappings":";;;;;;AAUA;;;cAAa,YAAA,SAAqB,KAAA;EAAA,SACvB,UAAA;EAAA,SACA,MAAA;EAET,WAAA,CAAY,MAAA,kCAAwC,UAAA;AAAA;;KAS1C,cAAA;EAT0C;AAAA;AAStD;;EAKE,OAAA,IACE,OAAA,EAAS,cAAA,EACT,OAAA,EAAS,cAAA,EACT,KAAA,EAAO,YAAA,YACG,OAAA;;;;;EAKZ,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;AAAA;AA6DtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOK;;;;;;;;;;;;;;iBAPW,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IAEV,OAAA,EAAS,cAAA;EAAiB,MAAA,EAAQ,MAAA,SAAe,EAAA,CAAG,KAAA;AAAA,IACpD,KAAA,EAAO,YAAA,KACJ,OAAA"}
+{"version":3,"file":"fastify.d.mts","names":[],"sources":["../src/adapters/fastify.ts"],"mappings":";;;;;;AAUA;;;cAAa,YAAA,SAAqB,KAAA;EAAA,SACvB,UAAA;EAAA,SACA,MAAA;EAET,WAAA,CAAY,MAAA,kCAAwC,UAAA;AAAA;;KAS1C,cAAA;EAT0C;AAAA;AAStD;;EAKE,OAAA,IACE,OAAA,EAAS,cAAA,EACT,OAAA,EAAS,cAAA,EACT,KAAA,EAAO,YAAA,YACG,OAAA;;;;;EAKZ,MAAA;IAAW,cAAA;IAAyB,SAAA;EAAA;AAAA;;;;;;;;;;AAAA;AA6DtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAOK;AA4DL;;;;;;;;;;;;;iBAnEgB,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IAEV,OAAA,EAAS,cAAA;EAAiB,MAAA,EAAQ,MAAA,SAAe,EAAA,CAAG,KAAA;AAAA,IACpD,KAAA,EAAO,YAAA,KACJ,OAAA;;;;;;;;;;;;;;;;AAmEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAPW,OAAA,gDACd,SAAA,EAAW,QAAA,EACX,KAAA,EAAO,OAAA,CAAQ,KAAA,GACf,OAAA,GAAU,cAAA,IAEV,OAAA,EAAS,cAAA;EAAiB,WAAA,EAAa,MAAA,SAAe,EAAA,CAAG,KAAA;AAAA,IACzD,KAAA,EAAO,YAAA,KACJ,OAAA"}

package/dist/fastify.mjs

@@ -1,4 +1,4 @@
-import { n as resolveIdParamFailure } from "./adapter-types-7wWdELSh.mjs";
+import { r as resolveIdParamFailure } from "./adapter-types-CjzFNDcJ.mjs";
 //#region src/adapters/fastify.ts
 /**
 * Typed error thrown into Fastify's `setErrorHandler` on validation failure.
@@ -87,7 +87,66 @@ function idParam(paramName, codec, options) {
 		request.params[paramName] = result.id;
 	};
 }
+/**
+* Fastify `preHandler` hook factory that validates a named query-string param against a codec
+* via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same
+* `IdParamError` thrown into `setErrorHandler` — but reads `request.query[queryName]` instead of
+* `request.params`.
+*
+* **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the
+* app's existing `setErrorHandler` controls rendering. The adapter does not write a response
+* body itself.
+*
+* **`options.onError`:** when provided, the hook calls `onError` and does not throw; the
+* consumer fully owns the response via `reply`.
+*
+* **`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 query param → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in `request.query` under `queryName`.
+*
+* @example
+* ```ts
+* import { idQuery, IdParamError } from "@smonn/ids/fastify";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws IdParamError → setErrorHandler renders it
+* // GET /users?userId=usr_...
+* fastify.get("/users", { preHandler: idQuery("userId", usr) }, (request, reply) => {
+*   const userId = request.query.userId; // string (compile-time); Id<"usr"> at runtime
+* });
+*
+* // Override: consumer fully owns the error response
+* fastify.get("/search", {
+*   preHandler: idQuery("cursor", usr, {
+*     onError: (failure, request, reply) =>
+*       reply.status(failure.status).send({ error: failure.reason }),
+*   }),
+* }, handler);
+* ```
+*/
+function idQuery(queryName, codec, options) {
+	return async (request, reply) => {
+		const raw = request.query[queryName];
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const failure = resolveIdParamFailure(result.error, options);
+			if (options?.onError) {
+				await options.onError(failure, request, reply);
+				return;
+			}
+			throw new IdParamError(failure.reason, failure.status);
+		}
+		request.query[queryName] = result.id;
+	};
+}
 //#endregion
-export { IdParamError, idParam };
+export { IdParamError, idParam, idQuery };
 
 //# sourceMappingURL=fastify.mjs.map

package/dist/fastify.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"fastify.mjs","names":[],"sources":["../src/adapters/fastify.ts"],"sourcesContent":["import type { FastifyReply, FastifyRequest } from \"fastify\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/**\n * Typed error thrown into Fastify's `setErrorHandler` on validation failure.\n * Inspect `err.reason` and `err.statusCode` in your error handler.\n */\nexport class IdParamError extends Error {\n  readonly statusCode: number;\n  readonly reason: \"brand_mismatch\" | \"malformed\";\n\n  constructor(reason: \"brand_mismatch\" | \"malformed\", statusCode: number) {\n    super(`ID validation failed: ${reason}`);\n    this.name = \"IdParamError\";\n    this.reason = reason;\n    this.statusCode = statusCode;\n  }\n}\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 does not throw.\n   */\n  onError?: (\n    failure: IdParamFailure,\n    request: FastifyRequest,\n    reply: FastifyReply,\n  ) => void | Promise<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 * Fastify `preHandler` hook factory that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the app's\n * existing `setErrorHandler` controls rendering. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook calls `onError` and does not throw; the consumer\n * fully owns the response via `reply`.\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 `request.params` under `paramName`.\n *\n * **Return type note:** the returned hook is typed as\n * `(request: FastifyRequest<{ Params: Record<string, Id<Brand>> }>, reply: FastifyReply) => Promise<void>`.\n * Assigning it to a Fastify `preHandler` slot is backward-compatible (method-signature bivariance applies).\n * However, a locally-annotated variable typed as the bare `(request: FastifyRequest, reply: FastifyReply) => Promise<void>`\n * will produce a TypeScript error under `--strictFunctionTypes` because function parameter types are contravariant.\n * Use `preHandler` assignment or let TypeScript infer the type to avoid this.\n *\n * @example\n * ```ts\n * import { idParam, IdParamError } from \"@smonn/ids/fastify\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws IdParamError → setErrorHandler renders it\n * fastify.get(\"/users/:id\", { preHandler: idParam(\"id\", usr) }, (request, reply) => {\n *   const id = request.params.id; // string (compile-time); Id<\"usr\"> at runtime after preHandler\n * });\n *\n * // Error handler receives the typed error\n * fastify.setErrorHandler((err, request, reply) => {\n *   if (err instanceof IdParamError) {\n *     reply.status(err.statusCode).send({ error: err.reason });\n *     return;\n *   }\n *   reply.send(err);\n * });\n *\n * // Override: consumer fully owns the error response\n * fastify.get(\"/orgs/:id\", {\n *   preHandler: idParam(\"id\", org, {\n *     onError: (failure, request, reply) =>\n *       reply.status(failure.status).send({ error: failure.reason }),\n *   }),\n * }, handler);\n *\n * // Or a lightweight status remap without a full handler\n * fastify.get(\"/things/:id\", {\n *   preHandler: idParam(\"id\", thing, { status: { brand_mismatch: 400 } }),\n * }, handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (\n  request: FastifyRequest<{ Params: Record<string, Id<Brand>> }>,\n  reply: FastifyReply,\n) => Promise<void> {\n  return async (request, reply): Promise<void> => {\n    const raw = request.params[paramName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        await options.onError(failure, request, reply);\n        return;\n      }\n      throw new IdParamError(failure.reason, failure.status);\n    }\n    request.params[paramName] = result.id;\n  };\n}\n"],"mappings":";;;;;;AAUA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CAEA,YAAY,QAAwC,YAAoB;EACtE,MAAM,yBAAyB,QAAQ;EACvC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,aAAa;CACpB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8EA,SAAgB,QACd,WACA,OACA,SAIiB;CACjB,OAAO,OAAO,SAAS,UAAyB;EAC9C,MAAM,MAAM,QAAQ,OAAO;EAC3B,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS,KAAK;IAC7C;GACF;GACA,MAAM,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM;EACvD;EACA,QAAQ,OAAO,aAAa,OAAO;CACrC;AACF"}
+{"version":3,"file":"fastify.mjs","names":[],"sources":["../src/adapters/fastify.ts"],"sourcesContent":["import type { FastifyReply, FastifyRequest } from \"fastify\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/**\n * Typed error thrown into Fastify's `setErrorHandler` on validation failure.\n * Inspect `err.reason` and `err.statusCode` in your error handler.\n */\nexport class IdParamError extends Error {\n  readonly statusCode: number;\n  readonly reason: \"brand_mismatch\" | \"malformed\";\n\n  constructor(reason: \"brand_mismatch\" | \"malformed\", statusCode: number) {\n    super(`ID validation failed: ${reason}`);\n    this.name = \"IdParamError\";\n    this.reason = reason;\n    this.statusCode = statusCode;\n  }\n}\n\n/** Options for `idParam` and `idQuery`. All fields are optional. */\nexport type IdParamOptions = {\n  /**\n   * Called instead of throwing when provided. The hook owns the response entirely —\n   * the adapter does not throw.\n   */\n  onError?: (\n    failure: IdParamFailure,\n    request: FastifyRequest,\n    reply: FastifyReply,\n  ) => void | Promise<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 * Fastify `preHandler` hook factory that validates a named route param against a codec via `safeParse`.\n *\n * **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the app's\n * existing `setErrorHandler` controls rendering. The adapter does not write a response body itself.\n *\n * **`options.onError`:** when provided, the hook calls `onError` and does not throw; the consumer\n * fully owns the response via `reply`.\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 `request.params` under `paramName`.\n *\n * **Return type note:** the returned hook is typed as\n * `(request: FastifyRequest<{ Params: Record<string, Id<Brand>> }>, reply: FastifyReply) => Promise<void>`.\n * Assigning it to a Fastify `preHandler` slot is backward-compatible (method-signature bivariance applies).\n * However, a locally-annotated variable typed as the bare `(request: FastifyRequest, reply: FastifyReply) => Promise<void>`\n * will produce a TypeScript error under `--strictFunctionTypes` because function parameter types are contravariant.\n * Use `preHandler` assignment or let TypeScript infer the type to avoid this.\n *\n * @example\n * ```ts\n * import { idParam, IdParamError } from \"@smonn/ids/fastify\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws IdParamError → setErrorHandler renders it\n * fastify.get(\"/users/:id\", { preHandler: idParam(\"id\", usr) }, (request, reply) => {\n *   const id = request.params.id; // string (compile-time); Id<\"usr\"> at runtime after preHandler\n * });\n *\n * // Error handler receives the typed error\n * fastify.setErrorHandler((err, request, reply) => {\n *   if (err instanceof IdParamError) {\n *     reply.status(err.statusCode).send({ error: err.reason });\n *     return;\n *   }\n *   reply.send(err);\n * });\n *\n * // Override: consumer fully owns the error response\n * fastify.get(\"/orgs/:id\", {\n *   preHandler: idParam(\"id\", org, {\n *     onError: (failure, request, reply) =>\n *       reply.status(failure.status).send({ error: failure.reason }),\n *   }),\n * }, handler);\n *\n * // Or a lightweight status remap without a full handler\n * fastify.get(\"/things/:id\", {\n *   preHandler: idParam(\"id\", thing, { status: { brand_mismatch: 400 } }),\n * }, handler);\n * ```\n */\nexport function idParam<ParamKey extends string, Brand extends string>(\n  paramName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (\n  request: FastifyRequest<{ Params: Record<string, Id<Brand>> }>,\n  reply: FastifyReply,\n) => Promise<void> {\n  return async (request, reply): Promise<void> => {\n    const raw = request.params[paramName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        await options.onError(failure, request, reply);\n        return;\n      }\n      throw new IdParamError(failure.reason, failure.status);\n    }\n    request.params[paramName] = result.id;\n  };\n}\n\n/**\n * Fastify `preHandler` hook factory that validates a named query-string param against a codec\n * via `safeParse`.\n *\n * Same failure contract as `idParam` — same `IdParamOptions` / `IdParamFailure` shape, same\n * `IdParamError` thrown into `setErrorHandler` — but reads `request.query[queryName]` instead of\n * `request.params`.\n *\n * **Default (no options):** throws `IdParamError` carrying `statusCode` and `reason` so the\n * app's existing `setErrorHandler` controls rendering. The adapter does not write a response\n * body itself.\n *\n * **`options.onError`:** when provided, the hook calls `onError` and does not throw; the\n * consumer fully owns the response via `reply`.\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 query param → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in `request.query` under `queryName`.\n *\n * @example\n * ```ts\n * import { idQuery, IdParamError } from \"@smonn/ids/fastify\";\n * import { createTimestampId } from \"@smonn/ids\";\n *\n * const usr = createTimestampId(\"usr\");\n *\n * // Default: throws IdParamError → setErrorHandler renders it\n * // GET /users?userId=usr_...\n * fastify.get(\"/users\", { preHandler: idQuery(\"userId\", usr) }, (request, reply) => {\n *   const userId = request.query.userId; // string (compile-time); Id<\"usr\"> at runtime\n * });\n *\n * // Override: consumer fully owns the error response\n * fastify.get(\"/search\", {\n *   preHandler: idQuery(\"cursor\", usr, {\n *     onError: (failure, request, reply) =>\n *       reply.status(failure.status).send({ error: failure.reason }),\n *   }),\n * }, handler);\n * ```\n */\nexport function idQuery<ParamKey extends string, Brand extends string>(\n  queryName: ParamKey,\n  codec: IdCodec<Brand>,\n  options?: IdParamOptions,\n): (\n  request: FastifyRequest<{ Querystring: Record<string, Id<Brand>> }>,\n  reply: FastifyReply,\n) => Promise<void> {\n  return async (request, reply): Promise<void> => {\n    const raw = request.query[queryName];\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        await options.onError(failure, request, reply);\n        return;\n      }\n      throw new IdParamError(failure.reason, failure.status);\n    }\n    request.query[queryName] = result.id;\n  };\n}\n"],"mappings":";;;;;;AAUA,IAAa,eAAb,cAAkC,MAAM;CACtC;CACA;CAEA,YAAY,QAAwC,YAAoB;EACtE,MAAM,yBAAyB,QAAQ;EACvC,KAAK,OAAO;EACZ,KAAK,SAAS;EACd,KAAK,aAAa;CACpB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8EA,SAAgB,QACd,WACA,OACA,SAIiB;CACjB,OAAO,OAAO,SAAS,UAAyB;EAC9C,MAAM,MAAM,QAAQ,OAAO;EAC3B,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS,KAAK;IAC7C;GACF;GACA,MAAM,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM;EACvD;EACA,QAAQ,OAAO,aAAa,OAAO;CACrC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8CA,SAAgB,QACd,WACA,OACA,SAIiB;CACjB,OAAO,OAAO,SAAS,UAAyB;EAC9C,MAAM,MAAM,QAAQ,MAAM;EAC1B,MAAM,SAAS,MAAM,UAAU,GAAG;EAClC,IAAI,CAAC,OAAO,IAAI;GACd,MAAM,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SAAS;IACpB,MAAM,QAAQ,QAAQ,SAAS,SAAS,KAAK;IAC7C;GACF;GACA,MAAM,IAAI,aAAa,QAAQ,QAAQ,QAAQ,MAAM;EACvD;EACA,QAAQ,MAAM,aAAa,OAAO;CACpC;AACF"}

package/dist/hono.d.mts

@@ -4,7 +4,7 @@ import { ContentfulStatusCode } from "hono/utils/http-status";
 import { Context, MiddlewareHandler } from "hono";
 
 //#region src/adapters/hono.d.ts
-/** Options for `idParam`. All fields are optional. */
+/** Options for `idParam` and `idQuery`. All fields are optional. */
 type IdParamOptions = {
   /**
   * Called instead of throwing when provided. The hook owns the response entirely —
@@ -61,6 +61,48 @@ type IdParamOptions = {
 declare function idParam<ParamKey extends string, Brand extends string>(paramName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): MiddlewareHandler<{
   Variables: Record<ParamKey, Id<Brand>>;
 }>;
+/**
+* Hono middleware that validates a named query-string param against a codec via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamFailure` shape, same `onError` / `status`
+* options — but reads `c.req.query(queryName)` instead of `c.req.param(queryName)`.
+*
+* **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 query param → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in the Hono context under `queryName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idQuery } from "@smonn/ids/hono";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws HTTPException → app.onError renders it
+* // GET /users?userId=usr_...
+* app.get("/users", idQuery("userId", usr), (c) => {
+*   const userId = c.get("userId"); // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/search", idQuery("cursor", usr, {
+*   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+* }), handler);
+* ```
+*/
+declare function idQuery<ParamKey extends string, Brand extends string>(queryName: ParamKey, codec: IdCodec<Brand>, options?: IdParamOptions): MiddlewareHandler<{
+  Variables: Record<ParamKey, Id<Brand>>;
+}>;
 //#endregion
-export { type IdParamFailure, IdParamOptions, idParam };
+export { type IdParamFailure, IdParamOptions, idParam, idQuery };
 //# sourceMappingURL=hono.d.mts.map

package/dist/hono.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"hono.d.mts","names":[],"sources":["../src/adapters/hono.ts"],"mappings":";;;;;;;KASY,cAAA;EAAA;;;;EAKV,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,CAAA,EAAG,OAAA,KAAY,QAAA,GAAW,OAAA,CAAQ,QAAA;;;;;EAKtE,MAAA;IAAW,cAAA,GAAiB,oBAAA;IAAsB,SAAA,GAAY,oBAAA;EAAA;AAAA;;;;;;;;;;;;AAAA;AAyChE;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"hono.d.mts","names":[],"sources":["../src/adapters/hono.ts"],"mappings":";;;;;;;KASY,cAAA;EAAA;;;;EAKV,OAAA,IAAW,OAAA,EAAS,cAAA,EAAgB,CAAA,EAAG,OAAA,KAAY,QAAA,GAAW,OAAA,CAAQ,QAAA;;;;;EAKtE,MAAA;IAAW,cAAA,GAAiB,oBAAA;IAAsB,SAAA,GAAY,oBAAA;EAAA;AAAA;;;;;;;;;;;;AAAA;AAyChE;;;;;;;;;;;;;;;;;;;;;;;;;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA;;;;;;;;;;iBAJtC,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

@@ -1,4 +1,4 @@
-import { n as resolveIdParamFailure } from "./adapter-types-7wWdELSh.mjs";
+import { r as resolveIdParamFailure } from "./adapter-types-CjzFNDcJ.mjs";
 import { HTTPException } from "hono/http-exception";
 //#region src/adapters/hono.ts
 /**
@@ -52,7 +52,59 @@ function idParam(paramName, codec, options) {
 		await next();
 	};
 }
+/**
+* Hono middleware that validates a named query-string param against a codec via `safeParse`.
+*
+* Same failure contract as `idParam` — same `IdParamFailure` shape, same `onError` / `status`
+* options — but reads `c.req.query(queryName)` instead of `c.req.param(queryName)`.
+*
+* **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 query param → `reason: "malformed"`, default 400**
+*
+* On success, stores the canonical `Id<Brand>` in the Hono context under `queryName`
+* and calls `next()`.
+*
+* @example
+* ```ts
+* import { idQuery } from "@smonn/ids/hono";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* // Default: throws HTTPException → app.onError renders it
+* // GET /users?userId=usr_...
+* app.get("/users", idQuery("userId", usr), (c) => {
+*   const userId = c.get("userId"); // Id<"usr">, canonical
+* });
+*
+* // Override: consumer fully owns the response
+* app.get("/search", idQuery("cursor", usr, {
+*   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
+* }), handler);
+* ```
+*/
+function idQuery(queryName, codec, options) {
+	return async (c, next) => {
+		const raw = c.req.query(queryName);
+		const result = codec.safeParse(raw);
+		if (!result.ok) {
+			const failure = resolveIdParamFailure(result.error, options);
+			if (options?.onError) return options.onError(failure, c);
+			throw new HTTPException(failure.status);
+		}
+		c.set(queryName, result.id);
+		await next();
+	};
+}
 //#endregion
-export { idParam };
+export { idParam, idQuery };
 
 //# sourceMappingURL=hono.mjs.map

package/dist/hono.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hono.mjs","names":[],"sources":["../src/adapters/hono.ts"],"sourcesContent":["import { HTTPException } from \"hono/http-exception\";\nimport type { ContentfulStatusCode } from \"hono/utils/http-status\";\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\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?: ContentfulStatusCode; malformed?: ContentfulStatusCode };\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 failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        return options.onError(failure, c);\n      }\n      throw new HTTPException(failure.status as ContentfulStatusCode);\n    }\n    c.set(paramName, result.id);\n    await next();\n    return;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,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,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SACX,OAAO,QAAQ,QAAQ,SAAS,CAAC;GAEnC,MAAM,IAAI,cAAc,QAAQ,MAA8B;EAChE;EACA,EAAE,IAAI,WAAW,OAAO,EAAE;EAC1B,MAAM,KAAK;CAEb;AACF"}
+{"version":3,"file":"hono.mjs","names":[],"sources":["../src/adapters/hono.ts"],"sourcesContent":["import { HTTPException } from \"hono/http-exception\";\nimport type { ContentfulStatusCode } from \"hono/utils/http-status\";\nimport type { Context, MiddlewareHandler } from \"hono\";\nimport { type IdCodec, type IdParamFailure, resolveIdParamFailure } from \"./adapter-types.js\";\nimport type { Id } from \"../types.js\";\n\nexport type { IdParamFailure };\n\n/** Options for `idParam` and `idQuery`. 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?: ContentfulStatusCode; malformed?: ContentfulStatusCode };\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 failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        return options.onError(failure, c);\n      }\n      throw new HTTPException(failure.status as ContentfulStatusCode);\n    }\n    c.set(paramName, result.id);\n    await next();\n    return;\n  };\n}\n\n/**\n * Hono middleware that validates a named query-string param against a codec via `safeParse`.\n *\n * Same failure contract as `idParam` — same `IdParamFailure` shape, same `onError` / `status`\n * options — but reads `c.req.query(queryName)` instead of `c.req.param(queryName)`.\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 query param → `reason: \"malformed\"`, default 400**\n *\n * On success, stores the canonical `Id<Brand>` in the Hono context under `queryName`\n * and calls `next()`.\n *\n * @example\n * ```ts\n * import { idQuery } 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 * // GET /users?userId=usr_...\n * app.get(\"/users\", idQuery(\"userId\", usr), (c) => {\n *   const userId = c.get(\"userId\"); // Id<\"usr\">, canonical\n * });\n *\n * // Override: consumer fully owns the response\n * app.get(\"/search\", idQuery(\"cursor\", usr, {\n *   onError: (failure, c) => c.json({ error: failure.reason }, failure.status),\n * }), handler);\n * ```\n */\nexport function idQuery<ParamKey extends string, Brand extends string>(\n  queryName: 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.query(queryName);\n    const result = codec.safeParse(raw);\n    if (!result.ok) {\n      const failure = resolveIdParamFailure(result.error, options);\n      if (options?.onError) {\n        return options.onError(failure, c);\n      }\n      throw new HTTPException(failure.status as ContentfulStatusCode);\n    }\n    c.set(queryName, result.id);\n    await next();\n    return;\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4DA,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,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SACX,OAAO,QAAQ,QAAQ,SAAS,CAAC;GAEnC,MAAM,IAAI,cAAc,QAAQ,MAA8B;EAChE;EACA,EAAE,IAAI,WAAW,OAAO,EAAE;EAC1B,MAAM,KAAK;CAEb;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,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,UAAU,sBAAsB,OAAO,OAAO,OAAO;GAC3D,IAAI,SAAS,SACX,OAAO,QAAQ,QAAQ,SAAS,CAAC;GAEnC,MAAM,IAAI,cAAc,QAAQ,MAA8B;EAChE;EACA,EAAE,IAAI,WAAW,OAAO,EAAE;EAC1B,MAAM,KAAK;CAEb;AACF"}

package/dist/kysely.d.mts

@@ -1,10 +1,21 @@
 import { t as Id } from "./types-hGBnCpJj.mjs";
 import { n as IdColumnCodec } from "./adapter-types-Bia_w9sg.mjs";
 import { n as IdsErrorCode, r as isIdsError, t as IdsError } from "./error-CifcKKOG.mjs";
-import { ColumnType } from "kysely";
+import { ColumnType, KyselyPlugin } from "kysely";
 
 //#region src/adapters/kysely.d.ts
 /**
+* Extension of {@link IdColumnCodec} that also exposes synchronous `generate()`.
+* Required by {@link insertId} so that the insert-time call site can produce a
+* fresh `Id<Brand>` with a compile-time constraint enforcing codec capability.
+* Only the **Timestamp codec** and **Reverse Timestamp codec** satisfy this;
+* async-generate codecs (Opaque, Signed, Wrapped, Digest) do not and are
+* therefore rejected at the TypeScript level.
+*/
+type IdGeneratingCodec<Brand extends string> = IdColumnCodec<Brand> & {
+  generate(): Id<Brand>;
+};
+/**
 * Kysely column type mapping for `Id<Brand>`.
 *
 * Use this in your Kysely `Database` interface to type a column as `Id<Brand>` at
@@ -23,6 +34,24 @@ import { ColumnType } from "kysely";
 */
 type IdColumnType<Brand extends string> = ColumnType<Id<Brand>, Id<Brand>, Id<Brand>>;
 /**
+* Kysely column type mapping for a nullable `Id<Brand>` column.
+*
+* Use in your Kysely `Database` interface for optional foreign keys or any
+* column that can be `NULL`. Pair with `nullableIdColumn(codec)` for runtime
+* transformation.
+*
+* @example
+* ```ts
+* import type { NullableIdColumnType } from "@smonn/ids/kysely";
+* import type { Id } from "@smonn/ids";
+*
+* interface Database {
+*   posts: { authorId: NullableIdColumnType<"usr"> };
+* }
+* ```
+*/
+type NullableIdColumnType<Brand extends string> = ColumnType<Id<Brand> | null, Id<Brand> | null, Id<Brand> | null>;
+/**
 * Kysely column adapter bound to a codec.
 *
 * Returns an object with `fromDriver` / `toDriver` helpers that mirror the read/write
@@ -51,6 +80,78 @@ declare function idColumn<Brand extends string>(codec: IdColumnCodec<Brand>): {
   toDriver(value: Id<Brand>): string;
   fromDriver(value: string): Id<Brand>;
 };
+/**
+* Generates a fresh `Id<Brand>` for use at a Kysely insert call site.
+*
+* Requires a codec variant that exposes a synchronous `generate()` — see
+* {@link IdGeneratingCodec}. Only the **Timestamp codec** and **Reverse
+* Timestamp codec** qualify; Opaque, Signed, Wrapped, and Digest codecs
+* are rejected at compile time.
+*
+* @example
+* ```ts
+* import { insertId } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+*
+* await db.insertInto("users").values({ id: insertId(usr), name: "Alice" }).execute();
+* ```
+*/
+declare function insertId<Brand extends string>(codec: IdGeneratingCodec<Brand>): Id<Brand>;
+/**
+* Kysely plugin that automatically transforms result columns using the provided codec map.
+*
+* Keys in `map` are plain column names (`"id"`) or `"table.column"` qualified names
+* (`"users.id"`). Plain names match any result column with that name; qualified names
+* match by the column-name part (after the last `.`). If both a plain key and a qualified
+* key resolve to the same column name, the qualified key takes precedence.
+*
+* `transformResult` calls `readIdColumn(codec, rawValue)` for each matched column, returning
+* a branded `Id<Brand>` on success and throwing `IdsError("invalid_id")` on parse failure.
+* `transformQuery` is a no-op identity pass-through.
+*
+* @example
+* ```ts
+* import { idPlugin } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+* import { Kysely } from "kysely";
+*
+* const usr = createTimestampId("usr");
+*
+* const db = new Kysely<Database>({
+*   // ...
+*   plugins: [idPlugin({ "users.id": usr })],
+* });
+*
+* // result.id is automatically validated and branded as Id<"usr">
+* const row = await db.selectFrom("users").selectAll().executeTakeFirstOrThrow();
+* ```
+*/
+declare function idPlugin(map: Record<string, IdColumnCodec<string>>): KyselyPlugin;
+/**
+* Kysely column adapter for a **nullable** `Id<Brand>` column.
+*
+* Behaves like {@link idColumn} but `fromDriver` returns `null` for `null` /
+* `undefined` driver values and `toDriver` passes `null` through unchanged.
+* Use for optional foreign keys and `LEFT JOIN` results.
+*
+* @example
+* ```ts
+* import { nullableIdColumn } from "@smonn/ids/kysely";
+* import { createTimestampId } from "@smonn/ids";
+*
+* const usr = createTimestampId("usr");
+* const authorCol = nullableIdColumn(usr);
+*
+* // In a query result handler:
+* const authorId = authorCol.fromDriver(row.author_id); // Id<"usr"> | null
+* ```
+*/
+declare function nullableIdColumn<Brand extends string>(codec: IdColumnCodec<Brand>): {
+  toDriver(value: Id<Brand> | null): string | null;
+  fromDriver(value: string | null): Id<Brand> | null;
+};
 //#endregion
-export { type IdColumnCodec, IdColumnType, IdsError, type IdsErrorCode, idColumn, isIdsError };
+export { type IdColumnCodec, IdColumnType, IdGeneratingCodec, IdsError, type IdsErrorCode, NullableIdColumnType, idColumn, idPlugin, insertId, isIdsError, nullableIdColumn };
 //# sourceMappingURL=kysely.d.mts.map

package/dist/kysely.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"kysely.d.mts","names":[],"sources":["../src/adapters/kysely.ts"],"mappings":";;;;;;AAyBA;;;;;;;;;;;;;;;;;AAAA,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"}
+{"version":3,"file":"kysely.d.mts","names":[],"sources":["../src/adapters/kysely.ts"],"mappings":";;;;;;AAuBA;;;;;;;;AAAA,KAAY,iBAAA,yBAA0C,aAAA,CAAc,KAAA;EAClE,QAAA,IAAY,EAAA,CAAG,KAAA;AAAA;;;;;;AAAA;AAoBjB;;;;;;;;;;;KAAY,YAAA,yBAAqC,UAAA,CAAW,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA,GAAQ,EAAA,CAAG,KAAA;;;;;;;;;;AAAA;AAmBrF;;;;;;;KAAY,oBAAA,yBAA6C,UAAA,CACvD,EAAA,CAAG,KAAA,UACH,EAAA,CAAG,KAAA,UACH,EAAA,CAAG,KAAA;;;;;;;;;;;;;;AAAA;AA4BL;;;;;;;;;;;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;;;;;;;;;;AAAA;AA8BhC;;;;;;;;iBAAgB,QAAA,uBAA+B,KAAA,EAAO,iBAAA,CAAkB,KAAA,IAAS,EAAA,CAAG,KAAA;;;;;;;;AAAA;AAiCpF;;;;;;;;;;;;;AAAsE;AAqDtE;;;;;;;iBArDgB,QAAA,CAAS,GAAA,EAAK,MAAA,SAAe,aAAA,YAAyB,YAAA;;;;;;;;;;;;;;;;;AAyD/B;;;iBAJvB,gBAAA,uBACd,KAAA,EAAO,aAAA,CAAc,KAAA;EAErB,QAAA,CAAS,KAAA,EAAO,EAAA,CAAG,KAAA;EACnB,UAAA,CAAW,KAAA,kBAAuB,EAAA,CAAG,KAAA;AAAA"}