.pipe() vs pipeline — and Backpressure

".pipe() looks beautiful in three lines. pipeline() actually handles errors. The visual elegance of the first costs you in production every time."

What .pipe() Looks Like

The classic Node stream syntax:

import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';

createReadStream('input.txt')
  .pipe(createGzip())
  .pipe(createWriteStream('output.txt.gz'));

Readable types from fs have a .pipe() method. It plumbs the source into a destination, with automatic flow control (backpressure handled), automatic end propagation, and a return value of the destination (so you can chain).

This is the canonical example in every Node tutorial. It also has a fatal flaw.

The Flaw — Errors Don't Propagate

const src = createReadStream('input.txt');
const gz = createGzip();
const dst = createWriteStream('output.txt.gz');

src.on('error', cleanup);
gz.on('error', cleanup);
dst.on('error', cleanup);

src.pipe(gz).pipe(dst);

function cleanup(err) {
  // destroy all three, log the error
  src.destroy(); gz.destroy(); dst.destroy();
  console.error(err);
}

pipeline() — The Right Answer Since Node 10

stream.pipeline (and its modern promise form stream/promises.pipeline) does what .pipe() chains can't: centralized error handling, automatic destruction of all participating streams on error, promise resolution when the whole thing completes.

import { createReadStream, createWriteStream } from 'node:fs';
import { createGzip } from 'node:zlib';
import { pipeline } from 'node:stream/promises';

await pipeline(
  createReadStream('input.txt'),
  createGzip(),
  createWriteStream('output.txt.gz')
);
// If any stage errors, all three are destroyed and the await throws.

One line per stage, one await, one source of truth for completion and failure. Always use pipeline in modern code. .pipe() exists for backward compatibility; treat it as legacy.

Backpressure — What pipeline Handles For You

Backpressure is the mechanism by which a slow consumer tells a fast producer "slow down, I can't keep up." Without it, the fast producer fills the slow consumer's internal buffer to infinity → out of memory → crash. With it, the producer pauses until the consumer drains, then resumes.

In Node streams: when a Writable's .write() returns false, it means "buffer full, wait for drain." When piping manually, you must respect this:

// Manual backpressure-aware copy — error-prone, don't ship this
async function copy(src, dst) {
  for await (const chunk of src) {
    if (!dst.write(chunk)) await new Promise(r => dst.once('drain', r));
  }
  dst.end();
}

pipeline does all of this for you. .pipe() does most of it. Manual loops without checking the return value of .write() are how Node servers OOM on large uploads.

When You DO Need Manual Control

Use pipeline 99% of the time. Reach for manual writes + drain handling when:

• You need to inject data into a Writable from multiple sources non-linearly.
• You're implementing a custom stream that needs precise control over output timing.
• You're optimizing a hot path where the overhead of an extra Transform is measurable (rare — measure first).

Pippa's Confession