Receita: Acesso a banco de dados
Problema: abrir uma conexão de banco de dados (ou qualquer cliente de vida longa — cache, mailer, fila) uma única vez e alcançá-la a partir de qualquer handler sem recriá-la por requisição nem recorrer a um global no nível do módulo.
Padrão: um slot singleton em defineContext. Conforme o ADR-0004, singletons vivem durante todo o tempo de vida do processo; c.get('db') retorna a mesma instância em toda requisição, de forma síncrona e totalmente tipada.
1. Defina um cliente tipado
Kata é funcional — sem classes, sem decorators (ADR-0002). Modele o cliente como uma interface mais uma função factory. Mantenha a superfície pequena e concreta; any é proibido.
// src/db.ts
import type { User } from './modules/users/users.schema'
export type Db = {
findUser: (id: string) => Promise<User | null>
insertUser: (user: User) => Promise<void>
// Libere o pool de conexões no shutdown — veja "Fechando o pool no shutdown".
close: () => Promise<void>
}
export function makeDb(env: NodeJS.ProcessEnv): Db {
// Troque este store em memória pelo seu driver real (node-postgres, Drizzle,
// Prisma, …). `env` é lido uma vez, aqui — não dentro dos handlers.
void env
const store = new Map<string, User>()
return {
findUser: async (id) => store.get(id) ?? null,
insertUser: async (user) => {
store.set(user.id, user)
},
// Um driver real aguarda `pool.end()` aqui; o stub em memória não tem nada a liberar.
close: async () => {},
}
}2. Registre-o como singleton
singleton(value) envolve uma instância pronta para uso. A factory executa quando o módulo que define o contexto é avaliado pela primeira vez, então a conexão é estabelecida uma única vez na inicialização.
// 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({
db: singleton(makeDb(process.env)),
currentUser: scoped<User>(),
})
export const { defineRoute, defineMiddleware, createApp } = k3. Leia-o num handler, passe-o a um serviço puro
Resolva o cliente no handler da rota com c.get('db'), depois entregue-o a uma função de serviço. Manter o serviço puro — ele recebe db como argumento em vez de importar o contexto — é o que o torna testável de forma unitária sem subir um servidor HTTP (o layout em examples/hello mantém os serviços livres de imports de framework exatamente por essa razão).
// src/modules/users/users.service.ts
import type { Db } from '../../db'
import type { CreateUserBody, User } from './users.schema'
export async function findUser(db: Db, id: string): Promise<User | null> {
return db.findUser(id)
}
export async function createUser(db: Db, input: CreateUserBody): Promise<User> {
const user: User = { id: crypto.randomUUID(), ...input }
await db.insertUser(user)
return user
}// src/modules/users/users.schema.ts (adicione o schema de params aqui, nunca inline)
export const UserIdParamSchema = z.object({ id: z.string() })// src/modules/users/users.route.ts
import { defineRoute } from '../../context'
import { CreateUserBodySchema, UserIdParamSchema, UserSchema } from './users.schema'
import { createUser, findUser } from './users.service'
export const getUserRoute = defineRoute({
method: 'GET',
path: '/users/:id',
input: { params: UserIdParamSchema },
output: UserSchema,
handler: async (c) => {
const user = await findUser(c.get('db'), c.input.params.id)
if (!user) return c.error('not_found', 'User not found', { status: 404 })
return user
},
})
export const createUserRoute = defineRoute({
method: 'POST',
path: '/users',
input: { body: CreateUserBodySchema },
output: UserSchema,
handler: async (c) => createUser(c.get('db'), c.input.body),
})Schemas são importados de
users.schema.ts, nunca escritos inline numa rota (ADR-0005).
4. Teste o serviço com um cliente falso
Como o serviço recebe db como parâmetro, um teste unitário passa um fake feito à mão — sem rede, sem contexto, sem Hono. Isso espelha users.test.ts.
// src/modules/users/users.test.ts
import { describe, expect, it } from 'vitest'
import type { Db } from '../../db'
import { findUser } from './users.service'
const fakeDb: Db = {
findUser: async (id) => (id === '1' ? { id: '1', name: 'Ada', email: 'ada@example.com' } : null),
insertUser: async () => {},
}
describe('users.service', () => {
it('findUser returns null for unknown ids', async () => {
expect(await findUser(fakeDb, 'nope')).toBeNull()
})
})5. Resete o singleton entre testes no nível HTTP
O falso acima funciona porque o serviço recebe db como parâmetro. Uma camada acima ele deixa de funcionar: um teste que dirige a app por app.request(...) — ou uma suíte .hurl contra um servidor vivo — passa pelo createApp real, então lê o singleton real. Singletons são ansiosos e valem para o processo inteiro, então as linhas que um teste escreveu continuam lá para o próximo, e a suíte passa a passar ou falhar conforme a ordem dos arquivos.
Não existe costura de injeção por teste, e isso é de propósito (ADR-0004): c.get('db') é monomórfico justamente porque nada pode trocá-lo por baixo. Então coloque a costura no próprio valor — um reset no Db, declarado como qualquer outro método:
// src/db.ts — estendendo o tipo do passo 1
export type Db = {
findUser: (id: string) => Promise<User | null>
insertUser: (user: User) => Promise<void>
close: () => Promise<void>
// Costura de teste: devolve o store ao vazio. Um driver de verdade reverte a
// transação que a suíte abriu, ou faz um truncate — mesma assinatura nos dois casos.
reset: () => Promise<void>
}
export function makeDb(env: NodeJS.ProcessEnv): Db {
void env
const store = new Map<string, User>()
return {
findUser: async (id) => store.get(id) ?? null,
insertUser: async (user) => {
store.set(user.id, user)
},
close: async () => {},
reset: async () => {
store.clear()
},
}
}Chame pelo k.resolve — o acessor exclusivo de singletons, que alcança exatamente a instância que todo handler vai ler. Essa suíte dirige o app através de app.request(...) em vez de testar um módulo isoladamente, então ela pertence à raiz de src/ — não dentro de src/modules/users/ — conforme Suítes de teste entre módulos e em nível de processo:
// src/users.http.test.ts
import { beforeEach, describe, expect, it } from 'vitest'
import { createApp, k } from './context'
import * as users from './modules/users/users.route'
const app = createApp({ modules: [users] })
beforeEach(async () => {
await k.resolve('db').reset()
})
describe('GET /users', () => {
it('começa de um store vazio em todo teste', async () => {
const res = await app.request('/users')
expect(await res.json()).toEqual([])
})
})Declarar reset no Db de fato o deixa ao alcance do código de produção — esse é o preço de não haver costura de injeção. Mantê-lo no tipo, em vez de escondido atrás de um cast, é a versão honesta: fica visível em db.ts, é tipado, e as proibições de kata/no-class e de any continuam intactas. O que ele nunca pode virar é um segundo caminho de escrita que a produção realmente chama.
Por que singleton, e não scoped
singleton(value) | scoped<T>() | |
|---|---|---|
| Tempo de vida | processo inteiro | uma requisição HTTP |
| Criado | uma vez, no defineContext | por um middleware, por requisição |
c.get retorna | a mesma instância sempre | o valor que o middleware definiu com set |
| Use para | db / cache / logger / mailer | usuário atual / tenant / id da requisição / tx ativa |
c.get('db') é monomórfico — sempre Db, nunca Promise<Db> ou Db | undefined — que é a propriedade de inferência que o ADR-0004 foi escolhido para preservar.
Estado de DB por requisição (transações)
Um pool de conexões é um singleton, mas uma transação é por requisição — então é um slot scoped, aberto e commitado por um middleware:
// context.ts: tx: scoped<Transaction>()
export const withTransaction = defineMiddleware({
provides: ['tx'] as const,
handler: async (c, next) => {
const tx = await c.get('db').begin()
c.set('tx', tx)
await next() // a fiação de commit/rollback vive aqui; veja a nota abaixo
},
})Um commit-no-sucesso / rollback-na-falha robusto depende do middleware enxergar o desfecho do handler — e a fronteira global de erros (#62) torna esse desfecho visível: envolva await next() num try/catch para fazer rollback (e relançar) num throw, e fazer rollback de qualquer transação que o handler deixou sem commit. O middleware de transação do examples/shop mostra o padrão completo.
Fechando o pool no shutdown
Um singleton é aberto uma vez na inicialização e vive durante todo o processo, então fechá-lo é uma preocupação de processo, não de cada requisição — não há hook de teardown por requisição em que pendurá-lo. Um app que ignora SIGTERM (um docker stop, uma rotação de pod do Kubernetes) é morto no meio do voo: requisições em andamento são descartadas e o pool nunca fecha. Conecte gracefulShutdown do subpath somente-Node @katajs-framework/core/node no main.ts — ele para de aceitar conexões, drena as requisições em andamento e então executa seu onClose (ADR-0014):
// src/main.ts
import { serve } from '@hono/node-server'
import { gracefulShutdown } from '@katajs-framework/core/node'
import { createApp, k } from './context'
import * as users from './modules/users/users.route'
const app = createApp({ modules: [users] })
const server = serve({ fetch: app.fetch, port: Number(process.env['PORT'] ?? 3000) })
gracefulShutdown(server, {
onClose: async () => {
await k.resolve('db').close() // fecha o pool *depois* do drain
},
})onClose executa depois do drain, então nenhum handler ativo perde seu pool no meio de uma query, e a ordem de teardown continua sua: sequencie-a explicitamente (faça flush de métricas, drene uma fila, então feche o pool — o inverso da ordem de construção). Kata não é dono de nenhum registry de dispose; gracefulShutdown é dono apenas da fiação sempre idêntica — o trap do sinal, o drain e um timer de force-exit (timeoutMs, padrão 10 s) para uma conexão que se recusa a fechar. O bootstrap do examples/shop conecta isso contra o stub do store de ponta a ponta.
Pegadinhas
- Singletons são eager.
makeDb(process.env)executa quandocontext.tsé importado pela primeira vez, não preguiçosamente no primeiroc.get. Faça o setup de conexão ali; não coloque lógica específica de requisição na factory. - O ciclo de vida está fora da requisição. Um singleton não tem hook de teardown por requisição; fechar o pool é uma preocupação de processo tratada no
main.tscomgracefulShutdown— veja Fechando o pool no shutdown. - Leia a configuração na borda. Passe
envparamakeDbuma vez; mantenhaprocess.envfora dos handlers e serviços para que permaneçam puros e testáveis. c.get('db')só compila se'db'estiver emdefineContext. Uma chave não registrada é tanto um erro de tipo quanto um throw em runtime (kata: key 'db' not registered in defineContext) — e a regra de lintkata/context-key-not-registeredtambém a sinaliza.