StackPractices
intermediate Por Mathias Paulenko

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.readFile es 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.

flowchart diagram: createReadStream<br>bloques de 64KB

Dos ajustes importan:

  • highWaterMark — tamaño del buffer interno. 64KB para streams de bytes, 16 objetos para objectMode. 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

EnfoqueMemoriaVelocidadUsar cuando
fs.readFileO(tamaño del archivo)RápidoArchivos < 100MB
readline + createReadStreamO(buffer)MedioArchivos por líneas
Pipeline TransformO(buffer)MedioTransformar mientras se lee
Readable.from + generador asyncO(buffer)FlexibleFuentes de datos personalizadas
csv-parse / stream-jsonO(buffer)MedioCSV/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.readFile falla con archivos de varios GB.
  • pipeline() (o la versión de stream/promises) en lugar de cadenas .pipe(): los errores destruyen todos los streams de la cadena.
  • readline para formatos por línea (logs, CSV, JSONL): maneja \n y \r\n correctamente.
  • Transforms objectMode para registros parseados.
  • Agrupa las llamadas externas (inserts, llamadas a API) en lugar de una por línea.
  • for await...of sobre 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 \n sin 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.
  • readline en archivos binarios: es una herramienta de texto. Usa bloques crudos para binario.
  • Olvidar objectMode al emitir objetos: se serializan.
  • Olvidar el callback() por completo: el stream cuelga a mitad del pipeline.

Ver También

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.