Web Streams API

Added in: v16.5.0

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.

MJScopy

CJScopy

API

C ReadableStream

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

Added in: v16.5.0

• 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'.
• 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

M readableStream.locked

Added in: v16.5.0

• 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.

M readableStream.cancel([reason])

Added in: v16.5.0

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

M readableStream.getReader([options])

Added in: v16.5.0

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

MJScopy

CJScopy

Causes the readableStream.locked to be true.

M readableStream.pipeThrough(transform[, options])

Added in: v16.5.0

• transform Object
  • readable ReadableStream The ReadableStream to which transform.writable will push the potentially modified data is 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 ReadableStream and WritableStream provided in the transform argument such that the data from this ReadableStream is written in to transform.writable, possibly transformed, then pushed to transform.readable. Once the pipeline is configured, transform.readable is returned.

Causes the readableStream.locked to be true while the pipe operation is active.

MJScopy

CJScopy

M readableStream.pipeTo(destination, options)

Added in: v16.5.0

• destination WritableStream A WritableStream to which this ReadableStream's data will be written.
• options Object
  • preventAbort boolean When true, errors in this ReadableStream will not cause destination to be aborted.
  • preventCancel boolean When true, errors in the destination will not cause this ReadableStream to be canceled.
  • preventClose boolean When true, closing this ReadableStream does not cause destination to be closed.
  • signal AbortSignal Allows the transfer of data to be canceled using an AbortController.
• Returns: A promise fulfilled with undefined

Causes the readableStream.locked to be true while the pipe operation is active.

M readableStream.tee()

• Returns: ReadableStream[]

Returns a pair of new ReadableStream instances to which this ReadableStream's data will be forwarded. Each will receive the same data.

Causes the readableStream.locked to be true.

M readableStream.values([options])

Added in: v16.5.0

• options Object
  • preventCancel boolean When true, prevents the ReadableStream from being closed when the async iterator abruptly terminates. Default: false.

Creates and returns an async iterator usable for consuming this ReadableStream's data.

Causes the readableStream.locked to be true while the async iterator is active.

MJScopy

Async Iteration

The ReadableStream object supports the async iterator protocol using for await syntax.

MJScopy

The async iterator will consume the ReadableStream until it terminates.

By default, if the async iterator exits early (via either a break, return, or a throw), the ReadableStream will be closed. To prevent automatic closing of the ReadableStream, use the readableStream.values() method to acquire the async iterator and set the preventCancel option to true.

The ReadableStream must not be locked (that is, it must not have an existing active reader). During the async iteration, the ReadableStream will be locked.

Transferring with postMessage()

A ReadableStream instance can be transferred using a MessagePort.

JScopy

C ReadableStreamDefaultReader

By default, calling readableStream.getReader() with no arguments will return an instance of ReadableStreamDefaultReader. The default reader treats the chunks of data passed through the stream as opaque values, which allows the ReadableStream to work with generally any JavaScript value.

M new ReadableStreamDefaultReader(stream)

Added in: v16.5.0

• stream ReadableStream

Creates a new ReadableStreamDefaultReader that is locked to the given ReadableStream.

M readableStreamDefaultReader.cancel([reason])

Added in: v16.5.0

• reason any
• Returns: A promise fulfilled with undefined.

Cancels the ReadableStream and returns a promise that is fulfilled when the underlying stream has been canceled.

M readableStreamDefaultReader.closed

Added in: v16.5.0

• Type: Promise Fulfilled with undefined when the associated ReadableStream is closed or rejected if the stream errors or the reader's lock is released before the stream finishes closing.

M readableStreamDefaultReader.read()

Added in: v16.5.0

• Returns: A promise fulfilled with an object:
  • value ArrayBuffer
  • done boolean

Requests the next chunk of data from the underlying ReadableStream and returns a promise that is fulfilled with the data once it is available.

M readableStreamDefaultReader.releaseLock()

Added in: v16.5.0

Releases this reader's lock on the underlying ReadableStream.

C ReadableStreamBYOBReader

The ReadableStreamBYOBReader is an alternative consumer for byte-oriented ReadableStreams (those that are created with underlyingSource.type set equal to 'bytes' when the ReadableStream was created).

The BYOB is short for "bring your own buffer". This is a pattern that allows for more efficient reading of byte-oriented data that avoids extraneous copying.

MJScopy

M new ReadableStreamBYOBReader(stream)

Added in: v16.5.0

• stream ReadableStream

Creates a new ReadableStreamBYOBReader that is locked to the given ReadableStream.

M readableStreamBYOBReader.cancel([reason])

Added in: v16.5.0

• reason any
• Returns: A promise fulfilled with undefined.

Cancels the ReadableStream and returns a promise that is fulfilled when the underlying stream has been canceled.

M readableStreamBYOBReader.closed

Added in: v16.5.0

• Type: Promise Fulfilled with undefined when the associated ReadableStream is closed or rejected if the stream errors or the reader's lock is released before the stream finishes closing.

M readableStreamBYOBReader.read(view)

Added in: v16.5.0

• view Buffer | TypedArray | DataView
• Returns: A promise fulfilled with an object:
  • value ArrayBuffer
  • done boolean

Requests the next chunk of data from the underlying ReadableStream and returns a promise that is fulfilled with the data once it is available.

Do not pass a pooled Buffer object instance in to this method. Pooled Buffer objects are created using Buffer.allocUnsafe(), or Buffer.from(), or are often returned by various node:fs module callbacks. These types of Buffers use a shared underlying ArrayBuffer object that contains all of the data from all of the pooled Buffer instances. When a Buffer, TypedArray, or DataView is passed in to readableStreamBYOBReader.read(), the view's underlying ArrayBuffer is detached, invalidating all existing views that may exist on that ArrayBuffer. This can have disastrous consequences for your application.

M readableStreamBYOBReader.releaseLock()

Added in: v16.5.0

Releases this reader's lock on the underlying ReadableStream.

C ReadableStreamDefaultController

Added in: v16.5.0

Every ReadableStream has a controller that is responsible for the internal state and management of the stream's queue. The ReadableStreamDefaultController is the default controller implementation for ReadableStreams that are not byte-oriented.

M readableStreamDefaultController.close()

Added in: v16.5.0

Closes the ReadableStream to which this controller is associated.

M readableStreamDefaultController.desiredSize

Added in: v16.5.0

• Type: number

Returns the amount of data remaining to fill the ReadableStream's queue.

M readableStreamDefaultController.enqueue(chunk)

Added in: v16.5.0

• chunk any

Appends a new chunk of data to the ReadableStream's queue.

M readableStreamDefaultController.error(error)

Added in: v16.5.0

• error any

Signals an error that causes the ReadableStream to error and close.

C ReadableByteStreamController

Every ReadableStream has a controller that is responsible for the internal state and management of the stream's queue. The ReadableByteStreamController is for byte-oriented ReadableStreams.

M readableByteStreamController.byobRequest

Added in: v16.5.0

• Type: ReadableStreamBYOBRequest

M readableByteStreamController.close()

Added in: v16.5.0

Closes the ReadableStream to which this controller is associated.

M readableByteStreamController.desiredSize

Added in: v16.5.0

• Type: number

Returns the amount of data remaining to fill the ReadableStream's queue.

M readableByteStreamController.enqueue(chunk)

Added in: v16.5.0

• chunk: Buffer | TypedArray | DataView

Appends a new chunk of data to the ReadableStream's queue.

M readableByteStreamController.error(error)

Added in: v16.5.0

• error any

Signals an error that causes the ReadableStream to error and close.

C ReadableStreamBYOBRequest

When using ReadableByteStreamController in byte-oriented streams, and when using the ReadableStreamBYOBReader, the readableByteStreamController.byobRequest property provides access to a ReadableStreamBYOBRequest instance that represents the current read request. The object is used to gain access to the ArrayBuffer/TypedArray that has been provided for the read request to fill, and provides methods for signaling that the data has been provided.

M readableStreamBYOBRequest.respond(bytesWritten)

Added in: v16.5.0

• bytesWritten number

Signals that a bytesWritten number of bytes have been written to readableStreamBYOBRequest.view.

M readableStreamBYOBRequest.respondWithNewView(view)

Added in: v16.5.0

• view Buffer | TypedArray | DataView

Signals that the request has been fulfilled with bytes written to a new Buffer, TypedArray, or DataView.

M readableStreamBYOBRequest.view

Added in: v16.5.0

• Type: Buffer | TypedArray | DataView

C WritableStream

The WritableStream is a destination to which stream data is sent.

MJScopy

M new WritableStream([underlyingSink[, strategy]])

Added in: v16.5.0

• underlyingSink Object
  • start Function A user-defined function that is invoked immediately when the WritableStream is created.
    • controller WritableStreamDefaultController
    • Returns: undefined or a promise fulfilled with undefined.
  • write Function A user-defined function that is invoked when a chunk of data has been written to the WritableStream.
    • chunk any
    • controller WritableStreamDefaultController
    • Returns: A promise fulfilled with undefined.
  • close Function A user-defined function that is called when the WritableStream is closed.
    • Returns: A promise fulfilled with undefined.
  • abort Function A user-defined function that is called to abruptly close the WritableStream.
    • reason any
    • Returns: A promise fulfilled with undefined.
  • type any The type option is reserved for future use and must be undefined.
• 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

M writableStream.abort([reason])

Added in: v16.5.0

• reason any
• Returns: A promise fulfilled with undefined.

Abruptly terminates the WritableStream. All queued writes will be canceled with their associated promises rejected.

M writableStream.close()

Added in: v16.5.0

• Returns: A promise fulfilled with undefined.

Closes the WritableStream when no additional writes are expected.

M writableStream.getWriter()

Added in: v16.5.0

• Returns: WritableStreamDefaultWriter

Creates and creates a new writer instance that can be used to write data into the WritableStream.

M writableStream.locked

Added in: v16.5.0

• Type: boolean

The writableStream.locked property is false by default, and is switched to true while there is an active writer attached to this WritableStream.

Transferring with postMessage()

A WritableStream instance can be transferred using a MessagePort.

JScopy

C WritableStreamDefaultWriter

M new WritableStreamDefaultWriter(stream)

Added in: v16.5.0

• stream WritableStream

Creates a new WritableStreamDefaultWriter that is locked to the given WritableStream.

M writableStreamDefaultWriter.abort([reason])

Added in: v16.5.0

• reason any
• Returns: A promise fulfilled with undefined.

Abruptly terminates the WritableStream. All queued writes will be canceled with their associated promises rejected.

M writableStreamDefaultWriter.close()

Added in: v16.5.0

• Returns: A promise fulfilled with undefined.

Closes the WritableStream when no additional writes are expected.

M writableStreamDefaultWriter.closed

Added in: v16.5.0

• Type: Promise Fulfilled with undefined when the associated WritableStream is closed or rejected if the stream errors or the writer's lock is released before the stream finishes closing.

M writableStreamDefaultWriter.desiredSize

Added in: v16.5.0

• Type: number

The amount of data required to fill the WritableStream's queue.

M writableStreamDefaultWriter.ready

Added in: v16.5.0

• type: A promise that is fulfilled with undefined when the writer is ready to be used.

M writableStreamDefaultWriter.releaseLock()

Added in: v16.5.0

Releases this writer's lock on the underlying ReadableStream.

M writableStreamDefaultWriter.write([chunk])

Added in: v16.5.0

• chunk: any
• Returns: A promise fulfilled with undefined.

Appends a new chunk of data to the WritableStream's queue.

C WritableStreamDefaultController

The WritableStreamDefaultController manage's the WritableStream's internal state.

M writableStreamDefaultController.error(error)

Added in: v16.5.0

• error any

Called by user-code to signal that an error has occurred while processing the WritableStream data. When called, the WritableStream will be aborted, with currently pending writes canceled.

M writableStreamDefaultController.signal

• Type: AbortSignal An AbortSignal that can be used to cancel pending write or close operations when a WritableStream is aborted.

C TransformStream

A TransformStream consists of a ReadableStream and a WritableStream that are connected such that the data written to the WritableStream is received, and potentially transformed, before being pushed into the ReadableStream's queue.

MJScopy

M new TransformStream([transformer[, writableStrategy[, readableStrategy]]])

Added in: v16.5.0

• transformer Object
  • start Function A user-defined function that is invoked immediately when the TransformStream is created.
    • controller TransformStreamDefaultController
    • Returns: undefined or a promise fulfilled with undefined
  • transform Function A user-defined function that receives, and potentially modifies, a chunk of data written to transformStream.writable, before forwarding that on to transformStream.readable.
    • chunk any
    • controller TransformStreamDefaultController
    • Returns: A promise fulfilled with undefined.
  • flush Function A user-defined function that is called immediately before the writable side of the TransformStream is closed, signaling the end of the transformation process.
    • controller TransformStreamDefaultController
    • Returns: A promise fulfilled with undefined.
  • readableType any the readableType option is reserved for future use and must be undefined.
  • writableType any the writableType option is reserved for future use and must be undefined.
• writableStrategy 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
• readableStrategy 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

M transformStream.readable

Added in: v16.5.0

• Type: ReadableStream

M transformStream.writable

Added in: v16.5.0

• Type: WritableStream

Transferring with postMessage()

A TransformStream instance can be transferred using a MessagePort.

JScopy

C TransformStreamDefaultController

The TransformStreamDefaultController manages the internal state of the TransformStream.

M transformStreamDefaultController.desiredSize

Added in: v16.5.0

• Type: number

The amount of data required to fill the readable side's queue.

M transformStreamDefaultController.enqueue([chunk])

Added in: v16.5.0

• chunk any

Appends a chunk of data to the readable side's queue.

M transformStreamDefaultController.error([reason])

Added in: v16.5.0

• reason any

Signals to both the readable and writable side that an error has occurred while processing the transform data, causing both sides to be abruptly closed.

M transformStreamDefaultController.terminate()

Added in: v16.5.0

Closes the readable side of the transport and causes the writable side to be abruptly closed with an error.

C ByteLengthQueuingStrategy

M new ByteLengthQueuingStrategy(options)

Added in: v16.5.0

• options Object
  • highWaterMark number

M byteLengthQueuingStrategy.highWaterMark

Added in: v16.5.0

• Type: number

M byteLengthQueuingStrategy.size

Added in: v16.5.0

• Type: Function
  • chunk any
  • Returns: number

C CountQueuingStrategy

M new CountQueuingStrategy(options)

Added in: v16.5.0

• options Object
  • highWaterMark number

M countQueuingStrategy.highWaterMark

Added in: v16.5.0

• Type: number

M countQueuingStrategy.size

Added in: v16.5.0

• Type: Function
  • chunk any
  • Returns: number

C TextEncoderStream

M new TextEncoderStream()

Added in: v16.6.0

Creates a new TextEncoderStream instance.

M textEncoderStream.encoding

Added in: v16.6.0

• Type: string

The encoding supported by the TextEncoderStream instance.

M textEncoderStream.readable

Added in: v16.6.0

• Type: ReadableStream

M textEncoderStream.writable

Added in: v16.6.0

• Type: WritableStream

C TextDecoderStream

M new TextDecoderStream([encoding[, options]])

Added in: v16.6.0

• encoding string Identifies the encoding that this TextDecoder instance supports. Default: 'utf-8'.
• options Object
  • fatal boolean true if decoding failures are fatal.
  • ignoreBOM boolean When true, the TextDecoderStream will include the byte order mark in the decoded result. When false, the byte order mark will be removed from the output. This option is only used when encoding is 'utf-8', 'utf-16be', or 'utf-16le'. Default: false.

Creates a new TextDecoderStream instance.

M textDecoderStream.encoding

Added in: v16.6.0

• Type: string

The encoding supported by the TextDecoderStream instance.

M textDecoderStream.fatal

Added in: v16.6.0

• Type: boolean

The value will be true if decoding errors result in a TypeError being thrown.

M textDecoderStream.ignoreBOM

Added in: v16.6.0

• Type: boolean

The value will be true if the decoding result will include the byte order mark.

M textDecoderStream.readable

Added in: v16.6.0

• Type: ReadableStream

M textDecoderStream.writable

Added in: v16.6.0

• Type: WritableStream

C CompressionStream

M new CompressionStream(format)

Added in: v17.0.0

• format string One of either 'deflate' or 'gzip'.

M compressionStream.readable

Added in: v17.0.0

• Type: ReadableStream

M compressionStream.writable

Added in: v17.0.0

• Type: WritableStream

C DecompressionStream

M new DecompressionStream(format)

Added in: v17.0.0

• format string One of either 'deflate' or 'gzip'.

M decompressionStream.readable

Added in: v17.0.0

• Type: ReadableStream

M decompressionStream.writable

Added in: v17.0.0

• Type: WritableStream

Utility Consumers

Added in: v16.7.0

The utility consumer functions provide common options for consuming streams.

They are accessed using:

MJScopy

CJScopy

M streamConsumers.arrayBuffer(stream)

Added in: v16.7.0

• stream ReadableStream | stream.Readable | AsyncIterator
• Returns: Promise Fulfills with an ArrayBuffer containing the full contents of the stream.

MJScopy

CJScopy

M streamConsumers.blob(stream)

Added in: v16.7.0

• stream ReadableStream | stream.Readable | AsyncIterator
• Returns: Promise Fulfills with a Blob containing the full contents of the stream.

MJScopy

CJScopy

M streamConsumers.buffer(stream)

Added in: v16.7.0

• stream ReadableStream | stream.Readable | AsyncIterator
• Returns: Promise Fulfills with a Buffer containing the full contents of the stream.

MJScopy

CJScopy

M streamConsumers.json(stream)

Added in: v16.7.0

• stream ReadableStream | stream.Readable | AsyncIterator
• Returns: Promise Fulfills with the contents of the stream parsed as a UTF-8 encoded string that is then passed through JSON.parse().

MJScopy

CJScopy

M streamConsumers.text(stream)

Added in: v16.7.0

• stream ReadableStream | stream.Readable | AsyncIterator
• Returns: Promise Fulfills with the contents of the stream parsed as a UTF-8 encoded string.

MJScopy

CJScopy