Skip to content

Rotas & schemas ​

Uma rota é uma única chamada a defineRoute. Nessa única chamada você declara tudo o que o framework precisa saber sobre um endpoint: seu método HTTP e path, o formato do que entra (in), o formato do que sai (out), uma cadeia opcional de middleware e o handler que faz o trabalho.

A regra principal é que tanto input quanto output são obrigatórios — omita qualquer um e é um erro de TypeScript, não algo que você descobre em produção (ADR-0003). O motivo é que o contrato de uma rota — o que ela aceita e o que ela retorna — nunca deve ser implícito. Ele é escrito, checado por tipos e (como você verá) imposto em runtime em ambas as pontas.

defineRoute vem do seu context, não de um import global. defineContext o retorna já vinculado ao seu registry (veja Context & DI), o que é o que permite que c.get('key') dentro do handler passe na checagem de tipos exatamente para os slots que você declarou.

ts
// src/modules/echo/echo.route.ts
import { defineRoute } from '../../context'

import { EchoBodySchema, EchoResponseSchema } from './echo.schema'

export const echoRoute = defineRoute({
  method: 'POST',
  path: '/echo',
  input: { body: EchoBodySchema },
  output: EchoResponseSchema,
  handler: (c) => ({ echoed: c.input.body.message }),
})

Um arquivo de rota contém chamadas a defineRoute e nada mais. Exporte cada rota como um const nomeado; createApp depois as coleta importando o arquivo .route.ts inteiro como um namespace, para que cada rota exportada seja captada automaticamente.

O formato de defineRoute ​

Aqui está o objeto completo, com a função de cada campo:

ts
defineRoute({
  method,   // 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
  path,     // uma string de path do Hono, ex.: '/users/:id'
  input,    // { params?, query?, body?, headers? } — cada um um schema Zod
  output,   // um único schema Zod OU um map status→schema
  use,      // opcional: Middleware[] que roda antes do handler desta rota
  handler,  // (c) => value | c.json(...) | c.error(...)
})

method e path não são apenas strings para o sistema de tipos — eles são inferidos como tipos literais e fluem até o cliente RPC, para que um chamador saiba que este é um POST /echo e nada mais. use assume [] quando você o omite; qualquer middleware de nível de app registrado em createApp roda antes da cadeia use: da própria rota (veja Middleware de app).

Path matching e precedência ​

Rotas casam em ordem de registro, não por especificidade. createApp percorre modules na ordem do array, e dentro de cada módulo percorre os exports do arquivo de rota na ordem das chaves do objeto; cada rota é registrada no router Hono subjacente nessa sequência exata, e o Hono casa na ordem de registro — um segmento estático não vence :param só por ser mais específico (prioridade de roteamento do Hono).

Isso significa que esta ordenação é um bug esperando para acontecer:

ts
export const getTeamRoute = defineRoute({ method: 'GET', path: '/teams/:id', /* ... */ })
export const getMyTeamRoute = defineRoute({ method: 'GET', path: '/teams/me', /* ... */ })

Uma requisição a GET /teams/me casa com getTeamRoute primeiro — :id se liga à string literal "me" — então getMyTeamRoute nunca roda. A mesma regra vale entre módulos: a ordem do array modules em createApp({ modules }) decide qual módulo registra suas rotas primeiro, então um GET /teams/:id adicionado depois por um módulo não relacionado pode sequestrar /teams/me silenciosamente.

A correção é registrar a rota estática mais específica primeiro, no mesmo módulo:

ts
export const getMyTeamRoute = defineRoute({ method: 'GET', path: '/teams/me', /* ... */ })
export const getTeamRoute = defineRoute({ method: 'GET', path: '/teams/:id', /* ... */ })

input — as quatro seções ​

Uma requisição HTTP não chega como uma coisa só. Seus dados vivem em quatro lugares diferentes, e input espelha exatamente esses quatro. Você fornece um schema Zod para cada seção que a rota realmente lê:

ts
type InputSchemas = {
  params?: z.ZodTypeAny
  query?: z.ZodTypeAny
  body?: z.ZodTypeAny
  headers?: z.ZodTypeAny
}

Você declara apenas as seções que a rota lê. Cada uma mapeia para uma parte da requisição:

SeçãoDe onde vem
paramsparâmetros de path (/users/:id)
querya query string da URL
bodyo corpo JSON da requisição parseado
headersheaders da requisição (em minúsculas)

Chaves de header são minúsculas

Nomes de header HTTP são case-insensitive, então o Kata converte toda chave de header recebida para minúsculas antes de validar. Por isso o seu schema de headers precisa usar chaves em minúsculas — z.object({ authorization: z.string() }), nunca Authorization. Um schema com a chave Authorization nunca casa, e a requisição falha na validação com 422.

Declarar uma seção faz dois trabalhos de uma vez só. Em runtime, o Kata valida essa parte da requisição contra o seu schema antes do handler rodar. Em tempo de compilação, ele tipa o campo correspondente em c.input — então dentro do handler c.input.params.id é uma string conhecida, não any. Uma seção que você não declarou é tipada como undefined em c.input, então ler c.input.query só passa na checagem de tipos quando você realmente declarou um schema query. Um único schema é a fonte da verdade tanto para a checagem em runtime quanto para o tipo estático; eles não podem divergir.

ts
// src/modules/users/users.route.ts
export const getUserRoute = defineRoute({
  method: 'GET',
  path: '/users/:id',
  input: { params: GetUserParamsSchema },
  output: { 200: UserSchema, 404: ErrorBodySchema },
  handler: async (c) => {
    const user = await getUser(c.input.params.id) // string, tipado
    if (!user) return c.error('not_found', 'User not found', { status: 404 })
    return user
  },
})

Uma rota que não lê nenhuma das quatro seções ainda declara input — como um objeto vazio:

ts
export const requestIdRoute = defineRoute({
  method: 'GET',
  path: '/request-id',
  input: {},
  output: RequestIdResponseSchema,
  handler: (c) => ({ requestId: c.requestId }),
})

TIP

input: {} não é ruído de boilerplate — é o contrato declarando, em voz alta, "esta rota não lê input". A regra de lint kata/no-route-without-input-schema exige que ele esteja presente e explícito, para que "eu esqueci de pensar no input" e "esta rota genuinamente não tem nenhum" nunca pareçam iguais no código fonte.

(c.input aqui é o objeto de input validado, e c.requestId é um id de correlação por requisição — ambos ficam pendurados no mesmo objeto de contexto c introduzido em Context & DI.)

Filtros opcionais em query: a armadilha do z.coerce.boolean() ​

Uma rota de listagem com um filtro booleano opcional — GET /todos?completed=true — é uma das formas mais comuns de query, e ela esconde uma armadilha. Uma query string é sempre texto, esteja presente ou não, então um campo booleano opcional precisa converter "true" / "false" em um boolean de verdade — e a forma óbvia de escrever isso está errada:

ts
// Parece certo, não é:
completed: z.coerce.boolean().optional()

z.coerce.boolean() executa Boolean(value) por baixo dos panos, e em JavaScript Boolean("false") é true — qualquer string não vazia converte para true, incluindo o texto literal "false". Esse schema trata ?completed=false e ?completed=true como a mesma requisição, e não há erro de validação para pegar isso — simplesmente significa "true" silenciosamente, nos dois casos.

A correção é validar as duas strings literais que a query string pode de fato carregar, e então transformar em boolean, em vez de coagir:

ts
// src/modules/todos/todos.schema.ts
import { z } from 'zod'

export const ListTodosQuerySchema = z.object({
  completed: z
    .enum(['true', 'false'])
    .optional()
    .transform((v) => (v === undefined ? undefined : v === 'true')),
})
ts
// src/modules/todos/todos.route.ts
import { defineRoute } from '../../context'

import { ListTodosQuerySchema, TodoListSchema } from './todos.schema'
import { listTodos } from './todos.service'

export const listTodosRoute = defineRoute({
  method: 'GET',
  path: '/todos',
  input: { query: ListTodosQuerySchema },
  output: TodoListSchema,
  handler: (c) => listTodos(c.get('store'), c.input.query.completed),
})

c.input.query.completed é tipado como boolean | undefined — omitir ?completed= deixa o filtro desligado, ?completed=true / ?completed=false o definem corretamente, e qualquer outro valor (?completed=yes, ?completed=1) falha na validação de input com o 422 de sempre, em vez de silenciosamente resolver para true.

Isso é comportamento do Zod, não do Kata

z.coerce.boolean() é documentado para funcionar exatamente assim — é coerção via Boolean(...), não um parser de strings truthy/falsy. É uma escolha razoável para um valor que você já confia ser "true"/"false"/ausente (uma flag de config interna, por exemplo), mas uma query string é input do usuário, então prefira o padrão z.enum(...).transform(...) acima sempre que o texto do campo deva ser exatamente "true" ou "false".

output — schema único ou map de status ​

output descreve o que a rota tem permissão para enviar de volta. Ele assume uma de duas formas:

ts
type OutputMap = { readonly [status: number]: z.ZodTypeAny }
type OutputSpec = z.ZodTypeAny | OutputMap

Schema único ​

A forma de schema único descreve o corpo de sucesso 200 — o caso comum, para uma rota com apenas um formato de caminho feliz:

ts
export const createUserRoute = defineRoute({
  method: 'POST',
  path: '/users',
  input: { body: CreateUserBodySchema },
  output: UserSchema,
  handler: async (c) => createUser(c.input.body),
})

Qualquer schema Zod nomeado é uma entrada válida, inclusive uma lista — output: TodoListSchema acima é exatamente z.array(TodoSchema), com um nome e declarado em <domain>.schema.ts como qualquer outro DTO (ADR-0005). output nunca distingue um schema de objeto de um schema de array; ele apenas valida o valor retornado pelo handler contra o schema que você fornecer.

Map de status para schema ​

Recorra à forma de map quando uma rota responde a mais de um status e você quer que cada um deles seja tipado e validado — digamos um corpo de sucesso 200 e um envelope de erro 404 (ADR-0011):

ts
import { ErrorBodySchema } from '@katajs-framework/core'

output: { 200: UserSchema, 404: ErrorBodySchema }

ErrorBodySchema é exportado de @katajs-framework/core. É o espelho Zod do envelope de erro unificado que c.error(...) produz (veja Erros), o que o torna o schema canônico para colocar atrás de qualquer status 4xx/5xx. Quando quiser um contrato mais apertado, substitua-o por um refinamento mais estrito — por exemplo, travando error em um código literal.

Como o Kata escolhe contra qual status validar

Esta é a regra que liga um valor de retorno a um código de status:

  • Um return simples é sempre o corpo 200. O Kata o valida contra o schema único, ou contra output[200] em um map.
  • Todo outro status é um que você define explicitamente, com c.json(body, status) ou c.error(...).

Então um map do qual você retorna valores simples precisa incluir uma entrada 200. Se não incluir, o tipo de return simples colapsa para never, e o TypeScript força você a retornar um Response em vez disso — o que é exatamente o certo para, digamos, uma rota de criação que só responde 201.

A forma de map é totalmente retrocompatível: uma rota escrita com um único output: Schema compila e se comporta exatamente como antes.

O handler ​

O handler é a função que roda a requisição. Ele recebe o contexto c e retorna uma de duas coisas — e qual você retorna decide como o Kata constrói a resposta:

  • Um valor simples — o caminho de sucesso. O Kata o valida contra o schema de sucesso, aplica quaisquer transforms do Zod e o serializa como uma resposta JSON 200. Este é o caso que você escreverá com mais frequência.
  • Um Response — o caminho explícito, para qualquer status além de um simples 200. Você o constrói com c.json(value, status?) ou c.error(code, message, extra?).
ts
json<T>(value: T, status?: number): Response
error(code: string, message: string, extra?: ErrorExtra): Response

c.json assume status 200 por padrão. c.error produz o envelope de erro unificado e assume status 400 por padrão; seu terceiro argumento define qualquer outra coisa:

ts
type ErrorExtra = {
  status?: number      // status HTTP; padrão 400
  issues?: FieldIssues // erros de campo estruturados, anexados sob `issues`
}

(c.json e c.error são os construtores de resposta em c; o envelope que c.error emite é documentado em detalhes em Erros.)

Validando um Response ​

Retornar um Response pula o caminho de sucesso de valor simples — então o que acontece com seu corpo depende de qual forma de output você usou:

  • Forma de map, e o status da resposta é uma chave declarada → O Kata valida um clone do corpo contra output[status], depois encaminha seu Response original inalterado assim que ele passar.
  • Forma de schema único, ou qualquer status que o map não declare → o Response passa direto sem validação.

Veja ADR-0011 para a semântica exata.

Respostas não-JSON: raw() ​

Todos os exemplos até aqui respondem com JSON. Uma route que serve outra coisa — um export CSV, um arquivo de texto puro, um download — constrói o Response ela mesma, já que um return simples só produz JSON. Declare esse contrato com raw() em vez de um schema Zod:

ts
import { raw } from '@katajs-framework/core'

export const usersCsvRoute = defineRoute({
  method: 'GET',
  path: '/users.csv',
  input: {},
  output: raw('text/csv', UsersCsvSchema), // UsersCsvSchema = z.string()
  handler: async () => {
    const users = await listUsers()
    return new Response(usersToCsv(users), { headers: { 'content-type': 'text/csv' } })
  },
})

raw(contentType, schema) declara duas coisas: o content-type da resposta e um schema para o corpo em texto (não JSON — o schema.safeParse roda contra a string crua). Só um Response satisfaz uma entrada raw — não existe equivalente de valor simples —, então o RouteHandlerReturn transforma qualquer outro retorno em erro de tsc.

Em runtime, o Kata checa o status declarado do mesmo jeito que checa uma entrada JSON (Validando um Response, acima), com uma diferença no que é checado e quando:

  • O header content-type é sempre comparado com o declarado (ignorando parâmetros como ; charset=utf-8) sempre que a validação de output não estiver em off — é barato, só uma leitura de header.
  • O corpo em texto é comparado com o schema apenas no modo strict. Checá-lo exige um response.clone().text(), que carrega o corpo inteiro na memória — tudo bem para uma resposta pequena em dev/CI, mas não é algo que o Kata vá fazer com um download grande em log (o padrão de produção). Uma route com uma entrada raw() emite um warning no startup quando o modo resolvido significa que o corpo dela ficará sem validação, para que esse trade-off nunca seja silencioso.

De um jeito ou de outro, um descasamento segue o mesmo modo de validação de output de um descasamento em JSON: strict troca a resposta pelo envelope 500 internal_output_shape_mismatch, log registra e serve a resposta original mesmo assim, off pula as duas checagens por completo.

O raw() também acerta o cliente RPC: o hc<typeof app> lê o outputFormat da entrada declarada, então a resposta do cliente para um endpoint raw() expõe um .text() tipado em vez de .json() — chamar .json() nela é erro de tipo, não surpresa em runtime.

Além dos construtores de resposta, o contexto entrega ao handler c.get(key) para suas dependências registradas (veja Context & DI), c.requestId para o id de correlação, e c.raw — o contexto Hono subjacente, uma escape hatch para a rara coisa que o Kata não encapsula.

204 No Content ​

output é obrigatório em toda rota (ADR-0003), mas uma resposta 204 não carrega corpo nenhum, por definição — o HTTP proíbe isso. As duas exigências não colidem de fato: declare a forma de map com uma entrada 204 e retorne a resposta sem corpo com c.json, sem precisar de nenhuma mudança no framework.

ts
// src/modules/things/things.schema.ts
export const NoContentSchema = z.void()
ts
// src/modules/things/things.route.ts
import { NoContentSchema } from './things.schema'

export const deleteThingRoute = defineRoute({
  method: 'DELETE',
  path: '/things/:id',
  input: { params: DeleteThingParamsSchema },
  output: { 204: NoContentSchema },
  handler: (c) => {
    deleteThing(c.get('store'), c.input.params.id)
    return c.json(undefined, 204) // não precisa de cast — veja abaixo
  },
})

Duas coisas fazem isso funcionar, nenhuma delas um caso especial para 204:

  • Sem chave 200, então SuccessOutput é never. Assim como o quadro informativo acima diz, um map sem entrada 200 força o handler a retornar um Response — não existe atalho de valor simples, nem mesmo para 204.
  • c.json(undefined, 204) não envia corpo, e não precisa de cast. O parâmetro de tipo genérico de c.json não tem restrição, então undefined é um argumento válido. JSON.stringify(undefined) avalia para o valor undefined, não para a string "undefined" — e passar undefined como corpo de um Response é o mesmo que não passar corpo nenhum. Essa distinção importa aqui porque o construtor Response do Fetch lança um erro se um corpo de verdade (mesmo '') for combinado com status: 204 — então c.json({ ok: true }, 204) falha no momento da requisição, enquanto c.json(undefined, 204) não falha.

Um schema em 204 documenta intenção — ele não é imposto

O Kata valida o corpo de um Response retornado lendo-o como JSON (response.clone().json()) e comparando o resultado com o schema declarado. Uma resposta 204 não tem nada para ler, então essa chamada lança um erro (Unexpected end of JSON input), e o fallback do Kata para um corpo ilegível — o mesmo que uma resposta em texto puro ou qualquer outra não-JSON aciona — é pular a validação e encaminhar a resposta inalterada. Na prática, output: { 204: NoContentSchema } nunca pode falhar sua checagem de formato, não importa qual schema esteja ali. Declare um mesmo assim: output continua obrigatório, e z.void() diz, no mesmo lugar que todo outro status, "esta resposta não tem nada dentro".

Se uma exclusão deve confirmar o que aconteceu em vez de retornar nada — o id que foi removido, uma flag deleted: true — modele-a como um corpo 200 comum:

ts
export const deleteThingRoute = defineRoute({
  method: 'DELETE',
  path: '/things/:id',
  input: { params: DeleteThingParamsSchema },
  output: { 200: DeleteConfirmationSchema }, // z.object({ id: z.string(), deleted: z.literal(true) })
  handler: (c) => {
    deleteThing(c.get('store'), c.input.params.id)
    return { id: c.input.params.id, deleted: true as const }
  },
})

Ambas as formas são legítimas — 204 serve a um cliente que só precisa do código de status, 200 { id, deleted: true } serve a um que quer confirmação no corpo. Escolha a que os chamadores da sua API precisam; o Kata valida qualquer uma da mesma forma.

Validação, em ambas as pontas ​

Junte as duas metades e você tem a promessa central do Kata: uma rota é checada na entrada e na saída (ADR-0003).

Na entrada. Se a requisição falhar no seu schema de input, o handler nunca roda. O Kata responde 422 com um envelope fixo: error: "validation_failed", uma message e um objeto issues indexado pela seção que falhou, cada uma contendo um array de issues de campo:

json
{
  "error": "validation_failed",
  "message": "Request input validation failed",
  "issues": {
    "body": [
      { "path": "name",  "code": "too_small",      "message": "String must contain at least 1 character(s)" },
      { "path": "email", "code": "invalid_string", "message": "Invalid email" }
    ]
  }
}

Cada issue de campo é { path, message, code }, com expected / received opcionais para incompatibilidades de tipo. path usa notação de ponto/colchete para campos aninhados (address.zip, tags[0]), de forma que um cliente pode mapear um erro diretamente de volta ao campo que o causou.

Na saída. Se um return simples não corresponde ao seu schema de output, o Kata responde 500 { "error": "internal_output_shape_mismatch" } e loga as issues Zod ofensoras no lado do servidor — o formato errado nunca chega ao cliente. Esse é o comportamento strict (o padrão fora de produção); o modo de validação de output decide se uma incompatibilidade gera 500, loga e serve mesmo assim, ou é ignorada completamente.

Veja Erros para a referência completa do envelope e como retornar seu próprio 4xx.

Schemas vivem em <domain>.schema.ts ​

Uma regra de layout surge aqui: schemas nunca são declarados inline em um arquivo .route.ts. Os schemas Zod de cada domínio vivem em src/modules/<domain>/<domain>.schema.ts, e rotas os importam pelo nome (ADR-0005). Um z.object(...) inline em um arquivo de rota é um erro de lint (kata/inline-schema).

Isso não é organização apenas por capricho. Puxar schemas para o seu próprio arquivo é o que permite que uma rota e o seu service compartilhem exatamente o mesmo tipo, e mantém cada DTO localizável de duas maneiras: por glob (src/modules/**/*.schema.ts) e por busca exata de símbolo (grep "UserSchema").

ts
// src/modules/users/users.schema.ts
import { z } from 'zod'

export const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string().email(),
})

export const CreateUserBodySchema = z.object({
  name: z.string().min(1),
  email: z.string().email(),
})

export const GetUserParamsSchema = z.object({
  id: z.string(),
})

export type User = z.infer<typeof UserSchema>
export type CreateUserBody = z.infer<typeof CreateUserBodySchema>
ts
// src/modules/users/users.route.ts
import { ErrorBodySchema } from '@katajs-framework/core'

import { defineRoute } from '../../context'

import { CreateUserBodySchema, GetUserParamsSchema, UserSchema } from './users.schema'
import { createUser, getUser } from './users.service'

Duas convenções de nomenclatura mantêm isso consistente:

  • *Schema para os próprios schemas Zod.
  • Um tipo * correspondente (ex.: User, CreateUserBody) inferido via z.infer, declarado logo ao lado do seu schema.

Como o tipo é inferido a partir do schema, os dois nunca podem divergir — e o service permanece uma função pura sobre esses tipos inferidos, sem imports de framework:

ts
// src/modules/users/users.service.ts
import type { CreateUserBody, User } from './users.schema'

export async function createUser(input: CreateUserBody): Promise<User> {
  const id = crypto.randomUUID()
  const user: User = { id, ...input }
  return user
}

Veja também ​

Código aberto — licença a definir. Feito com Hono + Zod.