Struct boa_engine::object::builtins::JsPromise

pub struct JsPromise { /* private fields */ }

An ECMAScript promise object.

Known as the concurrency primitive of ECMAScript, this is the main struct used to manipulate, chain and inspect Promises from Rust code.

Examples

let context = &mut Context::default();

context.register_global_property(
    js_string!("finally"),
    false,
    Attribute::all(),
);

let promise = JsPromise::new(
    |resolvers, context| {
        let result = js_string!("hello world!").into();
        resolvers.resolve.call(
            &JsValue::undefined(),
            &[result],
            context,
        )?;
        Ok(JsValue::undefined())
    },
    context,
);

let promise = promise
    .then(
        Some(
            NativeFunction::from_fn_ptr(|_, args, _| {
                Err(JsError::from_opaque(args.get_or_undefined(0).clone())
                    .into())
            })
            .to_js_function(context.realm()),
        ),
        None,
        context,
    )
    .catch(
        NativeFunction::from_fn_ptr(|_, args, _| {
            Ok(args.get_or_undefined(0).clone())
        })
        .to_js_function(context.realm()),
        context,
    )
    .finally(
        NativeFunction::from_fn_ptr(|_, _, context| {
            context.global_object().clone().set(
                js_string!("finally"),
                JsValue::from(true),
                true,
                context,
            )?;
            Ok(JsValue::undefined())
        })
        .to_js_function(context.realm()),
        context,
    );

context.run_jobs();

assert_eq!(
    promise.state(),
    PromiseState::Fulfilled(js_string!("hello world!").into())
);

assert_eq!(
    context
        .global_object()
        .clone()
        .get(js_string!("finally"), context)?,
    JsValue::from(true)
);

Implementations

impl JsPromise

pub fn new<F>(executor: F, context: &mut Context) -> Self

where F: FnOnce(&ResolvingFunctions, &mut Context) -> JsResult<JsValue>,

Creates a new promise object from an executor function.

It is equivalent to calling the Promise() constructor, which makes it share the same execution semantics as the constructor:

• The executor function executor is called synchronously just after the promise is created.
• The executor return value is ignored.
• Any error thrown within the execution of executor will call the reject function of the newly created promise, unless either resolve or reject were already called beforehand.

executor receives as an argument the ResolvingFunctions needed to settle the promise, which can be done by either calling the resolve function or the reject function.

Examples

let context = &mut Context::default();

let promise = JsPromise::new(
    |resolvers, context| {
        let result = js_string!("hello world").into();
        resolvers.resolve.call(
            &JsValue::undefined(),
            &[result],
            context,
        )?;
        Ok(JsValue::undefined())
    },
    context,
);

context.run_jobs();

assert_eq!(
    promise.state(),
    PromiseState::Fulfilled(js_string!("hello world").into())
);

pub fn new_pending(context: &mut Context) -> (Self, ResolvingFunctions)

Creates a new pending promise and returns it and its associated ResolvingFunctions.

This can be useful when you want to manually settle a promise from Rust code, instead of running an executor function that automatically settles the promise on creation (see JsPromise::new).

Examples

let context = &mut Context::default();

let (promise, resolvers) = JsPromise::new_pending(context);

assert_eq!(promise.state(), PromiseState::Pending);

resolvers
    .reject
    .call(&JsValue::undefined(), &[5.into()], context)?;

assert_eq!(promise.state(), PromiseState::Rejected(5.into()));

pub fn from_object(object: JsObject) -> JsResult<Self>

Wraps an existing object with the JsPromise interface, returning Err if the object is not a valid promise.

Examples

let context = &mut Context::default();

let promise = context.eval(Source::from_bytes(
    "new Promise((resolve, reject) => resolve())",
))?;
let promise = promise.as_object().cloned().unwrap();

let promise = JsPromise::from_object(promise)?;

assert_eq!(
    promise.state(),
    PromiseState::Fulfilled(JsValue::undefined())
);

assert!(JsPromise::from_object(JsObject::with_null_proto()).is_err());

pub fn from_future<Fut>(future: Fut, context: &mut Context) -> Self

where Fut: IntoFuture<Output = JsResult<JsValue>> + 'static,

Creates a new JsPromise from a Future-like.

If you want to convert a Rust async function into an ECMAScript async function, see NativeFunction::from_async_fn.

Examples

async fn f() -> JsResult<JsValue> {
    Ok(JsValue::null())
}
let context = &mut Context::default();

let promise = JsPromise::from_future(f(), context);

context.run_jobs();

assert_eq!(promise.state(), PromiseState::Fulfilled(JsValue::null()));

pub fn resolve<V: Into<JsValue>>(value: V, context: &mut Context) -> Self

Resolves a JsValue into a JsPromise.

Equivalent to the Promise.resolve() static method.

This function is mainly used to wrap a plain JsValue into a fulfilled promise, but it can also flatten nested layers of thenables, which essentially converts them into native promises.

Examples

let context = &mut Context::default();

let promise = JsPromise::resolve(js_string!("resolved!"), context);

assert_eq!(
    promise.state(),
    PromiseState::Fulfilled(js_string!("resolved!").into())
);

pub fn reject<E: Into<JsError>>(error: E, context: &mut Context) -> Self

Creates a JsPromise that is rejected with the reason error.

Equivalent to the Promise.reject static method.

JsPromise::reject is pretty similar to JsPromise::resolve, with the difference that it always wraps error into a rejected promise, even if error is a promise or a thenable.

Examples

let context = &mut Context::default();

let promise = JsPromise::reject(
    JsError::from_opaque(js_string!("oops!").into()),
    context,
);

assert_eq!(
    promise.state(),
    PromiseState::Rejected(js_string!("oops!").into())
);

pub fn state(&self) -> PromiseState

Gets the current state of the promise.

Examples

let context = &mut Context::default();

let promise = JsPromise::new_pending(context).0;

assert_eq!(promise.state(), PromiseState::Pending);

pub fn then( &self, on_fulfilled: Option<JsFunction>, on_rejected: Option<JsFunction>, context: &mut Context ) -> Self

Schedules callback functions to run when the promise settles.

Equivalent to the Promise.prototype.then method.

The return value is a promise that is always pending on return, regardless of the current state of the original promise. Two handlers can be provided as callbacks to be executed when the original promise settles:

• If the original promise is fulfilled, on_fulfilled is called with the fulfillment value of the original promise.
• If the original promise is rejected, on_rejected is called with the rejection reason of the original promise.

The return value of the handlers can be used to mutate the state of the created promise. If the callback:

• returns a value: the created promise gets fulfilled with the returned value.
• doesn’t return: the created promise gets fulfilled with undefined.
• throws: the created promise gets rejected with the thrown error as its value.
• returns a fulfilled promise: the created promise gets fulfilled with that promise’s value as its value.
• returns a rejected promise: the created promise gets rejected with that promise’s value as its value.
• returns another pending promise: the created promise remains pending but becomes settled with that promise’s value as its value immediately after that promise becomes settled.

Examples

let context = &mut Context::default();

let promise = JsPromise::new(
    |resolvers, context| {
        resolvers.resolve.call(
            &JsValue::undefined(),
            &[255.255.into()],
            context,
        )?;
        Ok(JsValue::undefined())
    },
    context,
)
.then(
    Some(
        NativeFunction::from_fn_ptr(|_, args, context| {
            args.get_or_undefined(0)
                .to_string(context)
                .map(JsValue::from)
        })
        .to_js_function(context.realm()),
    ),
    None,
    context,
);

context.run_jobs();

assert_eq!(
    promise.state(),
    PromiseState::Fulfilled(js_string!("255.255").into())
);

pub fn catch(&self, on_rejected: JsFunction, context: &mut Context) -> Self

Schedules a callback to run when the promise is rejected.

Equivalent to the Promise.prototype.catch method.

This is essentially a shortcut for calling promise.then(None, Some(function)), which only handles the error case and leaves the fulfilled case untouched.

Examples

let context = &mut Context::default();

let promise = JsPromise::new(
    |resolvers, context| {
        let error = JsNativeError::typ().with_message("thrown");
        let error = error.to_opaque(context);
        resolvers.reject.call(
            &JsValue::undefined(),
            &[error.into()],
            context,
        )?;
        Ok(JsValue::undefined())
    },
    context,
)
.catch(
    NativeFunction::from_fn_ptr(|_, args, context| {
        args.get_or_undefined(0)
            .to_string(context)
            .map(JsValue::from)
    })
    .to_js_function(context.realm()),
    context,
);

context.run_jobs();

assert_eq!(
    promise.state(),
    PromiseState::Fulfilled(js_string!("TypeError: thrown").into())
);

pub fn finally(&self, on_finally: JsFunction, context: &mut Context) -> Self

Schedules a callback to run when the promise is rejected.

Equivalent to the Promise.prototype.finally() method.

While this could be seen as a shortcut for calling promise.then(Some(function), Some(function)), it has slightly different semantics than then:

• on_finally doesn’t receive any argument, unlike on_fulfilled and on_rejected.
• finally() is transparent; a call like Promise.resolve("first").finally(() => "second") returns a promise fulfilled with the value "first", which would return "second" if finally was a shortcut of then.

Examples

let context = &mut Context::default();

context.register_global_property(
    js_string!("finally"),
    false,
    Attribute::all(),
)?;

let promise = JsPromise::new(
    |resolvers, context| {
        let error = JsNativeError::typ().with_message("thrown");
        let error = error.to_opaque(context);
        resolvers.reject.call(
            &JsValue::undefined(),
            &[error.into()],
            context,
        )?;
        Ok(JsValue::undefined())
    },
    context,
)
.finally(
    NativeFunction::from_fn_ptr(|_, _, context| {
        context.global_object().clone().set(
            js_string!("finally"),
            JsValue::from(true),
            true,
            context,
        )?;
        Ok(JsValue::undefined())
    })
    .to_js_function(context.realm()),
    context,
);

context.run_jobs();

assert_eq!(
    context
        .global_object()
        .clone()
        .get(js_string!("finally"), context)?,
    JsValue::from(true)
);

pub fn all<I>(promises: I, context: &mut Context) -> Self

where I: IntoIterator<Item = Self>,

Waits for a list of promises to settle with fulfilled values, rejecting the aggregate promise when any of the inner promises is rejected.

Equivalent to the Promise.all static method.

Examples

let context = &mut Context::default();

let promise1 = JsPromise::all(
    [
        JsPromise::resolve(0, context),
        JsPromise::resolve(2, context),
        JsPromise::resolve(4, context),
    ],
    context,
);

let promise2 = JsPromise::all(
    [
        JsPromise::resolve(1, context),
        JsPromise::reject(JsNativeError::typ(), context),
        JsPromise::resolve(3, context),
    ],
    context,
);

context.run_jobs();

let array = promise1
    .state()
    .as_fulfilled()
    .and_then(JsValue::as_object)
    .unwrap()
    .clone();
let array = JsArray::from_object(array)?;
assert_eq!(array.at(0, context)?, 0.into());
assert_eq!(array.at(1, context)?, 2.into());
assert_eq!(array.at(2, context)?, 4.into());

let error = promise2.state().as_rejected().unwrap().clone();
assert_eq!(error.to_string(context)?, js_string!("TypeError"));

pub fn all_settled<I>(promises: I, context: &mut Context) -> Self

where I: IntoIterator<Item = Self>,

Waits for a list of promises to settle, fulfilling with an array of the outcomes of every promise.

Equivalent to the Promise.allSettled static method.

Examples

let context = &mut Context::default();

let promise = JsPromise::all_settled(
    [
        JsPromise::resolve(1, context),
        JsPromise::reject(JsNativeError::typ(), context),
        JsPromise::resolve(3, context),
    ],
    context,
);

context.run_jobs();

let array = promise
    .state()
    .as_fulfilled()
    .and_then(JsValue::as_object)
    .unwrap()
    .clone();
let array = JsArray::from_object(array)?;

let a = array.at(0, context)?.as_object().unwrap().clone();
assert_eq!(
    a.get(js_string!("status"), context)?,
    js_string!("fulfilled").into()
);
assert_eq!(a.get(js_string!("value"), context)?, 1.into());

let b = array.at(1, context)?.as_object().unwrap().clone();
assert_eq!(
    b.get(js_string!("status"), context)?,
    js_string!("rejected").into()
);
assert_eq!(
    b.get(js_string!("reason"), context)?.to_string(context)?,
    js_string!("TypeError")
);

let c = array.at(2, context)?.as_object().unwrap().clone();
assert_eq!(
    c.get(js_string!("status"), context)?,
    js_string!("fulfilled").into()
);
assert_eq!(c.get(js_string!("value"), context)?, 3.into());

pub fn any<I>(promises: I, context: &mut Context) -> Self

where I: IntoIterator<Item = Self>,

Returns the first promise that fulfills from a list of promises.

Equivalent to the Promise.any static method.

If after settling all promises in promises there isn’t a fulfilled promise, the returned promise will be rejected with an AggregatorError containing the rejection values of every promise; this includes the case where promises is an empty iterator.

Examples

let context = &mut Context::default();

let promise = JsPromise::any(
    [
        JsPromise::reject(JsNativeError::syntax(), context),
        JsPromise::reject(JsNativeError::typ(), context),
        JsPromise::resolve(js_string!("fulfilled"), context),
        JsPromise::reject(JsNativeError::range(), context),
    ],
    context,
);

context.run_jobs();

assert_eq!(
    promise.state(),
    PromiseState::Fulfilled(js_string!("fulfilled").into())
);

pub fn race<I>(promises: I, context: &mut Context) -> Self

where I: IntoIterator<Item = Self>,

Returns the first promise that settles from a list of promises.

Equivalent to the Promise.race static method.

If the provided iterator is empty, the returned promise will remain on the pending state forever.

Examples

let context = &mut Context::default();

let (a, resolvers_a) = JsPromise::new_pending(context);
let (b, resolvers_b) = JsPromise::new_pending(context);
let (c, resolvers_c) = JsPromise::new_pending(context);

let promise = JsPromise::race([a, b, c], context);

resolvers_b
    .reject
    .call(&JsValue::undefined(), &[], context)?;
resolvers_a
    .resolve
    .call(&JsValue::undefined(), &[5.into()], context)?;
resolvers_c.reject.call(
    &JsValue::undefined(),
    &[js_string!("c error").into()],
    context,
)?;

context.run_jobs();

assert_eq!(
    promise.state(),
    PromiseState::Rejected(JsValue::undefined())
);

pub fn into_js_future(self, context: &mut Context) -> JsFuture

Creates a JsFuture from this JsPromise.

The returned JsFuture implements Future, which means it can be awaited within Rust’s async contexts (async functions and async blocks).

Examples

let context = &mut Context::default();

let (promise, resolvers) = JsPromise::new_pending(context);
let promise_future = promise.into_js_future(context);

let future1 = async move { promise_future.await };

let future2 = async move {
    resolvers
        .resolve
        .call(&JsValue::undefined(), &[10.into()], context)?;
    context.run_jobs();
    Ok::<(), JsError>(())
};

let (result1, result2) = future::block_on(future::zip(future1, future2));

assert_eq!(result1, Ok(JsValue::from(10)));
assert_eq!(result2, Ok(()));

Methods from Deref<Target = JsObject>

pub fn downcast_ref<T: NativeObject>(&self) -> Option<Ref<'_, T>>

Downcasts a reference to the object, if the object is of type T.

Panics

Panics if the object is currently mutably borrowed.

pub fn downcast_mut<T: NativeObject>( &self ) -> Option<RefMut<'_, ErasedObject, T>>

Downcasts a mutable reference to the object, if the object is type native object type T.

Panics

Panics if the object is currently borrowed.

pub fn is<T: NativeObject>(&self) -> bool

Checks if this object is an instance of a certain NativeObject.

Panics

Panics if the object is currently mutably borrowed.

pub fn is_ordinary(&self) -> bool

Checks if it’s an ordinary object.

Panics

Panics if the object is currently mutably borrowed.

pub fn is_array(&self) -> bool

Checks if it’s an Array object.

pub fn to_property_descriptor( &self, context: &mut Context ) -> JsResult<PropertyDescriptor>

The abstract operation ToPropertyDescriptor.

More information:

• ECMAScript reference

pub fn copy_data_properties<K>( &self, source: &JsValue, excluded_keys: Vec<K>, context: &mut Context ) -> JsResult<()>

where K: Into<PropertyKey>,

7.3.25 CopyDataProperties ( target, source, excludedItems )

More information:

• ECMAScript

pub fn borrow(&self) -> Ref<'_, Object<T>>

Immutably borrows the Object.

The borrow lasts until the returned Ref exits scope. Multiple immutable borrows can be taken out at the same time.

Panics

Panics if the object is currently mutably borrowed.

pub fn borrow_mut(&self) -> RefMut<'_, Object<T>, Object<T>>

Mutably borrows the Object.

The borrow lasts until the returned RefMut exits scope. The object cannot be borrowed while this borrow is active.

Panics

Panics if the object is currently borrowed.

pub fn try_borrow(&self) -> StdResult<Ref<'_, Object<T>>, BorrowError>

Immutably borrows the Object, returning an error if the value is currently mutably borrowed.

The borrow lasts until the returned GcCellRef exits scope. Multiple immutable borrows can be taken out at the same time.

This is the non-panicking variant of borrow.

pub fn try_borrow_mut( &self ) -> StdResult<RefMut<'_, Object<T>, Object<T>>, BorrowMutError>

Mutably borrows the object, returning an error if the value is currently borrowed.

The borrow lasts until the returned GcCellRefMut exits scope. The object be borrowed while this borrow is active.

This is the non-panicking variant of borrow_mut.

pub fn prototype(&self) -> JsPrototype

Get the prototype of the object.

Panics

Panics if the object is currently mutably borrowed.

pub fn set_prototype(&self, prototype: JsPrototype) -> bool

Set the prototype of the object.

Panics

Panics if the object is currently mutably borrowed

pub fn insert_property<K, P>(&self, key: K, property: P) -> bool

where K: Into<PropertyKey>, P: Into<PropertyDescriptor>,

Inserts a field in the object properties without checking if it’s writable.

If a field was already in the object with the same name, than true is returned with that field, otherwise false is returned.

pub fn is_callable(&self) -> bool

It determines if Object is a callable function with a [[Call]] internal method.

More information:

• ECMAScript reference

pub fn is_constructor(&self) -> bool

It determines if Object is a function object with a [[Construct]] internal method.

More information:

• ECMAScript reference

pub fn is_extensible(&self, context: &mut Context) -> JsResult<bool>

Check if object is extensible.

More information:

• ECMAScript reference

pub fn get<K>(&self, key: K, context: &mut Context) -> JsResult<JsValue>

where K: Into<PropertyKey>,

Get property from object or throw.

More information:

• ECMAScript reference

pub fn set<K, V>( &self, key: K, value: V, throw: bool, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>, V: Into<JsValue>,

set property of object or throw if bool flag is passed.

More information:

• ECMAScript reference

pub fn create_data_property<K, V>( &self, key: K, value: V, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>, V: Into<JsValue>,

Create data property

More information:

• ECMAScript reference

pub fn create_data_property_or_throw<K, V>( &self, key: K, value: V, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>, V: Into<JsValue>,

Create data property or throw

More information:

• ECMAScript reference

pub fn define_property_or_throw<K, P>( &self, key: K, desc: P, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>, P: Into<PropertyDescriptor>,

Define property or throw.

More information:

• ECMAScript reference

pub fn delete_property_or_throw<K>( &self, key: K, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>,

Defines the property or throws a TypeError if the operation fails.

More information:

• ECMAScript reference

pub fn has_property<K>(&self, key: K, context: &mut Context) -> JsResult<bool>

where K: Into<PropertyKey>,

Check if object has property.

More information:

• ECMAScript reference

pub fn has_own_property<K>( &self, key: K, context: &mut Context ) -> JsResult<bool>

where K: Into<PropertyKey>,

Check if object has an own property.

More information:

• ECMAScript reference

pub fn call( &self, this: &JsValue, args: &[JsValue], context: &mut Context ) -> JsResult<JsValue>

Call ( F, V [ , argumentsList ] )

Panics

Panics if the object is currently mutably borrowed.

More information:

• ECMAScript reference

pub fn construct( &self, args: &[JsValue], new_target: Option<&Self>, context: &mut Context ) -> JsResult<Self>

Construct ( F [ , argumentsList [ , newTarget ] ] )

Construct an instance of this object with the specified arguments.

Panics

Panics if the object is currently mutably borrowed.

More information:

• ECMAScript reference

pub fn set_integrity_level( &self, level: IntegrityLevel, context: &mut Context ) -> JsResult<bool>

Make the object sealed or frozen.

More information:

• ECMAScript reference

pub fn test_integrity_level( &self, level: IntegrityLevel, context: &mut Context ) -> JsResult<bool>

Check if the object is sealed or frozen.

More information:

• ECMAScript reference

Trait Implementations

impl Clone for JsPromise

fn clone(&self) -> JsPromise

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for JsPromise

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

Formats the value using the given formatter.

impl Deref for JsPromise

type Target = JsObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for JsPromise

fn drop(&mut self)

Executes the destructor for this type.

impl Finalize for JsPromise

fn finalize(&self)

Cleanup logic for a type.

impl From<JsPromise> for JsObject

fn from(o: JsPromise) -> Self

Converts to this type from the input type.

impl From<JsPromise> for JsValue

fn from(o: JsPromise) -> Self

Converts to this type from the input type.

impl Trace for JsPromise

unsafe fn trace(&self, tracer: &mut Tracer)

Marks all contained Gcs.

unsafe fn trace_non_roots(&self)

Trace handles located in GC heap, and mark them as non root.

fn run_finalizer(&self)

Runs Finalize::finalize on this object and all contained subobjects.

impl TryFromJs for JsPromise

fn try_from_js(value: &JsValue, _context: &mut Context) -> JsResult<Self>

This function tries to convert a JavaScript value into Self.