Struct Promise

pub struct Promise<TOk: Send + 'static, TErr: Send + 'static> { /* private fields */ }

Typed promises, working with Rust types.

This provides a higher level, Rust-like interface for working with Javascript promises. It allows passing Rust values through promises (even if they don’t implement stdweb::JsSerialize).

Other than the basic functions for creating already-resolved promises, the usual way to create a Promise is to create a RawPromise object using js!{} with a JS API, then use RawPromise::then_to_typed to convert the raw JS results to a Rust type (or do something else with it).

If you need to pass the promise to a JS API, you can use Promise::then_to_raw to convert the rust objects to JS objects and get a RawPromise, which exposes a JS promise object via js_obj.

The result types must have only 'static references, since promises may resolve arbitrairly late, or even not at all.

Note that there are a few limitations of this API due to how the internal passing of Rust objects works:

• Chained methods like then consume the promise, preventing code from using the promise results multiple times. This is because the result values have to be moved out of the internal box, making them unavailable for other promises. This may be relaxed in the future for types that impement Clone.
• For the above reason, and to avoid exposing internals that may result in other unsafe behavior, you cannot get the JS promsie object from this type. You can, however, use then_to_raw to get a RawPromise, which you can get the promise object of.
• Like RawPromise, if a promise is never resolved, it will leak memory.

Implementations

impl<TOk: Send + 'static, TErr: Send + 'static> Promise<TOk, TErr>

pub fn then<TNewOk: Send + 'static, TNewErr: Send + 'static, F: FnOnce(Result<TOk, TErr>) -> PromiseResult<TNewOk, TNewErr> + Send + 'static>( self, f: F, ) -> Promise<TNewOk, TNewErr>

Runs a function once the promise has resolved.

The callback is passed a Result, which is Ok if the promise was resolved or Err if rejected. It returns a PromiseResult, which can contain an immediate value to resolve to, another promise to run, or an error to reject the promise with.

pub fn new_resolved(v: TOk) -> Self

Creates a new promise, already resolved to a value

pub fn new_rejected(v: TErr) -> Self

Creates a new promise, already rejected

pub fn from_result(v: Result<TOk, TErr>) -> Self

Creates a new, already fulfilled promise from a Result.

Either resolved if the passed-in Result is Ok, or rejected if it was Err.

pub fn then_to_raw<F: FnOnce(Result<TOk, TErr>) -> Value + Send + 'static>( self, f: F, ) -> RawPromise

Runs a function once the promise has resolved, returning JS objects.

Use this to convert a typed promise into a raw promise, that can be passed to JS code.

pub fn map<TNewOk: Send + 'static, F: FnOnce(TOk) -> TNewOk + Send + 'static>( self, f: F, ) -> Promise<TNewOk, TErr>

Runs an operations on the resolve value if the promise resolves successfully.

Leaves rejected promises alone.

pub fn map_err<TNewErr: Send + 'static, F: FnOnce(TErr) -> TNewErr + Send + 'static>( self, f: F, ) -> Promise<TOk, TNewErr>

Runs an operation on the reject value if the promise is rejected.

Leaves resolved promises alone.

pub fn and_then<TNewOk: Send + 'static, F: FnOnce(TOk) -> PromiseResult<TNewOk, TErr> + Send + 'static>( self, f: F, ) -> Promise<TNewOk, TErr>

Runs an operation on the resolve value if the promise resolves successfully, possibly failing or returning another promise.

Leaves rejected promises alone, forwarding the error object.

pub fn all_settled<I: IntoIterator<Item = Self>>( promises: I, ) -> Promise<Vec<Result<TOk, TErr>>, Infallible>

Creates a promise that resolves when all of the passed-in promises have been resolved or rejected.

Resolves to a Vec of results for each of the promises. Never rejected.

This is currently the only promise combinator for typed Promises, due to memory leak issues with the other functions.

Trait Implementations

impl<TOk: Send, TErr: Send> Drop for Promise<TOk, TErr>

fn drop(&mut self)

Executes the destructor for this type.

impl<TOk: Send, TErr: Send> From<Promise<TOk, TErr>> for PromiseOk<TOk, TErr>

fn from(v: Promise<TOk, TErr>) -> Self

Converts to this type from the input type.