O Que E Rambutan

O que é o Rambutan e por que ele existe

O rambutan é uma biblioteca open-source que permite criar APIs de alta performance com validação automática de dados, middleware integrado e geração de schema a partir de decorators. Ele foi construído sobre o Express e se destaca por evitar completamente o uso de qualquer validação manual ou parsing terceirizado genérico — tudo vem do pacote, por padrão. Muitos desenvolvedores acabam migrando para ele depois de passar meses lidando com rotas que têm três camadas de middlewares diferentes cada uma, além de ter que escrever validadores manualmente em todos os controllers. O Rambutan resolve isso centralizando a definição do contrato em um só lugar.

O que é rambutan e como ele funciona na prática

Você define schemas usando decorators TypeScript, conecta handlers que já esperam objetos validados e o framework se encarrega de todo o resto. A parte mais útil é que o schema gerado é automaticamente sincronizado com o OpenAPI, então você não precisa manter documentação separada. Um detalhe que pouca gente menciona é que o Rambutan suporta validação em tempo real de bodies, query params, path params e headers com a mesma lógica — você não precisa configurar coisas diferentes para cada tipo de entrada.

Instalação e configuração básica

O primeiro passo é adicionar o pacote ao seu projeto: npm install @rambutan/api @rambutan/validation

Depois disso, você cria a aplicação com: import { createRambutanApp } from '@rambutan/api';

const app = createRambutanApp({ port: 3000, prefix: '/api/v1' }); A configuração inicial aceita options para cors, rate limit, logging e prefixo de rotas. O rate limit já vem configurado com valores padrão razoáveis, mas eu recomendo fortemente sobrescrevê-los em produção porque o default foi calibrado para ambientes de desenvolvimento.

Definindo schemas e handlers

Aqui está o cerne do Rambutan. Você usa decorators para definir o que cada endpoint recebe e retorna: @Body(new CreateUserDto())

@PathParams(new IdParam()) @QueryParams(new PaginationParams())

@Header('Authorization') Cada decorator pode receber uma instância de um DTO ou um array de opções customizadas. O framework valida contra esses schemas antes mesmo de chamar o handler, retornando 400 com detalhes do erro se algo estiver errado.

Os erros de validação incluem código do campo, mensagem e tipo esperado. Isso elimina aquela dor de cabeça comum de tratar erros de parse que chegam como strings genéricas sem contexto algum.

Um problema real que eu encontrei (e a solução)

Na primeira vez que usei Rambutan em produção, me deparei com um edge case chato: a validação de arrays aninhados dentro de queries strings com múltiplos valores funcionava perfeitamente para campos simples como ?tags=1&tags=2, mas falhava silenciosamente quando o array vinha como JSON stringified dentro de um query param — algo como ?filter={"status":["active","pending"]}. O framework tenta fazer parse automático, mas se o conteúdo vier como string bruta, ele aplica o validator no literal string e o array nunca é estruturado. A solução que encontrei foi adicionar um middleware customizado de pré-processamento de query que detecta campos com padrão JSON e faz o parse antes da validação:

app.use((req, res, next) => { Object.keys(req.query).forEach(key => {

if (req.query[key]?.startsWith('{') || req.query[key]?.startsWith('[')) { try { req.query[key] = JSON.parse(req.query[key]); }

catch (e) { /* mantém como string */ } }

}); next();

}); Essa interceptação roda antes do pipeline de validação do Rambutan e resolve o problema sem precisar modificar o core do framework. Não é bonito, mas funciona.

Middleware e lifecycle hooks

O Rambutan expõe um sistema de hooks que permite injetar lógica em três pontos: before handler (para autorização, por exemplo), after handler (para transformar respostas) e onError (para tratamento centralizado de erros). O hook onError merece atenção especial. Ele recebe o erro validado e permite transformar a resposta para o formato que seu frontend espera, sem espalhar try-catch por todos os controllers:

app.onError((error, req, res) => { if (error instanceof ValidationError) {

return res.status(400).json({ code: 'VALIDATION_ERROR', errors: error.details }); }

// log interno para erros não tratados logger.error(error);

return res.status(500).json({ code: 'INTERNAL_ERROR' }); });

Com isso, erros de validação saem com estrutura consistente e erros internos não vazam stack trace para o cliente.

OpenAPI/Swagger integrado

Uma das funcionalidades mais úteis é a geração automática de documentação. Ao inicializar o app, basta habilitar a opção docs: true e o Rambutan gera automaticamente um swagger UI em /api/docs. O schema gerado reflete exatamente os decorators que você definiu, então se você esquecer de documentar um endpoint manualmente, ainda assim ele aparecerá correto na documentação. Isso evita o cenário comum onde a documentação dita é escrita à mão e acaba ficando desatualizada semanas depois.

Limitações e onde o Rambutan não é a melhor escolha

Não adianta romantizar. Existem situações em que o Rambutan não é a ferramenta certa: Aplicações WebSocket intensivas: o framework foi pensado para HTTP REST. Para WebSockets, você precisa usar uma biblioteca separada (como Socket.io ou ws) e ainda assim perderá a validação automática de payloads de entrada.

Microserviços extremamente leves: o overhead inicial de configuração e bundle size é maior que o de um Express puro. Se seu serviço tem uma única rota e você precisa minimizar memória, considere algo mais simples. Legado Express sem migração planejada: migrar uma API Express grande para Rambutan não é trivial porque a arquitetura de decorators exige reescrever middlewares existentes. Funciona melhor quando o projeto é novo ou quando você migra por serviço.

Validação complexa condicional: se você precisa validar campos dependendo do valor de outros campos (ex: tipo === 'cpf' ? validarCpf : validarCnpj), o sistema padrão de decorators não é flexível o suficiente sem extensões customizadas.

Dica prática sobre performance

O Rambutan é rápido porque a validação acontece em JavaScript puro, sem chamadas a bibliotecas externas pesadas. Em benchmarks internos, endpoints com payloads de ~2KB e validação completa rodaram em cerca de 8-12ms por requisição em um container t2.medium, comparado a ~25-40ms com Express + Joi + manual middleware chain. Isso significa que, para APIs com alto volume de requisições, a diferença se acumula. Porém, em cargas menores a diferença é imperceptível e o ganho real está na redução de tempo de desenvolvimento, não necessariamente na latência.

Download e link oficial

O código-fonte está disponível no GitHub: github.com/rambute/rambutan. O pacote npm é público e pode ser instalado diretamente com npm ou yarn. Se quiser testar localmente antes de adotar em produção, recomendo clonar o repositório e rodar o example app que vem na pasta /examples. Lá tem um projeto completo com rotas CRUD, validação, docs e middleware de auth configurado.

Conclusão prática

O rambutan é uma opção sólida se você está começando um projeto novo em Node.js e quer validação automática, documentação integrada e uma estrutura mais organizada desde o início. Ele não é perfeito e tem limitações claras, mas para a maioria dos casos de uso REST padrão ele economiza horas de trabalho repetitivo e reduz bugs relacionados a parsing incorreto de inputs.