Struct ReadableStream

pub struct ReadableStream { /* private fields */ }

A ReadableStream.

ReadableStreams can be created from a raw JavaScript stream with from_raw, or from a Rust Stream with from_stream.

They can be converted into a raw JavaScript stream with into_raw, or into a Rust Stream with into_stream.

If the browser supports readable byte streams, then they can be created from a Rust AsyncRead with from_async_read, or converted into one with into_async_read.

Implementations

impl ReadableStream

pub fn from_raw(raw: ReadableStream) -> Self

Creates a new ReadableStream from a JavaScript stream.

pub fn from_stream<St>(stream: St) -> Self

where St: Stream<Item = Result<JsValue, JsValue>> + 'static,

Creates a new ReadableStream from a Stream.

Items and errors must be represented as raw JsValues. Use map, map_ok and/or map_err to convert a stream’s items to a JsValue before passing it to this function.

pub fn from_async_read<R>(async_read: R, default_buffer_len: usize) -> Self

where R: AsyncRead + 'static,

Creates a new ReadableStream from an AsyncRead.

This creates a readable byte stream whose autoAllocateChunkSize is default_buffer_len. Therefore, if a default reader is used to consume the stream, the given async_read will be polled with a buffer of this size. If a BYOB reader is used, then it will be polled with a buffer of the same size as the BYOB read request instead.

Panics if readable byte streams are not supported by the browser.

pub fn from(async_iterable: Object) -> Self

Creates a new ReadableStream wrapping the provided iterable or async iterable.

This can be used to adapt various kinds of objects into a readable stream, such as an array, an async generator or a Node.js readable stream.

Panics if ReadableStream.from() is not supported by the browser, or if the given object is not a valid iterable or async iterable. For a non-panicking variant, use try_from.

pub fn try_from(async_iterable: Object) -> Result<Self, Error>

Try to create a new ReadableStream wrapping the provided iterable or async iterable.

This can be used to adapt various kinds of objects into a readable stream, such as an array, an async generator or a Node.js readable stream.

If ReadableStream.from() is not supported by the browser, or if the given object is not a valid iterable or async iterable, then this returns an error.

pub fn as_raw(&self) -> &ReadableStream

Acquires a reference to the underlying JavaScript stream.

pub fn into_raw(self) -> ReadableStream

Consumes this ReadableStream, returning the underlying JavaScript stream.

pub fn is_locked(&self) -> bool

Returns true if the stream is locked to a reader.

pub async fn cancel(&mut self) -> Result<(), JsValue>

Cancels the stream, signaling a loss of interest in the stream by a consumer.

If the stream is currently locked to a reader, then this returns an error.

pub async fn cancel_with_reason( &mut self, reason: &JsValue, ) -> Result<(), JsValue>

Cancels the stream, signaling a loss of interest in the stream by a consumer.

The supplied reason will be given to the underlying source, which may or may not use it.

If the stream is currently locked to a reader, then this returns an error.

pub fn get_reader(&mut self) -> ReadableStreamDefaultReader<'_>

Creates a default reader and locks the stream to the new reader.

While the stream is locked, no other reader can be acquired until this one is released.

Panics if the stream is already locked to a reader. For a non-panicking variant, use try_get_reader.

pub fn try_get_reader( &mut self, ) -> Result<ReadableStreamDefaultReader<'_>, Error>

Try to create a default reader and lock the stream to the new reader.

While the stream is locked, no other reader can be acquired until this one is released.

If the stream is already locked to a reader, then this returns an error.

pub fn get_byob_reader(&mut self) -> ReadableStreamBYOBReader<'_>

Creates a BYOB reader and locks the stream to the new reader.

While the stream is locked, no other reader can be acquired until this one is released.

Panics if the stream is already locked to a reader, or if this stream is not a readable byte stream. For a non-panicking variant, use try_get_reader.

pub fn try_get_byob_reader( &mut self, ) -> Result<ReadableStreamBYOBReader<'_>, Error>

Try to create a BYOB reader and lock the stream to the new reader.

While the stream is locked, no other reader can be acquired until this one is released.

If the stream is already locked to a reader, then this returns an error.

pub async fn pipe_to<'a>( &'a mut self, dest: &'a mut WritableStream, ) -> Result<(), JsValue>

Pipes this readable stream to a given writable stream.

Piping a stream will lock it for the duration of the pipe, preventing any other consumer from acquiring a reader.

This returns () if the pipe completes successfully, or Err(error) if any error was encountered during the process.

pub async fn pipe_to_with_options<'a>( &'a mut self, dest: &'a mut WritableStream, options: &PipeOptions, ) -> Result<(), JsValue>

Pipes this readable stream to a given writable stream.

Piping a stream will lock it for the duration of the pipe, preventing any other consumer from acquiring a reader.

Errors and closures of the source and destination streams propagate as follows:

• An error in the source readable stream will abort the destination writable stream, unless options.prevent_abort is true.
• An error in the destination writable stream will cancel the source readable stream, unless options.prevent_cancel is true.
• When the source readable stream closes, the destination writable stream will be closed, unless options.prevent_close is true.
• If the destination writable stream starts out closed or closing, the source readable stream will be canceled, unless unless options.prevent_cancel is true.

This returns () if the pipe completes successfully, or Err(error) if any error was encountered during the process.

pub fn tee(self) -> (ReadableStream, ReadableStream)

Tees this readable stream, returning the two resulting branches as new ReadableStream instances.

Teeing a stream will lock it, preventing any other consumer from acquiring a reader. To cancel the stream, cancel both of the resulting branches; a composite cancellation reason will then be propagated to the stream’s underlying source.

Note that the chunks seen in each branch will be the same object. If the chunks are not immutable, this could allow interference between the two branches.

Panics if the stream is already locked to a reader. For a non-panicking variant, use try_tee.

pub fn try_tee(self) -> Result<(ReadableStream, ReadableStream), (Error, Self)>

Tries to tee this readable stream, returning the two resulting branches as new ReadableStream instances.

Teeing a stream will lock it, preventing any other consumer from acquiring a reader. To cancel the stream, cancel both of the resulting branches; a composite cancellation reason will then be propagated to the stream’s underlying source.

Note that the chunks seen in each branch will be the same object. If the chunks are not immutable, this could allow interference between the two branches.

If the stream is already locked to a reader, then this returns an error along with the original ReadableStream.

pub fn into_stream(self) -> IntoStream<'static>

Converts this ReadableStream into a Stream.

Items and errors are represented by their raw JsValue. Use map, map_ok and/or map_err on the returned stream to convert them to a more appropriate type.

Panics if the stream is already locked to a reader. For a non-panicking variant, use try_into_stream.

pub fn try_into_stream(self) -> Result<IntoStream<'static>, (Error, Self)>

Try to convert this ReadableStream into a Stream.

Items and errors are represented by their raw JsValue. Use map, map_ok and/or map_err on the returned stream to convert them to a more appropriate type.

If the stream is already locked to a reader, then this returns an error along with the original ReadableStream.

pub fn into_async_read(self) -> IntoAsyncRead<'static>

Converts this ReadableStream into an AsyncRead.

Panics if the stream is already locked to a reader, or if this stream is not a readable byte stream. For a non-panicking variant, use try_into_async_read.

pub fn try_into_async_read( self, ) -> Result<IntoAsyncRead<'static>, (Error, Self)>

Try to convert this ReadableStream into an AsyncRead.

If the stream is already locked to a reader, or if this stream is not a readable byte stream, then this returns an error along with the original ReadableStream.

Trait Implementations

impl Debug for ReadableStream

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<St> From<St> for ReadableStream

where St: Stream<Item = Result<JsValue, JsValue>> + 'static,

fn from(stream: St) -> Self

Equivalent to from_stream.