idQuery

Call Signature

idQuery<ParamKey, Brand>(queryName, codec, options?): MiddlewareHandler<{ Variables: Record<ParamKey, Id<Brand>>; }>

Defined in: src/adapters/hono.ts:198

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 IdParamError (extends HTTPException) carrying both the HTTP status and reason so the app’s existing onError handler can discriminate by reason. 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().

Type Parameters

ParamKey

ParamKey extends string

Brand

Brand extends string

Parameters

queryName

ParamKey

codec

IdVerifiableCodec<Brand>

options?

IdParamVerifyOptions

Returns

MiddlewareHandler<{ Variables: Record<ParamKey, Id<Brand>>; }>

Example

import { idQuery, IdParamError } from "@smonn/ids/hono";
import { createTimestampId } from "@smonn/ids";

const usr = createTimestampId("usr");

// Default: throws IdParamError (extends HTTPException) → app.onError renders it
// GET /users?userId=usr_...
app.get("/users", idQuery("userId", usr), (c) => {
  const userId = c.get("userId"); // Id<"usr">, canonical
});

// Discriminate by reason in app.onError
app.onError((err, c) => {
  if (err instanceof IdParamError) {
    return c.json({ error: err.reason }, err.status); // err.reason: "brand_mismatch" | "malformed"
  }
  return c.json({ error: "internal" }, 500);
});

// Override: consumer fully owns the response
app.get("/search", idQuery("cursor", usr, {
  onError: (failure, c) => c.json({ error: failure.reason }, failure.status),
}), handler);