ReadableStream: pipeThrough() method
Streams
Streams
The pipeThrough() method of the ReadableStream interface provides a chainable way of piping the current stream through a transform stream or any other writable/readable pair.
Piping a stream will generally lock it for the duration of the pipe, preventing other readers from locking it.
Syntax
pipeThrough(transformStream)
pipeThrough(transformStream, options)
Parameters
transformStream-
: A TransformStream (or an object with the structure
{writable, readable}) consisting of a readable stream and a writable stream working together to transform some data from one form to another. Data written to thewritablestream can be read in some transformed state by thereadablestream. For example, a TextDecoder, has bytes written to it and strings read from it, while a video decoder has encoded bytes written to it and uncompressed video frames read from it. -
options -
: The options that should be used when piping to the
writablestream. Available options are:preventClose-
: If this is set to
true, closing the sourceReadableStreamwill no longer cause the destinationWritableStreamto be closed. -
preventAbort -
: If this is set to
true, errors in the sourceReadableStreamwill no longer abort the destinationWritableStream. -
preventCancel -
: If this is set to
true, errors in the destinationWritableStreamwill no longer cancel the sourceReadableStream. -
signal - : If set to an
AbortSignalobject, ongoing pipe operations can then be aborted via the correspondingAbortController.
Return value
The readable side of the transformStream.
Exceptions
- TypeError
- : Thrown if the
writableand/orreadableproperty oftransformStreamare undefined.
Examples
In the following example (see Unpack chunks of a PNG for the full code running live, and png-transform-stream for the source code), an image is fetched and its body retrieved as a ReadableStream.
Next, we log the contents of the readable stream, use pipeThrough() to send it to a new function that creates a gray-scaled version of the stream, then log the new stream's contents too.
// Fetch the original image
fetch("png-logo.png")
// Retrieve its body as ReadableStream
.then((response) => response.body)
.then((rs) => logReadableStream("Fetch Response Stream", rs))
// Create a gray-scaled PNG stream out of the original
.then((body) => body.pipeThrough(new PNGTransformStream()))
.then((rs) => logReadableStream("PNG Chunk Stream", rs));
Specifications
Browser compatibility
See also
- ReadableStream() constructor
- Pipe chains