ReadableStream
Last update：2024-08-14 19:50:28
The ReadableStream object represents a readable stream of bytes, used for asynchronous data reading. It is based on the ReadableStream interface of the Web API standard. You can use the ReadableStream object to handle streaming data, such as large file downloads and video streams.
Obtaining a ReadableStream Object
ReadableStream objects are typically obtained as return values from other APIs, such as:
- The
Response.bodyproperty returns aReadableStreamobject representing the response body. - The
readableproperty of aTransformStreamreturns aReadableStreamobject.
Properties
-
locked(read-only)A boolean value indicating whether the stream is locked.
Note:
A stream is in a locked state under the following circumstances:- A stream can have at most one active reader. The stream remains locked until the reader calls the
releaseLock()method. - A stream is locked during a pipe operation until the operation completes.
- A stream can have at most one active reader. The stream remains locked until the reader calls the
Methods
Note: All the following methods require the current stream to be in an unlocked state; otherwise, an exception will be thrown.
getReader
readable.getReader(options?: ReaderOptions): ReadableStreamDefaultReader | ReadableStreamBYOBReader;
Creates a Reader object and locks the current stream until the Reader calls releaseLock() to release the lock.
Parameters:
| Parameter Name | Type | Required | Description |
|---|---|---|---|
options |
ReaderOptions |
No | Configuration options for creating the Reader. |
ReaderOptions
| Attribute Name | Type | Required | Description |
|---|---|---|---|
mode |
string |
No | The type of Reader. The default value is undefined. If undefined, a ReadableStreamDefaultReader is created; if byob, a ReadableStreamBYOBReader is created. |
pipeThrough
readable.pipeThrough(transformStream: TransformStream, options?: PipeToOptions): ReadableStream;
Pipes the data from the current readable stream to the writable end of the transformStream and returns the readable end of the transformStream.
Note: The writable end of the current stream is locked during the pipe operation.
Parameters:
| Parameter Name | Type | Required | Description |
|---|---|---|---|
transformStream |
TransformStream |
Yes | The target stream to which the current stream is piped. |
options |
PipeToOptions |
No | Stream processing options. |
PipeToOptions
| Attribute Name | Type | Required | Description |
|---|---|---|---|
preventClose |
boolean |
No | If set to true, closing the readable stream will not close the writable stream. |
preventAbort |
boolean |
No | If set to true, errors in the readable stream will not abort the writable stream. pipeTo will return a rejected promise with the error from the source or any error that occurred while aborting the destination. |
preventCancel |
boolean |
No | If set to true, errors in the writable stream will not cancel the readable stream. |
signal |
AbortSignal |
No | If the signal is aborted, the ongoing transfer will be aborted. |
pipeTo
readable.pipeTo(destination: WritableStream, options?: PipeToOptions): Promise<void>;
Pipes the current readable stream to the destination writable stream.
Note: The destination stream is locked during the pipe operation.
Parameters:
| Parameter Name | Type | Required | Description |
|---|---|---|---|
destination |
WritableStream |
Yes | The writable stream. |
options |
PipeToOptions |
No | Stream processing options. |
tee
readable.tee(): [ReadableStream, ReadableStream];
Creates two independent readable streams from the current stream.
cancel
readable.cancel(reason?: string): Promise<string>;
Ends the current stream.