Web Streams API

自 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]])

自 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

自 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])

自 v16.5.0 版本开始新增

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

M readableStream.getReader([options])

自 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])

自 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)

自 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])

自 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)

自 v16.5.0 版本开始新增

• stream ReadableStream

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

M readableStreamDefaultReader.cancel([reason])

自 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

自 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()

自 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()

自 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)

自 v16.5.0 版本开始新增

• stream ReadableStream

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

M readableStreamBYOBReader.cancel([reason])

自 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

自 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)

自 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()

自 v16.5.0 版本开始新增

Releases this reader's lock on the underlying ReadableStream.

C ReadableStreamDefaultController

自 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()

自 v16.5.0 版本开始新增

Closes the ReadableStream to which this controller is associated.

M readableStreamDefaultController.desiredSize

自 v16.5.0 版本开始新增

• Type: number

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

M readableStreamDefaultController.enqueue(chunk)

自 v16.5.0 版本开始新增

• chunk any

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

M readableStreamDefaultController.error(error)

自 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

自 v16.5.0 版本开始新增

• Type: ReadableStreamBYOBRequest

M readableByteStreamController.close()

自 v16.5.0 版本开始新增

Closes the ReadableStream to which this controller is associated.

M readableByteStreamController.desiredSize

自 v16.5.0 版本开始新增

• Type: number

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

M readableByteStreamController.enqueue(chunk)

自 v16.5.0 版本开始新增

• chunk: Buffer | TypedArray | DataView

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

M readableByteStreamController.error(error)

自 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)

自 v16.5.0 版本开始新增

• bytesWritten number

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

M readableStreamBYOBRequest.respondWithNewView(view)

自 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

自 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]])

自 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])

自 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()

自 v16.5.0 版本开始新增

• Returns: A promise fulfilled with undefined.

Closes the WritableStream when no additional writes are expected.

M writableStream.getWriter()

自 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

自 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)

自 v16.5.0 版本开始新增

• stream WritableStream

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

M writableStreamDefaultWriter.abort([reason])

自 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()

自 v16.5.0 版本开始新增

• Returns: A promise fulfilled with undefined.

Closes the WritableStream when no additional writes are expected.

M writableStreamDefaultWriter.closed

自 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

自 v16.5.0 版本开始新增

• Type: number

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

M writableStreamDefaultWriter.ready

自 v16.5.0 版本开始新增

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

M writableStreamDefaultWriter.releaseLock()

自 v16.5.0 版本开始新增

Releases this writer's lock on the underlying ReadableStream.

M writableStreamDefaultWriter.write([chunk])

自 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)

自 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]]])

自 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

自 v16.5.0 版本开始新增

• Type: ReadableStream

M transformStream.writable

自 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

自 v16.5.0 版本开始新增

• Type: number

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

M transformStreamDefaultController.enqueue([chunk])

自 v16.5.0 版本开始新增

• chunk any

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

M transformStreamDefaultController.error([reason])

自 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()

自 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)

自 v16.5.0 版本开始新增

• options Object
  • highWaterMark number

M byteLengthQueuingStrategy.highWaterMark

自 v16.5.0 版本开始新增

• Type: number

M byteLengthQueuingStrategy.size

自 v16.5.0 版本开始新增

• Type: Function
  • chunk any
  • Returns: number

C CountQueuingStrategy

M new CountQueuingStrategy(options)

自 v16.5.0 版本开始新增

• options Object
  • highWaterMark number

M countQueuingStrategy.highWaterMark

自 v16.5.0 版本开始新增

• Type: number

M countQueuingStrategy.size

自 v16.5.0 版本开始新增

• Type: Function
  • chunk any
  • Returns: number

C TextEncoderStream

M new TextEncoderStream()

自 v16.6.0 版本开始新增

Creates a new TextEncoderStream instance.

M textEncoderStream.encoding

自 v16.6.0 版本开始新增

• Type: string

The encoding supported by the TextEncoderStream instance.

M textEncoderStream.readable

自 v16.6.0 版本开始新增

• Type: ReadableStream

M textEncoderStream.writable

自 v16.6.0 版本开始新增

• Type: WritableStream

C TextDecoderStream

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

自 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

自 v16.6.0 版本开始新增

• Type: string

The encoding supported by the TextDecoderStream instance.

M textDecoderStream.fatal

自 v16.6.0 版本开始新增

• Type: boolean

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

M textDecoderStream.ignoreBOM

自 v16.6.0 版本开始新增

• Type: boolean

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

M textDecoderStream.readable

自 v16.6.0 版本开始新增

• Type: ReadableStream

M textDecoderStream.writable

自 v16.6.0 版本开始新增

• Type: WritableStream

C CompressionStream

M new CompressionStream(format)

自 v17.0.0 版本开始新增

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

M compressionStream.readable

自 v17.0.0 版本开始新增

• Type: ReadableStream

M compressionStream.writable

自 v17.0.0 版本开始新增

• Type: WritableStream

C DecompressionStream

M new DecompressionStream(format)

自 v17.0.0 版本开始新增

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

M decompressionStream.readable

自 v17.0.0 版本开始新增

• Type: ReadableStream

M decompressionStream.writable

自 v17.0.0 版本开始新增

• Type: WritableStream

Utility Consumers

自 v16.7.0 版本开始新增

The utility consumer functions provide common options for consuming streams.

They are accessed using:

MJScopy

CJScopy

M streamConsumers.arrayBuffer(stream)

自 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)

自 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)

自 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)

自 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)

自 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