Ler JSON grande em Node.js: parsing em streaming com stream-json e contrapressão na prática
Resumo: Ler um array JSON de 186MB com readFileSync e JSON.parse leva a memória ao pico de 612MB; trocar pelo streamArray do stream-json mantém a curva plana em 104MB. Este artigo compara quatro estratégias de leitura com medições, explica por que for await produz contrapressão naturalmente, como o evento data a perde e como ajustar highWaterMark e drain no lado da escrita.

Quando importar um ficheiro JSON de 186MB empurra o processo para 600MB de memória, o culpado não é o tamanho do ficheiro — o JSON.parse trocou o texto inteiro por todo o grafo de objetos de uma só vez. Mude a estratégia de leitura e a curva de memória fica plana.
Um sintoma: ficheiro de 186MB com pico de 612MB
As tarefas de importação do lado do servidor são o terreno onde este problema mais aparece: sincronizações agendadas de encomendas, limpeza de logs, carregamento de histórico em massa. A implementação típica tem este aspeto:
const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);
Medimos este padrão no Node 22.13. A amostra: um array de objetos com 480 000 registos de encomendas, ficheiro de 186MB com strings, objetos aninhados e arrays nos campos, imitando estruturas reais. Pico do Maximum resident set size medido com /usr/bin/time -v: a leitura leva 1.3 segundos, mas o RSS atinge 612MB — 3.3 vezes o ficheiro. Com o limite predefinido do espaço antigo da V8 em 1.4–2GB, algumas tarefas destas em paralelo bastam para o contêiner morrer por OOM Kill.
A aritmética não é exótica: o texto bruto ocupa uma cópia na memória (cerca de 186MB), o grafo de objetos resultante do parse ocupa outra (cada chave string, cada cabeçalho de objeto aninhado e cada array tem custo), e o próprio processo de parsing aloca transitoriamente por cima. Chegar a 600MB de pico é normal.
Segunda causa: o JSON.parse troca texto inteiro por grafo inteiro
O contrato do JSON.parse é «dá-me o texto completo, devolvo-te o grafo completo». Exige que todo o texto esteja no lugar antes de começar e só entrega o resultado no fim. Não existe mecanismo para «aqui vão primeiro os primeiros 1 000 registos».
O custo do grafo de objetos foi medido item por item em A conta de memória do JSON: cada string ocupa espaço real, cada chave de objeto toma um slot, e a largura de um array depende dos tipos dos elementos. Uma dezena de MB de JSON torna-se rotineiramente três a cinco vezes maior depois do parsing, com o pico por cima.
Mas a maioria das importações nunca precisa do grafo inteiro: inserir linha por linha, filtrar linha por linha, transformar linha por linha — cada registo pode ser libertado assim que tratado. O que a tarefa precisa é de «parse de um registo, entrega de um registo». É precisamente a definição de parsing em streaming.
A solução: streamArray consome registo a registo, e o for await oferece contrapressão
O stream-json implementa o parser como um Transform stream que consome tokens e nunca espera pelo ficheiro inteiro. Quando o nível de topo é um array, o streamArray() emite {key, value} no instante em que cada elemento termina de ser parseado:
const fs = require('fs');
const { chain } = require('stream-chain');
const { parser } = require('stream-json');
const { streamArray } = require('stream-json/streamers/StreamArray');
async function importOrders(filePath) {
const pipeline = chain([
fs.createReadStream(filePath, { highWaterMark: 64 * 1024 }),
parser(),
streamArray(),
]);
for await (const { key, value } of pipeline) {
await saveToDb(value);
}
}
No mesmo ficheiro de 186MB com os mesmos 480 000 registos, esta versão atinge um pico de RSS de 104MB, plano durante toda a execução. Existem em memória apenas «o elemento atual + o estado do parser»; os registos terminados são recuperados imediatamente.
Um detalhe fácil de perder: o for await não puxa o próximo registo do parser até saveToDb terminar, por isso o parser deixa de ler o ficheiro. Base de dados mais lenta, leitura mais lenta — isso é contrapressão, formada naturalmente, sem uma linha de código extra. Um artigo do dev.to sobre a ingestão de um feed municipal de 4GB usa a mesma cadeia com pick({filter:'data'}) e relata uma curva de memória igualmente plana.
Quando o lado da escrita falha: um evento data sem pausa empurra a memória de volta
O parsing em streaming só disciplina a leitura. Se a escrita não aceitar a contrapressão, a memória sobe de novo. A falha clássica: escritas assíncronas num handler de data sem olhar para o buffer do writable:
// Errado: evento data + escrita assíncrona, contrapressão totalmente perdida
readable.on('data', async (chunk) => {
await slowWrite(chunk); // o stream não espera; o buffer continua a crescer
});
No modo data o stream continua a fluir, por mais lento que seja o slowWrite, e tudo se acumula no buffer interno do writable. Na mesma amostra de 186MB, dirigimos os registos a um Writable lento que atrasa 1ms em cada centésimo bloco. Ignorando a contrapressão, o RSS chegou ao pico de 407MB; suspendendo com await once(sink, 'drain') quando write() devolve false, 161MB. A diferença de 246MB são literalmente dados sentados no buffer de escrita.
// Correto: pausar quando write() devolve false, retomar no drain
for await (const { value } of pipeline) {
if (!sink.write(value)) {
await once(sink, 'drain');
}
}
Duas notas de campo: ao montar cadeias de streams à mão, defina highWaterMark explicitamente em cada stream — o valor predefinido de 16 em objectMode é demasiado generoso para objetos grandes; e prefira pipeline() de stream/promises em vez de pipe(), que trata da propagação de erros e da limpeza.
As medições: pico de memória de quatro estratégias
| Estratégia | Amostra | Pico RSS | Duração | Uso |
|---|---|---|---|---|
| readFileSync + JSON.parse | 186MB / 480k | 612MB | 1.3s | ficheiros pequenos, acesso aleatório |
| streamArray + for await + escritas lentas na BD (0.5ms cada) | a mesma | 104MB (plana) | ao ritmo da BD | ingestão registo a registo, transformações |
| streamArray + escritas via data, sem contrapressão | a mesma | 407MB | ~10s | o exemplo a não seguir |
| streamArray + write()/drain | a mesma | 161MB | ~10s | gravar em disco ou reencaminhar |
Ambiente: Node 22.13, Maximum resident set size via /usr/bin/time -v, amostra sintética com campos de forma real, execuções únicas sem média, escritas lentas simuladas com setTimeout. Estes números são conclusões de ordem de grandeza para esta amostra, não constantes universais — meça com os seus próprios dados.
Duas leituras merecem atenção. A primeira e a segunda estratégia diferem num fator de seis em memória, ao preço de trocar «1.3 segundos» por «a velocidade da BD». A terceira e a quarta diferem num fator de 2.5: ler em streaming sem contrapressão na escrita resolve só metade do problema.
Diagnóstico: confirmar que a contrapressão funciona mesmo
Problemas de memória em produção não se diagnostical por intuição. Um artigo da Tencent Cloud sobre resolução de contrapressão dá um método prático:
- Faça log temporário de
'pause'e'resume'nos streams críticos. Se uma pipeline de grande débito nunca pausa, algures há dados a acumular-se em memória; - Observe
writable.writableLength— crescimento contínuo significa que o buffer nunca esvazia; - Amostre o RSS com
process.memoryUsage()a intervalos e trace a curva, distinguindo «crescimento em rampa» (acumulação) de «planalto em dente de serra» (libertação saudável).
Sob a semântica do for await, os eventos pause e resume têm de alternar; se nunca dispararem, procure um listener data a mais ou um await esquecido.
Quando o streaming não é a resposta
O streaming não é a solução predefinida. Para ficheiros de algumas dezenas de MB com acesso aleatório por chave, uma chamada simples de JSON.parse é mais simples e barata. Abrir um ficheiro grande no navegador é outro domínio de problema — como abrir um ficheiro JSON grande cobre a escada de visualizadores. As fronteiras do parsing em streaming são claras:
- o nível de topo é um array (ou os dados dividem-se como JSONL), o consumo é sequencial, sem olhar para trás;
- o tamanho do ficheiro é incontrolável ou excede largamente a margem do heap, e uma importação não pode duplicar a pegada do processo;
- o consumidor tem um desfasamento de velocidade natural (escritas na BD, chamadas a APIs a jusante), por isso precisa de contrapressão em vez de uma mangueira a pleno débito.
Quando a forma de topo é irregular, inspecione primeiro a estrutura na ferramenta parser e formatador JSON; o equivalente na linha de comandos está coberto em jq para JSON grande — jq --stream e streamArray são a mesma ideia em dois runtimes.
FAQ
Quanto mais lento é o stream-json comparado com o JSON.parse?
No parsing puro, o JSON.parse ganha: 1.3 segundos para a amostra de 186MB, contra cerca de 7 segundos para o streamArray sem latência de escrita (parsing por tokens mais construção de objetos registo a registo). O benefício do streaming vive inteiramente no lado da memória: o pico cai de 612MB para 104MB. Uma importação é de qualquer forma limitada pela BD, pelo que pagar alguns segundos de parsing por uma margem de memória seis vezes maior é normalmente um bom negócio; dentro de respostas API ao milissegundo, não.
A contrapressão do for await é a mesma que pause/resume manuais?
Semanticamente sim: o for await suspende o stream legível enquanto o corpo do ciclo está pendente, o que equivale a chamar pause() quando write() devolve false e resume() no drain. A diferença: a mecânica da linguagem assume a contabilidade e nada se esquece; o cabeamento manual perde a contrapressão de toda a cadeia assim que um ponto falha.
E se o nível de topo for um único objeto imenso?
O stream-json fornece streamObject() (emite por chave) e o filtro Pick (analisa só a subárvore escolhida). Se bastam alguns campos, o Pick com um JSONPath reduz o grafo inteiro ao subgrafo necessário. Entrada multi-documento (JSON Lines, sequências JSON) vale melhor dividida linha a linha e tratada como documentos independentes.
Como escrever o resultado como JSONL ou reencaminhar a jusante?
O lado da escrita é a mesma questão de contrapressão: fs.createWriteStream e http.request exigem verificar o valor de retorno de write() e aguardar once(stream, 'drain') em caso de false — ou ligar o writable ao pipeline(). A verificação é simples: a curva de RSS após uma passagem tem de ser estável e o writableLength não pode crescer persistentemente.
Qual é o monitor de memória mais rápido para uma tarefa de importação?
Versão mínima: um temporizador que amostra process.memoryUsage().rss a cada 100ms para um array e imprime o máximo no fim. Mais preciso: /usr/bin/time -v node task.js dá diretamente o Maximum resident set size. Em contêineres, coloque a linha de alerta em 70% do limite de memória para deixar margem ao GC.