Skip to content

Referência da API ​

Kata distribui um único pacote, @katajs-framework/core, com três caminhos de import e um binário. Nada é re-exportado de Hono — a superfície pública é exatamente o que as tabelas abaixo listam, derivada dos próprios entry points do pacote.

ImportPropósito
@katajs-framework/coreNúcleo: a factory de contexto, os construtores de slot, o error envelope, os middlewares embutidos e todos os tipos públicos.
@katajs-framework/core/jwtPrimitivas JWT stateless mais o middleware jwtAuth e os guards de autorização.
@katajs-framework/core/nodegracefulShutdown exclusivo de Node, para drenar um servidor em SIGTERM / SIGINT.
kata (bin)A CLI: kata init faz o scaffold de um app completo, kata new adiciona um módulo, kata verify roda as regras de lint.
ts
import { defineContext, scoped, singleton } from '@katajs-framework/core'
import { jwtAuth, requireRole, signJwt } from '@katajs-framework/core/jwt'
import { gracefulShutdown } from '@katajs-framework/core/node'

A divisão é deliberada: @katajs-framework/core é neutro em relação ao runtime e roda onde quer que Hono rode (Node, Bun, Deno, edge), @katajs-framework/core/jwt é o único módulo que toca hono/jwt, e @katajs-framework/core/node é o único módulo que toca node:process — assim, um build edge que importa @katajs-framework/core nunca puxa internals do Node.

Dependências peer ​

Kata declara duas dependências peer. Instale-as junto com @katajs-framework/core; ele não empacota nenhuma das duas.

json
{
  "peerDependencies": {
    "hono": "^4",
    "zod": "^3"
  }
}
PeerFaixaUsada para
hono^4O router, o contexto, os adaptadores de runtime e o cliente RPC tipado (hc).
zod^3Cada schema de input / output e os schemas de claims em @katajs-framework/core/jwt.

@katajs-framework/core — núcleo ​

Valores:

ExportTipoPropósito
defineContextfunçãoO registry de DI único. Recebe um registry de slots e retorna { registry, defineRoute, defineMiddleware, createApp }, todos ligados a ele.
singletonfunçãosingleton(value) — declara um slot com tempo de vida do processo, guardando value.
scopedfunçãoscoped<T>() — declara um slot por request do tipo T, preenchido por um middleware.
corsfunçãoMiddleware de CORS embutido.
secureHeadersfunçãoMiddleware de headers de segurança embutido.
bodyLimitfunçãoMiddleware embutido de limite de tamanho do corpo da request.
fromHonoTransformfunçãoAdapta um middleware do Hono que transforma a resposta (compress, etag) para que ele possa reescrever o corpo final da resposta do kata.
DEFAULT_MAX_BODY_SIZEconstO teto de bytes padrão que bodyLimit aplica quando nenhum maxBytes é informado.
buildErrorBodyfunçãoConstrói o error envelope unificado (ADR-0008) como um objeto plano — { error, message, issues? }.
formatZodIssuesfunçãoConverte um ZodError no formato FieldIssue[] usado nos error envelopes.
ErrorBodySchemaschema ZodSchema Zod para o error envelope; declare-o atrás de um status 4xx/5xx em um mapa de output.
FieldIssueSchemaschema ZodSchema Zod para um issue de campo estruturado; compõe ErrorBodySchema.
REQUEST_ID_HEADERconstO header (x-request-id) do qual Kata lê um id de correlação de entrada e ecoa de volta.

Tipos:

ExportPropósito
AppConfigO objeto que createApp aceita (modules, middlewares?, requestLogging?, outputValidation?).
RouteUm valor de route produzido por defineRoute.
ModuleUm record de routes nomeadas — o que um import * as de um arquivo *.route.ts produz.
MiddlewareUm valor de middleware produzido por defineMiddleware.
MiddlewareContextO c passado a um handler de middleware (get, set, header, json, error, raw, requestId).
RouteContextO c passado a um handler de route (get, input, json, error, raw, requestId).
HttpMethodOs métodos suportados: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'.
InputSchemasO formato de input: { params?, query?, body?, headers? } de schemas Zod.
InferInputO z.infer de um InputSchemas, como exposto em c.input.
OutputSpecO output de uma route: um único schema Zod ou um OutputMap.
OutputMapUm mapa status-code → schema Zod, ex.: { 200: X, 404: Y }.
SuccessOutputO tipo do corpo 200 que um handler pode retornar como valor plano.
RouteHandlerReturnO que um handler pode retornar: SuccessOutput ou um Response.
RegistryO tipo de registry que defineContext aceita — um record de Slots.
SlotUm Singleton<unknown> ou Scoped<unknown>.
SingletonUm tipo de slot singleton.
ScopedUm tipo de slot scoped.
SingletonKeysAs chaves singleton de um registry.
ScopedKeysAs chaves scoped de um registry — as únicas chaves que um middleware pode provides/set.
ResolvedValueO tipo de valor para o qual um slot resolve via c.get.
LoggerO formato de logger estruturado que um singleton logger pode satisfazer para logging por request. extra.err chega pré-achatado como um SerializedError, nunca um Error bruto.
SerializedErrorO espelho de dados puros de um Error — { name, message, stack?, cause?, errors? } — que logger.error recebe sob extra.err.
LogExtraO tipo do payload extra de todo método de Logger: aberto (Record<string, unknown>), com a chave reservada err tipada como SerializedError.
RequestLogFieldsO registro por requisição que requestLogging passa como extra: { requestId, method, path, status, durationMs }. Veja createApp.
OutputValidationMode'strict' | 'log' | 'off' — como uma divergência de output-schema é tratada (ADR-0009).
ErrorBodyO tipo do objeto error-envelope: { error, message, issues? }.
ErrorExtraOs extras opcionais para c.error / buildErrorBody: { status?, issues? }.
FieldIssueUm erro de campo estruturado: { path, message, code, expected?, received? }.
FieldIssuesRecord<string, FieldIssue[]>, chaveado pela origem do input.
KataAppO tipo paramétrico do app Hono que createApp retorna — export type AppType = KataApp<typeof modules> alimenta o cliente RPC.
RpcModuleA projeção relevante para o wire de um módulo, usada pela ponte de tipos RPC.
ModulesToHonoSchemaO Schema RPC do Hono derivado de uma tupla de módulos.

Tipos de opções dos middlewares embutidos — CorsOptions, SecureHeadersOptions e BodyLimitOptions — também são exportados. Veja Middleware para os campos deles.

@katajs-framework/core/jwt — auth ​

Valores:

ExportTipoPropósito
signJwtfunçãosignJwt(claims, options) — assina um objeto de claims em um JWT compacto. Carimba iat; options define os claims registrados (exp, nbf, iss, aud, sub).
verifyJwtfunçãoverifyJwt(token, options) — verifica a assinatura + os claims de tempo, depois faz o parse do payload através de options.claims. Retorna um Result, nunca lança.
jwtAuthfunçãoConstrói um handler de middleware que lê Authorization: Bearer <token>, o verifica e escreve os claims (ou um usuário vindo de resolve) em um slot scoped. Envolva com defineMiddleware({ provides: [...] }).
guardfunçãoConstrói um handler de guard de autorização que lê um slot já provido e rejeita com um envelope 403 quando authorize retorna false.
requireRolefunçãoAçúcar sobre guard: permite apenas quando o role do valor do slot é (um d)os role(s) informado(s).
requireClaimfunçãoAçúcar sobre guard: permite apenas quando o claim do valor do slot em key é igual a expected (ou passa no predicado informado).

Tipos:

ExportPropósito
JwtAlgorithmOs algoritmos de assinatura suportados (HS*, RS*, PS*, ES*, EdDSA).
SignOptionsOpções para signJwt: secret, alg?, expiresInSeconds?, notBeforeSeconds?, issuer?, audience?, subject?.
VerifyOptionsOpções para verifyJwt: secret, claims, alg?, issuer?, audience?.
JwtVerifyResultO resultado de verifyJwt: { ok: true, claims } ou { ok: false, error }.
JwtErrorUma falha de verificação: { code, message, issues? }.
JwtErrorCode'invalid_token' | 'expired' | 'claims_mismatch'.
JwtAuthOptionsOpções para jwtAuth: secret, claims, slot?, alg?, issuer?, audience?, header?, resolve?.
GuardOptionsOpções para guard: slot?, authorize, code?, message?.

Você é dono do fluxo de login

@katajs-framework/core/jwt te dá assinatura, verificação, o middleware de auth e os guards. Hashing de senha, o store de usuários, a route de login e os refresh tokens continuam sendo seus. Veja o cookbook de Autenticação para o padrão completo.

@katajs-framework/core/node — runtime Node ​

Valores:

ExportTipoPropósito
gracefulShutdownfunçãogracefulShutdown(server, options) — captura sinais de término, para de aceitar conexões, drena as requests em andamento e então executa onClose.

Tipos:

ExportPropósito
ServerTypeO handle de servidor node:http / node:http2 que o serve() do @hono/node-server retorna.
GracefulShutdownOptionsOpções para gracefulShutdown: onClose, signals? (padrão ['SIGTERM', 'SIGINT']), timeoutMs? (padrão 10_000).

gracefulShutdown recebe o servidor, não o app: o app é o request handler, o servidor é dono do socket que precisa ter close() chamado para drenar. Opte por ele a partir do main.ts — createApp não instala nenhum signal handler.

kata — o bin ​

O pacote instala um binário kata com três comandos: kata init faz o scaffold de um projeto, kata new <domain> adiciona um módulo e kata verify roda as regras de lint.

bash
kata init [dir] [options]
OpçãoPropósito
-C, --cwd <dir>Diretório base para resolver [dir]. Padrão é o diretório atual.
--minimalEscreve só as configs do harness — sem app (para projetos existentes).
-f, --forceSobrescreve arquivos-fonte existentes (nunca os manifests/configs).
-h, --helpImprime o uso e sai.

Por padrão, kata init escreve um app completo e executável: o harness (.claude / .codex / .agents + AGENTS.md / CLAUDE.md / lefthook.yml), o layout src/ canônico com dois módulos de exemplo e — apenas se ausentes — package.json, tsconfig.json e as configs de lint. Veja A CLI para o passo a passo completo.

Páginas de referência ​

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