O que são streams no Node.js e quando você deve usá-los?

Question

Accepted Answer

**Streams** processam dados **incrementalmente, em pedaços**, em vez de carregar tudo na memória de uma só vez. Isso os torna essenciais para dados grandes (arquivos grandes, transferências de rede) onde armazenar tudo em buffer esgotaria a memória.

## O problema que streams resolvem

```js
// ❌ loads the ENTIRE file into memory — crashes on a 10GB file
const data = await fs.promises.readFile("huge.csv");
process(data);

// ✅ stream it — constant memory, processes chunk by chunk
fs.createReadStream("huge.csv")
  .pipe(transform)
  .pipe(fs.createWriteStream("out.csv"));
```

Com streams, o uso de memória permanece estável independentemente do tamanho do arquivo — você lida com um pedaço por vez.

## Os quatro tipos de stream

```text
Readable  → source you read FROM (fs.createReadStream, http request)
Writable  → destination you write TO (fs.createWriteStream, http response)
Duplex    → both readable & writable (TCP socket)
Transform → modify data as it passes through (zlib gzip, encryption)
```

## pipe — conectar streams

```js
import { createReadStream, createWriteStream } from "fs";
import { createGzip } from "zlib";

// read → compress → write, all streaming, low memory
createReadStream("file.txt")
  .pipe(createGzip())            // Transform: compress on the fly
  .pipe(createWriteStream("file.txt.gz"));
```

`pipe` conecta um readable a um writable (com transforms no meio), gerenciando automaticamente o fluxo — a forma idiomática de compor streams.

## pipeline — pipe com tratamento adequado de erros

```js
import { pipeline } from "stream/promises";

await pipeline(
  createReadStream("in.txt"),
  createGzip(),
  createWriteStream("out.gz")
); // ✅ cleans up all streams on error/completion (pipe alone leaks on errors)
```

`pipeline` é preferido em vez de `.pipe()` encadeado porque propaga erros e limpa cada stream adequadamente.

## Onde streams aparecem

```text
✓ HTTP request/response bodies (req and res ARE streams)
✓ File reading/writing, file uploads/downloads
✓ Compression (zlib), encryption (crypto)
✓ Database cursors, large query results
✓ Real-time data processing, video streaming
```

## Quando NÃO usar

```text
Small data that fits comfortably in memory → readFile/simple buffering is simpler.
Streams add complexity; use them for LARGE or continuous data.
```

## Por que isso importa

Streams são um recurso definidor do Node.js para tratamento **eficiente em memória** de dados grandes ou contínuos — a diferença entre um aplicativo que falha em um grande upload e um que lida com qualquer tamanho com memória estável.

Entender os quatro tipos, composição `pipe`/`pipeline` (e por que `pipeline` é mais seguro) e que requisições/respostas HTTP são elas mesmas streams é essencial para construir serviços escaláveis de manipulação de arquivos, processamento de dados e proxy no Node.