Validation

Typically, input/output validation is offered as an extension or plugin. With webroute, I/O validation is a first-class citizen and can be declared easily.

Overview

We can define several different types of input and output using the route utility, including query params, path params, request body and headers, as well as response data.

route()
  .query(SomeSchema) // Query params
  .params(SomeSchema) // Path params
  .body(SomeSchema) // Request body
  .headers(SomeSchema) // Request headers
  .output(SomeSchema); // Response, or "output", data

Declared input schema are not automatically validated. Webroute requires explicit parsing of the inputs, which can be done via the .parse() context method.

route()
  // ---input schema defined here---
  .handle(async (req, c) => {
    // Parse everything at once
    const { query, params, body, headers } = await c.parse();
  });

While this adds slightly more work, it makes custom error handling significantly more flexible, including where and how parsing occurs.

By default, we will want to parse all inputs at once. However, at times we may want to parse parts of the input individually, which we can do like so.

// ...
const params = await c.parse("params");
// ...

Schema Library Support

Webroute is agnostic to schema validation library, meaning you can continue using most popular schema libraries.

The below examples will use zod.

Path Params

Path parameters are defined in the route path. We can validate these parameters by supplying a .params() schema.

const PathParams = z.object({
  id: z.number({ coerce: true }),
});
 
route("/user/:id")
  .params(PathParams)
  .handle(async (req, c) => {
    const { 
const id: numberid } = await c.parse("params");
  });

Inference

Path parameters are also automatically inferred as type string. This means we have some type-safety without providing any explicit schema.

route("/user/:id")
  // No params defined, still some type-safety
  .handle(async (req, c) => {
    const { 
const id: stringid } = await c.parse("params");
  });

Query Params

Query params are typically used for secondary or optional data. They can be declared similar to path params.

const QueryParams = z.object({
  limit: z.number({ coerce: true }).optional(),
});
 
route()
  .query(QueryParams)
  .handle(async (req, c) => {
    const { 
const limit: number | undefinedlimit } = await c.parse("query");
  });

Request Headers

Some routes may require headers, which we can specify via .headers().

const AuthHeaders = z.object({
  Authorization: z.string().regex(/Bearer [a-zA-Z0-9]+/),
});
 
route()
  .headers(AuthHeaders)
  .handle(async (req, { parse }) => {
    const { 
const Authorization: stringAuthorization } = await parse("headers");
  });

Request Body

We can specify request body schema using .body().

 
route()
  .body(z.object({ email: z.string().email() }))
  .handle(async (req, { parse }) => {
    const 
const body: {
    email: string;
}body = await parse("body");
  });

Output (response)

In addition to validating whether our output is the correct shape, we often want to add, remove or format the response data. The .output() method allows specifying schema to do exactly that.

 
const MoneyAmountResult = z.object({
  amount: z.number().transform(formatMoney),
});
 
route("/balance")
  .method("get")
  .output(MoneyAmountResult)
  .handle(() => {
    return { amount: 1_000_000 };
    // <- "1,000,000"
  });

Skipping Output Parsing

Returning a Response from a handler will skip any validation. While returned data is treated as JSON, a Response is returned to the user as is (with the exception of any middleware effects).