Napi Async Local Extension

This crate extends napi-rs with the ability to run local futures.

Run local futures with:

use napi::*;
use napi_derive::napi;
use napi_async_local::SpawnLocalExt;

#[napi]
fn my_js_func(env: Env) -> napi::Result<JsObject> {
  env.spawn_local(|env| async {
    println!("Running async!");
    Ok(())
  })
}

This allows for the usage of Channels, Timers and other async utilities in Rust without blocking the main JavaScript thread while retaining the capability of interacting with the underlying JavaScript values.

Installation

Install the crate with:

cargo add napi_async_local

Usage

Use env.spawn_local() to spawn a non-blocking future on the local thread. Returns a Promise with the value returned in the async closure.

To ensure the availability of NapiValue types beyond the life of the parent function scope, ensure that NapiValue types that will be used in an async closure are wrapped in a JsRc which delegates GC to Rust.

Timers & Callbacks

use std::time::Duration;

use napi::*;
use napi_derive::napi;
use napi_async_local::JsRc;
use napi_async_local::JsRcExt;
use napi_async_local::SpawnLocalExt;
use async_std::task;

#[napi]
fn my_js_func(env: Env, callback: JsRc<JsFunction>) -> napi::Result<JsObject> {
  env.spawn_local(move |env| async move {
    task::sleep(Duration::from_millis(1000)).await;
    callback.inner(&env)?.call_without_args(None)?;
    Ok(())
  })
}

import napi from './napi.node'

napi.myJsFunc(() => console.log('Waited for 1 second'))

Channels and Threads

You may combine OS threads with async channels to coordinate off-thread workloads.

I recommend using async_std for async utilities as the custom Futures reactor is not compatible with Tokio utilities.

use std::thread;
use std::time::Duration;
 
use napi::*;
use napi_derive::napi;
use napi_async_local::JsRc;
use napi_async_local::JsRcExt;
use napi_async_local::SpawnLocalExt;
use async_std::channel;
 
#[napi]
fn my_js_func(env: Env, callback: JsRc<JsFunction>) -> napi::Result<JsObject> {
  let (tx, rx) = channel::unbounded();
 
  thread::spawn(move || {
    for i in 0..10 {
      tx.send_blocking(i).unwrap();
      thread::sleep(Duration::from_millis(1000));
    }
  });
 
  env.spawn_local(move |env| async move {
    while let Ok(value) = rx.recv().await {
      println!("Got number: {}", value);
      callback.inner(&env)?.call(None, &[env.create_int32(value)?])?;
    }
 
    Ok(())
  })
}

Development

To setup the development environment ensure you have installed just, then run:

npm install
just run example-a