Node.js v26.9.0 documentation

Web Streams API#

An implementation of the WHATWG Streams Standard.

Overview#

The WHATWG Streams Standard (or "web streams") defines an API for handling streaming data. It is similar to the Node.js Streams API but emerged later and has become the "standard" API for streaming data across many JavaScript environments.

There are three primary types of objects:

• ReadableStream - Represents a source of streaming data.
• WritableStream - Represents a destination for streaming data.
• TransformStream - Represents an algorithm for transforming streaming data.

Example ReadableStream#

This example creates a simple ReadableStream that pushes the current performance.now() timestamp once every second forever. An async iterable is used to read the data from the stream.

import {
  ReadableStream,
} from 'node:stream/web';

import {
  setInterval as every,
} from 'node:timers/promises';

import {
  performance,
} from 'node:perf_hooks';

const SECOND = 1000;

const stream = new ReadableStream({
  async start(controller) {
    for await (const _ of every(SECOND))
      controller.enqueue(performance.now());
  },
});

for await (const value of stream)
  console.log(value);
const {
  ReadableStream,
} = require('node:stream/web');

const {
  setInterval: every,
} = require('node:timers/promises');

const {
  performance,
} = require('node:perf_hooks');

const SECOND = 1000;

const stream = new ReadableStream({
  async start(controller) {
    for await (const _ of every(SECOND))
      controller.enqueue(performance.now());
  },
});

(async () => {
  for await (const value of stream)
    console.log(value);
})();
javascriptcopy

Node.js streams interoperability#

Node.js streams can be converted to web streams and vice versa via the toWeb and fromWeb methods present on stream.Readable, stream.Writable and stream.Duplex objects.

For more details refer to the relevant documentation:

• stream.Readable.toWeb
• stream.Readable.fromWeb
• stream.Writable.toWeb
• stream.Writable.fromWeb
• stream.Duplex.toWeb
• stream.Duplex.fromWeb

API#

ReadableStreamTee(stream[, cloneForBranch2])#

• stream <ReadableStream>
• cloneForBranch2 <boolean> When true, chunks enqueued into the second branch are cloned from chunks enqueued into the first branch. Default: false.
• Returns: <ReadableStream>[] Two <ReadableStream> branches.

Runs the WHATWG ReadableStreamTee abstract operation on stream.

This differs from readableStream.tee() only when cloneForBranch2 is true. The tee() method always passes false, while other web platform specifications, such as Fetch body cloning, pass true so that the second branch receives cloned chunks and consumption of one branch cannot mutate chunks seen by the other.

Class: ReadableStream#

new ReadableStream([underlyingSource [, strategy]])#

• underlyingSource <Object>
  • start <Function> A user-defined function that is invoked immediately when the ReadableStream is created.
    • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
    • Returns: undefined or a promise fulfilled with undefined.
  • pull <Function> A user-defined function that is called repeatedly when the ReadableStream internal queue is not full. The operation may be sync or async. If async, the function will not be called again until the previously returned promise is fulfilled.
    • controller <ReadableStreamDefaultController> | <ReadableByteStreamController>
    • Returns: A promise fulfilled with undefined.
  • cancel <Function> A user-defined function that is called when the ReadableStream is canceled.
    • reason <any>
    • Returns: A promise fulfilled with undefined.
  • type <string> Must be 'bytes' or undefined.
  • autoAllocateChunkSize <number> Used only when type is equal to 'bytes'. When set to a non-zero value a view buffer is automatically allocated to ReadableByteStreamController.byobRequest. When not set one must use stream's internal queues to transfer data via the default reader ReadableStreamDefaultReader.
• strategy <Object>
  • highWaterMark <number> The maximum internal queue size before backpressure is applied.
  • size <Function> A user-defined function used to identify the size of each chunk of data.
    • chunk <any>
    • Returns: <number>

readableStream.locked#

• Type: <boolean> Set to true if there is an active reader for this <ReadableStream>.

The readableStream.locked property is false by default, and is switched to true while there is an active reader consuming the stream's data.

readableStream.cancel([reason])#

• reason <any>
• Returns: A promise fulfilled with undefined once cancelation has been completed.

readableStream.getReader([options])#

• options <Object>
  • mode <string> 'byob' or undefined
• Returns: <ReadableStreamDefaultReader> | <ReadableStreamBYOBReader>

import { ReadableStream } from 'node:stream/web';

const stream = new ReadableStream();

const reader = stream.getReader();

console.log(await reader.read());
const { ReadableStream } = require('node:stream/web');

const stream = new ReadableStream();

const reader = stream.getReader();

reader.read().then(console.log);
javascriptcopy

Causes the readableStream.locked to be true.

readableStream.pipeThrough(transform[, options])#

• transform <Object>
  • readable <ReadableStream> The ReadableStream to which transform.writable will push the potentially modified data it receives from this ReadableStream.
  • writable <WritableStream> The WritableStream to which this ReadableStream's data will be written.
• options <Object>
  • preventAbort <boolean> When true, errors in this ReadableStream will not cause transform.writable to be aborted.
  • preventCancel <boolean> When true, errors in the destination transform.writable do not cause this ReadableStream to be canceled.
  • preventClose <boolean> When true, closing this ReadableStream does not cause transform.writable to be closed.
  • signal <AbortSignal> Allows the transfer of data to be canceled using an <AbortController>.
• Returns: <ReadableStream> From transform.readable.

Connects this <ReadableStream> to the pair of