home / documentation / v16 / webstreams

Web Streams API

目录

自 v16.5.0 版本开始新增

稳定级别：1 - Experimental

An implementation of the WHATWG Streams Standard.

MJS
CJS

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.

MJS
CJS

API

C ReadableStream

自 v16.5.0 版本开始新增

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.
    • 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.
    • 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.
M readableStream.locked

自 v16.5.0 版本开始新增

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 版本开始新增

MJS
CJS

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.

MJS
CJS
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()
历史
版本历史变更
v16.18.0Support teeing a readable byte stream.
v16.5.0自 v16.5.0 版本开始新增
  • 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.

MJS
Async Iteration

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

MJS

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.

JS

C ReadableStreamDefaultReader

自 v16.5.0 版本开始新增

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 版本开始新增

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 版本开始新增

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

自 v16.5.0 版本开始新增

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.

MJS
M new ReadableStreamBYOBReader(stream)

自 v16.5.0 版本开始新增

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 版本开始新增

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 版本开始新增

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

M readableStreamDefaultController.enqueue(chunk)

自 v16.5.0 版本开始新增

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

M readableStreamDefaultController.error(error)

自 v16.5.0 版本开始新增

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

C ReadableByteStreamController

自 v16.5.0 版本开始新增

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 版本开始新增

M readableByteStreamController.close()

自 v16.5.0 版本开始新增

Closes the ReadableStream to which this controller is associated.

M readableByteStreamController.desiredSize

自 v16.5.0 版本开始新增

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

M readableByteStreamController.enqueue(chunk)

自 v16.5.0 版本开始新增

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

M readableByteStreamController.error(error)

自 v16.5.0 版本开始新增

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

C ReadableStreamBYOBRequest

自 v16.5.0 版本开始新增

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 版本开始新增

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

M readableStreamBYOBRequest.respondWithNewView(view)

自 v16.5.0 版本开始新增

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

M readableStreamBYOBRequest.view

自 v16.5.0 版本开始新增

C WritableStream

自 v16.5.0 版本开始新增

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

MJS
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.
    • write Function A user-defined function that is invoked when a chunk of data has been written to the WritableStream.
    • 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.
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 版本开始新增

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

M writableStream.locked

自 v16.5.0 版本开始新增

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.

JS

C WritableStreamDefaultWriter

自 v16.5.0 版本开始新增

M new WritableStreamDefaultWriter(stream)

自 v16.5.0 版本开始新增

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 版本开始新增

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

自 v16.5.0 版本开始新增

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

M writableStreamDefaultController.abortReason
  • Type: any The reason value passed to writableStream.abort().
M writableStreamDefaultController.error(error)

自 v16.5.0 版本开始新增

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

自 v16.5.0 版本开始新增

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.

MJS
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.
    • 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.
    • 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.
    • 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.
  • 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.
M transformStream.readable

自 v16.5.0 版本开始新增

M transformStream.writable

自 v16.5.0 版本开始新增

Transferring with postMessage()

A TransformStream instance can be transferred using a MessagePort.

JS

C TransformStreamDefaultController

自 v16.5.0 版本开始新增

The TransformStreamDefaultController manages the internal state of the TransformStream.

M transformStreamDefaultController.desiredSize

自 v16.5.0 版本开始新增

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

M transformStreamDefaultController.enqueue([chunk])

自 v16.5.0 版本开始新增

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

M transformStreamDefaultController.error([reason])

自 v16.5.0 版本开始新增

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

自 v16.5.0 版本开始新增

M new ByteLengthQueuingStrategy(options)

自 v16.5.0 版本开始新增

M byteLengthQueuingStrategy.highWaterMark

自 v16.5.0 版本开始新增

M byteLengthQueuingStrategy.size

自 v16.5.0 版本开始新增

C CountQueuingStrategy

自 v16.5.0 版本开始新增

M new CountQueuingStrategy(options)

自 v16.5.0 版本开始新增

M countQueuingStrategy.highWaterMark

自 v16.5.0 版本开始新增

M countQueuingStrategy.size

自 v16.5.0 版本开始新增

C TextEncoderStream

自 v16.6.0 版本开始新增

M new TextEncoderStream()

自 v16.6.0 版本开始新增

Creates a new TextEncoderStream instance.

M textEncoderStream.encoding

自 v16.6.0 版本开始新增

The encoding supported by the TextEncoderStream instance.

M textEncoderStream.readable

自 v16.6.0 版本开始新增

M textEncoderStream.writable

自 v16.6.0 版本开始新增

C TextDecoderStream

自 v16.6.0 版本开始新增

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 版本开始新增

The encoding supported by the TextDecoderStream instance.

M textDecoderStream.fatal

自 v16.6.0 版本开始新增

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

M textDecoderStream.ignoreBOM

自 v16.6.0 版本开始新增

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

M textDecoderStream.readable

自 v16.6.0 版本开始新增

M textDecoderStream.writable

自 v16.6.0 版本开始新增

Utility Consumers

自 v16.7.0 版本开始新增

The utility consumer functions provide common options for consuming streams.

They are accessed using:

MJS
CJS
M streamConsumers.arrayBuffer(stream)

自 v16.7.0 版本开始新增

MJS
CJS
M streamConsumers.blob(stream)

自 v16.7.0 版本开始新增

MJS
CJS
M streamConsumers.buffer(stream)

自 v16.7.0 版本开始新增

MJS
CJS
M streamConsumers.json(stream)

自 v16.7.0 版本开始新增

MJS
CJS
M streamConsumers.text(stream)

自 v16.7.0 版本开始新增

MJS
CJS
在 GitHub 上编辑当前页面
以 JSON 格式预览