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:
```rust
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)
}
```
⬇️⬇️⬇️
```typescript
export function callbackJavascriptCallback(add_one: (arg0: number) => number): number;
```
⬇️⬇️⬇️
```javascript
callbackJavascriptCallback((arg0) => arg0 + 1);
// 101
```
If you define a tuple as the `Function` arguments, it will be converted to JavaScript arguments automatically.
```rust
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))
}
```
⬇️⬇️⬇️
```typescript
export function callbackJavascriptCallback(add: (arg0: number, arg1: number) => number): number;
```
⬇️⬇️⬇️
```javascript
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:
```rust
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:
```text
error[E0597]: `on_credential` does not live long enough
```
To fix this issue, you can create a reference to it:
```rust
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(...)
});
}
```
[](https://renovatebot.com)
This PR contains the following updates:
| Package | Type | Update | Change |
|---|---|---|---|
| [actions/cache](https://togithub.com/actions/cache) | action | major | `v3` -> `v4` |
---
### Release Notes
<details>
<summary>actions/cache (actions/cache)</summary>
### [`v4`](https://togithub.com/actions/cache/compare/v3...v4)
[Compare Source](https://togithub.com/actions/cache/compare/v3...v4)
</details>
---
### Configuration
📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).
🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.
♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
🔕 **Ignore**: Close this PR and you won't be reminded about this update again.
---
- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box
---
This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/napi-rs/napi-rs).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4xMzUuMCIsInVwZGF0ZWRJblZlciI6IjM3LjEzNS4wIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->
[](https://renovatebot.com)
This PR contains the following updates:
| Update | Change |
|---|---|
| lockFileMaintenance | All locks refreshed |
🔧 This Pull Request updates lock files to use the latest dependency versions.
---
### Configuration
📅 **Schedule**: Branch creation - "before 4am on the first day of the month" (UTC), Automerge - At any time (no schedule defined).
🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.
♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox.
👻 **Immortal**: This PR will be recreated if closed unmerged. Get [config help](https://togithub.com/renovatebot/renovate/discussions) if that's undesired.
---
- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box
---
This PR has been generated by [Mend Renovate](https://www.mend.io/free-developer-tools/renovate/). View repository job log [here](https://developer.mend.io/github/napi-rs/napi-rs).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzNy4xMDMuMSIsInVwZGF0ZWRJblZlciI6IjM3LjEwMy4xIiwidGFyZ2V0QnJhbmNoIjoibWFpbiJ9-->
