1# Function
2
3The `Napi::Function` class provides a set of methods for creating a function object in
4native code that can later be called from JavaScript. The created function is not
5automatically visible from JavaScript. Instead it needs to be part of the add-on's
6module exports or be returned by one of the module's exported functions.
7
8In addition the `Napi::Function` class also provides methods that can be used to call
9functions that were created in JavaScript and passed to the native add-on.
10
11The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info
12see: [`Napi::Object`](object.md)).
13
14> For callbacks that will be called with asynchronous events from a
15> non-JavaScript thread, please refer to [`Napi::ThreadSafeFunction`][] for more
16> examples.
17
18## Example
19
20```cpp
21#include <napi.h>
22
23using namespace Napi;
24
25Value Fn(const CallbackInfo& info) {
26  Env env = info.Env();
27  // ...
28  return String::New(env, "Hello World");
29}
30
31Object Init(Env env, Object exports) {
32  exports.Set(String::New(env, "fn"), Function::New<Fn>(env));
33  return exports;
34}
35
36NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
37```
38
39The above code can be used from JavaScript as follows:
40
41```js
42const addon = require('./addon');
43addon.fn();
44```
45
46With the `Napi::Function` class it is possible to call a JavaScript function object
47from a native add-on with two different methods: `Call` and `MakeCallback`.
48The API of these two methods is very similar, but they are used in different
49contexts. The `MakeCallback` method is used to call from native code back into
50JavaScript after returning from an [asynchronous operation](async_operations.md)
51and in general in situations which don't have an existing JavaScript function on
52the stack. The `Call` method is used when there is already a JavaScript function
53on the stack (for example when running a native method called from JavaScript).
54
55## Type definitions
56
57### Napi::Function::VoidCallback
58
59This is the type describing a callback returning `void` that will be invoked
60from JavaScript.
61
62```cpp
63using VoidCallback = void (*)(const Napi::CallbackInfo& info);
64```
65
66### Napi::Function::Callback
67
68This is the type describing a callback returning a value that will be invoked
69from JavaScript.
70
71
72```cpp
73using Callback = Value (*)(const Napi::CallbackInfo& info);
74```
75
76## Methods
77
78### Constructor
79
80Creates a new empty instance of `Napi::Function`.
81
82```cpp
83Napi::Function::Function();
84```
85
86### Constructor
87
88Creates a new instance of the `Napi::Function` object.
89
90```cpp
91Napi::Function::Function(napi_env env, napi_value value);
92```
93
94- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
95- `[in] value`: The `napi_value` which is a handle for a JavaScript function.
96
97Returns a non-empty `Napi::Function` instance.
98
99### New
100
101Creates an instance of a `Napi::Function` object.
102
103```cpp
104template <Napi::VoidCallback cb>
105static Napi::Function New(napi_env env,
106                          const char* utf8name = nullptr,
107                          void* data = nullptr);
108```
109
110- `[template] cb`: The native function to invoke when the JavaScript function is
111invoked.
112- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
113- `[in] utf8name`: Null-terminated string to be used as the name of the function.
114- `[in] data`: User-provided data context. This will be passed back into the
115function when invoked later.
116
117Returns an instance of a `Napi::Function` object.
118
119### New
120
121Creates an instance of a `Napi::Function` object.
122
123```cpp
124template <Napi::Callback cb>
125static Napi::Function New(napi_env env,
126                          const char* utf8name = nullptr,
127                          void* data = nullptr);
128```
129
130- `[template] cb`: The native function to invoke when the JavaScript function is
131invoked.
132- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
133- `[in] utf8name`: Null-terminated string to be used as the name of the function.
134- `[in] data`: User-provided data context. This will be passed back into the
135function when invoked later.
136
137Returns an instance of a `Napi::Function` object.
138
139### New
140
141Creates an instance of a `Napi::Function` object.
142
143```cpp
144template <Napi::VoidCallback cb>
145static Napi::Function New(napi_env env,
146                          const std::string& utf8name,
147                          void* data = nullptr);
148```
149
150- `[template] cb`: The native function to invoke when the JavaScript function is
151invoked.
152- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
153- `[in] utf8name`: String to be used as the name of the function.
154- `[in] data`: User-provided data context. This will be passed back into the
155function when invoked later.
156
157Returns an instance of a `Napi::Function` object.
158
159### New
160
161Creates an instance of a `Napi::Function` object.
162
163```cpp
164template <Napi::Callback cb>
165static Napi::Function New(napi_env env,
166                          const std::string& utf8name,
167                          void* data = nullptr);
168```
169
170- `[template] cb`: The native function to invoke when the JavaScript function is
171invoked.
172- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
173- `[in] utf8name`: String to be used as the name of the function.
174- `[in] data`: User-provided data context. This will be passed back into the
175function when invoked later.
176
177Returns an instance of a `Napi::Function` object.
178
179### New
180
181Creates an instance of a `Napi::Function` object.
182
183```cpp
184template <typename Callable>
185static Napi::Function Napi::Function::New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr);
186```
187
188- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
189- `[in] cb`: Object that implements `Callable`.
190- `[in] utf8name`: Null-terminated string to be used as the name of the function.
191- `[in] data`: User-provided data context. This will be passed back into the
192function when invoked later.
193
194Returns an instance of a `Napi::Function` object.
195
196### New
197
198```cpp
199template <typename Callable>
200static Napi::Function Napi::Function::New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr);
201```
202
203- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
204- `[in] cb`: Object that implements `Callable`.
205- `[in] utf8name`: String to be used as the name of the function.
206- `[in] data`: User-provided data context. This will be passed back into the
207function when invoked later.
208
209Returns an instance of a `Napi::Function` object.
210
211### New
212
213Creates a new JavaScript value from one that represents the constructor for the
214object.
215
216```cpp
217Napi::Object Napi::Function::New(const std::initializer_list<napi_value>& args) const;
218```
219
220- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
221the arguments of the constructor function.
222
223Returns a new JavaScript object.
224
225### New
226
227Creates a new JavaScript value from one that represents the constructor for the
228object.
229
230```cpp
231Napi::Object Napi::Function::New(const std::vector<napi_value>& args) const;
232```
233
234- `[in] args`: Vector of JavaScript values as `napi_value` representing the
235arguments of the constructor function.
236
237Returns a new JavaScript object.
238
239### New
240
241Creates a new JavaScript value from one that represents the constructor for the
242object.
243
244```cpp
245Napi::Object Napi::Function::New(size_t argc, const napi_value* args) const;
246```
247
248- `[in] argc`: The number of the arguments passed to the constructor function.
249- `[in] args`: Array of JavaScript values as `napi_value` representing the
250arguments of the constructor function.
251
252Returns a new JavaScript object.
253
254### Call
255
256Calls a Javascript function from a native add-on.
257
258```cpp
259Napi::Value Napi::Function::Call(const std::initializer_list<napi_value>& args) const;
260```
261
262- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
263the arguments of the function.
264
265Returns a `Napi::Value` representing the JavaScript value returned by the function.
266
267### Call
268
269Calls a JavaScript function from a native add-on.
270
271```cpp
272Napi::Value Napi::Function::Call(const std::vector<napi_value>& args) const;
273```
274
275- `[in] args`: Vector of JavaScript values as `napi_value` representing the
276arguments of the function.
277
278Returns a `Napi::Value` representing the JavaScript value returned by the function.
279
280### Call
281
282Calls a Javascript function from a native add-on.
283
284```cpp
285Napi::Value Napi::Function::Call(size_t argc, const napi_value* args) const;
286```
287
288- `[in] argc`: The number of the arguments passed to the function.
289- `[in] args`: Array of JavaScript values as `napi_value` representing the
290arguments of the function.
291
292Returns a `Napi::Value` representing the JavaScript value returned by the function.
293
294### Call
295
296Calls a Javascript function from a native add-on.
297
298```cpp
299Napi::Value Napi::Function::Call(napi_value recv, const std::initializer_list<napi_value>& args) const;
300```
301
302- `[in] recv`: The `this` object passed to the called function.
303- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
304the arguments of the function.
305
306Returns a `Napi::Value` representing the JavaScript value returned by the function.
307
308### Call
309
310Calls a Javascript function from a native add-on.
311
312```cpp
313Napi::Value Napi::Function::Call(napi_value recv, const std::vector<napi_value>& args) const;
314```
315
316- `[in] recv`: The `this` object passed to the called function.
317- `[in] args`: Vector of JavaScript values as `napi_value` representing the
318arguments of the function.
319
320Returns a `Napi::Value` representing the JavaScript value returned by the function.
321
322### Call
323
324Calls a Javascript function from a native add-on.
325
326```cpp
327Napi::Value Napi::Function::Call(napi_value recv, size_t argc, const napi_value* args) const;
328```
329
330- `[in] recv`: The `this` object passed to the called function.
331- `[in] argc`: The number of the arguments passed to the function.
332- `[in] args`: Array of JavaScript values as `napi_value` representing the
333arguments of the function.
334
335Returns a `Napi::Value` representing the JavaScript value returned by the function.
336
337### MakeCallback
338
339Calls a Javascript function from a native add-on after an asynchronous operation.
340
341```cpp
342Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::initializer_list<napi_value>& args, napi_async_context context = nullptr) const;
343```
344
345- `[in] recv`: The `this` object passed to the called function.
346- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
347the arguments of the function.
348- `[in] context`: Context for the async operation that is invoking the callback.
349This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
350However `nullptr` is also allowed, which indicates the current async context
351(if any) is to be used for the callback.
352
353Returns a `Napi::Value` representing the JavaScript value returned by the function.
354
355### MakeCallback
356
357Calls a Javascript function from a native add-on after an asynchronous operation.
358
359```cpp
360Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::vector<napi_value>& args, napi_async_context context = nullptr) const;
361```
362
363- `[in] recv`: The `this` object passed to the called function.
364- `[in] args`: List of JavaScript values as `napi_value` representing the
365arguments of the function.
366- `[in] context`: Context for the async operation that is invoking the callback.
367This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
368However `nullptr` is also allowed, which indicates the current async context
369(if any) is to be used for the callback.
370
371Returns a `Napi::Value` representing the JavaScript value returned by the function.
372
373### MakeCallback
374
375Calls a Javascript function from a native add-on after an asynchronous operation.
376
377```cpp
378Napi::Value Napi::Function::MakeCallback(napi_value recv, size_t argc, const napi_value* args, napi_async_context context = nullptr) const;
379```
380
381- `[in] recv`: The `this` object passed to the called function.
382- `[in] argc`: The number of the arguments passed to the function.
383- `[in] args`: Array of JavaScript values as `napi_value` representing the
384arguments of the function.
385- `[in] context`: Context for the async operation that is invoking the callback.
386This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
387However `nullptr` is also allowed, which indicates the current async context
388(if any) is to be used for the callback.
389
390Returns a `Napi::Value` representing the JavaScript value returned by the function.
391
392## Operator
393
394```cpp
395Napi::Value Napi::Function::operator ()(const std::initializer_list<napi_value>& args) const;
396```
397
398- `[in] args`: Initializer list of JavaScript values as `napi_value`.
399
400Returns a `Napi::Value` representing the JavaScript value returned by the function.
401
402[`Napi::ThreadSafeFunction`]: ./threadsafe_function.md
403