Leer Archivos Grandes en Node.js con Streams (5GB en 64KB RAM)
Procesa archivos de varios GB en Node.js con createReadStream, readline, pipelines Transform y backpressure — memoria constante, código funcional.
Descripción General
Leer un archivo grande con fs.readFile() lo carga entero en memoria: un archivo de 5GB necesita 5GB de heap y falla. Los streams procesan los datos en bloques de ~64KB, así que un archivo de 5GB cuesta unos 64KB de RAM. Esta receta cubre createReadStream, readline, pipeline y streams Transform en Node.js, con backpressure bien hecho.
¿Lo mismo en Python, Java o Bash? Mira la versión multi-lenguaje: Leer Archivos Grandes.
Cuándo Usar
- Archivos más grandes que la RAM: logs, exports CSV, datasets JSONL
- Transformas datos mientras lees (filtrar, mapear, convertir formato)
- La memoria debe mantenerse plana sin importar el tamaño de entrada
- Parseas línea a línea o en bloques de tamaño fijo
Cuándo NO Usar
- Archivos pequeños (<100MB):
fs.readFilees más simple y suficientemente rápido - Necesitas acceso aleatorio al medio del archivo: los streams son secuenciales
- El resultado completo debe estar en memoria de todas formas (un objeto JSON): usa
fs.readFile+JSON.parse
Solución
Leer línea a línea con readline
const fs = require("fs");
const readline = require("readline");
async function processLineByLine(filePath) {
const fileStream = fs.createReadStream(filePath);
const rl = readline.createInterface({
input: fileStream,
crlfDelay: Infinity,
});
let lineCount = 0;
for await (const line of rl) {
lineCount++;
if (lineCount % 100_000 === 0) {
console.log(`Processed ${lineCount} lines`);
}
}
console.log(`Total lines: ${lineCount}`);
}
processLineByLine("large_file.log");
Procesar CSV con transform streams
El parser guarda un buffer de resto: una línea partida entre dos bloques se mantiene entera, y flush() emite la última línea parcial:
const fs = require("fs");
const { Transform } = require("stream");
function createCsvParser() {
let leftover = "";
return new Transform({
readableObjectMode: true, // lee bytes, emite arrays de filas
transform(chunk, encoding, callback) {
const lines = (leftover + chunk.toString()).split("\n");
leftover = lines.pop(); // la última línea incompleta espera al siguiente bloque
for (const line of lines) {
if (line.trim()) {
this.push(line.split(","));
}
}
callback();
},
flush(callback) {
if (leftover.trim()) {
this.push(leftover.split(","));
}
callback();
},
});
}
function createFilter(filterFn) {
return new Transform({
objectMode: true,
transform(row, encoding, callback) {
if (filterFn(row)) {
this.push(row);
}
callback();
},
});
}
function createJsonStringifier() {
return new Transform({
objectMode: true,
transform(row, encoding, callback) {
this.push(JSON.stringify(row) + "\n");
callback();
},
});
}
// Pipeline: leer CSV -> parsear -> filtrar -> convertir a JSON -> escribir
fs.createReadStream("data.csv")
.pipe(createCsvParser())
.pipe(createFilter(row => row[2] === "active"))
.pipe(createJsonStringifier())
.pipe(fs.createWriteStream("active_users.jsonl"));
Usar pipeline para manejar errores
pipeline() destruye todos los streams de la cadena cuando uno falla — .pipe() los deja perder recursos:
const fs = require("fs");
const { pipeline } = require("stream/promises");
async function processFile(inputPath, outputPath) {
try {
await pipeline(
fs.createReadStream(inputPath),
createCsvParser(),
createFilter(row => row[2] === "active"),
createJsonStringifier(),
fs.createWriteStream(outputPath)
);
console.log("Pipeline succeeded");
} catch (err) {
console.error("Pipeline failed:", err);
}
}
processFile("data.csv", "output.jsonl");
Procesar en lotes
const fs = require("fs");
const readline = require("readline");
async function processInBatches(filePath, batchSize = 1000) {
const rl = readline.createInterface({
input: fs.createReadStream(filePath),
crlfDelay: Infinity,
});
let batch = [];
for await (const line of rl) {
batch.push(line);
if (batch.length >= batchSize) {
await processBatch(batch); // pausa la lectura hasta terminar
batch = [];
}
}
if (batch.length > 0) {
await processBatch(batch);
}
}
async function processBatch(lines) {
// p. ej., insert masivo, llamada a API
console.log(`Processing batch of ${lines.length} lines`);
}
processInBatches("large_file.log", 500);
Trabajo asíncrono por línea con límite de concurrencia
Haz la concurrencia fuera del stream — for await sobre la salida da backpressure natural, sin malabares de callbacks:
const fs = require("fs");
const readline = require("readline");
async function enrichFile(inputPath, concurrency = 5) {
const rl = readline.createInterface({
input: fs.createReadStream(inputPath),
crlfDelay: Infinity,
});
const pending = new Set();
for await (const line of rl) {
const row = line.split(",");
const task = enrichRow(row);
pending.add(task);
task.finally(() => pending.delete(task));
if (pending.size >= concurrency) {
await Promise.race(pending); // backpressure: espera a un hueco
}
}
await Promise.all(pending);
}
async function enrichRow(row) {
const response = await fetch(`https://api.example.com/user/${row[0]}`);
const data = await response.json();
return [...row, data.name];
}
enrichFile("users.csv");
Leer un archivo gzip
const fs = require("fs");
const zlib = require("zlib");
const readline = require("readline");
async function processGzippedFile(filePath) {
// el fileStream DEBE conectarse a gunzip — readline lee de la salida de gunzip
const gunzipped = fs.createReadStream(filePath).pipe(zlib.createGunzip());
const rl = readline.createInterface({ input: gunzipped });
let count = 0;
for await (const line of rl) {
count++;
}
console.log(`Total lines: ${count}`);
}
processGzippedFile("large_file.log.gz");
Uso de memoria: readFile vs stream
// MAL — carga el archivo entero en memoria
// archivo de 5GB = 5GB de heap, probablemente falla
fs.readFile("huge.log", (err, data) => {
const lines = data.toString().split("\n");
console.log(lines.length);
});
// BIEN — memoria constante, ~64KB en todo momento
const rl = readline.createInterface({
input: fs.createReadStream("huge.log", { highWaterMark: 64 * 1024 }),
});
let count = 0;
rl.on("line", () => count++);
rl.on("close", () => console.log(count));
Cómo Funcionan los Streams
Node.js tiene cuatro tipos de stream: Readable produce datos (lectura de archivos, respuestas HTTP), Writable los consume (escritura de archivos), Transform hace ambas cosas modificando los datos, y Duplex es un canal bidireccional. Un pipeline de leer-transformar-escribir es Readable → Transform(s) → Writable.
Dos ajustes importan:
highWaterMark— tamaño del buffer interno. 64KB para streams de bytes, 16 objetos paraobjectMode. Buffers más grandes implican menos llamadas al sistema y más memoria.objectMode— emite objetos en lugar de bytes; obligatorio para registros parseados (filas CSV).
El backpressure es automático a través de .pipe() y pipeline(): cuando el destino está ocupado, el origen se pausa. Si escribes a un stream manualmente, respeta que write() devuelva false y espera el evento drain.
Variantes
| Enfoque | Memoria | Velocidad | Usar cuando |
|---|---|---|---|
fs.readFile | O(tamaño del archivo) | Rápido | Archivos < 100MB |
readline + createReadStream | O(buffer) | Medio | Archivos por líneas |
| Pipeline Transform | O(buffer) | Medio | Transformar mientras se lee |
Readable.from + generador async | O(buffer) | Flexible | Fuentes de datos personalizadas |
| csv-parse / stream-json | O(buffer) | Medio | CSV/JSON real con quoting y anidado |
Para parseo de CSV/JSON en producción, prefiere parsers streaming consolidados (csv-parse maneja campos entrecomillados; stream-json maneja JSON anidado) en lugar de splits caseros.
Lo Que Funciona
- Streams para cualquier cosa por encima de ~100MB.
fs.readFilefalla con archivos de varios GB. pipeline()(o la versión destream/promises) en lugar de cadenas.pipe(): los errores destruyen todos los streams de la cadena.readlinepara formatos por línea (logs, CSV, JSONL): maneja\ny\r\ncorrectamente.- Transforms
objectModepara registros parseados. - Agrupa las llamadas externas (inserts, llamadas a API) en lugar de una por línea.
for await...ofsobre un stream para backpressure natural: el bucle simplemente espera.
Errores Comunes
fs.readFile()en archivos grandes: un fallo por falta de memoria a la espera de ocurrir..pipe()sin manejo de errores: un stream que falla deja a los demás perdiendo descriptores de archivo.- Cortar bloques por
\nsin buffer de resto: las líneas quedan partidas en los bordes de bloque. - Llamar
callback()dos veces dentro de un Transform:ERR_MULTIPLE_CALLBACK. Si lo difieres, guarda el callback y llámalo exactamente una vez. readlineen archivos binarios: es una herramienta de texto. Usa bloques crudos para binario.- Olvidar
objectModeal emitir objetos: se serializan. - Olvidar el
callback()por completo: el stream cuelga a mitad del pipeline.
Ver También
- API de stream de Node.js: pipeline, Transform, backpressure.
- readline de Node.js: detalles de la interfaz línea a línea.
- csv-parse: parser CSV streaming para quoting del mundo real.
- Guía de procesamiento con streams: la versión larga.
Código complementario: un pipeline CSV→JSONL ejecutable está en el repo complementario.
Preguntas frecuentes
¿Cuál es la diferencia entre readline y createReadStream?
createReadStream emite bloques de bytes crudos (~64KB cada uno) sin concepto de líneas. readline envuelve un stream y emite líneas completas, manejando \n y \r\n. Usa createReadStream directamente para datos binarios o bloques de tamaño fijo; usa readline para formatos de texto.
¿Cómo leo un archivo sin cargarlo en memoria?
fs.createReadStream(path) más readline o un pipeline Transform: el archivo se procesa en bloques de ~64KB y solo el buffer vive en RAM.
¿Cuál es el tamaño máximo de archivo que puedo procesar con streams?
Sin límite práctico. La memoria se mantiene plana porque los datos fluyen en bloques: puedes procesar archivos más grandes que la RAM disponible.
¿Debo usar .pipe() o pipeline()?
pipeline(). Destruye todos los streams de la cadena cuando uno falla; .pipe() no propaga errores y deja streams abiertos.
¿Cómo manejo el backpressure en un Transform personalizado?
Que this.push() devuelva false significa que el destino está lleno: deja de emitir hasta la siguiente llamada a transform(). Deja que el framework paute el callback(); si lo difieres, guarda el callback y llámalo exactamente una vez.
¿Puedo procesar archivos binarios con readline?
No: readline corta por fines de línea y corrompe datos binarios. Usa bloques crudos de createReadStream y operaciones de Buffer.
Recursos Relacionados
Leer Archivos Grandes
Cómo leer archivos grandes de forma eficiente sin agotar la memoria.
RecipeProcesar Archivos Grandes con Streams
Cómo leer, transformar y escribir archivos grandes eficientemente usando streams sin cargar archivos completos en memoria en Python, Node.js y Java.
RecipeEscribir Archivos Grandes
Cómo escribir archivos grandes de forma eficiente usando salida bufferizada y streaming.
RecipeComprimir y Descomprimir Archivos con ZIP, GZIP y TAR
Crea y extrae archivos ZIP, GZIP y TAR en Python, Node.js, Java y Bash con lectura en streaming y patrones de extracción segura.
RecipeObservar Cambios en Archivos
Cómo monitorear cambios en el sistema de archivos en tiempo real. Incluye watchers a nivel kernel en Python, JavaScript, Java y Bash, con debounce, manejo de OVERFLOW y fallback por polling.
GuideProcesamiento de Streams: Pipelines con Kafka y Flink
Guía práctica sobre procesamiento de streams: elegir entre Kafka Streams, Flink y Spark Streaming, diseñar esquemas de eventos, manejar operaciones stateful, y construir pipelines exactly-once para datos en tiempo real.