idParam

Call Signature

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

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

Hono middleware that validates a named route param against a codec via safeParse.

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 ID → reason: "malformed", default 400

On success, stores the canonical Id<Brand> in the Hono context under paramName and calls next().

Type Parameters

ParamKey

ParamKey extends string

Brand

Brand extends string

Parameters

paramName

ParamKey

codec

IdVerifiableCodec<Brand>

options?

IdParamVerifyOptions

Returns

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

Example

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

const usr = createTimestampId("usr");

// Default: throws IdParamError (extends HTTPException) → app.onError renders it
app.get("/users/:id", idParam("id", usr), (c) => {
  const id = c.get("id"); // 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("/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);