1# FunctionReference
2
3`Napi::FunctionReference` is a subclass of [`Napi::Reference`](reference.md), and
4is equivalent to an instance of `Napi::Reference<Napi::Function>`. This means
5that a `Napi::FunctionReference` holds a [`Napi::Function`](function.md), and a
6count of the number of references to that `Napi::Function`. When the count is
7greater than 0, a `Napi::FunctionReference` is not eligible for garbage collection.
8This ensures that the `Function` will remain accessible, even if the original
9reference to it is no longer available.
10`Napi::FunctionReference` allows the referenced JavaScript function object to be
11called from a native add-on with two different methods: `Call` and `MakeCallback`.
12See the documentation for [`Napi::Function`](function.md) for when `Call` should
13be used instead of `MakeCallback` and vice-versa.
14
15The `Napi::FunctionReference` class inherits its behavior from the `Napi::Reference`
16class (for more info see: [`Napi::Reference`](reference.md)).
17
18## Methods
19
20### Weak
21
22Creates a "weak" reference to the value, in that the initial reference count is
23set to 0.
24
25```cpp
26static Napi::FunctionReference Napi::Weak(const Napi::Function& value);
27```
28
29- `[in] value`: The value which is to be referenced.
30
31Returns the newly created reference.
32
33### Persistent
34
35Creates a "persistent" reference to the value, in that the initial reference
36count is set to 1.
37
38```cpp
39static Napi::FunctionReference Napi::Persistent(const Napi::Function& value);
40```
41
42- `[in] value`: The value which is to be referenced.
43
44Returns the newly created reference.
45
46### Constructor
47
48Creates a new empty instance of `Napi::FunctionReference`.
49
50```cpp
51Napi::FunctionReference::FunctionReference();
52```
53
54### Constructor
55
56Creates a new instance of the `Napi::FunctionReference`.
57
58```cpp
59Napi::FunctionReference::FunctionReference(napi_env env, napi_ref ref);
60```
61
62- `[in] env`: The environment in which to construct the `Napi::FunctionReference` object.
63- `[in] ref`: The Node-API reference to be held by the `Napi::FunctionReference`.
64
65Returns a newly created `Napi::FunctionReference` object.
66
67### New
68
69Constructs a new instance by calling the constructor held by this reference.
70
71```cpp
72Napi::Object Napi::FunctionReference::New(const std::initializer_list<napi_value>& args) const;
73```
74
75- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
76the arguments of the constructor function.
77
78Returns a new JavaScript object.
79
80### New
81
82Constructs a new instance by calling the constructor held by this reference.
83
84```cpp
85Napi::Object Napi::FunctionReference::New(const std::vector<napi_value>& args) const;
86```
87
88- `[in] args`: Vector of JavaScript values as `napi_value` representing the
89arguments of the constructor function.
90
91Returns a new JavaScript object.
92
93### Call
94
95Calls a referenced Javascript function from a native add-on.
96
97```cpp
98Napi::Value Napi::FunctionReference::Call(const std::initializer_list<napi_value>& args) const;
99```
100
101- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
102the arguments of the referenced function.
103
104Returns a `Napi::Value` representing the JavaScript object returned by the referenced
105function.
106
107### Call
108
109Calls a referenced JavaScript function from a native add-on.
110
111```cpp
112Napi::Value Napi::FunctionReference::Call(const std::vector<napi_value>& args) const;
113```
114
115- `[in] args`: Vector of JavaScript values as `napi_value` representing the
116arguments of the referenced function.
117
118Returns a `Napi::Value` representing the JavaScript object returned by the referenced
119function.
120
121### Call
122
123Calls a referenced JavaScript function from a native add-on.
124
125```cpp
126Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::initializer_list<napi_value>& args) const;
127```
128
129- `[in] recv`: The `this` object passed to the referenced function when it's called.
130- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
131the arguments of the referenced function.
132
133Returns a `Napi::Value` representing the JavaScript object returned by the referenced
134function.
135
136### Call
137
138Calls a referenced JavaScript function from a native add-on.
139
140```cpp
141Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::vector<napi_value>& args) const;
142```
143
144- `[in] recv`: The `this` object passed to the referenced function when it's called.
145- `[in] args`: Vector of JavaScript values as `napi_value` representing the
146arguments of the referenced function.
147
148Returns a `Napi::Value` representing the JavaScript object returned by the referenced
149function.
150
151### Call
152
153Calls a referenced JavaScript function from a native add-on.
154
155```cpp
156Napi::Value Napi::FunctionReference::Call(napi_value recv, size_t argc, const napi_value* args) const;
157```
158
159- `[in] recv`: The `this` object passed to the referenced function when it's called.
160- `[in] argc`: The number of arguments passed to the referenced function.
161- `[in] args`: Array of JavaScript values as `napi_value` representing the
162arguments of the referenced function.
163
164Returns a `Napi::Value` representing the JavaScript object returned by the referenced
165function.
166
167
168### MakeCallback
169
170Calls a referenced JavaScript function from a native add-on after an asynchronous
171operation.
172
173```cpp
174Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::initializer_list<napi_value>& args, napi_async_context = nullptr) const;
175```
176
177- `[in] recv`: The `this` object passed to the referenced function when it's called.
178- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
179the arguments of the referenced function.
180- `[in] context`: Context for the async operation that is invoking the callback.
181This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
182However `nullptr` is also allowed, which indicates the current async context
183(if any) is to be used for the callback.
184
185Returns a `Napi::Value` representing the JavaScript object returned by the referenced
186function.
187
188### MakeCallback
189
190Calls a referenced JavaScript function from a native add-on after an asynchronous
191operation.
192
193```cpp
194Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::vector<napi_value>& args, napi_async_context context = nullptr) const;
195```
196
197- `[in] recv`: The `this` object passed to the referenced function when it's called.
198- `[in] args`: Vector of JavaScript values as `napi_value` representing the
199arguments of the referenced function.
200- `[in] context`: Context for the async operation that is invoking the callback.
201This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
202However `nullptr` is also allowed, which indicates the current async context
203(if any) is to be used for the callback.
204
205Returns a `Napi::Value` representing the JavaScript object returned by the referenced
206function.
207
208### MakeCallback
209
210Calls a referenced JavaScript function from a native add-on after an asynchronous
211operation.
212
213```cpp
214Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, size_t argc, const napi_value* args, napi_async_context context = nullptr) const;
215```
216
217- `[in] recv`: The `this` object passed to the referenced function when it's called.
218- `[in] argc`: The number of arguments passed to the referenced function.
219- `[in] args`: Array of JavaScript values as `napi_value` representing the
220arguments of the referenced function.
221- `[in] context`: Context for the async operation that is invoking the callback.
222This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
223However `nullptr` is also allowed, which indicates the current async context
224(if any) is to be used for the callback.
225
226Returns a `Napi::Value` representing the JavaScript object returned by the referenced
227function.
228
229## Operator
230
231```cpp
232Napi::Value operator ()(const std::initializer_list<napi_value>& args) const;
233```
234
235- `[in] args`: Initializer list of reference to JavaScript values as `napi_value`
236
237Returns a `Napi::Value` representing the JavaScript value returned by the referenced
238function.
239