Web Streams API
Table des matières
- Overview
- API
- Class: ReadableStream
- Class: ReadableStreamDefaultReader
- Class: ReadableStreamBYOBReader
- Class: ReadableStreamDefaultController
- Class: ReadableByteStreamController
- Class: ReadableStreamBYOBRequest
- Class: WritableStream
- Class: WritableStreamDefaultWriter
- Class: WritableStreamDefaultController
- Class: TransformStream
- Class: TransformStreamDefaultController
- Class: ByteLengthQueuingStrategy
- Class: CountQueuingStrategy
- Class: TextEncoderStream
- Class: TextDecoderStream
- Class: CompressionStream
- Class: DecompressionStream
- Utility Consumers
Ajouté en: v16.5.0
Historique
Version | Changements |
---|---|
v18.0.0 | Use of this API no longer emit a runtime warning. |
v16.5.0 | Ajouté en: 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.
MJS
CJS
API
C ReadableStream
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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 theReadableStream
is created.controller
ReadableStreamDefaultController
|ReadableByteStreamController
- Returns:
undefined
or a promise fulfilled withundefined
.
pull
Function
A user-defined function that is called repeatedly when theReadableStream
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 theReadableStream
is canceled.reason
any
- Returns: A promise fulfilled with
undefined
.
type
string
Must be'bytes'
orundefined
.autoAllocateChunkSize
number
Used only whentype
is equal to'bytes'
.
strategy
Object
M readableStream.locked
Ajouté en: v16.5.0
- Type:
boolean
Set totrue
if there is an active reader for thisReadableStream
.
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
options
Object
mode
string
'byob'
orundefined
- Returns:
ReadableStreamDefaultReader
|ReadableStreamBYOBReader
MJS
CJS
Causes the readableStream.locked
to be true
.
M readableStream.pipeThrough(transform[, options])
Ajouté en: v16.5.0
transform
Object
readable
ReadableStream
TheReadableStream
to whichtransform.writable
will push the potentially modified data is receives from thisReadableStream
.writable
WritableStream
TheWritableStream
to which thisReadableStream
's data will be written.
options
Object
preventAbort
boolean
Whentrue
, errors in thisReadableStream
will not causetransform.writable
to be aborted.preventCancel
boolean
Whentrue
, errors in the destinationtransform.writable
do not cause thisReadableStream
to be canceled.preventClose
boolean
Whentrue
, closing thisReadableStream
does not causetransform.writable
to be closed.signal
AbortSignal
Allows the transfer of data to be canceled using anAbortController
.
- Returns:
ReadableStream
Fromtransform.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
AWritableStream
to which thisReadableStream
's data will be written.options
Object
preventAbort
boolean
Whentrue
, errors in thisReadableStream
will not causedestination
to be aborted.preventCancel
boolean
Whentrue
, errors in thedestination
will not cause thisReadableStream
to be canceled.preventClose
boolean
Whentrue
, closing thisReadableStream
does not causedestination
to be closed.signal
AbortSignal
Allows the transfer of data to be canceled using anAbortController
.
- Returns: A promise fulfilled with
undefined
Causes the readableStream.locked
to be true
while the pipe operation
is active.
M readableStream.tee()
Historique
Version | Changements |
---|---|
v18.10.0 | Support teeing a readable byte stream. |
v16.5.0 | Ajouté 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
Whentrue
, prevents theReadableStream
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
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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
stream
ReadableStream
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 withundefined
when the associatedReadableStream
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
- 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()
Ajouté en: v16.5.0
Releases this reader's lock on the underlying ReadableStream
.
C ReadableStreamBYOBReader
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Ajouté en: v16.5.0 |
The ReadableStreamBYOBReader
is an alternative consumer for
byte-oriented ReadableStream
s (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
stream
ReadableStream
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 withundefined
when the associatedReadableStream
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
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 Buffer
s 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 ReadableStream
s 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
- Type:
number
Returns the amount of data remaining to fill the ReadableStream
's
queue.
M readableStreamDefaultController.enqueue(chunk)
Ajouté en: v16.5.0
chunk
any
Appends a new chunk of data to the ReadableStream
's queue.
M readableStreamDefaultController.error(error)
Ajouté en: v16.5.0
error
any
Signals an error that causes the ReadableStream
to error and close.
C ReadableByteStreamController
Historique
Version | Changements |
---|---|
v18.10.0 | Support handling a BYOB pull request from a released reader. |
v16.5.0 | 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 ReadableStream
s.
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
- Type:
number
Returns the amount of data remaining to fill the ReadableStream
's
queue.
M readableByteStreamController.enqueue(chunk)
Ajouté en: v16.5.0
chunk
:Buffer
|TypedArray
|DataView
Appends a new chunk of data to the ReadableStream
's queue.
M readableByteStreamController.error(error)
Ajouté en: v16.5.0
error
any
Signals an error that causes the ReadableStream
to error and close.
C ReadableStreamBYOBRequest
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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
bytesWritten
number
Signals that a bytesWritten
number of bytes have been written
to readableStreamBYOBRequest.view
.
M readableStreamBYOBRequest.respondWithNewView(view)
Ajouté en: 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
Ajouté en: v16.5.0
- Type:
Buffer
|TypedArray
|DataView
C WritableStream
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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 theWritableStream
is created.controller
WritableStreamDefaultController
- Returns:
undefined
or a promise fulfilled withundefined
.
write
Function
A user-defined function that is invoked when a chunk of data has been written to theWritableStream
.chunk
any
controller
WritableStreamDefaultController
- Returns: A promise fulfilled with
undefined
.
close
Function
A user-defined function that is called when theWritableStream
is closed.- Returns: A promise fulfilled with
undefined
.
- Returns: A promise fulfilled with
abort
Function
A user-defined function that is called to abruptly close theWritableStream
.reason
any
- Returns: A promise fulfilled with
undefined
.
type
any
Thetype
option is reserved for future use and must be undefined.
strategy
Object
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
- Returns:
WritableStreamDefaultWriter
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
- 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
.
JS
C WritableStreamDefaultWriter
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Ajouté en: v16.5.0 |
M new WritableStreamDefaultWriter(stream)
Ajouté en: v16.5.0
stream
WritableStream
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 withundefined
when the associatedWritableStream
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
- Type:
number
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
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Ajouté en: v16.5.0 |
The WritableStreamDefaultController
manage's the WritableStream
's
internal state.
M writableStreamDefaultController.error(error)
Ajouté en: 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
AnAbortSignal
that can be used to cancel pending write or close operations when aWritableStream
is aborted.
C TransformStream
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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 theTransformStream
is created.controller
TransformStreamDefaultController
- Returns:
undefined
or a promise fulfilled withundefined
transform
Function
A user-defined function that receives, and potentially modifies, a chunk of data written totransformStream.writable
, before forwarding that on totransformStream.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 theTransformStream
is closed, signaling the end of the transformation process.controller
TransformStreamDefaultController
- Returns: A promise fulfilled with
undefined
.
readableType
any
thereadableType
option is reserved for future use and must beundefined
.writableType
any
thewritableType
option is reserved for future use and must beundefined
.
writableStrategy
Object
readableStrategy
Object
M transformStream.readable
Ajouté en: v16.5.0
- Type:
ReadableStream
M transformStream.writable
Ajouté en: v16.5.0
- Type:
WritableStream
Transferring with postMessage()
A TransformStream
instance can be transferred using a MessagePort
.
JS
C TransformStreamDefaultController
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Ajouté en: v16.5.0 |
The TransformStreamDefaultController
manages the internal state
of the TransformStream
.
M transformStreamDefaultController.desiredSize
Ajouté en: v16.5.0
- Type:
number
The amount of data required to fill the readable side's queue.
M transformStreamDefaultController.enqueue([chunk])
Ajouté en: v16.5.0
chunk
any
Appends a chunk of data to the readable side's queue.
M transformStreamDefaultController.error([reason])
Ajouté en: 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()
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
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Ajouté en: v16.5.0 |
M new ByteLengthQueuingStrategy(options)
Ajouté en: v16.5.0
M byteLengthQueuingStrategy.highWaterMark
Ajouté en: v16.5.0
- Type:
number
M byteLengthQueuingStrategy.size
Ajouté en: v16.5.0
C CountQueuingStrategy
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Ajouté en: v16.5.0 |
M new CountQueuingStrategy(options)
Ajouté en: v16.5.0
M countQueuingStrategy.highWaterMark
Ajouté en: v16.5.0
- Type:
number
M countQueuingStrategy.size
Ajouté en: v16.5.0
C TextEncoderStream
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.6.0 | 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
- Type:
string
The encoding supported by the TextEncoderStream
instance.
M textEncoderStream.readable
Ajouté en: v16.6.0
- Type:
ReadableStream
M textEncoderStream.writable
Ajouté en: v16.6.0
- Type:
WritableStream
C TextDecoderStream
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.6.0 | Ajouté en: v16.6.0 |
M new TextDecoderStream([encoding[, options]])
Ajouté en: v16.6.0
encoding
string
Identifies theencoding
that thisTextDecoder
instance supports. Default:'utf-8'
.options
Object
fatal
boolean
true
if decoding failures are fatal.ignoreBOM
boolean
Whentrue
, theTextDecoderStream
will include the byte order mark in the decoded result. Whenfalse
, the byte order mark will be removed from the output. This option is only used whenencoding
is'utf-8'
,'utf-16be'
, or'utf-16le'
. Default:false
.
Creates a new TextDecoderStream
instance.
M textDecoderStream.encoding
Ajouté en: v16.6.0
- Type:
string
The encoding supported by the TextDecoderStream
instance.
M textDecoderStream.fatal
Ajouté en: v16.6.0
- Type:
boolean
The value will be true
if decoding errors result in a TypeError
being
thrown.
M textDecoderStream.ignoreBOM
Ajouté en: v16.6.0
- Type:
boolean
The value will be true
if the decoding result will include the byte order
mark.
M textDecoderStream.readable
Ajouté en: v16.6.0
- Type:
ReadableStream
M textDecoderStream.writable
Ajouté en: v16.6.0
- Type:
WritableStream
C CompressionStream
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v17.0.0 | Ajouté en: v17.0.0 |
M new CompressionStream(format)
Ajouté en: v17.0.0
format
string
One of either'deflate'
or'gzip'
.
M compressionStream.readable
Ajouté en: v17.0.0
- Type:
ReadableStream
M compressionStream.writable
Ajouté en: v17.0.0
- Type:
WritableStream
C DecompressionStream
Historique
Version | Changements |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v17.0.0 | Ajouté en: v17.0.0 |
M new DecompressionStream(format)
Ajouté en: v17.0.0
format
string
One of either'deflate'
or'gzip'
.
M decompressionStream.readable
Ajouté en: v17.0.0
- Type:
ReadableStream
M decompressionStream.writable
Ajouté en: v17.0.0
- Type:
WritableStream
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
stream
ReadableStream
|stream.Readable
|AsyncIterator
- Returns:
Promise
Fulfills with anArrayBuffer
containing the full contents of the stream.
MJS
CJS
M streamConsumers.blob(stream)
Ajouté en: v16.7.0
stream
ReadableStream
|stream.Readable
|AsyncIterator
- Returns:
Promise
Fulfills with aBlob
containing the full contents of the stream.
MJS
CJS
M streamConsumers.buffer(stream)
Ajouté en: v16.7.0
stream
ReadableStream
|stream.Readable
|AsyncIterator
- Returns:
Promise
Fulfills with aBuffer
containing the full contents of the stream.
MJS
CJS
M streamConsumers.json(stream)
Ajouté en: 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 throughJSON.parse()
.
MJS
CJS
M streamConsumers.text(stream)
Ajouté en: v16.7.0
stream
ReadableStream
|stream.Readable
|AsyncIterator
- Returns:
Promise
Fulfills with the contents of the stream parsed as a UTF-8 encoded string.
MJS
CJS