Skip to content

Commit 757eb1f

Browse files
NickNasomhdawson
NickNaso
authored and
mhdawson
committed
doc: add function and function reference doc
PR-URL: #299 Reviewed-By: Michael Dawson <[email protected]>
1 parent a3951ab commit 757eb1f

File tree

2 files changed

+471
-7
lines changed

2 files changed

+471
-7
lines changed

‎doc/function.md

Lines changed: 280 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,282 @@
11
# Function
22

3-
You are reading a draft of the next documentation and it's in continuous update so
4-
if you don't find what you need please refer to:
5-
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
3+
The `Napi::Function` class provides a set of methods for creating a function object in
4+
native code that can later be called from JavaScript. The created function is not
5+
automatically visible from JavaScript. Instead it needs to be part of the add-on's
6+
module exports or be returned by one of the module's exported functions.
7+
8+
In addition the `Function` class also provides methods that can be used to call
9+
functions that were created in JavaScript and passed to the native add-on.
10+
11+
The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info
12+
see: [`Napi::Object`](object.md)).
13+
14+
## Example
15+
16+
```cpp
17+
#include <napi.h>
18+
19+
using namespace Napi;
20+
21+
Value Fn(const CallbackInfo& info) {
22+
Env env = info.Env();
23+
// ...
24+
return String::New(env, "Hello World");
25+
}
26+
27+
Object Init(Env env, Object exports) {
28+
exports.Set(String::New(env, "fn"), Function::New(env, Fn));
29+
}
30+
31+
NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
32+
```
33+
34+
The above code can be used from JavaScript as follows:
35+
36+
```js
37+
const addon = require('./addon');
38+
addon.fn();
39+
```
40+
41+
With the `Napi::Function` class it is possible to call a JavaScript function object
42+
from a native add-on with two different methods: `Call` and `MakeCallback`.
43+
The API of these two methods is very similar, but they are used in different
44+
contexts. The `MakeCallback` method is used to call from native code back into
45+
JavaScript after returning from an [asynchronous operation](async_operations.md)
46+
and in general in situations which don't have an existing JavaScript function on
47+
the stack. The `Call` method is used when there is already a JavaScript function
48+
on the stack (for example when running a native method called from JavaScript).
49+
50+
## Methods
51+
52+
### Constructor
53+
54+
Creates a new empty instance of `Napi::Function`.
55+
56+
```cpp
57+
Function();
58+
```
59+
60+
### Constructor
61+
62+
Creates a new instance of the `Napi::Function` object.
63+
64+
```cpp
65+
Function(napi_env env, napi_value value);
66+
```
67+
68+
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
69+
- `[in] value`: The `napi_value` which is a handle for a JavaScript function.
70+
71+
Returns a non-empty `Napi::Function` instance.
72+
73+
### New
74+
75+
Creates an instance of a `Napi::Function` object.
76+
77+
```cpp
78+
template <typename Callable>
79+
static Function New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr);
80+
```
81+
82+
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
83+
- `[in] cb`: Object that implements `Callable`.
84+
- `[in] utf8name`: Null-terminated string to be used as the name of the function.
85+
- `[in] data`: User-provided data context. This will be passed back into the
86+
function when invoked later.
87+
88+
Returns an instance of a `Napi::Function` object.
89+
90+
### New
91+
92+
```cpp
93+
template <typename Callable>
94+
static Function New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr);
95+
```
96+
97+
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
98+
- `[in] cb`: Object that implements `Callable`.
99+
- `[in] utf8name`: String to be used as the name of the function.
100+
- `[in] data`: User-provided data context. This will be passed back into the
101+
function when invoked later.
102+
103+
Returns an instance of a `Napi::Function` object.
104+
105+
### New
106+
107+
Creates a new JavaScript value from one that represents the constructor for the
108+
object.
109+
110+
```cpp
111+
Napi::Object New(const std::initializer_list<napi_value>& args) const;
112+
```
113+
114+
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
115+
the arguments of the contructor function.
116+
117+
Returns a new JavaScript object.
118+
119+
### New
120+
121+
Creates a new JavaScript value from one that represents the constructor for the
122+
object.
123+
124+
```cpp
125+
Napi::Object New(const std::vector<napi_value>& args) const;
126+
```
127+
128+
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
129+
arguments of the constructor function.
130+
131+
Returns a new JavaScript object.
132+
133+
### New
134+
135+
Creates a new JavaScript value from one that represents the constructor for the
136+
object.
137+
138+
```cpp
139+
Napi::Object New(size_t argc, const napi_value* args) const;
140+
```
141+
142+
- `[in] argc`: The number of the arguments passed to the contructor function.
143+
- `[in] args`: Array of JavaScript values as `napi_value` representing the
144+
arguments of the constructor function.
145+
146+
Returns a new JavaScript object.
147+
148+
### Call
149+
150+
Calls a Javascript function from a native add-on.
151+
152+
```cpp
153+
Napi::Value Call(const std::initializer_list<napi_value>& args) const;
154+
```
155+
156+
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
157+
the arguments of the function.
158+
159+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
160+
161+
### Call
162+
163+
Calls a JavaScript function from a native add-on.
164+
165+
```cpp
166+
Napi::Value Call(const std::vector<napi_value>& args) const;
167+
```
168+
169+
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
170+
arguments of the function.
171+
172+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
173+
174+
### Call
175+
176+
Calls a Javascript function from a native add-on.
177+
178+
```cpp
179+
Napi::Value Call(size_t argc, const napi_value* args) const;
180+
```
181+
182+
- `[in] argc`: The number of the arguments passed to the function.
183+
- `[in] args`: Array of JavaScript values as `napi_value` representing the
184+
arguments of the function.
185+
186+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
187+
188+
### Call
189+
190+
Calls a Javascript function from a native add-on.
191+
192+
```cpp
193+
Napi::Value Call(napi_value recv, const std::initializer_list<napi_value>& args) const;
194+
```
195+
196+
- `[in] recv`: The `this` object passed to the called function.
197+
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
198+
the arguments of the function.
199+
200+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
201+
202+
### Call
203+
204+
Calls a Javascript function from a native add-on.
205+
206+
```cpp
207+
Napi::Value Call(napi_value recv, const std::vector<napi_value>& args) const;
208+
```
209+
210+
- `[in] recv`: The `this` object passed to the called function.
211+
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
212+
arguments of the function.
213+
214+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
215+
216+
### Call
217+
218+
Calls a Javascript function from a native add-on.
219+
220+
```cpp
221+
Napi::Value Call(napi_value recv, size_t argc, const napi_value* args) const;
222+
```
223+
224+
- `[in] recv`: The `this` object passed to the called function.
225+
- `[in] argc`: The number of the arguments passed to the function.
226+
- `[in] args`: Array of JavaScript values as `napi_value` representing the
227+
arguments of the function.
228+
229+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
230+
231+
### MakeCallback
232+
233+
Calls a Javascript function from a native add-on after an asynchronous operation.
234+
235+
```cpp
236+
Napi::Value MakeCallback(napi_value recv, const std::initializer_list<napi_value>& args) const;
237+
```
238+
239+
- `[in] recv`: The `this` object passed to the called function.
240+
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
241+
the arguments of the function.
242+
243+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
244+
245+
### MakeCallback
246+
247+
Calls a Javascript function from a native add-on after an asynchronous operation.
248+
249+
```cpp
250+
Napi::Value MakeCallback(napi_value recv, const std::vector<napi_value>& args) const;
251+
```
252+
253+
- `[in] recv`: The `this` object passed to the called function.
254+
- `[in] args`: List of JavaScript values as `napi_value` representing the
255+
arguments of the function.
256+
257+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
258+
259+
### MakeCallback
260+
261+
Calls a Javascript function from a native add-on after an asynchronous operation.
262+
263+
```cpp
264+
Napi::Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const;
265+
```
266+
267+
- `[in] recv`: The `this` object passed to the called function.
268+
- `[in] argc`: The number of the arguments passed to the function.
269+
- `[in] args`: Array of JavaScript values as `napi_value` representing the
270+
arguments of the function.
271+
272+
Returns a `Napi::Value` representing the JavaScript value returned by the function.
273+
274+
## Operator
275+
276+
```cpp
277+
Napi::Value operator ()(const std::initializer_list<napi_value>& args) const;
278+
```
279+
280+
- `[in] args`: Initializer list of JavaScript values as `napi_value`.
281+
282+
Returns a `Napi::Value` representing the JavaScript value returned by the function.

0 commit comments

Comments
 (0)