Framework HTTP para Node.js
Structure that flows.
Consistency without complexity.
Rotas declarativas, contratos explícitos e composição flexível. Toda a equipe declara rotas do mesmo jeito, sem a estrutura pesada que o projeto não precisa.
const buscar = {
params: Type.Object({
id: Type.String({ format: 'uuid' }),
}),
response: { 200: User },
} satisfies RouteSchemas;
@Router('/users')
export class UserRoutes {
@Get('/:id', buscar)
async getById(ctx: Context<typeof buscar>) {
return users.find(ctx.params.id);
}
}Rotas declarativas
Uma forma consistente de declarar rotas, que qualquer pessoa da equipe reconhece.
Contratos e validação
Um contrato por rota valida a entrada, tipa o ctx, filtra a resposta e gera o OpenAPI.
Composição flexível
Use só o que o projeto precisa: middlewares, guards, hooks e grupos de rotas.
Infraestrutura pronta
Segurança, uploads, streaming, observabilidade e shutdown gracioso de fábrica.
O problema
Liberdade sem convenção gera inconsistência. Arquitetura obrigatória gera complexidade.
O FlowingTS nasce do equilíbrio entre os dois extremos: uma maneira consistente de construir APIs, sem impor uma arquitetura pesada ao seu projeto.
- Padrão claro para toda a equipe.
- Recursos integrados, sem excesso.
- Flexibilidade para evoluir do seu jeito.
O contrato
Um schema, usado quatro vezes
O contrato é escrito uma vez, com TypeBox ou Zod, e o framework o usa em cada etapa da requisição.
Valida a entrada
body, params e query são validados antes do handler. Um erro vira 400 em Problem Details.
Tipa o ctx
ctx.body e ctx.params chegam com os tipos do schema, sem declarar nada duas vezes.
Filtra a resposta
Campos fora do schema não saem. Um password esquecido no objeto não vaza.
Documenta a API
O mesmo schema gera o OpenAPI 3.1 e a página /docs.
De fábrica
O que já vem no lugar
- Segurança
- Headers de segurança, validação de Host, CSRF, CORS, rate limit, limite de body e timeouts, ligados por padrão.
- Composição
- app.mount() e app.group() com prefixos, middlewares, guards, hooks e virtual hosts. Sem container de DI.
- Produção
- Shutdown gracioso com drain para o balanceador, healthchecks e HTTPS com troca de certificado sem reiniciar.
- Streaming
- SSE, NDJSON e arquivos, com cancelamento pelo ctx.signal quando o cliente sai ou o app encerra.
- Observabilidade
- OpenTelemetry pelo próprio @opentelemetry/api, ctx.route com o template da rota e logs com request id e redact.
- Erros
- Problem Details em toda resposta de erro, com a fase em que o erro aconteceu para quem observa.
Antes de adotar
O que o FlowingTS exige do seu projeto
- Só decorators padrão (TC39)
- Não convive no mesmo projeto com bibliotecas que exigem experimentalDecorators, como NestJS e TypeORM.
- Node.js 22.12+
- ESM ou CommonJS (pelo require de módulos ESM do Node). Versões anteriores não são suportadas.
- Sem container de DI
- As dependências entram pelo construtor, no ponto em que o app é montado.
- API em 0.x
- Pode mudar entre versões minor, sempre com a migração descrita no CHANGELOG.
- TypeScript
- Decorators TC39
- Validação
- OpenAPI 3.1
- Observabilidade
- Uploads