Web Streams API
目录
- 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
Added in: v16.5.0
历史
版本 | 更改 |
---|---|
v18.0.0 | Use of this API no longer emit a runtime warning. |
v16.5.0 | Added in: 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
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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 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
Added in: 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])
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
options
Object
mode
string
'byob'
orundefined
- Returns:
ReadableStreamDefaultReader
|ReadableStreamBYOBReader
MJS
CJS
Causes the readableStream.locked
to be true
.
M readableStream.pipeThrough(transform[, options])
Added in: 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)
Added in: 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()
历史
版本 | 更改 |
---|---|
v18.10.0, v16.18.0 | Support teeing a readable byte stream. |
v16.5.0 | Added 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
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
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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
stream
ReadableStream
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 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()
Added in: 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()
Added in: v16.5.0
Releases this reader's lock on the underlying ReadableStream
.
C ReadableStreamBYOBReader
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Added in: 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)
Added in: v16.5.0
stream
ReadableStream
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 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)
Added in: 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()
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 ReadableStream
s 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
- Type:
number
Returns the amount of data remaining to fill the ReadableStream
's
queue.
M readableStreamDefaultController.enqueue(chunk)
Added in: v16.5.0
chunk
any
Appends a new chunk of data to the ReadableStream
's queue.
M readableStreamDefaultController.error(error)
Added in: v16.5.0
error
any
Signals an error that causes the ReadableStream
to error and close.
C ReadableByteStreamController
历史
版本 | 更改 |
---|---|
v18.10.0 | Support handling a BYOB pull request from a released reader. |
v16.5.0 | 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 ReadableStream
s.
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
- Type:
number
Returns the amount of data remaining to fill the ReadableStream
's
queue.
M readableByteStreamController.enqueue(chunk)
Added in: v16.5.0
chunk
:Buffer
|TypedArray
|DataView
Appends a new chunk of data to the ReadableStream
's queue.
M readableByteStreamController.error(error)
Added in: v16.5.0
error
any
Signals an error that causes the ReadableStream
to error and close.
C ReadableStreamBYOBRequest
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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
bytesWritten
number
Signals that a bytesWritten
number of bytes have been written
to readableStreamBYOBRequest.view
.
M readableStreamBYOBRequest.respondWithNewView(view)
Added in: 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
Added in: v16.5.0
- Type:
Buffer
|TypedArray
|DataView
C WritableStream
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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 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])
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
- Returns:
WritableStreamDefaultWriter
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
- 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
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Added in: v16.5.0 |
M new WritableStreamDefaultWriter(stream)
Added in: v16.5.0
stream
WritableStream
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 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
Added in: v16.5.0
- Type:
number
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
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Added in: v16.5.0 |
The WritableStreamDefaultController
manage's the WritableStream
's
internal state.
M writableStreamDefaultController.error(error)
Added in: 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
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | 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 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
Added in: v16.5.0
- Type:
ReadableStream
M transformStream.writable
Added in: v16.5.0
- Type:
WritableStream
Transferring with postMessage()
A TransformStream
instance can be transferred using a MessagePort
.
JS
C TransformStreamDefaultController
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Added in: v16.5.0 |
The TransformStreamDefaultController
manages the internal state
of the TransformStream
.
M transformStreamDefaultController.desiredSize
Added in: v16.5.0
- Type:
number
The amount of data required to fill the readable side's queue.
M transformStreamDefaultController.enqueue([chunk])
Added in: v16.5.0
chunk
any
Appends a chunk of data to the readable side's queue.
M transformStreamDefaultController.error([reason])
Added in: 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()
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
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Added in: v16.5.0 |
M new ByteLengthQueuingStrategy(options)
Added in: v16.5.0
M byteLengthQueuingStrategy.highWaterMark
Added in: v16.5.0
- Type:
number
M byteLengthQueuingStrategy.size
Added in: v16.5.0
C CountQueuingStrategy
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.5.0 | Added in: v16.5.0 |
M new CountQueuingStrategy(options)
Added in: v16.5.0
M countQueuingStrategy.highWaterMark
Added in: v16.5.0
- Type:
number
M countQueuingStrategy.size
Added in: v16.5.0
C TextEncoderStream
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.6.0 | 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
- Type:
string
The encoding supported by the TextEncoderStream
instance.
M textEncoderStream.readable
Added in: v16.6.0
- Type:
ReadableStream
M textEncoderStream.writable
Added in: v16.6.0
- Type:
WritableStream
C TextDecoderStream
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v16.6.0 | Added in: v16.6.0 |
M new TextDecoderStream([encoding[, options]])
Added in: 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
Added in: v16.6.0
- Type:
string
The encoding supported by the TextDecoderStream
instance.
M textDecoderStream.fatal
Added in: v16.6.0
- Type:
boolean
The value will be true
if decoding errors result in a TypeError
being
thrown.
M textDecoderStream.ignoreBOM
Added in: v16.6.0
- Type:
boolean
The value will be true
if the decoding result will include the byte order
mark.
M textDecoderStream.readable
Added in: v16.6.0
- Type:
ReadableStream
M textDecoderStream.writable
Added in: v16.6.0
- Type:
WritableStream
C CompressionStream
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v17.0.0 | Added in: v17.0.0 |
M new CompressionStream(format)
Added in: v17.0.0
format
string
One of either'deflate'
or'gzip'
.
M compressionStream.readable
Added in: v17.0.0
- Type:
ReadableStream
M compressionStream.writable
Added in: v17.0.0
- Type:
WritableStream
C DecompressionStream
历史
版本 | 更改 |
---|---|
v18.0.0 | This class is now exposed on the global object. |
v17.0.0 | Added in: v17.0.0 |
M new DecompressionStream(format)
Added in: v17.0.0
format
string
One of either'deflate'
or'gzip'
.
M decompressionStream.readable
Added in: v17.0.0
- Type:
ReadableStream
M decompressionStream.writable
Added in: v17.0.0
- Type:
WritableStream
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
stream
ReadableStream
|stream.Readable
|AsyncIterator
- Returns:
Promise
Fulfills with anArrayBuffer
containing the full contents of the stream.
MJS
CJS
M streamConsumers.blob(stream)
Added in: 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)
Added in: 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)
Added in: 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)
Added in: 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