idQuery

Call Signature

idQuery<ParamKey, Brand>(queryName, codec, options?): (request, reply) => 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 adapter awaits the hook on validation failure. If the hook sends a response (reply.sent is true after it resolves), the adapter takes no further action. Otherwise, the adapter falls back to throwing IdParamError, so the route handler never runs with an invalid ID.

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

Storage: on success, stores the canonical Id<Brand> in request.query[queryName] by mutating the query object in place. This contrasts with the Express adapter, which writes to res.locals[queryName]. See the idParam JSDoc for the rationale on in-place mutation.

Type Parameters

ParamKey

ParamKey extends string

Brand

Brand extends string

Parameters

queryName

ParamKey

codec

IdVerifiableCodec<Brand>

options?

IdParamVerifyOptions

Returns

(request, reply) => Promise<void>

Example

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);