Skip to content

Cookbook ​

Receitas do mundo real que não cabem no quickstart. Cada receita resolve um problema comum com código pronto para copiar e colar que espelha os apps de exemplo executáveis — examples/hello (mínimo) e examples/shop (scoped transactions, filtragem de queries).

Receitas ​

ReceitaProblema que resolve
Autenticação e autorizaçãoIdentificar quem chama e expô-lo aos handlers via um scoped slot, e então autorizar rotas por role ou claim.
Acesso a banco de dadosCompartilhar um cliente de vida longa (db, cache, mailer) entre handlers via um singleton slot, e uma camada de serviço pura que você pode testar de forma unitária.
Erros e validaçãoRetornar respostas 4xx corretas e entender os envelopes automáticos 422 / 500 do Kata.
LoggingCorrelacionar uma linha de log da camada de service com c.requestId passando um logger vinculado à requisição ao service como argumento.
Migrando do NestJSMapear cada bloco de construção do NestJS — controllers, providers, guards, pipes, DTOs — para seu equivalente funcional no Kata.
Non-goals e BYOVeja o que o Kata deliberadamente deixa por sua conta — persistência, rate limiting, métricas, env, paginação — e o padrão idiomático bring-your-own para cada um.

Como estas receitas são fundamentadas ​

Cada trecho é verificado contra a superfície real do framework, não parafraseado de memória:

Se uma receita mostra uma API, essa API existe hoje. Quando uma receita se apoia em algo planejado mas ainda não entregue, ela é rotulada como Planejado e linka para a issue de acompanhamento — nunca presuma que uma API planejada já funciona.

O context compartilhado ​

Cada receita se constrói sobre um arquivo. O Kata centraliza a injeção de dependência em uma única chamada defineContext({...}) (veja Context e DI e ADR-0004), e os helpers defineRoute / defineMiddleware / createApp que ela retorna são vinculados a esse context. A configuração idiomática os re-exporta para que o resto do app importe de ./context, nunca de @katajs-framework/core diretamente:

ts
// src/context.ts
import { defineContext, scoped, singleton } from '@katajs-framework/core'

import { makeDb } from './db'
import type { User } from './modules/users/users.schema'

export const k = defineContext({
  // singletons — uma instância para o processo inteiro (veja /pt/cookbook/database)
  db: singleton(makeDb(process.env)),
  // scoped slots — um valor por requisição, definido por um middleware (veja /pt/cookbook/auth)
  currentUser: scoped<User>(),
})

// Vincula os helpers a este context, depois os importa em todos os outros lugares.
export const { defineRoute, defineMiddleware, createApp } = k

export type AppRegistry = typeof k.registry
ts
// src/main.ts
import { serve } from '@hono/node-server'

import { createApp } from './context'
import * as users from './modules/users/users.route'

const app = createApp({ modules: [users] })

serve({ fetch: app.fetch, port: Number(process.env.PORT ?? 3000) })

Cada module passado para createApp é um arquivo *.route.ts importado com import * as; o Kata registra cada route que ele exporta. Veja App e createApp para a assinatura completa.

Convenções que toda receita segue ​

Estas são impostas em todo o projeto — os trechos as obedecem para que você possa colá-los:

  • Apenas funcional — sem classes, sem decorators (ADR-0002).
  • Apenas named exports — sem default exports.
  • Sem any — use unknown mais narrowing.
  • Schemas vivem em <domain>.schema.ts, nunca inline numa route (ADR-0005).
  • Toda route declara schemas de input e output (ADR-0003).
  • DI passa por c.get('key'), onde 'key' precisa estar registrada em defineContext (ADR-0004).

API planejada referenciada neste cookbook ​

Nenhuma receita depende hoje de API que exista só no roadmap — toda superfície mostrada já está publicada. A única superfície antes rastreada aqui, o middleware de nível de app (global) de primeira classe (#84, ADR-0012), foi entregue como a opção middlewares de createApp — veja Não-objetivos & BYO para como as receitas a usam.

Também entregues — documentadas como API disponível nestas receitas: o helper unificado c.error + envelope de erro (#18, ADR-0008), o error boundary global (#62), o modo de validação de output (#17, ADR-0009) e os schemas de output multi-status (#19, ADR-0011).

Leia a reference junto com as receitas

O cookbook é orientado a tarefas. Para a assinatura exaustiva de cada helper, veja a reference: defineContext, defineRoute, defineMiddleware, createApp, os middlewares embutidos e @katajs-framework/core/jwt.

Veja também ​

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