feat(napi): new Function/FunctionRef API

[Brooooooklyn]

This is the experimental feature that provides a all new design Function API in NAPI-RS.
The main motivation to design a new Function instead of improving the old JsFunction is there are some fundamental problems in the old JsFunction API.

1. The old JsFunction doesn't contains a lifetime, which means you can send it to a outlive scope and call it later, which would cause a napi_invalid_arg error in the underlying napi_call_function API. This design issue also happens in the JsObject/JsBuffer and all other non-primitive types APIs.
2. It's not possible to generate correct TypeScript type definitions for the old JsFunction API.
3. The arguments of the old JsFunction API must be the same type, which is makes it really unfriendly to use.

Expect that, we also have a high level and modern Function exists in the NAPI-RS which is the Generic type style Fn(Args) -> Return.
This API is pretty nice to use, and more importantly, it's sound.
But there are some limitations to use it, like create a reference to it to outlive the scope of the JavaScript function under the hood. And you can't use it create a ThreadsafeFunction.
So there is the new design Function API, there are some core features:

1. It's a generic typed API, which means you can get more accurate Rust type information and generate correct TypeScript type definitions.
2. It's sound, which means you can't send it to a outlive scope and call it later, if you want do that, you must create a reference to it or create a ThreadsafeFunction.
3. It's friendly to use, you can use different types of arguments and return types, and it can covert the Rust tuple type to JavaScript arguments automatically.
   Here is some examples to show how to use it:

use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi]
pub fn callback_javascript_callback(add_one: Function<u32, u32>) -> Result<u32> {
  add_one.call(100)
}

⬇️⬇️⬇️

export function callbackJavascriptCallback(add_one: (arg0: number) => number): number;

⬇️⬇️⬇️

callbackJavascriptCallback((arg0) => arg0 + 1);
// 101

If you define a tuple as the Function arguments, it will be converted to JavaScript arguments automatically.

use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi]
pub fn callback_javascript_callback(add: Function<(u32, u32), u32>) -> Result<u32> {
  add.call((100, 200))
}

⬇️⬇️⬇️

export function callbackJavascriptCallback(add: (arg0: number, arg1: number) => number): number;

⬇️⬇️⬇️

callbackJavascriptCallback((arg0, arg1) => arg0 + arg1);
// 300

If you are trying to send it into a outlive scope, you will get a compile error.
For example, if you are trying to send a callback to git2-rs RemoteCallbacks::credentials API:

use napi::bindgen_prelude::*;
use napi_derive::napi;

#[napi]
pub fn build_credential(on_credential: Function<(String, Option<String>, CredentialType), ClassInstance<Cred>>) -> Result<()> {
 let mut callbacks = git2::RemoteCallbacks::new();
 callbacks.credentials(move |url, username_from_url, allowed_types| {
   on_credential.call((url.to_string(), username_from_url.map(|s| s.to_string()), allowed_types.into()))
    .map(...)
    .map_error(...)
 });
}

You will get a compile error:

error[E0597]: `on_credential` does not live long enough

To fix this issue, you can create a reference to it:

use napi::bindgen_prelude::*;
use napi_derive::napi;
#[napi]
pub fn build_credential(env: Env. on_credential: Function<(String, Option<String>, CredentialType), ClassInstance<Cred>>) -> Result<()> {
  let mut callbacks = git2::RemoteCallbacks::new();
  let on_credential_ref = on_credential.create_ref()?;
  callbacks.credentials(move |url, username_from_url, allowed_types| {
    let on_credential = on_credential_ref.borrow_back(&env)?;
    on_credential.call((url.to_string(), username_from_url.map(|s| s.to_string()), allowed_types.into()))
    .map(...)
    .map_error(...)
  });
}

[Brooooooklyn]

Current dependencies on/for this PR:

• main
  • PR fix(napi): callback in execute_tokio_future does not need to be Send #1917
    • PR feat(napi): new Function/FunctionRef API #1913 👈
      • PR chore(napi): delete unwrap_from_ref API because it was never work #1915
        • PR chore(napi): remove napi_val on Ref because it is unused #1916

This stack of pull requests is managed by Graphite.

[Brooooooklyn]

Merge activity

• Jan 25, 9:28 PM: Graphite rebased this pull request as part of a merge.
• Jan 25, 9:58 PM: @Brooooooklyn merged this pull request with Graphite.