Noções Básicas de Streams

8 exemplos para você começar com Streams - 6 básicos e 2 intermediários.

Pré-requisitos

• Node.js 24.18.0, import { Readable, Writable } from 'node:stream'.
• Leia Noções Básicas de Buffers para manipulação de blocos.

Exemplos Básicos

1. Readable a partir de um Iterador

Gere blocos sem carregar tudo na memória.

import { Readable } from 'node:stream';
 
const readable = Readable.from(['chunk-a', 'chunk-b', 'chunk-c']);
 
for await (const chunk of readable) {
  console.log(chunk);
}

• Readable.from envolve iteráveis e iteráveis assíncronos.
• for await...of consome até o final null.
• O padrão é modo de byte/string, a menos que objectMode: true.

Relacionado: Padrões Readable & Writable - modos

2. Pipe para Writable

Conecte produtor a consumidor - encadeamento clássico no estilo Unix.

import { createWriteStream } from 'node:fs';
import { Readable } from 'node:stream';
 
Readable.from(['line1\n', 'line2\n']).pipe(createWriteStream('out.txt'));

• pipe conecta data a write e lida com end.
• Erros em qualquer lado precisam de manipuladores explícitos - prefira pipeline em produção.
• pipe não encaminha erros automaticamente em padrões mais antigos.

Relacionado: stream/promises.pipeline - encadeamento seguro

3. fs.createReadStream

Transmita arquivos grandes do disco.

import { createReadStream } from 'node:fs';
 
const stream = createReadStream('package.json', { encoding: 'utf8', highWaterMark: 64 * 1024 });
 
stream.on('data', (chunk) => console.log('chunk', chunk.length));
stream.on('end', () => console.log('done'));

• highWaterMark controla o tamanho do buffer interno por stream.
• Encoding produz strings; omita para Buffers brutos.
• Prefira pipeline para respostas HTTP para downloads.

4. Resposta HTTP como Writable

ServerResponse é um stream Writable.

import { createServer } from 'node:http';
import { createReadStream } from 'node:fs';
 
createServer((req, res) => {
  createReadStream('package.json').pipe(res);
}).listen(3000);

• Cabeçalhos devem ser definidos antes de encadear ou via writeHead primeiro.
• Desconexão do cliente deve destruir o stream de leitura - pipeline cuida da limpeza.
• Veja Streaming de Respostas HTTP para proxies.

5. Transform com map (simples)

Altere os dados enquanto eles passam.

import { Transform } from 'node:stream';
 
const upper = new Transform({
  transform(chunk, _enc, cb) {
    cb(null, String(chunk).toUpperCase());
  },
});
 
Readable.from(['hello']).pipe(upper).pipe(process.stdout);

• Transform é tanto legível quanto gravável - fica no meio do pipeline.
• Callback cb(err, data) sinaliza chunk processado ou erro.
• _flush é executado no final para saída pendente.

Relacionado: Transform & Duplex - pipelines de análise

6. Stream em Modo de Objeto

Transmita objetos JavaScript em vez de bytes.

import { Transform } from 'node:stream';
 
const parseLines = new Transform({
  objectMode: true,
  transform(chunk, _enc, cb) {
    const lines = String(chunk).split('\n').filter(Boolean);
    for (const line of lines) this.push({ line });
    cb();
  },
});

• highWaterMark conta objetos em modo de objeto, não bytes.
• Consumidores devem esperar objetos em eventos data.
• Útil para análise de linhas CSV e pipelines de eventos de log.

Exemplos Intermediários

7. pipeline com Promises

Propagação de erros e limpeza em uma única chamada.

import { pipeline } from 'node:stream/promises';
import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';
 
await pipeline(
  createReadStream('access.log'),
  createGzip(),
  createWriteStream('access.log.gz'),
);

• pipeline destrói streams em caso de erro ou fechamento antecipado.
• Retorna uma Promise - use try/catch em manipuladores assíncronos.
• Preferível a cadeias manuais de .pipe().pipe().

Relacionado: stream/promises.pipeline - mergulho profundo

8. Backpressure com pause/resume

Writable sinaliza quando não pode aceitar mais dados.

import { Readable, Writable } from 'node:stream';
 
const slow = new Writable({
  write(chunk, _enc, cb) {
    setTimeout(() => cb(), 100);
  },
});
 
const fast = Readable.from(['a', 'b', 'c', 'd']);
fast.pipe(slow); // pipe lida com pause/resume automaticamente

• Quando write retorna false, pause o readable até drain.
• Loops read manuais devem verificar o valor de retorno de writable.write.
• Veja Backpressure para ajuste de produção.

Versões da Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.