wasm_streams/writable/
default_writer.rs

1use std::marker::PhantomData;
2
3use wasm_bindgen::JsValue;
4
5use crate::util::promise_to_void_future;
6
7use super::{sys, IntoAsyncWrite, IntoSink, WritableStream};
8
9/// A [`WritableStreamDefaultWriter`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStreamDefaultWriter)
10/// that can be used to write chunks to a [`WritableStream`](WritableStream).
11///
12/// This is returned by the [`get_writer`](WritableStream::get_writer) method.
13///
14/// When the writer is dropped, it automatically [releases its lock](https://streams.spec.whatwg.org/#release-a-lock).
15#[derive(Debug)]
16pub struct WritableStreamDefaultWriter<'stream> {
17    raw: sys::WritableStreamDefaultWriter,
18    _stream: PhantomData<&'stream mut WritableStream>,
19}
20
21impl<'stream> WritableStreamDefaultWriter<'stream> {
22    pub(crate) fn new(stream: &mut WritableStream) -> Result<Self, js_sys::Error> {
23        Ok(Self {
24            raw: stream.as_raw().get_writer()?,
25            _stream: PhantomData,
26        })
27    }
28
29    /// Acquires a reference to the underlying [JavaScript writer](sys::WritableStreamDefaultWriter).
30    #[inline]
31    pub fn as_raw(&self) -> &sys::WritableStreamDefaultWriter {
32        &self.raw
33    }
34
35    /// Waits for the stream to become closed.
36    ///
37    /// This returns an error if the stream ever errors, or if the writer's lock is
38    /// [released](https://streams.spec.whatwg.org/#release-a-lock) before the stream finishes
39    /// closing.
40    pub async fn closed(&self) -> Result<(), JsValue> {
41        promise_to_void_future(self.as_raw().closed()).await
42    }
43
44    /// Returns the desired size to fill the stream's internal queue.
45    ///
46    /// * It can be negative, if the queue is over-full.
47    ///   A producer can use this information to determine the right amount of data to write.
48    /// * It will be `None` if the stream cannot be successfully written to
49    ///   (due to either being errored, or having an abort queued up).
50    /// * It will return zero if the stream is closed.
51    #[inline]
52    pub fn desired_size(&self) -> Option<f64> {
53        self.as_raw().desired_size()
54    }
55
56    /// Waits until the desired size to fill the stream's internal queue transitions
57    /// from non-positive to positive, signaling that it is no longer applying backpressure.
58    ///
59    /// Once the desired size to fill the stream's internal queue dips back to zero or below,
60    /// this will return a new future that stays pending until the next transition.
61    ///
62    /// This returns an error if the stream ever errors, or if the writer's lock is
63    /// [released](https://streams.spec.whatwg.org/#release-a-lock) before the stream finishes
64    /// closing.
65    pub async fn ready(&self) -> Result<(), JsValue> {
66        promise_to_void_future(self.as_raw().ready()).await
67    }
68
69    /// [Aborts](https://streams.spec.whatwg.org/#abort-a-writable-stream) the stream,
70    /// signaling that the producer can no longer successfully write to the stream.
71    ///
72    /// Equivalent to [`WritableStream.abort`](WritableStream::abort).
73    pub async fn abort(&mut self) -> Result<(), JsValue> {
74        promise_to_void_future(self.as_raw().abort()).await
75    }
76
77    /// [Aborts](https://streams.spec.whatwg.org/#abort-a-writable-stream) the stream with the
78    /// given `reason`, signaling that the producer can no longer successfully write to the stream.
79    ///
80    /// Equivalent to [`WritableStream.abort_with_reason`](WritableStream::abort_with_reason).
81    pub async fn abort_with_reason(&mut self, reason: &JsValue) -> Result<(), JsValue> {
82        promise_to_void_future(self.as_raw().abort_with_reason(reason)).await
83    }
84
85    /// Writes the given `chunk` to the writable stream, by waiting until any previous writes
86    /// have finished successfully, and then sending the chunk to the underlying sink's `write()`
87    /// method.
88    ///
89    /// This returns `Ok(())` upon a successful write, or `Err(error)` if the write fails or stream
90    /// becomes errored before the writing process is initiated.
91    ///
92    /// Note that what "success" means is up to the underlying sink; it might indicate simply
93    /// that the chunk has been accepted, and not necessarily that it is safely saved to
94    /// its ultimate destination.
95    pub async fn write(&mut self, chunk: JsValue) -> Result<(), JsValue> {
96        promise_to_void_future(self.as_raw().write(chunk)).await
97    }
98
99    /// Closes the stream.
100    ///
101    /// The underlying sink will finish processing any previously-written chunks, before invoking
102    /// its close behavior. During this time any further attempts to write will fail
103    /// (without erroring the stream).
104    ///
105    /// This returns `Ok(())` if all remaining chunks are successfully written and the stream
106    /// successfully closes, or `Err(error)` if an error is encountered during this process.
107    pub async fn close(&mut self) -> Result<(), JsValue> {
108        promise_to_void_future(self.as_raw().close()).await
109    }
110
111    /// Converts this `WritableStreamDefaultWriter` into a [`Sink`].
112    ///
113    /// This is similar to [`WritableStream.into_sink`](WritableStream::into_sink),
114    /// except that after the returned `Sink` is dropped, the original `WritableStream` is still
115    /// usable. This allows writing only a few chunks through the `Sink`, while still allowing
116    /// another writer to write more chunks later on.
117    ///
118    /// [`Sink`]: https://docs.rs/futures/0.3.18/futures/sink/trait.Sink.html
119    #[inline]
120    pub fn into_sink(self) -> IntoSink<'stream> {
121        IntoSink::new(self)
122    }
123
124    /// Converts this `WritableStreamDefaultWriter` into an [`AsyncWrite`].
125    ///
126    /// The writable stream must accept [`Uint8Array`](js_sys::Uint8Array) chunks.
127    ///
128    /// This is similar to [`WritableStream.into_async_write`](WritableStream::into_async_write),
129    /// except that after the returned `AsyncWrite` is dropped, the original `WritableStream` is
130    /// still usable. This allows writing only a few bytes through the `AsyncWrite`, while still
131    /// allowing another writer to write more bytes later on.
132    ///
133    /// [`AsyncWrite`]: https://docs.rs/futures/0.3.18/futures/io/trait.AsyncWrite.html
134    #[inline]
135    pub fn into_async_write(self) -> IntoAsyncWrite<'stream> {
136        IntoAsyncWrite::new(self.into_sink())
137    }
138}
139
140impl Drop for WritableStreamDefaultWriter<'_> {
141    fn drop(&mut self) {
142        self.as_raw().release_lock()
143    }
144}
wasm_streams/writable/default_writer.rs

wasm_streams/writable/
default_writer.rs
