Lire du gros JSON en Node.js : parsing en flux avec stream-json et contre-pression en pratique
L’essentiel : Lire un tableau JSON de 186MB avec readFileSync et JSON.parse fait culminer la mémoire à 612MB ; passer au streamArray de stream-json la maintient plate à 104MB. Cet article compare quatre stratégies de lecture mesurées, explique pourquoi for await produit une contre-pression naturelle, comment l'événement data la perd, et comment régler highWaterMark et drain côté écriture.

Quand l'import d'un fichier JSON de 186MB pousse le processus à 600MB de mémoire, ce n'est pas la taille du fichier qui est en cause — JSON.parse a échangé tout le texte contre tout le graphe d'objets d'un seul coup. Changez de stratégie de lecture et la courbe mémoire devient plate.
Un symptôme : un fichier de 186MB avec un pic à 612MB
Les tâches d'import côté serveur sont le terrain privilégié de ce problème : synchronisation planifiée de commandes, nettoyage de logs, chargement d'historique en masse. L'implémentation typique ressemble à ceci :
const fs = require('fs');
const raw = fs.readFileSync('./orders.json', 'utf8');
const orders = JSON.parse(raw);
for (const order of orders) await saveToDb(order);
Nous avons mesuré ce modèle sur Node 22.13. L'échantillon : un tableau de 480 000 enregistrements de commandes, fichier de 186MB avec chaînes, objets imbriqués et tableaux dans les champs, imitant une structure métier réelle. Pic de Maximum resident set size mesuré avec /usr/bin/time -v : la lecture prend 1.3 seconde, mais le RSS culmine à 612MB — 3.3 fois le fichier. Avec la limite par défaut de l'ancien espace V8 à 1.4–2GB, quelques tâches concurrentes suffisent pour se faire tuer par OOM Kill en conteneur.
L'arithmétique n'a rien d'exotique : le texte brut occupe une copie en mémoire (environ 186MB), le graphe d'objets issu du parse en occupe une seconde (chaque clé de type chaîne, chaque en-tête d'objet imbriqué et chaque tableau a un coût), et le parsing lui-même alloue de façon transitoire par-dessus. Atteindre 600MB est normal.
Deux causes : JSON.parse échange tout le texte contre tout le graphe
Le contrat de JSON.parse est « donne-moi le texte complet, je te rends le graphe complet ». Il exige que tout le texte soit en place avant de commencer et ne remet le résultat qu'à la fin. Aucun mécanisme pour « voici d'abord les 1 000 premiers enregistrements ».
Le coût du graphe d'objets a été mesuré poste par poste dans Le compte mémoire de JSON : chaque chaîne occupe un vrai espace, chaque clé d'objet prend un emplacement, et la largeur d'un tableau dépend du type de ses éléments. Une dizaine de MB de JSON devient régulièrement trois à cinq fois plus grande après parsing, pic inclus.
Or la plupart des imports n'ont jamais besoin du graphe entier : insérer ligne par ligne, filtrer ligne par ligne, transformer ligne par ligne — chaque enregistrement peut être libéré dès qu'il est traité. Ce qu'il faut, c'est « un enregistrement parsé, un enregistrement émis ». C'est précisément la définition du parsing en flux.
La solution : streamArray consomme enregistrement par enregistrement, et for await offre la contre-pression
stream-json implémente le parseur comme un Transform stream qui consomme des jetons et n'attend jamais le fichier entier. Quand le niveau supérieur est un tableau, streamArray() émet {key, value} à l'instant où chaque élément finit d'être parsé :
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);
}
}
Sur le même fichier de 186MB et les mêmes 480 000 enregistrements, cette version culmine à 104MB de RSS, plate sur toute la durée. Seuls « l'élément courant + l'état du parseur » existent en mémoire à chaque instant ; les enregistrements finis sont récupérés immédiatement.
Un détail facile à rater : for await ne tire pas l'enregistrement suivant du parseur tant que saveToDb n'est pas terminée, donc le parseur cesse de lire le fichier. Base de données plus lente, lecture plus lente — c'est la contre-pression, formée naturellement, sans une ligne de code en plus. Un article de dev.to sur l'ingestion d'un flux municipal de 4GB utilise la même chaîne avec pick({filter:'data'}), et rapporte une courbe mémoire tout aussi plate.
Quand le côté écriture faillit : un événement data sans pause fait remonter la mémoire
Le parsing en flux ne discipline que la lecture. Si l'écriture n'accepte pas la contre-pression, la mémoire remonte. L'échec classique : écrire en asynchrone dans un gestionnaire data sans se soucier du buffer du writable :
// Faux : événement data + écriture asynchrone, contre-pression totalement perdue
readable.on('data', async (chunk) => {
await slowWrite(chunk); // le flux n'attend pas ; le buffer gonfle sans fin
});
En mode data le flux continue de couler, aussi lent que soit slowWrite, et tout s'entasse dans le buffer interne du writable. Sur le même échantillon de 186MB, nous avons dirigé les enregistrements vers un Writable lent qui retarde de 1ms chaque centième bloc. En ignorant la contre-pression, le RSS culmine à 407MB ; en suspensant avec await once(sink, 'drain') quand write() renvoie false, à 161MB. La différence de 246MB, ce sont littéralement des données assises dans le buffer d'écriture.
// Correct : pause quand write() renvoie false, reprise au drain
for await (const { value } of pipeline) {
if (!sink.write(value)) {
await once(sink, 'drain');
}
}
Deux conseils de terrain : en assemblant une chaîne de flux à la main, définissez highWaterMark explicitement sur chaque flux — la valeur par défaut de 16 en objectMode est trop généreuse pour de gros objets ; et préférez pipeline() de stream/promises à pipe(), qui gère pour vous la propagation d'erreurs et le nettoyage.
Les mesures : pic mémoire de quatre stratégies
| Stratégie | Échantillon | Pic RSS | Durée | Usage |
|---|---|---|---|---|
| readFileSync + JSON.parse | 186MB / 480k | 612MB | 1.3s | petits fichiers, accès aléatoire |
| streamArray + for await + écritures lentes en BDD (0.5ms chacune) | idem | 104MB (plate) | dicté par la BDD | ingestion ligne à ligne, transformations |
| streamArray + écritures via data, sans contre-pression | idem | 407MB | ~10s | l'exemple à ne pas suivre |
| streamArray + write()/drain | idem | 161MB | ~10s | écrire sur disque ou transférer |
Environnement : Node 22.13, Maximum resident set size via /usr/bin/time -v, échantillon synthétique aux champs de forme métier, exécutions uniques sans moyenne, écritures lentes simulées par setTimeout. Ces chiffres sont des conclusions d'ordre de grandeur pour cet échantillon, pas des constantes universelles — mesurez sur vos propres données.
Deux lectures méritent attention. La première et la deuxième stratégie diffèrent d'un facteur six en mémoire, au prix d'un échange de « 1.3 seconde » contre « la vitesse de la BDD ». La troisième et la quatrième diffèrent d'un facteur 2.5 : lire en flux sans contre-pression à l'écriture ne résout que la moitié du problème.
Diagnostic : vérifier que la contre-pression fonctionne vraiment
Les problèmes mémoire en production ne se diagnostiquent pas à l'intuition. Un article de Tencent Cloud sur le dépannage de la contre-pression donne une méthode concrète :
- Loguez temporairement
'pause'et'resume'sur les flux critiques. Si un pipeline à fort débit ne pause jamais, quelque part des données s'accumulent en mémoire ; - Observez
writable.writableLength— une croissance continue signifie que le buffer ne se vide jamais ; - Échantillonnez le RSS avec
process.memoryUsage()à intervalle et tracez la courbe, en distinguant « croissance en rampe » (accumulation) et « plateau en dents de scie » (libération saine).
Sous la sémantique for await, les événements pause et resume doivent alterner ; s'ils ne se déclenchent jamais, cherchez un écouteur data parasite ou un await oublié.
Quand le flux n'est pas la réponse
Le flux n'est pas la solution par défaut. Pour des fichiers de quelques dizaines de MB avec accès aléatoire par clé, un simple JSON.parse est plus simple et moins cher. Ouvrir un gros fichier dans le navigateur est un autre problème — comment ouvrir un gros fichier JSON couvre l'échelle des visualiseurs. Les frontières du parsing en flux sont claires :
- le niveau supérieur est un tableau (ou les données sont découpables en JSONL), la consommation est séquentielle, sans retour en arrière ;
- la taille du fichier est incontrôlée ou dépasse largement le tas disponible, et un import ne doit pas doubler l'empreinte du processus ;
- le consommateur a un écart de vitesse naturel (écritures en BDD, appels d'API aval), il faut donc une contre-pression plutôt qu'un tuyau à plein débit.
Quand la forme de haut niveau est irrégulière, inspectez d'abord la structure dans l'outil analyseur et formateur JSON ; l'équivalent en ligne de commande est traité dans jq pour les gros JSON — jq --stream et streamArray sont la même idée dans deux runtimes.
FAQ
stream-json est-il beaucoup plus lent que JSON.parse ?
En parsing pur, JSON.parse gagne : 1.3 seconde pour l'échantillon de 186MB, contre environ 7 secondes pour streamArray sans latence d'écriture (parsing par jetons plus construction d'objets enregistrement par enregistrement). Le bénéfice du flux est entièrement côté mémoire : le pic passe de 612MB à 104MB. Un import est de toute façon limité par la BDD, donc payer quelques secondes de parsing pour une marge mémoire de six fois est généralement un bon marché ; dans des réponses API à la milliseconde, non.
La contre-pression de for await équivaut-elle à pause/resume manuels ?
Sémantiquement oui : for await suspend le flux lisible tant que le corps de boucle est en attente, ce qui équivaut à appeler pause() quand write() renvoie false et resume() au drain. La différence : la mécanique du langage s'en charge et rien n'est oublié ; le câblage manuel perd la contre-pression de toute la chaîne dès qu'un point est raté.
Et si le niveau supérieur est un seul immense objet ?
stream-json fournit streamObject() (émet par clé) et le filtre Pick (ne parse que le sous-arbre choisi). Si quelques champs suffisent, Pick avec un JSONPath réduit le graphe entier au sous-graphe requis. L'entrée multi-documents (JSON Lines, séquences JSON) vaut mieux découpée ligne à ligne et traitée comme des documents indépendants.
Comment écrire le résultat en JSONL ou le transférer en aval ?
Le côté écriture pose la même question de contre-pression : fs.createWriteStream et http.request exigent de vérifier la valeur de retour de write() et d'attendre once(stream, 'drain') sur false — ou branchez le writable dans pipeline(). La vérification est simple : la courbe RSS après un passage doit être stable et writableLength ne doit pas croître en continu.
Quel est le moniteur mémoire le plus rapide pour une tâche d'import ?
Version minimale : un minuteur qui échantillonne process.memoryUsage().rss toutes les 100ms dans un tableau et imprime le maximum à la fin. Plus précis : /usr/bin/time -v node task.js donne directement le Maximum resident set size. En conteneur, placez la ligne d'alerte à 70% de la limite mémoire pour laisser de la marge au GC.