rhythmjs

Search documentation

Search guides, the tutorial and every package.

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.

Shell
bun add @rhythmjs/middleware @rhythmjs/rhythm @rhythmjs/router

You 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:

TypeScript
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 from ctx.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).
TypeScript
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:

TypeScript
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.

JSON
{
  "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.