Leggere JSON di grandi dimensioni in Node.js: parsing in streaming con stream-json e backpressure in pratica
In sintesi: Leggere un array JSON da 186MB con readFileSync e JSON.parse porta la memoria al picco di 612MB; passare al streamArray di stream-json la mantiene piatta a 104MB. Questo articolo confronta quattro strategie di lettura con misurazioni, spiega perché for await produce backpressure naturalmente, come l'evento data la perde e come configurare highWaterMark e drain sul lato scrittura.

Quando l'import di un file JSON da 186MB spinge il processo a 600MB di memoria, il colpevole non è la dimensione del file — JSON.parse ha scambiato tutto il testo con l'intero grafo di oggetti in un colpo solo. Cambiate strategia di lettura e la curva di memoria diventa piatta.
Un sintomo: un file da 186MB con picco a 612MB
I job di import lato server sono il terreno dove questo problema compare più spesso: sincronizzazioni pianificate degli ordini, pulizia dei log, caricamento in blocco della cronologia. L'implementazione tipica assomiglia a questa:
const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);
Abbiamo misurato questo schema su Node 22.13. Il campione: un array di 480 000 record di ordini, file da 186MB con stringhe, oggetti annidati e array nei campi, a imitazione di strutture aziendali reali. Picco del Maximum resident set size misurato con /usr/bin/time -v: la lettura richiede 1.3 secondi, ma l'RSS culmina a 612MB — 3.3 volte il file. Con il limite predefinito del vecchio spazio di V8 a 1.4–2GB, pochi job di questo tipo in parallelo bastano per finire uccisi da OOM Kill nel container.
L'aritmetica non è esotica: il testo grezzo occupa una copia in memoria (circa 186MB), il grafo di oggetti prodotto dal parse ne occupa un'altra (ogni chiave stringa, ogni intestazione di oggetto annidato e ogni array ha un costo), e il processo di parsing stesso alloca transitoriamente sopra. Arrivare a 600MB di picco è normale.
Seconda causa: JSON.parse scambia tutto il testo con tutto il grafo
Il contratto di JSON.parse è «dammi il testo completo, ti restituisco il grafo completo». Esige che tutto il testo sia pronto prima di iniziare e consegna il risultato solo alla fine. Non esiste alcun meccanismo per «prima ecco i primi 1 000 record».
Il costo del grafo di oggetti è stato misurato voce per voce in Il conto memoria di JSON: ogni stringa occupa spazio reale, ogni chiave di oggetto prende uno slot, e la larghezza di un array dipende dai tipi degli elementi. Una decina di MB di JSON diventa regolarmente da tre a cinque volte più grande dopo il parsing, con il picco aggiunto sopra.
Ma la maggior parte degli import non ha mai bisogno dell'intero grafo: inserire riga per riga, filtrare riga per riga, trasformare riga per riga — ogni record può essere liberato appena elaborato. Quello che il job serve è «un record parseato, un record emesso». È precisamente la definizione di parsing in streaming.
La soluzione: streamArray consuma record per record, e for await fornisce la backpressure
stream-json implementa il parser come uno Transform stream che consuma token e non aspetta mai l'intero file. Quando il livello superiore è un array, streamArray() emette {key, value} nell'istante in cui ogni elemento termina di essere parseato:
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);
}
}
Sullo stesso file da 186MB con gli stessi 480 000 record, questa versione culmina a 104MB di RSS, piatto per tutta la durata. In memoria esistono solo «l'elemento corrente + lo stato del parser»; i record finiti vengono recuperati immediatamente.
Un dettaglio facile da perdere: for await non tira il record successivo dal parser finché saveToDb non è completata, quindi il parser smette di leggere il file. Database più lento, lettura più lenta — questa è la backpressure, formata naturalmente, senza una riga di codice in più. Un articolo su dev.to sull'ingestion di un feed municipale da 4GB usa la stessa catena con pick({filter:'data'}) e riporta una curva di memoria altrettanto piatta.
Quando il lato scrittura fallisce: un evento data senza pausa riporta su la memoria
Il parsing in streaming disciplina solo la lettura. Se la scrittura non accetta la backpressure, la memoria risale. Il fallimento classico: scritture asincrone dentro un handler di data senza curarsi del buffer del writable:
// Sbagliato: evento data + scrittura asincrona, backpressure persa del tutto
readable.on('data', async (chunk) => {
await slowWrite(chunk); // lo stream non aspetta; il buffer continua a gonfiarsi
});
In modalità data lo stream continua a fluire, per quanto lento sia slowWrite, e tutto si accumula nel buffer interno del writable. Sullo stesso campione da 186MB abbiamo indirizzato i record verso uno Writable lento che ritarda 1ms ogni centesimo blocco. Ignorando la backpressure l'RSS culmina a 407MB; sospendendo con await once(sink, 'drain') quando write() restituisce false, a 161MB. La differenza di 246MB sono letteralmente dati seduti nel buffer di scrittura.
// Corretto: pausa quando write() restituisce false, ripresa al drain
for await (const { value } of pipeline) {
if (!sink.write(value)) {
await once(sink, 'drain');
}
}
Due note pratiche: assemblando catene di stream a mano, impostate highWaterMark esplicitamente su ogni stream — il valore predefinito di 16 in objectMode è troppo generoso per oggetti grandi; e preferite pipeline() da stream/promises a pipe(), che si occupa di propagazione degli errori e pulizia.
Le misurazioni: picco di memoria di quattro strategie
| Strategia | Campione | Picco RSS | Durata | Uso |
|---|---|---|---|---|
| readFileSync + JSON.parse | 186MB / 480k | 612MB | 1.3s | file piccoli, accesso casuale |
| streamArray + for await + scritture lente su DB (0.5ms ciascuna) | lo stesso | 104MB (piatto) | dettato dal DB | ingestion record per record, trasformazioni |
| streamArray + scritture via data, senza backpressure | lo stesso | 407MB | ~10s | l'esempio da non seguire |
| streamArray + write()/drain | lo stesso | 161MB | ~10s | scrivere su disco o inoltrare |
Ambiente: Node 22.13, Maximum resident set size via /usr/bin/time -v, campione sintetico con campi di forma aziendale, esecuzioni singole senza media, scritture lente simulate con setTimeout. Questi numeri sono conclusioni di ordine di grandezza per questo campione, non costanti universali — misurate sui vostri dati.
Due letture meritano attenzione. La prima e la seconda strategia differiscono di un fattore sei in memoria, al prezzo di scambiare «1.3 secondi» con «la velocità del DB». La terza e la quarta differiscono di un fattore 2.5: leggere in streaming senza backpressure in scrittura risolve solo metà del problema.
Diagnosi: confermare che la backpressure funziona davvero
I problemi di memoria in produzione non si risolvono a intuizione. Un articolo di Tencent Cloud sul troubleshooting della backpressure offre un metodo pratico:
- Loggate temporaneamente gli eventi
'pause'e'resume'sugli stream critici. Se una pipeline ad alto throughput non pausa mai, da qualche parte i dati si stanno accumulando in memoria; - Osservate
writable.writableLength— crescita continua significa che il buffer non si svuota mai; - Campionate l'RSS con
process.memoryUsage()a intervalli e tracciate la curva, distinguendo «crescita a rampa» (accumulo) e «plateau a denti di sega» (liberazione sana).
Sotto la semantica di for await, gli eventi pause e resume devono alternarsi; se non scattano mai, cercate un listener data di troppo o un await dimenticato.
Quando lo streaming non è la risposta
Lo streaming non è la soluzione predefinita. Per file di poche decine di MB con accesso casuale per chiave, una singola chiamata a JSON.parse è più semplice ed economica. Aprire un file grande nel browser è un altro dominio di problemi — come aprire un file JSON grande copre la scala dei visualizzatori. I confini del parsing in streaming sono chiari:
- il livello superiore è un array (o i dati si dividono come JSONL), il consumo è sequenziale, senza sguardi indietro;
- la dimensione del file è incontrollata o supera ampiamente la riserva dell'heap, e un import non deve raddoppiare l'ingombro del processo;
- il consumatore ha un divario di velocità naturale (scritture su DB, chiamate API a valle), quindi serve backpressure anziché un tubo a piena portata.
Quando la forma di livello superiore è irregolare, ispezionate prima la struttura nello strumento parser e formattatore JSON; l'equivalente da riga di comando è coperto in jq per JSON grandi — jq --stream e streamArray sono la stessa idea in due runtime.
FAQ
Quanto è più lento stream-json rispetto a JSON.parse?
Nel parsing puro vince JSON.parse: 1.3 secondi per il campione da 186MB, contro circa 7 secondi per streamArray senza latenza di scrittura (parsing a token più costruzione di oggetti record per record). Il beneficio dello streaming vive interamente sul lato memoria: il picco scende da 612MB a 104MB. Un import è comunque limitato dal DB, quindi pagare qualche secondo di parsing per un margine di memoria di sei volte è di solito un buon affare; dentro risposte API al millisecondo, no.
La backpressure di for await è la stessa di pause/resume manuali?
Semanticamente sì: for await sospende lo stream leggibile mentre il corpo del ciclo è in attesa, equivalendo a chiamare pause() quando write() restituisce false e resume() al drain. La differenza: la meccanica del linguaggio tiene la contabilità e non dimentica nulla; il cablaggio manuale perde la backpressure dell'intera catena appena un punto manca.
E se il livello superiore è un unico oggetto enorme?
stream-json fornisce streamObject() (emette per chiave) e il filtro Pick (parsea solo il sottoalbero scelto). Se bastano alcuni campi, Pick con un JSONPath riduce l'intero grafo al sotto-grafo richiesto. L'input multi-documento (JSON Lines, sequenze JSON) conviene dividerlo riga per riga e trattarlo come documenti indipendenti.
Come scrivere il risultato come JSONL o inoltrarlo a valle?
Il lato scrittura pone la stessa domanda di backpressure: fs.createWriteStream e http.request richiedono di controllare il valore di ritorno di write() e attendere once(stream, 'drain') su false — oppure collegare il writable a pipeline(). La verifica è semplice: la curva di RSS dopo una passata deve essere stabile e writableLength non deve crescere persistentemente.
Qual è il monitor di memoria più rapido per un job di import?
Versione minima: un timer che campiona process.memoryUsage().rss ogni 100ms in un array e stampa il massimo alla fine. Più preciso: /usr/bin/time -v node task.js dà direttamente il Maximum resident set size. Nei container, mettete la linea di allarme al 70% del limite di memoria lasciando margine al GC.