Readable & Writable Patterns

Readable and Writable streams share modes and flow control primitives - choose byte vs object mode up front and match producer chunk sizes to consumer throughput.

Recipe

import { Readable, Writable } from 'node:stream';
 
// Byte mode (default)
const byteStream = Readable.from([Buffer.from('ab'), Buffer.from('cd')]);
 
// Object mode
const objectStream = Readable.from([{ id: 1 }, { id: 2 }], { objectMode: true });

When to reach for this:

• Parsing CSV/NDJSON line objects from disk
• Writing aggregated metrics objects to a batch writer
• Tuning highWaterMark for memory vs latency
• Implementing custom Readable from async data source

Working Example

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) {
    // simulate DB batch insert
    setImmediate(cb);
  },
});
 
const source = new CounterSource(1000);
source.pipe(batchWriter);

// Paused mode - explicit read()
const r = Readable.from(['a', 'b', 'c']);
r.on('readable', () => {
  let chunk;
  while ((chunk = r.read()) !== null) {
    console.log(chunk);
  }
});

What this demonstrates:

• Custom Readable implements _read and pushes until null ends stream
• Object mode Writable receives typed objects - batch in _write or accumulate for bulk insert
• Paused mode uses readable event + read() - useful for parsing framing
• Flowing mode (data event or pipe) is default for most I/O

Deep Dive

How It Works

• Flowing mode - data auto-emitted via data events or pipe.
• Paused mode - consumer calls read(n) to pull chunks.
• highWaterMark - internal buffer threshold; exceeding triggers backpressure (false from write).
• cork/uncork on Writable batches small writes into fewer syscalls.

Mode Matrix

TypeScript Notes

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;
    })(),
  );
}

Gotchas

• Mixing object and byte streams in one pipe - type confusion. Fix: explicit Transform to convert.
• Pushing after null - throws. Fix: track ended state in custom Readable.
• Ignoring write return false - memory blowup. Fix: wait for drain event.
• Tiny highWaterMark on high-latency I/O - syscall overhead. Fix: benchmark 16-64 KB for files.
• Object mode with huge objects - each object may be MB. Fix: stay byte mode or stream references.

Alternatives

FAQs

Related

• Streams Basics - four stream types
• Backpressure - pause/drain details
• Transform & Duplex - middle streams
• fs and fs/promises - createReadStream

External Related Links

• Node.js API Documentation - Complete reference for core modules and APIs.
• Node.js Best Practices (GitHub) - Curated production best practices.
• Node.js GitHub Repository - Source code, issues, contribution guides.
• Node.js Design Patterns, 4th Edition - Production-grade application patterns.
• Node.js Design Patterns (author site) - Author site for Design Patterns.

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.

cGJxcnRodnFyZi52YnxwdHZiODM0fDIwMjYwNw==