Struct neon::types::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)?;
            let result = cx.empty_object();
            result.set(&mut cx, "indices", indices)?;
            result.set(&mut cx, "kinds", kinds)?;
            Ok(result)
        });

    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(TaskContext<'_>, 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 get_opt<'a, V: Value, C: Context<'a>, K: PropertyKey>( &self, cx: &mut C, key: K ) -> NeonResult<Option<Handle<'a, V>>>

Gets a property from a JavaScript object that may be undefined and attempts to downcast the value if it existed.

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

Gets a property from a JavaScript object as a JsValue.

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

Gets a property from a JavaScript object and attempts to downcast as a specific type. Equivalent to calling obj.get_value(&mut cx)?.downcast_or_throw(&mut cx).

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>

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,

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.