Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js readable.pipe() method

Reference for readable.pipe() in Node.js: connect a readable to a writable with automatic backpressure, chain transforms, and know what pipe does not do.

readable.pipe(destination[, options]) connects a readable stream to a writable one. Every chunk the readable produces is written to the destination, and when the destination's buffer fills up, the readable is paused until the destination emits 'drain'. That is backpressure handled for you.

pipe() returns the destination, so calls can be chained through duplex and transform streams. It is the oldest way to connect streams. For new code that must handle errors and cleanup, prefer stream.pipeline().

NODE
source.pipe(transform).pipe(destination);

Try it

Node.js Pipe through a transform

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Errors are not forwarded

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
readable.pipe(destination)
readable.pipe(destination, { end: false })
Name Description
destination Any writable stream (stream.Writable, Duplex, Transform, process.stdout, an HTTP response, a socket).
options.end Boolean, default true. When true, destination.end() is called when the readable emits 'end'. Set it to false to keep the destination open, for example when several sources write to process.stdout one after another.

Returns: the destination, so you can chain a.pipe(b).pipe(c). Chaining only makes sense when the destination is readable too (a Duplex or Transform).

Edge cases: if the readable emits an error, the destination is not closed and stays open waiting for more data. If the destination emits an error, the readable unpipes from it but is not destroyed. Both situations can leak file descriptors.

Usage notes

  • pipe() switches the readable into flowing mode. A second pipe() to another destination works as fan-out: each destination gets every chunk, and the slowest one sets the pace.
  • Backpressure is automatic: when destination.write() returns false, the readable is paused until 'drain'.
  • Errors do not propagate along a chain. Each stream needs its own 'error' listener, and a failed stream has to be destroyed by hand. stream.pipeline() does all of that.
  • readable.unpipe([destination]) disconnects one destination (or all of them without an argument). The readable is not paused by unpipe(), so data can be lost if no one is listening.
  • The destination emits 'pipe' when a source is connected and 'unpipe' when it is disconnected.
  • process.stdout and process.stderr are never closed by pipe(), even with end: true.
  • For simple file copies, fs.copyFile() is faster than piping two file streams.