home / documentation / v16 / webstreams

Web Streams API

Table des matières

Ajouté en: v16.5.0

Stabilité: 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

Ajouté en: v16.5.0

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

Ajouté en: 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

Ajouté en: 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])

Ajouté en: v16.5.0

  • reason any
  • Returns: A promise fulfilled with undefined once cancelation has been completed.
M readableStream.getReader([options])

Ajouté en: v16.5.0

MJS
CJS

Causes the readableStream.locked to be true.

M readableStream.pipeThrough(transform[, options])

Ajouté en: 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)

Ajouté en: 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()
Historique
VersionChangements
v16.18.0Support teeing a readable byte stream.
v16.5.0Ajouté en: 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])

Ajouté en: 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

Ajouté en: 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)

Ajouté en: v16.5.0

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

M readableStreamDefaultReader.cancel([reason])

Ajouté en: 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

Ajouté en: 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()

Ajouté en: 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()

Ajouté en: v16.5.0

Releases this reader's lock on the underlying ReadableStream.

C ReadableStreamBYOBReader

Ajouté en: 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)

Ajouté en: v16.5.0

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

M readableStreamBYOBReader.cancel([reason])

Ajouté en: 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

Ajouté en: 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)

Ajouté en: 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()

Ajouté en: v16.5.0

Releases this reader's lock on the underlying ReadableStream.

C ReadableStreamDefaultController

Ajouté en: 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()

Ajouté en: v16.5.0

Closes the ReadableStream to which this controller is associated.

M readableStreamDefaultController.desiredSize

Ajouté en: v16.5.0

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

M readableStreamDefaultController.enqueue(chunk)

Ajouté en: v16.5.0

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

M readableStreamDefaultController.error(error)

Ajouté en: v16.5.0

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

C ReadableByteStreamController

Ajouté en: 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

Ajouté en: v16.5.0

M readableByteStreamController.close()

Ajouté en: v16.5.0

Closes the ReadableStream to which this controller is associated.

M readableByteStreamController.desiredSize

Ajouté en: v16.5.0

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

M readableByteStreamController.enqueue(chunk)

Ajouté en: v16.5.0

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

M readableByteStreamController.error(error)

Ajouté en: v16.5.0

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

C ReadableStreamBYOBRequest

Ajouté en: 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)

Ajouté en: v16.5.0

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

M readableStreamBYOBRequest.respondWithNewView(view)

Ajouté en: v16.5.0

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

M readableStreamBYOBRequest.view

Ajouté en: v16.5.0

C WritableStream

Ajouté en: v16.5.0

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

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

Ajouté en: 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])

Ajouté en: 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()

Ajouté en: v16.5.0

  • Returns: A promise fulfilled with undefined.

Closes the WritableStream when no additional writes are expected.

M writableStream.getWriter()

Ajouté en: v16.5.0

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

M writableStream.locked

Ajouté en: 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

Ajouté en: v16.5.0

M new WritableStreamDefaultWriter(stream)

Ajouté en: v16.5.0

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

M writableStreamDefaultWriter.abort([reason])

Ajouté en: 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()

Ajouté en: v16.5.0

  • Returns: A promise fulfilled with undefined.

Closes the WritableStream when no additional writes are expected.

M writableStreamDefaultWriter.closed

Ajouté en: 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

Ajouté en: v16.5.0

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

M writableStreamDefaultWriter.ready

Ajouté en: v16.5.0

  • type: A promise that is fulfilled with undefined when the writer is ready to be used.
M writableStreamDefaultWriter.releaseLock()

Ajouté en: v16.5.0

Releases this writer's lock on the underlying ReadableStream.

M writableStreamDefaultWriter.write([chunk])

Ajouté en: v16.5.0

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

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

C WritableStreamDefaultController

Ajouté en: 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)

Ajouté en: 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

Ajouté en: 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]]])

Ajouté en: 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

Ajouté en: v16.5.0

M transformStream.writable

Ajouté en: v16.5.0

Transferring with postMessage()

A TransformStream instance can be transferred using a MessagePort.

JS

C TransformStreamDefaultController

Ajouté en: v16.5.0

The TransformStreamDefaultController manages the internal state of the TransformStream.

M transformStreamDefaultController.desiredSize

Ajouté en: v16.5.0

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

M transformStreamDefaultController.enqueue([chunk])

Ajouté en: v16.5.0

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

M transformStreamDefaultController.error([reason])

Ajouté en: 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()

Ajouté en: v16.5.0

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

C ByteLengthQueuingStrategy

Ajouté en: v16.5.0

M new ByteLengthQueuingStrategy(options)

Ajouté en: v16.5.0

M byteLengthQueuingStrategy.highWaterMark

Ajouté en: v16.5.0

M byteLengthQueuingStrategy.size

Ajouté en: v16.5.0

C CountQueuingStrategy

Ajouté en: v16.5.0

M new CountQueuingStrategy(options)

Ajouté en: v16.5.0

M countQueuingStrategy.highWaterMark

Ajouté en: v16.5.0

M countQueuingStrategy.size

Ajouté en: v16.5.0

C TextEncoderStream

Ajouté en: v16.6.0

M new TextEncoderStream()

Ajouté en: v16.6.0

Creates a new TextEncoderStream instance.

M textEncoderStream.encoding

Ajouté en: v16.6.0

The encoding supported by the TextEncoderStream instance.

M textEncoderStream.readable

Ajouté en: v16.6.0

M textEncoderStream.writable

Ajouté en: v16.6.0

C TextDecoderStream

Ajouté en: v16.6.0

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

Ajouté en: 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

Ajouté en: v16.6.0

The encoding supported by the TextDecoderStream instance.

M textDecoderStream.fatal

Ajouté en: v16.6.0

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

M textDecoderStream.ignoreBOM

Ajouté en: v16.6.0

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

M textDecoderStream.readable

Ajouté en: v16.6.0

M textDecoderStream.writable

Ajouté en: v16.6.0

Utility Consumers

Ajouté en: v16.7.0

The utility consumer functions provide common options for consuming streams.

They are accessed using:

MJS
CJS
M streamConsumers.arrayBuffer(stream)

Ajouté en: v16.7.0

MJS
CJS
M streamConsumers.blob(stream)

Ajouté en: v16.7.0

MJS
CJS
M streamConsumers.buffer(stream)

Ajouté en: v16.7.0

MJS
CJS
M streamConsumers.json(stream)

Ajouté en: v16.7.0

MJS
CJS
M streamConsumers.text(stream)

Ajouté en: v16.7.0

MJS
CJS
Modifier cette page sur GitHub
Afficher en JSON