1## Miscellaneous Node Helpers
2
3 - <a href="#api_nan_asyncresource"><b><code>Nan::AsyncResource</code></b></a>
4 - <a href="#api_nan_make_callback"><b><code>Nan::MakeCallback()</code></b></a>
5 - <a href="#api_nan_module_init"><b><code>NAN_MODULE_INIT()</code></b></a>
6 - <a href="#api_nan_export"><b><code>Nan::Export()</code></b></a>
7
8<a name="api_nan_asyncresource"></a>
9### Nan::AsyncResource
10
11This class is analogous to the `AsyncResource` JavaScript class exposed by Node's [async_hooks][] API.
12
13When calling back into JavaScript asynchronously, special care must be taken to ensure that the runtime can properly track
14async hops. `Nan::AsyncResource` is a class that provides an RAII wrapper around `node::EmitAsyncInit`, `node::EmitAsyncDestroy`,
15and `node::MakeCallback`. Using this mechanism to call back into JavaScript, as opposed to `Nan::MakeCallback` or
16`v8::Function::Call` ensures that the callback is executed in the correct async context. This ensures that async mechanisms
17such as domains and [async_hooks][] function correctly.
18
19Definition:
20
21```c++
22class AsyncResource {
23 public:
24  AsyncResource(v8::Local<v8::String> name,
25                v8::Local<v8::Object> resource = New<v8::Object>());
26  AsyncResource(const char* name,
27                v8::Local<v8::Object> resource = New<v8::Object>());
28  ~AsyncResource();
29
30  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
31                                            v8::Local<v8::Function> func,
32                                            int argc,
33                                            v8::Local<v8::Value>* argv);
34  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
35                                            v8::Local<v8::String> symbol,
36                                            int argc,
37                                            v8::Local<v8::Value>* argv);
38  v8::MaybeLocal<v8::Value> runInAsyncScope(v8::Local<v8::Object> target,
39                                            const char* method,
40                                            int argc,
41                                            v8::Local<v8::Value>* argv);
42};
43```
44
45* `name`: Identifier for the kind of resource that is being provided for diagnostics information exposed by the [async_hooks][]
46  API. This will be passed to the possible `init` hook as the `type`. To avoid name collisions with other modules we recommend
47  that the name include the name of the owning module as a prefix. For example `mysql` module could use something like
48  `mysql:batch-db-query-resource`.
49* `resource`: An optional object associated with the async work that will be passed to the possible [async_hooks][]
50  `init` hook. If this parameter is omitted, or an empty handle is provided, this object will be created automatically.
51* When calling JS on behalf of this resource, one can use `runInAsyncScope`. This will ensure that the callback runs in the
52  correct async execution context.
53* `AsyncDestroy` is automatically called when an AsyncResource object is destroyed.
54
55For more details, see the Node [async_hooks][] documentation. You might also want to take a look at the documentation for the
56[N-API counterpart][napi]. For example usage, see the `asyncresource.cpp` example in the `test/cpp` directory.
57
58<a name="api_nan_make_callback"></a>
59### Nan::MakeCallback()
60
61Deprecated wrappers around the legacy `node::MakeCallback()` APIs. Node.js 10+
62has deprecated these legacy APIs as they do not provide a mechanism to preserve
63async context.
64
65We recommend that you use the `AsyncResource` class and `AsyncResource::runInAsyncScope` instead of using `Nan::MakeCallback` or
66`v8::Function#Call()` directly. `AsyncResource` properly takes care of running the callback in the correct async execution
67context – something that is essential for functionality like domains, async_hooks and async debugging.
68
69Signatures:
70
71```c++
72NAN_DEPRECATED
73v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
74                                       v8::Local<v8::Function> func,
75                                       int argc,
76                                       v8::Local<v8::Value>* argv);
77NAN_DEPRECATED
78v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
79                                       v8::Local<v8::String> symbol,
80                                       int argc,
81                                       v8::Local<v8::Value>* argv);
82NAN_DEPRECATED
83v8::Local<v8::Value> Nan::MakeCallback(v8::Local<v8::Object> target,
84                                       const char* method,
85                                       int argc,
86                                       v8::Local<v8::Value>* argv);
87```
88
89
90<a name="api_nan_module_init"></a>
91### NAN_MODULE_INIT()
92
93Used to define the entry point function to a Node add-on. Creates a function with a given `name` that receives a `target` object representing the equivalent of the JavaScript `exports` object.
94
95See example below.
96
97<a name="api_nan_export"></a>
98### Nan::Export()
99
100A simple helper to register a `v8::FunctionTemplate` from a JavaScript-accessible method (see [Methods](./methods.md)) as a property on an object. Can be used in a way similar to assigning properties to `module.exports` in JavaScript.
101
102Signature:
103
104```c++
105void Export(v8::Local<v8::Object> target, const char *name, Nan::FunctionCallback f)
106```
107
108Also available as the shortcut `NAN_EXPORT` macro.
109
110Example:
111
112```c++
113NAN_METHOD(Foo) {
114  ...
115}
116
117NAN_MODULE_INIT(Init) {
118  NAN_EXPORT(target, Foo);
119}
120```
121
122[async_hooks]: https://nodejs.org/dist/latest-v9.x/docs/api/async_hooks.html
123[napi]: https://nodejs.org/dist/latest-v9.x/docs/api/n-api.html#n_api_custom_asynchronous_operations
124