Validation

defineHandler wraps a route handler to add schema validation and type inference. It accepts any library that implements the Standard Schema spec — Zod, Valibot, and ArkType all work out of the box.

Basic usage

import { defineHandler } from 'lacis'
import { z } from 'zod'

export const GET = defineHandler({
  params: z.object({ id: z.string().uuid() }),
  query: z.object({ verbose: z.coerce.boolean().optional() }),
  meta: { summary: 'Get user by ID', tags: ['users'] },
  handler: async (req, res) => {
    req.params.id      // string — validated and typed
    req.query.verbose  // boolean | undefined — validated and typed
    res.json({ id: req.params.id })
  },
})

The return value is a plain async function — export it like any other route handler.

Configuration fields

params, query, body

Each field accepts a Standard Schema. Schemas are validated in order: params first, then query, then body. If any fails, Lacis returns 400 immediately.

• params — validated against req.params (URL path parameters)
• query — validated against req.query (parsed query string)
• body — Lacis calls req.json() internally and validates the result

meta

Attached to the OpenAPI operation when the spec is generated. No effect at request time.

meta: {
  summary: 'Create user',
  description: 'Creates a new user account.',
  tags: ['users'],
  deprecated: false,
}

responses

A map of status code → Standard Schema. Declaring it does two things from one source of truth: it types the handler’s res (see Typed responses) and it feeds the OpenAPI spec.

responses: {
  200: z.object({ id: z.string(), name: z.string() }),
  404: z.object({ error: z.string() }),
}

use

Per-route, per-method middleware — runs after path +middleware, before the handler. See Per-route middleware.

use: [rateLimit, auth]

handler

The actual request handler with fully typed req and res.

Validation errors

When validation fails, Lacis sends a 400 automatically:

{
  "error": "Validation failed",
  "issues": [
    { "message": "Invalid uuid", "path": ["id"] }
  ]
}

The handler is never called when validation fails.

Query coercion

Query strings are always strings. Use your validator’s coercion utilities:

Zod

query: z.object({
  page: z.coerce.number().int().positive(),
  active: z.coerce.boolean().optional(),
})

Valibot

import * as v from 'valibot'

query: v.object({
  page: v.pipe(v.string(), v.transform(Number), v.integer()),
  active: v.optional(v.pipe(v.string(), v.transform((s) => s === 'true'))),
})

ArkType

import { type } from 'arktype'

query: type({ page: 'number.integer > 0', 'active?': 'boolean' })

Body validation

Zod

import { defineHandler } from 'lacis'
import { z } from 'zod'

export const POST = defineHandler({
  body: z.object({
    name: z.string().min(1),
    email: z.string().email(),
  }),
  meta: { summary: 'Create user', tags: ['users'] },
  handler: async (req, res) => {
    const { name, email } = req.body  // fully typed
    res.status(201).json({ name, email })
  },
})

Valibot

import { defineHandler } from 'lacis'
import * as v from 'valibot'

export const POST = defineHandler({
  body: v.object({
    name: v.pipe(v.string(), v.minLength(1)),
    email: v.pipe(v.string(), v.email()),
  }),
  meta: { summary: 'Create user', tags: ['users'] },
  handler: async (req, res) => {
    const { name, email } = req.body
    res.status(201).json({ name, email })
  },
})

ArkType

import { defineHandler } from 'lacis'
import { type } from 'arktype'

export const POST = defineHandler({
  body: type({ name: 'string > 0', email: 'string.email' }),
  meta: { summary: 'Create user', tags: ['users'] },
  handler: async (req, res) => {
    const { name, email } = req.body
    res.status(201).json({ name, email })
  },
})

Combined schemas

export const PUT = defineHandler({
  params: z.object({ id: z.string().uuid() }),
  query: z.object({ dryRun: z.coerce.boolean().default(false) }),
  body: z.object({ name: z.string(), email: z.string().email() }),
  handler: async (req, res) => {
    if (req.query.dryRun) return res.json({ ok: true, dry: true })
    res.json({ id: req.params.id, ...req.body })
  },
})

Typed responses

When you declare responses, the output side becomes type-safe too: res.status(code).json(data) only accepts the schema declared for that status code. It’s opt-in and non-breaking — without responses, res stays the regular Response.

export const GET = defineHandler({
  responses: {
    200: z.object({ id: z.string(), name: z.string() }),
    404: z.object({ error: z.string() }),
  },
  handler: async (req, res) => {
    res.status(200).json({ id: '1', name: 'Ada' })  // ✓ matches the 200 schema
    res.status(404).json({ id: 1 })                 // ✗ type error — 404 wants { error: string }
  },
})

Escape hatch

res.raw is the untyped Response for streaming or edge cases: res.raw.json(anything).

Dev-only runtime check (configurable)

By default, in non-production (NODE_ENV !== 'production') a returned body that violates its declared schema fails loudly — types don’t catch an any coming from the database — and there is zero response validation in production (for performance).

A violation surfaces as a 500 Internal Server Error, not a 400: it signals a server-side bug (you returned the wrong shape), not bad client input. One caveat — enforcement is asymmetric by validator kind: a synchronous schema throws (→ 500), while an async schema can only log the mismatch with console.error (the response has already been written by the time it resolves).

Override it per route with validateResponses:

defineHandler({
  responses: { 200: UserSchema },
  validateResponses: true,   // enforce in production too
  // validateResponses: false // or disable entirely, even in dev
  handler: async (req, res) => res.status(200).json(user),
})

Type inference

TypeScript infers the output types of your schemas. Change a schema, and the types in handler update automatically — no manual annotations needed.