Express.js
Explica cómo transmitir responses grandes con streams, respetar backpressure, manejar errores y aborts y evitar cargar archivos completos en memoria.
Un stream permite procesar datos por partes sin esperar a tenerlos completos en memoria. La idea central no es “hacer todo más rápido”, sino mantener el consumo de memoria y la presión entre productor y consumidor bajo control.
Los objetos HTTP de Node.js son streams:
request es un Readable: el cliente produce bytes y la aplicación los consume.response es un Writable: la aplicación produce bytes y el cliente los consume.Express añade helpers, pero no elimina este comportamiento. Cuando utilizas express.json(), el middleware consume el stream completo, aplica límites, interpreta los bytes y finalmente asigna un valor a request.body. Cuando envías un archivo o un CSV grande, puedes evitar construir todo el contenido en memoria conectando una fuente directamente con la response.
Sin streaming, una exportación puede seguir este flujo:
consultar 200 000 filas
↓
crear un array enorme
↓
convertir todo a CSV
↓
guardar un string o Buffer completo
↓
enviar la responseEl coste crece con el volumen. La aplicación retiene memoria hasta completar la operación, aumenta la pausa del garbage collector y no empieza a entregar datos hasta terminar todo el cálculo.
Con streams:
leer lote
↓
transformar filas
↓
escribir chunks
↓
respetar backpressure
↓
continuar hasta finalizarEl cliente recibe datos progresivamente y el proceso mantiene una ventana limitada de memoria.
source Readable
↓ chunks
Transform opcional
↓ chunks
response WritableCada etapa posee una capacidad interna. Cuando el destino no puede consumir al mismo ritmo, comunica backpressure para que la fuente reduzca o pause la producción.
Backpressure no significa que la red nunca acumule datos. Significa que el pipeline dispone de señales para evitar que el productor genere indefinidamente más de lo que el consumidor puede manejar.
const canContinue = response.write(chunk);
if (!canContinue) {
await once(response, 'drain');
}response.write() devuelve false cuando el buffer interno alcanzó su umbral. Ignorar ese valor y continuar escribiendo puede aumentar memoria, especialmente con clientes lentos.
Normalmente no necesitas manejar esto manualmente. pipeline() conecta streams y coordina propagación de presión, errores y cierre.
import { createReadStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
router.get('/manual.pdf', async (_request, response) => {
response.status(200);
response.type('application/pdf');
response.set('Content-Disposition', 'attachment; filename="manual.pdf"');
await pipeline(
createReadStream('/srv/files/manual.pdf'),
response,
);
});Flujo:
createReadStream abre el archivo y lee por partes.pipeline escribe en la response respetando backpressure.En producción, la ruta también necesita autorización, resolución segura del archivo, manejo de abort y un strategy de almacenamiento apropiado.
import { Readable, Transform } from 'node:stream';
import { pipeline } from 'node:stream/promises';
function rowsToCsv(): Transform {
let headerWritten = false;
return new Transform({
objectMode: true,
transform(row: OrderExportRow, _encoding, callback) {
try {
const header = headerWritten
? ''
: 'id,status,total,created_at\n';
headerWritten = true;
const line = [
escapeCsv(row.id),
escapeCsv(row.status),
escapeCsv(row.total.toString()),
escapeCsv(row.createdAt.toISOString()),
].join(',') + '\n';
callback(null, header + line);
} catch (error) {
callback(error as Error);
}
},
});
}
router.get('/orders/export.csv', async (request, response) => {
const signal = AbortSignal.timeout(30_000);
const rows = ordersRepository.streamForExport({
tenantId: response.locals.tenantId,
signal,
});
response.status(200);
response.type('text/csv; charset=utf-8');
response.set(
'Content-Disposition',
'attachment; filename="orders.csv"',
);
await pipeline(
Readable.from(rows),
rowsToCsv(),
response,
{ signal },
);
});El ejemplo evita cargar todas las órdenes simultáneamente. El repository debe producir filas de forma incremental —por cursor, stream del driver o lotes— y cerrar correctamente su recurso al terminar o abortar.
Un stream binario mueve Buffer o strings. Un stream con objectMode: true puede mover objetos JavaScript entre etapas.
Object mode facilita transformaciones como fila → CSV, pero cada objeto conserva su coste en memoria. No convierte una consulta que carga todo el array en una consulta incremental. La fuente debe ser streaming desde el comienzo.
El primer write puede enviar headers. Después de ese punto:
Por eso se deben validar permisos, parámetros y dependencias críticas antes de iniciar el body.
El cliente puede cerrar la conexión durante una descarga:
const controller = new AbortController();
request.once('aborted', () => {
controller.abort(new Error('Client aborted request'));
});La señal debe propagarse a:
Cerrar la response no cancela automáticamente una query ni libera todos los recursos de origen.
try {
await pipeline(source, response);
} catch (error) {
if (response.headersSent) {
response.destroy(error as Error);
return;
}
throw error;
}Antes de enviar headers, el error middleware todavía puede construir una respuesta consistente. Después, lo más seguro suele ser cerrar la conexión y registrar el fallo.
Conviene cuando:
Content-Length exactamente.Conviene cuando:
Streaming añade complejidad: errores parciales, cancelación, backpressure, límites y observabilidad.
El writable aplica backpressure, pero mantiene la conexión y algunos recursos abiertos. Define timeouts y límites de concurrencia para descargas grandes.
No existe problema de backpressure; la response esperará chunks. Aun así, un proxy puede aplicar timeout por inactividad.
El cliente recibirá un archivo incompleto. No existe una respuesta HTTP posterior que repare el contenido. Puedes incluir checksums, jobs de exportación o archivos generados previamente para operaciones críticas.
Usar streams no evita bloquear el event loop. Compresión intensa, cifrado o transformación pesada puede requerir workers, límites o procesamiento fuera del request.
Videos y archivos grandes pueden requerir Range, 206 Partial Content, Content-Range y seek en la fuente. pipeline por sí solo no implementa ese contrato.
Mide:
drain.Un endpoint que usa poca memoria con una request puede agotar el proceso con cien streams concurrentes y recursos de base de datos retenidos.
Readable.from(hugeArray) mejora la escritura, pero el array ya ocupa memoria. La fuente debe producir incrementalmente.
Escribir sin atender write() === false permite acumulación de buffers.
pipeline ofrece una coordinación más segura de errores y cierre.
Puede producir respuestas con tipo, cache o filename incorrectos.
Cuando la generación tarda minutos, suele ser mejor crear un job, guardar el archivo y notificar al usuario.
pipeline() es la opción preferida para conectar etapas.headersSent no pueden convertirse en un JSON limpio.Readable.from(arrayGrande) no soluciona el uso de memoria de origen?response.write() cuando devuelve false?drain.Compression y Content-Encoding explica cómo reducir bytes sin ignorar CPU, negociación, buffering y seguridad.