Padrões Readable & Writable

Streams Readable e Writable compartilham modos e primitivas de controle de fluxo - escolha o modo byte vs objeto antecipadamente e combine os tamanhos dos chunks do produtor com a taxa de transferência do consumidor.

Receita

import { Readable, Writable } from 'node:stream';
 
// Modo byte (padrão)
const byteStream = Readable.from([Buffer.from('ab'), Buffer.from('cd')]);
 
// Modo objeto
const objectStream = Readable.from([{ id: 1 }, { id: 2 }], { objectMode: true });

Quando usar isso:

• Analisar objetos de linha CSV/NDJSON de um disco
• Escrever objetos de métricas agregadas para um escritor em lote
• Ajustar highWaterMark para memória vs latência
• Implementar Readable customizado a partir de uma fonte de dados assíncrona

Exemplo de Trabalho

import { Readable, Writable } from 'node:stream';
 
class CounterSource extends Readable {
  private i = 0;
  constructor(private max: number, opts?: ConstructorParameters<typeof Readable>[0]) {
    super({ objectMode: true, ...opts });
  }
  _read(): void {
    if (this.i >= this.max) {
      this.push(null);
      return;
    }
    this.push({ n: this.i++ });
  }
}
 
const batchWriter = new Writable({
  objectMode: true,
  write(obj: { n: number }, _enc, cb) {
    // simula inserção em lote no DB
    setImmediate(cb);
  },
});
 
const source = new CounterSource(1000);
source.pipe(batchWriter);

// Modo pausado - read() explícito
const r = Readable.from(['a', 'b', 'c']);
r.on('readable', () => {
  let chunk;
  while ((chunk = r.read()) !== null) {
    console.log(chunk);
  }
});

O que isso demonstra:

• Readable customizado implementa _read e faz push até null encerrar o stream
• Writable em modo objeto recebe objetos tipados - agrupe em _write ou acumule para inserção em massa
• Modo pausado usa o evento readable + read() - útil para analisar framing
• Modo flowing (data event ou pipe) é o padrão para a maioria das I/Os

Mergulho Profundo

Como Funciona

• Modo Flowing - dados emitidos automaticamente via eventos data ou pipe.
• Modo Pausado - o consumidor chama read(n) para puxar chunks.
• highWaterMark - limite do buffer interno; exceder dispara backpressure (false de write).
• cork/uncork no Writable agrupa pequenas escritas em menos chamadas de sistema.

Matriz de Modos

Notas TypeScript

import { Readable } from 'node:stream';
 
function linesFromFile(path: string): Readable {
  return Readable.from(
    (async function* () {
      const { createReadStream } = await import('node:fs');
      const { createInterface } = await import('node:readline');
      const rl = createInterface({ input: createReadStream(path) });
      for await (const line of rl) yield line;
    })(),
  );
}

Armadilhas

• Misturar streams de objeto e byte em um pipe - confusão de tipo. Correção: Transform explícito para converter.
• Fazer push após null - lança erro. Correção: rastrear estado de finalização em Readable customizado.
• Ignorar o retorno false de write - estouro de memória. Correção: aguardar o evento drain.
• highWaterMark minúsculo em I/O de alta latência - sobrecarga de chamada de sistema. Correção: benchmark de 16-64 KB para arquivos.
• Modo objeto com objetos enormes - cada objeto pode ter MB. Correção: permanecer no modo byte ou transmitir referências.

Alternativas

FAQs

Relacionados

• Fundamentos de Streams - quatro tipos de stream
• Backpressure - detalhes de pause/drain
• Transform & Duplex - streams intermediários
• fs e fs/promises - createReadStream

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.