Struct JsPromise

pub struct JsPromise(/* private fields */);

The type of JavaScript Promise objects.

JsPromise instances may be constructed with Context::promise, which produces both a promise and a Deferred, which can be used to control the behavior of the promise. A Deferred struct is similar to the resolve and reject functions produced by JavaScript’s standard Promise constructor:

let deferred;
let promise = new Promise((resolve, reject) => {
  deferred = { resolve, reject };
});

Example

fn resolve_promise(mut cx: FunctionContext) -> JsResult<JsPromise> {
    let (deferred, promise) = cx.promise();
    let msg = cx.string("Hello, World!");

    deferred.resolve(&mut cx, msg);

    Ok(promise)
}

Example: Asynchronous task

This example uses the linkify crate in an asynchronous task, i.e. a Node worker pool thread, to find all the links in a text string.

Alternate implementations might use a custom Rust thread or thread pool to avoid blocking the worker pool; for more information, see the JsFuture example.

use linkify::{LinkFinder, LinkKind};
use easy_cast::Cast; // for safe numerical conversions

fn linkify(mut cx: FunctionContext) -> JsResult<JsPromise> {
    let text = cx.argument::<JsString>(0)?.value(&mut cx);

    let promise = cx
        .task(move || {
            let (indices, kinds): (Vec<_>, Vec<_>) = LinkFinder::new()
                // The spans() method fully partitions the text
                // into a sequence of contiguous spans, some of which
                // are plain text and some of which are links.
                .spans(&text)
                .map(|span| {
                    // The first span starts at 0 and the rest start
                    // at their preceding span's end index.
                    let end: u32 = span.end().cast();

                    let kind: u8 = match span.kind() {
                        Some(LinkKind::Url) => 1,
                        Some(LinkKind::Email) => 2,
                        _ => 0,
                    };

                    (end, kind)
                })
                .unzip();
            (indices, kinds)
        })
        .promise(|mut cx, (indices, kinds)| {
            let indices = JsUint32Array::from_slice(&mut cx, &indices)?;
            let kinds = JsUint8Array::from_slice(&mut cx, &kinds)?;
            Ok(cx.empty_object()
                .prop(&mut cx, "indices")
                .set(indices)?
                .prop("kinds")
                .set(kinds)?
                .this())
        });

    Ok(promise)
}

Implementations

impl JsPromise

pub fn resolve<'a, C: Context<'a>, T: Value>( cx: &mut C, value: Handle<'_, T>, ) -> Handle<'a, Self>

Creates a new Promise immediately resolved with the given value. If the value is a Promise or a then-able, it will be flattened.

JsPromise::resolve is useful to ensure a value that might not be a Promise or might not be a native promise is converted to a Promise before use.

pub fn reject<'a, C: Context<'a>, E: Value>( cx: &mut C, err: Handle<'_, E>, ) -> Handle<'a, Self>

Creates a nwe Promise immediately rejected with the given error.

pub fn to_future<'a, O, C, F>( &self, cx: &mut C, f: F, ) -> NeonResult<JsFuture<O>>

where O: Send + 'static, C: Context<'a>, F: FnOnce(Cx<'_>, Result<Handle<'_, JsValue>, Handle<'_, JsValue>>) -> NeonResult<O> + Send + 'static,

Available on crate features napi-5 and futures only.

Creates a Future that can be awaited to receive the result of a JavaScript Promise.

A callback must be provided that maps a Result representing the resolution or rejection of the Promise and returns a value as the Future output.

Note: Unlike Future, Promise are eagerly evaluated and so are JsFuture.

Trait Implementations

impl Debug for JsPromise

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

Formats the value using the given formatter.

impl Object for JsPromise

fn prop<'a, 'cx: 'a, K: PropertyKey>( &self, cx: &'a mut Cx<'cx>, key: K, ) -> PropOptions<'a, 'cx, Self, K>

Create a PropOptions for accessing a property.

fn method<'a, 'cx: 'a, K: PropertyKey>( &self, cx: &'a mut Cx<'cx>, key: K, ) -> NeonResult<BindOptions<'a, 'cx>>

Gets a property from the object as a method and binds this to the object.

fn get_opt<'a, V: Value, C: Context<'a>, K: PropertyKey>( &self, cx: &mut C, key: K, ) -> NeonResult<Option<Handle<'a, V>>>

👎Deprecating in a future version: use Object::prop() instead

fn get_value<'a, C: Context<'a>, K: PropertyKey>( &self, cx: &mut C, key: K, ) -> NeonResult<Handle<'a, JsValue>>

👎Deprecating in a future version: use Object::prop() instead

fn get<'a, V: Value, C: Context<'a>, K: PropertyKey>( &self, cx: &mut C, key: K, ) -> NeonResult<Handle<'a, V>>

👎Deprecating in a future version: use Object::prop() instead

fn get_own_property_names<'a, C: Context<'a>>( &self, cx: &mut C, ) -> JsResult<'a, JsArray>

Available on crate feature napi-6 only.

fn freeze<'a, C: Context<'a>>(&self, cx: &mut C) -> NeonResult<&Self>

fn seal<'a, C: Context<'a>>(&self, cx: &mut C) -> NeonResult<&Self>

fn set<'a, C: Context<'a>, K: PropertyKey, W: Value>( &self, cx: &mut C, key: K, val: Handle<'_, W>, ) -> NeonResult<bool>

👎Deprecating in a future version: use Object::prop() instead

fn root<'a, C: Context<'a>>(&self, cx: &mut C) -> Root<Self>

fn call_method_with<'a, C, K>( &self, cx: &mut C, method: K, ) -> NeonResult<CallOptions<'a>>

where C: Context<'a>, K: PropertyKey,

👎Deprecating in a future version: use Object::method() instead

impl Value for JsPromise

fn to_string<'cx, C: Context<'cx>>(&self, cx: &mut C) -> JsResult<'cx, JsString>

fn as_value<'cx, C: Context<'cx>>(&self, _: &mut C) -> Handle<'cx, JsValue>

fn to_raw(&self) -> Value

Available on crate feature sys only.

Get a raw reference to the wrapped Node-API value.

unsafe fn from_raw<'cx, C: Context<'cx>>( cx: &C, value: Value, ) -> Handle<'cx, Self>

Available on crate feature sys only.

Creates a value from a raw Node-API value.