JSON Toolkit

Leer JSON grande en Node.js: análisis en streaming con stream-json y contrapresión en la práctica

En resumen: Leer un array JSON de 186MB con readFileSync y JSON.parse lleva la memoria al pico de 612MB; cambiar al streamArray de stream-json la mantiene plana en 104MB. Este artículo compara cuatro estrategias de lectura con mediciones, explica por qué for await produce contrapresión de forma natural, cómo el evento data la pierde y cómo configurar highWaterMark y drain en el lado de escritura.

Intermedio~5 min de lecturaPublicado el 2026-11-17Actualizado el 2026-11-17
Streaming de un archivo JSON grande en Node.js: comparación de streamArray y contrapresión

Cuando importar un archivo JSON de 186MB empuja el proceso a 600MB de memoria, el culpable no es el tamaño del archivo — JSON.parse intercambió todo el texto por todo el grafo de objetos de una sola vez. Cambia la estrategia de lectura y la curva de memoria se vuelve plana.

Un síntoma: archivo de 186MB con pico de 612MB

Los trabajos de importación en el servidor son el terreno donde este problema aparece más: sincronizaciones programadas de pedidos, limpieza de logs, carga masiva de historial. La implementación típica se ve así:

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 patrón en Node 22.13. La muestra: un array de 480 000 registros de pedidos, archivo de 186MB con cadenas, objetos anidados y arrays en los campos, imitando estructuras de negocio reales. Pico del Maximum resident set size medido con /usr/bin/time -v: el archivo se lee en 1.3 segundos, pero el RSS culmina en 612MB — 3.3 veces el archivo. Con el límite por defecto del espacio viejo de V8 en 1.4–2GB, pocos trabajos de este tipo en paralelo bastan para acabar con el contenedor por OOM Kill.

La aritmética no es exótica: el texto crudo ocupa una copia en memoria (unos 186MB), el grafo de objetos tras el parse ocupa otra (cada clave de tipo cadena, cada cabecera de objeto anidado y cada array lleva coste), y el propio proceso de análisis asigna transitoriamente encima. Llegar a 600MB de pico es normal.

Segunda causa: JSON.parse intercambia todo el texto por todo el grafo

El contrato de JSON.parse es «dame el texto completo — te devuelvo el grafo completo». Exige que todo el texto esté en su lugar antes de empezar y solo entrega el resultado al terminar. No existe mecanismo alguno para «primero te doy los primeros 1 000 registros».

El coste del grafo de objetos se ha medido punto por punto en La cuenta de memoria de JSON: cada cadena ocupa espacio real, cada clave de objeto toma un hueco, y la anchura de un array depende de los tipos de sus elementos. Unas decenas de MB de JSON se convierten rutinariamente en tres a cinco veces más tras el análisis, con el pico apilado encima.

Pero la mayoría de los trabajos de importación nunca necesitan el grafo entero: insertar línea a línea, filtrar línea a línea, transformar línea a línea — cada registro puede liberarse nada más procesarlo. Lo que el trabajo necesita es la capacidad «analizado un registro — entrego un registro». Eso es precisamente la definición de análisis en streaming.

La solución: streamArray entrega registro a registro, y for await da contrapresión gratis

stream-json implementa el parser como un Transform stream que consume tokens y nunca espera el archivo entero. Cuando el nivel superior es un array, streamArray() emite {key, value} en el instante en que cada elemento termina de analizarse:

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);
  }
}

Sobre el mismo archivo de 186MB con los mismos 480 000 registros, esta versión tiene un pico de RSS de 104MB, plano durante toda la ejecución. En memoria solo existen en cada instante «el elemento actual + el estado del parser»; los registros terminados se reclaman de inmediato.

Un detalle fácil de perder: for await no tira del siguiente registro del parser hasta que saveToDb termina, así que el parser deja de leer el archivo. Base de datos más lenta, lectura más lenta — eso es la contrapresión, formada de forma natural, sin una sola línea de código extra. Un análisis en dev.to sobre la ingesta de un flujo municipal de 4GB usa la misma cadena con pick({filter:'data'}) y reporta una curva de memoria igual de plana.

Cuando el lado de escritura falla: un evento data sin pausa vuelve a subir la memoria

El análisis en streaming solo disciplina la lectura. Si la escritura no acepta la contrapresión, la memoria vuelve a subir. El fallo clásico: escribir de forma asíncrona dentro de un manejador de data sin mirar el buffer del writable:

// Mal: evento data + escritura asíncrona, contrapresión totalmente perdida
readable.on('data', async (chunk) => {
  await slowWrite(chunk); // el stream no espera; el buffer sigue hinchándose
});

En modo data el stream sigue fluyendo, por lento que sea slowWrite, y todo se acumula en el buffer interno del writable. Sobre la misma muestra de 186MB dirigimos los registros a un Writable lento que retrasa 1ms cada centésimo bloque. Ignorando la contrapresión el RSS culminó en 407MB; suspendiendo con await once(sink, 'drain') cuando write() devuelve false, en 161MB. La diferencia de 246MB son literalmente datos sentados en el buffer de escritura.

// Bien: pausa cuando write() devuelve false, reanudación en drain
for await (const { value } of pipeline) {
  if (!sink.write(value)) {
    await once(sink, 'drain');
  }
}

Dos notas de campo más: al montar cadenas de streams a mano, define highWaterMark explícitamente en cada stream — el valor por defecto de 16 en objectMode es demasiado generoso para objetos grandes; y prefiere pipeline() de stream/promises en lugar de pipe(), que se encarga de la propagación de errores y la limpieza.

Las mediciones: pico de memoria de cuatro estrategias

Estrategia Muestra Pico RSS Duración Uso
readFileSync + JSON.parse 186MB / 480 mil 612MB 1.3s archivos pequeños, acceso aleatorio
streamArray + for await + escrituras lentas en BD (0.5ms cada una) la misma 104MB (plana) al ritmo de la BD ingesta registro a registro, transformaciones
streamArray + escrituras vía data, sin contrapresión la misma 407MB ~10s el ejemplo a no seguir
streamArray + write()/drain la misma 161MB ~10s escribir a disco o reenviar

Entorno: Node 22.13, Maximum resident set size vía /usr/bin/time -v, muestra sintética con campos de forma empresarial, ejecuciones únicas sin promediar, escrituras lentas simuladas con setTimeout. Estos números son conclusiones de orden de magnitud para esta muestra, no constantes universales — mide con tus propios datos.

Dos lecturas merecen atención. La primera y la segunda estrategia difieren seis veces en memoria, al precio de cambiar «1.3 segundos» por «la velocidad de la BD». La tercera y la cuarta difieren 2.5 veces: leer en streaming sin contrapresión en la escritura resuelve solo la mitad del trabajo.

Diagnóstico: confirmar que la contrapresión funciona de verdad

Los problemas de memoria en producción no se resuelven por intuición. Un material de Tencent Cloud sobre localización de fallos de contrapresión da un plan práctico:

  1. Logea temporalmente los eventos 'pause' y 'resume' en los streams críticos. Si una tubería de gran volumen nunca se pausa, en algún sitio los datos se están acumulando en memoria;
  2. Observa writable.writableLength — crecimiento continuo significa que el buffer nunca se vacía;
  3. Muestrea el RSS con process.memoryUsage() a intervalos y dibuja la curva, distinguiendo «crecimiento en rampa» (acumulación) de «estabilidad en dientes de sierra» (liberación sana).

Bajo la semántica de for await, los eventos pause y resume deben alternarse; si nunca se disparan, busca un listener data de más o un await olvidado.

Cuándo el streaming no es la respuesta

El streaming no es la solución por defecto. Para archivos de unas decenas de MB con acceso aleatorio por clave, una sola llamada a JSON.parse es más simple y barata. Abrir un archivo grande en el navegador es otro dominio de problemas — cómo abrir un archivo JSON grande cubre la escalera de visores. Las fronteras del análisis en streaming son claras:

  • el nivel superior es un array (o los datos se pueden partir como JSONL), el consumo es secuencial, sin miradas atrás;
  • el tamaño del archivo es incontrolado o supera con creces el margen del heap, y una importación no debe duplicar la huella del proceso;
  • el consumidor tiene un desnivel de velocidad natural (escrituras en BD, llamadas API aguas abajo), así que necesita contrapresión y no una manguera a plena potencia.

Cuando la forma del nivel superior es irregular, mira primero la estructura en la herramienta parser y formateador JSON; el equivalente de línea de comandos está en jq para JSON grandes — jq --stream y streamArray son la misma idea en dos runtimes.

FAQ

¿Cuánto más lento es stream-json que JSON.parse?

En análisis puro gana JSON.parse: 1.3 segundos para la muestra de 186MB, frente a unos 7 segundos de streamArray sin latencia de escritura (análisis por tokens más construcción de objetos registro a registro). El beneficio del streaming vive por completo en el lado de la memoria: el pico baja de 612MB a 104MB. Una importación ya está limitada por la escritura en la BD, así que pagar unos segundos de análisis por un margen de memoria de seis veces suele ser un buen trato; dentro de respuestas API de milisegundos, no.

¿La contrapresión de for await es lo mismo que pause/resume manuales?

Semánticamente sí: for await suspende el stream legible mientras el cuerpo del bucle está pendiente, lo que equivale a llamar pause() cuando write() devuelve false y resume() en el drain. La diferencia: la mecánica del lenguaje lleva la contabilidad y no olvida nada; el cableado manual pierde la contrapresión de toda la cadena en cuanto se escapa un punto.

¿Y si el nivel superior es un único objeto inmenso?

stream-json trae streamObject() (emite por clave) y el filtro Pick (analiza solo el subárbol elegido). Si bastan algunos campos, Pick con un JSONPath reduce el grafo entero al subgrafo requerido. La entrada multi-documento (JSON Lines, secuencias JSON) conviene partirla línea a línea y tratarla como documentos independientes.

¿Cómo escribir el resultado como JSONL o reenviarlo aguas abajo?

El lado de escritura es la misma pregunta de contrapresión: fs.createWriteStream y http.request exigen comprobar el valor de retorno de write() y esperar once(stream, 'drain') cuando es false — o conecta el writable a pipeline(). La verificación es simple: la curva de RSS tras una pasada debe ser estable y writableLength no debe crecer persistentemente.

¿Cuál es el monitor de memoria más rápido para un trabajo de importación?

Versión mínima: un temporizador que muestrea process.memoryUsage().rss cada 100ms en un array e imprime el máximo al final. Más preciso: /usr/bin/time -v node task.js da directamente el Maximum resident set size. En contenedores, coloca la línea de alarma en el 70% del límite de memoria dejando margen al GC.

Referencias

Herramientas relacionadas

Artículos relacionados

jq y archivos JSON grandes: por qué -s revienta la memoria y cómo procesar en streaming

Agregar cientos de MB de logs JSON con jq -s termina en OOM, mientras que reduce inputs produce la misma estadística con unos pocos MB de RAM. Medido sobre una muestra de 220 MB y 2 millones de líneas: slurp culmina en 2,08 GB frente a 3,5 MB del reductor en streaming. Este artículo explica el mecanismo de consumo de memoria, el procesamiento línea a línea del JSONL, los eventos de ruta de --stream y tres trampas reales, incluida la salida vacía silenciosa de -n --stream.

Avanzado~6 min de lecturaActualizado el 2026-11-12

¿El archivo JSON grande no abre? Elige la herramienta según el tamaño

Las exportaciones JSON de decenas de MB suelen congelar editores de texto y herramientas en línea, mientras que el parseo en sí solo tarda unos cientos de milisegundos. Medimos el tiempo y la memoria en cada etapa para una muestra de 45 MB con 500.000 registros, mostrando que el coste real está en el número de líneas y nodos, y construimos una tabla de selección de herramientas por tamaño de archivo: visor en línea, línea de comandos, procesamiento por stream y aplicación de escritorio.

Intermedio~6 min de lecturaActualizado el 2026-11-07