210315.5 · src,doc: refactor to replace typedefs with usings

Function

The Napi::Function class provides a set of methods for creating a function object in native code that can later be called from JavaScript. The created function is not automatically visible from JavaScript. Instead it needs to be part of the add-on’s module exports or be returned by one of the module’s exported functions.

In addition the Napi::Function class also provides methods that can be used to call functions that were created in JavaScript and passed to the native add-on.

The Napi::Function class inherits its behavior from the Napi::Object class (for more info see: Napi::Object).

For callbacks that will be called with asynchronous events from a non-JavaScript thread, please refer to Napi::ThreadSafeFunction for more examples.

Example

#include <napi.h>

using namespace Napi;

Value Fn(const CallbackInfo& info) {
  Env env = info.Env();
  // ...
  return String::New(env, "Hello World");
}

Object Init(Env env, Object exports) {
  exports.Set(String::New(env, "fn"), Function::New<Fn>(env));
  return exports;
}

NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)

The above code can be used from JavaScript as follows:

const addon = require('./addon');
addon.fn();

With the Napi::Function class it is possible to call a JavaScript function object from a native add-on with two different methods: Call and MakeCallback. The API of these two methods is very similar, but they are used in different contexts. The MakeCallback method is used to call from native code back into JavaScript after returning from an asynchronous operation and in general in situations which don’t have an existing JavaScript function on the stack. The Call method is used when there is already a JavaScript function on the stack (for example when running a native method called from JavaScript).

Type definitions

Napi::Function::VoidCallback

This is the type describing a callback returning void that will be invoked from JavaScript.

using VoidCallback = void (*)(const Napi::CallbackInfo& info);

Napi::Function::Callback

This is the type describing a callback returning a value that will be invoked from JavaScript.

using Callback = Value (*)(const Napi::CallbackInfo& info);

Methods

Constructor

Creates a new empty instance of Napi::Function.

Napi::Function::Function();

Constructor

Creates a new instance of the Napi::Function object.

Napi::Function::Function(napi_env env, napi_value value);

[in] env: The napi_env environment in which to construct the Napi::Function object.
[in] value: The napi_value which is a handle for a JavaScript function.

Returns a non-empty Napi::Function instance.

New

Creates an instance of a Napi::Function object.

template <Napi::VoidCallback cb>
static Napi::Function New(napi_env env,
                          const char* utf8name = nullptr,
                          void* data = nullptr);

[template] cb: The native function to invoke when the JavaScript function is invoked.
[in] env: The napi_env environment in which to construct the Napi::Function object.
[in] utf8name: Null-terminated string to be used as the name of the function.
[in] data: User-provided data context. This will be passed back into the function when invoked later.

Returns an instance of a Napi::Function object.

New

Creates an instance of a Napi::Function object.

template <Napi::Callback cb>
static Napi::Function New(napi_env env,
                          const char* utf8name = nullptr,
                          void* data = nullptr);

[template] cb: The native function to invoke when the JavaScript function is invoked.
[in] env: The napi_env environment in which to construct the Napi::Function object.
[in] utf8name: Null-terminated string to be used as the name of the function.
[in] data: User-provided data context. This will be passed back into the function when invoked later.

Returns an instance of a Napi::Function object.

New

Creates an instance of a Napi::Function object.

template <Napi::VoidCallback cb>
static Napi::Function New(napi_env env,
                          const std::string& utf8name,
                          void* data = nullptr);

[template] cb: The native function to invoke when the JavaScript function is invoked.
[in] env: The napi_env environment in which to construct the Napi::Function object.
[in] utf8name: String to be used as the name of the function.
[in] data: User-provided data context. This will be passed back into the function when invoked later.

Returns an instance of a Napi::Function object.

New

Creates an instance of a Napi::Function object.

template <Napi::Callback cb>
static Napi::Function New(napi_env env,
                          const std::string& utf8name,
                          void* data = nullptr);

[template] cb: The native function to invoke when the JavaScript function is invoked.
[in] env: The napi_env environment in which to construct the Napi::Function object.
[in] utf8name: String to be used as the name of the function.
[in] data: User-provided data context. This will be passed back into the function when invoked later.

Returns an instance of a Napi::Function object.

New

Creates an instance of a Napi::Function object.

template <typename Callable>
static Napi::Function Napi::Function::New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr);

[in] env: The napi_env environment in which to construct the Napi::Function object.
[in] cb: Object that implements Callable.
[in] utf8name: Null-terminated string to be used as the name of the function.
[in] data: User-provided data context. This will be passed back into the function when invoked later.

Returns an instance of a Napi::Function object.

New

template <typename Callable>
static Napi::Function Napi::Function::New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr);

[in] env: The napi_env environment in which to construct the Napi::Function object.
[in] cb: Object that implements Callable.
[in] utf8name: String to be used as the name of the function.
[in] data: User-provided data context. This will be passed back into the function when invoked later.

Returns an instance of a Napi::Function object.

New

Creates a new JavaScript value from one that represents the constructor for the object.

Napi::Object Napi::Function::New(const std::initializer_list<napi_value>& args) const;

[in] args: Initializer list of JavaScript values as napi_value representing the arguments of the constructor function.

Returns a new JavaScript object.

New

Creates a new JavaScript value from one that represents the constructor for the object.

Napi::Object Napi::Function::New(const std::vector<napi_value>& args) const;

[in] args: Vector of JavaScript values as napi_value representing the arguments of the constructor function.

Returns a new JavaScript object.

New

Creates a new JavaScript value from one that represents the constructor for the object.

Napi::Object Napi::Function::New(size_t argc, const napi_value* args) const;

[in] argc: The number of the arguments passed to the constructor function.
[in] args: Array of JavaScript values as napi_value representing the arguments of the constructor function.

Returns a new JavaScript object.