Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท Streams and readline

Node.js ReadableStream (web streams)

Reference for the global ReadableStream in Node.js: create sources, read with readers and async iteration, tee, pipe and cancel, with backpressure rules.

ReadableStream is the standard web API for a source of data that is consumed in chunks. It is a global in Node.js (also exported from node:stream/web), and it is what fetch() uses for response.body. Unlike a Node.js Readable, it was designed to be identical in browsers, workers and servers, and it works with any JavaScript value, not just bytes.

You create one by passing an underlying source object with start, pull and cancel callbacks. Consumers read it with a reader (getReader()), with for await, or by piping it into a WritableStream or TransformStream. A stream can be locked to only one reader at a time.

NODE
const stream = new ReadableStream({
  start(controller) {
    controller.enqueue('hello');
    controller.close();
  },
});

Try it

Node.js Creating a stream and reading it

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 Pull-based source, iteration and tee

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
new ReadableStream(underlyingSource?, strategy?)
ReadableStream.from(asyncIterableOrIterable)
stream.getReader(options?)     // ReadableStreamDefaultReader | BYOB reader
stream.pipeTo(writable, options?)
stream.pipeThrough({ writable, readable }, options?)
stream.tee()
stream.cancel(reason?)
stream.values(options?)        // async iterator, also [Symbol.asyncIterator]
stream.locked
Name Description
underlyingSource.start(controller) Runs once immediately. May return a promise.
underlyingSource.pull(controller) Called whenever the internal queue wants more chunks.
underlyingSource.cancel(reason) Called if a consumer cancels the stream.
underlyingSource.type Set to 'bytes' for a byte stream that supports BYOB readers.
strategy { highWaterMark, size }, or an instance of CountQueuingStrategy or ByteLengthQueuingStrategy. Default is a high-water mark of 1 chunk.
controller enqueue(chunk), close(), error(e) and desiredSize.

Returns: getReader() returns a reader with read(), cancel() and releaseLock(). tee() returns an array of two new streams. pipeTo() returns a promise.

Errors: getReader(), tee() and pipeTo() throw ERR_INVALID_STATE (a TypeError) if the stream is already locked. Calling controller.error(e) rejects pending reads with e.

Usage notes

  • Backpressure is built in. desiredSize tells a source how many more chunks the queue wants. A pull()-based source is called only when the queue is below its high-water mark.
  • One reader at a time. While a reader holds the lock the stream cannot be piped or iterated. Call reader.releaseLock() to hand it on.
  • for await cancels on early exit. Breaking out of a for await loop cancels the stream and calls your cancel(). Pass { preventCancel: true } to values() to avoid it.
  • tee() buffers. The two branches share a queue, so a slow branch makes the faster one buffer without limit.
  • Converting. Use Readable.fromWeb() and Readable.toWeb() to cross to Node.js streams, and ReadableStream.from() to wrap an async iterable.
  • Byte streams. type: 'bytes' enables zero-copy reads into your own buffer through getReader({ mode: 'byob' }).
  • Stability. Web streams in Node.js have been stable since v21; the global classes exist since v18.