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.
const stream = new ReadableStream({ start(controller) { controller.enqueue('hello'); controller.close(); }, });
Try 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.
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
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.
desiredSizetells a source how many more chunks the queue wants. Apull()-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 awaitcancels on early exit. Breaking out of afor awaitloop cancels the stream and calls yourcancel(). Pass{ preventCancel: true }tovalues()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()andReadable.toWeb()to cross to Node.js streams, andReadableStream.from()to wrap an async iterable. - Byte streams.
type: 'bytes'enables zero-copy reads into your own buffer throughgetReader({ mode: 'byob' }). - Stability. Web streams in Node.js have been stable since v21; the global classes exist since v18.