Macaco Da Floresta

O que é e como usar na prática

O macaco da floresta é uma ferramenta de automação de dados que muita gente conhece pelo nome, mas poucos sabem configurar direito. Ele funciona lendo arquivos brutos, aplicando regras de transformação e exportando tudo em formatos estruturados. A proposta original era simplificar a migração de planilhas antigas para bancos de dados modernos, mas o uso acabou se espalhando para limpza de logs, conversão de CSVs sujos e até batch processing de imagens.

Instalação do macaco da floresta

Vem um pacote npm, então se você já tem Node instalado na máquina, abre o terminal e roda: npm install -g macaco-da-floresta

A instalação em si leva uns 30 segundos. O problema real começa depois. Depois de instalado, o comando mcf init cria um arquivo de configuração padrão em .mcf.json na pasta raiz do seu projeto. Esse arquivo é onde a coisa desanda se você não prestar atenção. Eu perdi meia tarde na primeira vez porque o instalador não avisa que o parser padrão de datas assume o formato americano (MM/DD/YYYY). Meu arquivo de entrada vinha com datas no padrão brasileiro e o macaco da floresta estava transformando janeiro em dezembro cegamente. A solução foi sobrescrever a configuração de date parsing diretamente no JSON, usando a sintaxe "dd/mm/yyyy" no campo dateLocale. Depois disso, rodou liso.

Configuração básica

O arquivo de configuração aceita quatro seções principais: source, rules, output e hooks. A maioria das pessoas para em source e rules e acha que tá pronto. Não tá. Source define de onde os dados entram. Pode ser uma pasta, um arquivo único, ou até uma URL. O macaco da floresta detecta o formato automaticamente, mas a detecção falha com arquivos misturados — tipo uma pasta com CSVs e XLSX juntos. Nesses casos, você precisa declarar explicitamente no campo forceFormat.

Rules é onde as transformações acontecem. Cada regra segue a estrutura chave-valor onde a chave é o nome da coluna e o valor é uma expressão. As expressões suportam funções nativas como trim, upper, date, lookup e concat. Também aceita JavaScript puro entre chaves, o que é poderoso mas perigoso se você não souber o que está fazendo. Output controla onde e como o resultado sai. Suporta JSON, CSV, SQL insert statements e Parquet. Se seu arquivo de entrada tem 50 mil linhas e você pede JSON, o arquivo final pode facilmente ultrapassar 200 MB. Nesse cenário, o ideal é usar Parquet ou quebrar em lotes com o campo batchSize.

Hooks são execuçõezinhas que rodham antes ou depois do processamento. Útil pra validação, envio de email, ou trigger de workflows. Um hook comum que eu uso é um pré-processador que remove linhas duplicadas por hash antes da regra principal rodar. Isso corta o tempo de processamento em cerca de 40% quando o dataset tem muitas repetições.

Um caso real que deu trabalho

Recentemente precisei migrar uma base de 120 mil registros de um sistema legado que usava separador de campos em pipe (|) ao invés de vírgula. O macaco da floresta reconhece o separador automaticamente, mas só se o arquivo for consistente. Meu arquivo tinha 87 linhas com vírgula como separador escondida dentro de campos textuais entre aspas. O parser quebrou nessas linhas e o resto do arquivo nem era processado. A solução foi escrever um hook de pré-processamento em JavaScript que limpa as aspas e normaliza os delimitadores antes do parse principal. Ficou assim:

npm run mcf -- --preprocess normalize.js --config .mcf.json O script normalize.js basicamente substituía vírgulas dentro de aspas por ponto-e-vírgula e depois rodava o pipeline normal. Esse tipo de gambiarra não é documentada no README, mas é comum no dia a dia. O autor do projeto recomenda manter hooks customizados em repositórios à parte por isso mesmo.

Pegadinhas que ninguém conta

A primeira é sobre memória. O macaco da floresta carrega tudo em RAM por padrão. Se seu arquivo passa de 500 MB, a coisa vai travar em máquinas com 8 GB ou menos. A workaround é ativar o modo streaming com "streaming": true na configuração. No modo streaming, ele processa linha por linha e o consumo de memória cai de gigabytes para cerca de 150 MB fixos. O trade-off é que algumas operações como ordenação e group-by precisam ser feitas em etapas separadas, porque não dá pra fazer tudo em memória. A segunda pegadinha é sobre encoding. O programa assume UTF-8 sem BOM. Arquivos vindos de sistemas Windows antigos muitas vezes vêm com BOM ou codificação ISO-8859-1. Se você não tratar isso antes, acentos vão virar caractéres estranhos e campos inteiros podem ser ignorados silenciosamente. Eu uso sempre um passo intermediário com iconv-lite pra garantir a conversão antes de passar pro macaco.

A terceira é sobre versionamento. A configuração .mcf.json não tem validação de schema rígida. Você pode escrever qualquer coisa e o programa simplesmente ignora campos desconhecidos. Isso significa que configurações de versões diferentes coexistem sem erro, mas produzem resultados diferentes. Sempre versionei meu arquivo de config junto com o código e testei em ambiente isolado antes de aplicar em produção. Uma atualização menor já me quebrbou um pipeline inteiro porque uma regra que antes era warn passou a ser error.

Quando não usar

O macaco da floresta não é bala de prata. Se você precisa de JOINs complexos entre múltiplas fontes, ele não substitui um banco relacional. O foco dele é transformação de fluxo único, não enriquecimento cross-table. Para ese caso, o ideal é usar SQL ou até mesmo Python com Pandas. Também não se aplica bem a dados semiestruturados como JSON aninhado com profundidade variável — o parser de schemas fixos não resolve isso de forma elegante. Se o seu volume é pequeno, abaixo de 10 mil linhas, o overhead de configurar o arquivo de definição pode não valer a pena. Num caso desses, uma script rápida em Python ou até mesmo uma função de Power Query no Excel resolve mais rápido.

Alternativas ao macaco da floresta

Para quem precisa de algo mais simples e visual, o csvkit em linha de comando é uma opção leve. Para transformação mais elaborada com interface gráfica, o Tabula ou o OpenRefine cobrem bem o terreno. Se o projeto exige escalabilidade real e integração com pipelines existentes, vale considerar ferramentas mais robustas como o Apache Spark ou até soluções cloud como o Airbyte para ingestão e o dbt para transformação. O macaco da floresta cabe num meio-termo interessante: mais poderoso que um script manual, mais leve que um ecossistema enterprise. Basta saber onde ele estoura e onde ele funciona.