Middleware@rhythmjs/middleware
Validate requests
One middleware per request part: check it against any Standard Schema and read the typed output from ctx.valid.
On this page
Install the package#
@rhythmjs/middleware is a middleware collection for Rhythm routers: request validation (/validate), response transformation (/intercept), and exception handling (/filter). Each module lives on its own subpath export; there is no root barrel export.
bun add @rhythmjs/middleware @rhythmjs/rhythm @rhythmjs/routerYou build routes and middleware on a RhythmRouter, mount the router into a Rhythm app with mount(router), and serve the app with Bun.serve({ fetch: toFetchHandler(app) }). The samples on these pages show the router; the app around it is always the same:
import { Rhythm, mount } from "@rhythmjs/rhythm";
import { toFetchHandler } from "@rhythmjs/router/fetch";
const app = new Rhythm().use(mount(router));
Bun.serve({ fetch: toFetchHandler(app) });One request part, one schema#
validate(target, schema) checks one part of the request against any Standard Schema v1 schema: zod, valibot, arktype, or anything else implementing the spec, including asynchronous schemas. The target selects what gets extracted:
"body": the JSON request body, read fromctx.request.clone()so the handler can still read the original body itself."query": URL search params collected into an object; a key that repeats becomes an array of its values."param": the route params matched by the router (ctx.params; an empty object when nothing matched).
import { RhythmRouter } from "@rhythmjs/router";
import { validate, type Validated } from "@rhythmjs/middleware/validate";
import { z } from "zod";
import { json } from "@rhythmjs/router/response";
const createUser = z.object({ name: z.string().min(1), age: z.coerce.number().int() });
const router = new RhythmRouter().post("/users", validate("body", createUser), (ctx) => {
// ctx.valid.body is inferred as { name: string; age: number }
json(ctx, ctx.valid.body);
});The typed context#
On success the schema’s output (after coercions and transforms) is merged into the context as ctx.valid[target]. The merge is a spread over the previous ctx.valid, so chained validators compose: validate the body and the query on one route and both results are present, each under its own key.
validate is typed as a derive-style extension, so the context type widens for the handlers after it with no annotation. A route accepts only one such extension handler, and it must come first. To combine validators on one route, compose them and declare the combined type with the exported Validated<Target, Schema> and ValidationContext types, because compose drops extension types:
import { compose } from "@rhythmjs/rhythm/compose";
import type { ExtensionMiddleware } from "@rhythmjs/rhythm/types";
import { validate, type Validated, type ValidationContext } from "@rhythmjs/middleware/validate";
const both = compose([validate("param", userParams), validate("query", paging)]) as ExtensionMiddleware<
ValidationContext,
Validated<"param", typeof userParams> & Validated<"query", typeof paging>
>;
router.get("/users/:id/posts", both, (ctx) => {
ctx.valid.param.id; // validated route param
ctx.valid.query.page; // coerced number
});The failure shape#
On failure the chain short-circuits with status 400, content-type: application/json; charset=utf-8, and a ValidationFailure body. Schema issues are serialized to { message, path? }: property-key path segments are unwrapped to their keys and symbol segments are dropped, so the payload is always JSON-safe.
{
"success": false,
"target": "body",
"issues": [{ "message": "Too small: expected string to have >=1 characters", "path": ["name"] }]
}A body that is not valid JSON never reaches the schema: it fails early with a single issue reading "Malformed JSON in request body".
Where to next#
Intercept is the response-side counterpart: validate and reshape what leaves the handler. Filter turns thrown errors into HTTP responses. The API reference lists every export on the three subpaths.