home / documentation / v16 / webstreams

Web Streams API

目录

Added in: 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

Added in: v16.5.0

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

Added in: 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])

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

MJS
CJS

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.

MJS
CJS
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()
历史
版本更改
v16.18.0Support teeing a readable byte stream.
v16.5.0Added in: 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])

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.

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

Added in: 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)

Added in: v16.5.0

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

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

Added in: 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)

Added in: v16.5.0

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

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

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

M readableStreamDefaultController.enqueue(chunk)

Added in: v16.5.0

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

M readableStreamDefaultController.error(error)

Added in: v16.5.0

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

C ReadableByteStreamController

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 ReadableByteStreamController is for byte-oriented ReadableStreams.

M readableByteStreamController.byobRequest

Added in: v16.5.0

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

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

M readableByteStreamController.enqueue(chunk)

Added in: v16.5.0

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

M readableByteStreamController.error(error)

Added in: v16.5.0

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

C ReadableStreamBYOBRequest

Added in: 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)

Added in: v16.5.0

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

M readableStreamBYOBRequest.respondWithNewView(view)

Added in: v16.5.0

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

C WritableStream

Added in: v16.5.0

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

MJS
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.
    • 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])

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

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

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

Added in: v16.5.0

M new WritableStreamDefaultWriter(stream)

Added in: v16.5.0

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

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

Added in: 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)

Added in: 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

Added in: 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]]])

Added in: 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

Added in: v16.5.0

M transformStream.writable

Added in: v16.5.0

Transferring with postMessage()

A TransformStream instance can be transferred using a MessagePort.

JS

C TransformStreamDefaultController

Added in: v16.5.0

The TransformStreamDefaultController manages the internal state of the TransformStream.

M transformStreamDefaultController.desiredSize

Added in: v16.5.0

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

M transformStreamDefaultController.enqueue([chunk])

Added in: v16.5.0

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

M transformStreamDefaultController.error([reason])

Added in: 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()

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

Added in: v16.5.0

M new ByteLengthQueuingStrategy(options)

Added in: v16.5.0

M byteLengthQueuingStrategy.highWaterMark

Added in: v16.5.0

M byteLengthQueuingStrategy.size

Added in: v16.5.0

C CountQueuingStrategy

Added in: v16.5.0

M new CountQueuingStrategy(options)

Added in: v16.5.0

M countQueuingStrategy.highWaterMark

Added in: v16.5.0

M countQueuingStrategy.size

Added in: v16.5.0

C TextEncoderStream

Added in: v16.6.0

M new TextEncoderStream()

Added in: v16.6.0

Creates a new TextEncoderStream instance.

M textEncoderStream.encoding

Added in: v16.6.0

The encoding supported by the TextEncoderStream instance.

M textEncoderStream.readable

Added in: v16.6.0

M textEncoderStream.writable

Added in: v16.6.0

C TextDecoderStream

Added in: v16.6.0

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

The encoding supported by the TextDecoderStream instance.

M textDecoderStream.fatal

Added in: v16.6.0

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

M textDecoderStream.ignoreBOM

Added in: v16.6.0

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

M textDecoderStream.readable

Added in: v16.6.0

M textDecoderStream.writable

Added in: v16.6.0

Utility Consumers

Added in: v16.7.0

The utility consumer functions provide common options for consuming streams.

They are accessed using:

MJS
CJS
M streamConsumers.arrayBuffer(stream)

Added in: v16.7.0

MJS
CJS
M streamConsumers.blob(stream)

Added in: v16.7.0

MJS
CJS
M streamConsumers.buffer(stream)

Added in: v16.7.0

MJS
CJS
M streamConsumers.json(stream)

Added in: v16.7.0

MJS
CJS
M streamConsumers.text(stream)

Added in: v16.7.0

MJS
CJS
在 GitHub 上编辑此页面
以 JSON 格式查看