FM / api

/usr/share/doc/nodejs/api

Name	Size	Mode	Actions
assets/	-	0755	rm
addons.html	85172	0644	edit dl rm
addons.json.gz	11188	0644	edit dl rm
addons.md	41013	0644	edit dl rm
all.html	4598048	0644	edit dl rm
all.json.gz	681643	0644	edit dl rm
assert.html	110665	0644	edit dl rm
assert.json.gz	12007	0644	edit dl rm
assert.md	47147	0644	edit dl rm
async_hooks.html	83599	0644	edit dl rm
async_hooks.json.gz	14085	0644	edit dl rm
async_hooks.md	38888	0644	edit dl rm
buffer.html	245762	0644	edit dl rm
buffer.json.gz	24105	0644	edit dl rm
buffer.md	105044	0644	edit dl rm
child_process.html	136767	0644	edit dl rm
child_process.json.gz	19399	0644	edit dl rm
child_process.md	62919	0644	edit dl rm
cli.html	87936	0644	edit dl rm
cli.json.gz	16615	0644	edit dl rm
cli.md	42263	0644	edit dl rm
cluster.html	60116	0644	edit dl rm
cluster.json.gz	9557	0644	edit dl rm
cluster.md	25426	0644	edit dl rm
console.html	46093	0644	edit dl rm
console.json.gz	6056	0644	edit dl rm
console.md	16431	0644	edit dl rm
crypto.html	283043	0644	edit dl rm
crypto.json.gz	32118	0644	edit dl rm
crypto.md	125198	0644	edit dl rm
debugger.html	18089	0644	edit dl rm
debugger.json.gz	2820	0644	edit dl rm
debugger.md	6133	0644	edit dl rm
deprecations.html	138537	0644	edit dl rm
deprecations.json.gz	18470	0644	edit dl rm
deprecations.md	79120	0644	edit dl rm
dgram.html	62425	0644	edit dl rm
dgram.json.gz	9630	0644	edit dl rm
dgram.md	27746	0644	edit dl rm
dns.html	98289	0644	edit dl rm
dns.json.gz	13838	0644	edit dl rm
dns.md	40799	0644	edit dl rm
documentation.html	10978	0644	edit dl rm
documentation.json	3328	0644	edit dl rm
documentation.md	2247	0644	edit dl rm
domain.html	36301	0644	edit dl rm
domain.json.gz	6355	0644	edit dl rm
domain.md	15521	0644	edit dl rm
embedding.html	18165	0644	edit dl rm
embedding.json.gz	3625	0644	edit dl rm
embedding.md	8811	0644	edit dl rm
errors.html	182982	0644	edit dl rm
errors.json.gz	36479	0644	edit dl rm
errors.md	81734	0644	edit dl rm
esm.html	92490	0644	edit dl rm
esm.json.gz	15054	0644	edit dl rm
esm.md	48466	0644	edit dl rm
events.html	75986	0644	edit dl rm
events.json.gz	9561	0644	edit dl rm
events.md	28823	0644	edit dl rm
fs.html	437179	0644	edit dl rm
fs.json.gz	47095	0644	edit dl rm
fs.md	187735	0644	edit dl rm
globals.html	19795	0644	edit dl rm
globals.json.gz	2525	0644	edit dl rm
globals.md	5838	0644	edit dl rm
http.html	164378	0644	edit dl rm
http.json.gz	25888	0644	edit dl rm
http.md	74465	0644	edit dl rm
http2.html	256451	0644	edit dl rm
http2.json.gz	37157	0644	edit dl rm
http2.md	121722	0644	edit dl rm
https.html	38345	0644	edit dl rm
https.json.gz	4847	0644	edit dl rm
https.md	13942	0644	edit dl rm
index.html	10087	0644	edit dl rm
index.json	54	0644	edit dl rm
index.md	1825	0644	edit dl rm
inspector.html	22433	0644	edit dl rm
inspector.json.gz	3338	0644	edit dl rm
inspector.md	6825	0644	edit dl rm
intl.html	23154	0644	edit dl rm
intl.json.gz	4038	0644	edit dl rm
intl.md	11092	0644	edit dl rm
module.html	21739	0644	edit dl rm
module.json.gz	2821	0644	edit dl rm
module.md	5341	0644	edit dl rm
modules.html	61333	0644	edit dl rm
modules.json.gz	11897	0644	edit dl rm
modules.md	30610	0644	edit dl rm
n-api.html	340382	0644	edit dl rm
n-api.json.gz	48682	0644	edit dl rm
n-api.md	206268	0644	edit dl rm
net.html	95113	0644	edit dl rm
net.json.gz	14265	0644	edit dl rm
net.md	40473	0644	edit dl rm
os.html	58658	0644	edit dl rm
os.json.gz	8576	0644	edit dl rm
os.md	34632	0644	edit dl rm
packages.html	65483	0644	edit dl rm
packages.json.gz	12401	0644	edit dl rm
packages.md	36538	0644	edit dl rm
path.html	39321	0644	edit dl rm
path.json.gz	4873	0644	edit dl rm
path.md	14750	0644	edit dl rm
perf_hooks.html	56215	0644	edit dl rm
perf_hooks.json.gz	6973	0644	edit dl rm
perf_hooks.md	20116	0644	edit dl rm
policy.html	15908	0644	edit dl rm
policy.json.gz	2908	0644	edit dl rm
policy.md	6324	0644	edit dl rm
process.html	169341	0644	edit dl rm
process.json.gz	27734	0644	edit dl rm
process.md	82162	0644	edit dl rm
punycode.html	16904	0644	edit dl rm
punycode.json.gz	1939	0644	edit dl rm
punycode.md	4063	0644	edit dl rm
querystring.html	19334	0644	edit dl rm
querystring.json.gz	2519	0644	edit dl rm
querystring.md	5423	0644	edit dl rm
readline.html	58434	0644	edit dl rm
readline.json.gz	8835	0644	edit dl rm
readline.md	25133	0644	edit dl rm
repl.html	54152	0644	edit dl rm
repl.json.gz	10053	0644	edit dl rm
repl.md	23754	0644	edit dl rm
report.html	44941	0644	edit dl rm
report.json.gz	6227	0644	edit dl rm
report.md	18287	0644	edit dl rm
stream.html	200501	0644	edit dl rm
stream.json.gz	34485	0644	edit dl rm
stream.md	98619	0644	edit dl rm
string_decoder.html	14415	0644	edit dl rm
string_decoder.json.gz	1545	0644	edit dl rm
string_decoder.md	2934	0644	edit dl rm
synopsis.html	11475	0644	edit dl rm
synopsis.json	3013	0644	edit dl rm
synopsis.md	2129	0644	edit dl rm
timers.html	27467	0644	edit dl rm
timers.json.gz	3637	0644	edit dl rm
timers.md	9738	0644	edit dl rm
tls.html	148381	0644	edit dl rm
tls.json.gz	29988	0644	edit dl rm
tls.md	81388	0644	edit dl rm
tracing.html	19586	0644	edit dl rm
tracing.json.gz	2829	0644	edit dl rm
tracing.md	6756	0644	edit dl rm
tty.html	26930	0644	edit dl rm
tty.json.gz	3758	0644	edit dl rm
tty.md	8989	0644	edit dl rm
url.html	97495	0644	edit dl rm
url.json.gz	13611	0644	edit dl rm
url.md	44869	0644	edit dl rm
util.html	178081	0644	edit dl rm
util.json.gz	20542	0644	edit dl rm
util.md	71255	0644	edit dl rm
v8.html	44688	0644	edit dl rm
v8.json.gz	6082	0644	edit dl rm
v8.md	15533	0644	edit dl rm
vm.html	103392	0644	edit dl rm
vm.json.gz	14023	0644	edit dl rm
vm.md	48293	0644	edit dl rm
wasi.html	17088	0644	edit dl rm
wasi.json.gz	2814	0644	edit dl rm
wasi.md	5932	0644	edit dl rm
worker_threads.html	70808	0644	edit dl rm
worker_threads.json.gz	11326	0644	edit dl rm
worker_threads.md	33883	0644	edit dl rm
zlib.html	90124	0644	edit dl rm
zlib.json.gz	10569	0644	edit dl rm
zlib.md	35697	0644	edit dl rm

Edit: /usr/share/doc/nodejs/api/addons.html (85172B)

<!doctype html>
<html lang="en">
<head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width">
 <meta name="nodejs.org:node-version" content="v12.20.0">
 <title>C++ addons | Node.js v12.20.0 Documentation</title>
 <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700,400italic&display=fallback">
 <link rel="stylesheet" href="assets/style.css">
 <link rel="stylesheet" href="assets/hljs.css">
 <link rel="canonical" href="https://nodejs.org/api/addons.html">
</head>
<body class="alt apidoc" id="api-section-addons">
 <div id="content" class="clearfix">
 <div id="column2" class="interior">
 <div id="intro" class="interior">
 <a href="/" title="Go back to the home page">
 Node.js
 </a>
 </div>
 <ul>
<li><a href="documentation.html" class="nav-documentation">About this documentation</a></li>
<li><a href="synopsis.html" class="nav-synopsis">Usage and example</a></li>
</ul>
<hr class="line">
<ul>
<li><a href="assert.html" class="nav-assert">Assertion testing</a></li>
<li><a href="async_hooks.html" class="nav-async_hooks">Async hooks</a></li>
<li><a href="buffer.html" class="nav-buffer">Buffer</a></li>
<li><a href="addons.html" class="nav-addons active">C++ Addons</a></li>
<li><a href="n-api.html" class="nav-n-api">C/C++ Addons with N-API</a></li>
<li><a href="embedding.html" class="nav-embedding">C++ Embedder API</a></li>
<li><a href="child_process.html" class="nav-child_process">Child Processes</a></li>
<li><a href="cluster.html" class="nav-cluster">Cluster</a></li>
<li><a href="cli.html" class="nav-cli">Command line options</a></li>
<li><a href="console.html" class="nav-console">Console</a></li>
<li><a href="crypto.html" class="nav-crypto">Crypto</a></li>
<li><a href="debugger.html" class="nav-debugger">Debugger</a></li>
<li><a href="deprecations.html" class="nav-deprecations">Deprecated APIs</a></li>
<li><a href="dns.html" class="nav-dns">DNS</a></li>
<li><a href="domain.html" class="nav-domain">Domain</a></li>
<li><a href="errors.html" class="nav-errors">Errors</a></li>
<li><a href="events.html" class="nav-events">Events</a></li>
<li><a href="fs.html" class="nav-fs">File system</a></li>
<li><a href="globals.html" class="nav-globals">Globals</a></li>
<li><a href="http.html" class="nav-http">HTTP</a></li>
<li><a href="http2.html" class="nav-http2">HTTP/2</a></li>
<li><a href="https.html" class="nav-https">HTTPS</a></li>
<li><a href="inspector.html" class="nav-inspector">Inspector</a></li>
<li><a href="intl.html" class="nav-intl">Internationalization</a></li>
<li><a href="modules.html" class="nav-modules">Modules: CommonJS modules</a></li>
<li><a href="esm.html" class="nav-esm">Modules: ECMAScript modules</a></li>
<li><a href="module.html" class="nav-module">Modules: <code>module</code> API</a></li>
<li><a href="packages.html" class="nav-packages">Modules: Packages</a></li>
<li><a href="net.html" class="nav-net">Net</a></li>
<li><a href="os.html" class="nav-os">OS</a></li>
<li><a href="path.html" class="nav-path">Path</a></li>
<li><a href="perf_hooks.html" class="nav-perf_hooks">Performance hooks</a></li>
<li><a href="policy.html" class="nav-policy">Policies</a></li>
<li><a href="process.html" class="nav-process">Process</a></li>
<li><a href="punycode.html" class="nav-punycode">Punycode</a></li>
<li><a href="querystring.html" class="nav-querystring">Query strings</a></li>
<li><a href="readline.html" class="nav-readline">Readline</a></li>
<li><a href="repl.html" class="nav-repl">REPL</a></li>
<li><a href="report.html" class="nav-report">Report</a></li>
<li><a href="stream.html" class="nav-stream">Stream</a></li>
<li><a href="string_decoder.html" class="nav-string_decoder">String decoder</a></li>
<li><a href="timers.html" class="nav-timers">Timers</a></li>
<li><a href="tls.html" class="nav-tls">TLS/SSL</a></li>
<li><a href="tracing.html" class="nav-tracing">Trace events</a></li>
<li><a href="tty.html" class="nav-tty">TTY</a></li>
<li><a href="dgram.html" class="nav-dgram">UDP/datagram</a></li>
<li><a href="url.html" class="nav-url">URL</a></li>
<li><a href="util.html" class="nav-util">Utilities</a></li>
<li><a href="v8.html" class="nav-v8">V8</a></li>
<li><a href="vm.html" class="nav-vm">VM</a></li>
<li><a href="wasi.html" class="nav-wasi">WASI</a></li>
<li><a href="worker_threads.html" class="nav-worker_threads">Worker threads</a></li>
<li><a href="zlib.html" class="nav-zlib">Zlib</a></li>
</ul>
<hr class="line">
<ul>
<li><a href="https://github.com/nodejs/node" class="nav-https-github-com-nodejs-node">Code repository and issue tracker</a></li>
</ul>
 </div>

<div id="column1" data-id="addons" class="interior">
 <header>
 <h1>Node.js v12.20.0 Documentation</h1>
 <div id="gtoc">
 <ul>
 <li>
 <a href="index.html">Index</a>
 </li>
 <li>
 <a href="all.html">View on single page</a>
 </li>
 <li>
 <a href="addons.json">View as JSON</a>
 </li>
 
 <li class="version-picker">
 <a href="#">View another version &#x25bc;</a>
 <ol class="version-picker"><li><a href="https://nodejs.org/docs/latest-v15.x/api/addons.html">15.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v14.x/api/addons.html">14.x LTS</a></li>
<li><a href="https://nodejs.org/docs/latest-v13.x/api/addons.html">13.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v12.x/api/addons.html">12.x LTS</a></li>
<li><a href="https://nodejs.org/docs/latest-v11.x/api/addons.html">11.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v10.x/api/addons.html">10.x LTS</a></li>
<li><a href="https://nodejs.org/docs/latest-v9.x/api/addons.html">9.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v8.x/api/addons.html">8.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v7.x/api/addons.html">7.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v6.x/api/addons.html">6.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v5.x/api/addons.html">5.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v4.x/api/addons.html">4.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v0.12.x/api/addons.html">0.12.x</a></li>
<li><a href="https://nodejs.org/docs/latest-v0.10.x/api/addons.html">0.10.x</a></li></ol>
 </li>
 
 <li class="edit_on_github"><a href="https://github.com/nodejs/node/edit/master/doc/api/addons.md"><svg height="16" width="16" viewBox="0 0 16.1 16.1" fill="currentColor"><path d="M8 0a8 8 0 0 0-2.5 15.6c.4 0 .5-.2.5-.4v-1.5c-2 .4-2.5-.5-2.7-1 0-.1-.5-.9-.8-1-.3-.2-.7-.6 0-.6.6 0 1 .6 1.2.8.7 1.2 1.9 1 2.4.7 0-.5.2-.9.5-1-1.8-.3-3.7-1-3.7-4 0-.9.3-1.6.8-2.2 0-.2-.3-1 .1-2 0 0 .7-.3 2.2.7a7.4 7.4 0 0 1 4 0c1.5-1 2.2-.8 2.2-.8.5 1.1.2 2 .1 2.1.5.6.8 1.3.8 2.2 0 3-1.9 3.7-3.6 4 .3.2.5.7.5 1.4v2.2c0 .2.1.5.5.4A8 8 0 0 0 16 8a8 8 0 0 0-8-8z"/></svg>Edit on GitHub</a></li>
 </ul>
 </div>
 <hr>
 </header>

<div id="toc">
 <h2>Table of Contents</h2>
 <ul>
<li><a href="#addons_c_addons">C++ addons</a>
<ul>
<li><a href="#addons_hello_world">Hello world</a>
<ul>
<li><a href="#addons_context_aware_addons">Context-aware addons</a>
<ul>
<li><a href="#addons_worker_support">Worker support</a></li>
</ul>
</li>
<li><a href="#addons_building">Building</a></li>
<li><a href="#addons_linking_to_libraries_included_with_node_js">Linking to libraries included with Node.js</a></li>
<li><a href="#addons_loading_addons_using_require">Loading addons using <code>require()</code></a></li>
</ul>
</li>
<li><a href="#addons_native_abstractions_for_node_js">Native abstractions for Node.js</a></li>
<li><a href="#addons_n_api">N-API</a></li>
<li><a href="#addons_addon_examples">Addon examples</a>
<ul>
<li><a href="#addons_function_arguments">Function arguments</a></li>
<li><a href="#addons_callbacks">Callbacks</a></li>
<li><a href="#addons_object_factory">Object factory</a></li>
<li><a href="#addons_function_factory">Function factory</a></li>
<li><a href="#addons_wrapping_c_objects">Wrapping C++ objects</a></li>
<li><a href="#addons_factory_of_wrapped_objects">Factory of wrapped objects</a></li>
<li><a href="#addons_passing_wrapped_objects_around">Passing wrapped objects around</a></li>
</ul>
</li>
</ul>
</li>
</ul>
 </div>

<div id="apicontent">
 <h1>C++ addons<a class="mark" href="#addons_c_addons" id="addons_c_addons">#</a></h1>

Addons are dynamically-linked shared objects written in C++. The
<a href="modules.html#modules_require_id"><code>require()</code></a> function can load addons as ordinary Node.js modules.
Addons provide an interface between JavaScript and C/C++ libraries.
There are three options for implementing addons: N-API, nan, or direct
use of internal V8, libuv and Node.js libraries. Unless there is a need for
direct access to functionality which is not exposed by N-API, use N-API.
Refer to <a href="n-api.html">C/C++ addons with N-API</a> for more information on N-API.
When not using N-API, implementing addons is complicated,
involving knowledge of several components and APIs:
<ul>
<li>
V8: the C++ library Node.js uses to provide the
JavaScript implementation. V8 provides the mechanisms for creating objects,
calling functions, etc. V8's API is documented mostly in the
<code>v8.h</code> header file (<code>deps/v8/include/v8.h</code> in the Node.js source
tree), which is also available <a href="https://v8docs.nodesource.com/">online</a>.
</li>
<li>
<a href="https://github.com/libuv/libuv">libuv</a>: The C library that implements the Node.js event loop, its worker
threads and all of the asynchronous behaviors of the platform. It also
serves as a cross-platform abstraction library, giving easy, POSIX-like
access across all major operating systems to many common system tasks, such
as interacting with the filesystem, sockets, timers, and system events. libuv
also provides a pthreads-like threading abstraction that may be used to
power more sophisticated asynchronous addons that need to move beyond the
standard event loop. Addon authors are encouraged to think about how to
avoid blocking the event loop with I/O or other time-intensive tasks by
off-loading work via libuv to non-blocking system operations, worker threads
or a custom use of libuv's threads.
</li>
<li>
Internal Node.js libraries. Node.js itself exports C++ APIs that addons can
use, the most important of which is the <code>node::ObjectWrap</code> class.
</li>
<li>
Node.js includes other statically linked libraries including OpenSSL. These
other libraries are located in the <code>deps/</code> directory in the Node.js source
tree. Only the libuv, OpenSSL, V8 and zlib symbols are purposefully
re-exported by Node.js and may be used to various extents by addons. See
<a href="#addons_linking_to_libraries_included_with_node_js">Linking to libraries included with Node.js</a> for additional information.
</li>
</ul>
All of the following examples are available for <a href="https://github.com/nodejs/node-addon-examples">download</a> and may
be used as the starting-point for an addon.
<h2>Hello world<a class="mark" href="#addons_hello_world" id="addons_hello_world">#</a></h2>
This "Hello world" example is a simple addon, written in C++, that is the
equivalent of the following JavaScript code:
<pre><code class="language-js">module.exports.hello = () => 'world';</code></pre>
First, create the file <code>hello.cc</code>:
<pre><code class="language-cpp">// hello.cc
#include &#x3C;node.h>

namespace demo {

using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::NewStringType;
using v8::Object;
using v8::String;
using v8::Value;

void Method(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();
 args.GetReturnValue().Set(String::NewFromUtf8(
 isolate, "world", NewStringType::kNormal).ToLocalChecked());
}

void Initialize(Local&#x3C;Object> exports) {
 NODE_SET_METHOD(exports, "hello", Method);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)

} // namespace demo</code></pre>
All Node.js addons must export an initialization function following
the pattern:
<pre><code class="language-cpp">void Initialize(Local&#x3C;Object> exports);
NODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)</code></pre>
There is no semi-colon after <code>NODE_MODULE</code> as it's not a function (see
<code>node.h</code>).
The <code>module_name</code> must match the filename of the final binary (excluding
the <code>.node</code> suffix).
In the <code>hello.cc</code> example, then, the initialization function is <code>Initialize</code>
and the addon module name is <code>addon</code>.
When building addons with <code>node-gyp</code>, using the macro <code>NODE_GYP_MODULE_NAME</code> as
the first parameter of <code>NODE_MODULE()</code> will ensure that the name of the final
binary will be passed to <code>NODE_MODULE()</code>.
<h3>Context-aware addons<a class="mark" href="#addons_context_aware_addons" id="addons_context_aware_addons">#</a></h3>
There are environments in which Node.js addons may need to be loaded multiple
times in multiple contexts. For example, the <a href="https://electronjs.org/">Electron</a> runtime runs multiple
instances of Node.js in a single process. Each instance will have its own
<code>require()</code> cache, and thus each instance will need a native addon to behave
correctly when loaded via <code>require()</code>. From the addon's perspective, this means
that it must support multiple initializations.
A context-aware addon can be constructed by using the macro
<code>NODE_MODULE_INITIALIZER</code>, which expands to the name of a function which Node.js
will expect to find when it loads an addon. An addon can thus be initialized as
in the following example:
<pre><code class="language-cpp">using namespace v8;

extern "C" NODE_MODULE_EXPORT void
NODE_MODULE_INITIALIZER(Local&#x3C;Object> exports,
 Local&#x3C;Value> module,
 Local&#x3C;Context> context) {
 /* Perform addon initialization steps here. */
}</code></pre>
Another option is to use the macro <code>NODE_MODULE_INIT()</code>, which will also
construct a context-aware addon. Unlike <code>NODE_MODULE()</code>, which is used to
construct an addon around a given addon initializer function,
<code>NODE_MODULE_INIT()</code> serves as the declaration of such an initializer to be
followed by a function body.
The following three variables may be used inside the function body following an
invocation of <code>NODE_MODULE_INIT()</code>:
<ul>
<li><code>Local&#x3C;Object> exports</code>,</li>
<li><code>Local&#x3C;Value> module</code>, and</li>
<li><code>Local&#x3C;Context> context</code></li>
</ul>
The choice to build a context-aware addon carries with it the responsibility of
carefully managing global static data. Since the addon may be loaded multiple
times, potentially even from different threads, any global static data stored
in the addon must be properly protected, and must not contain any persistent
references to JavaScript objects. The reason for this is that JavaScript
objects are only valid in one context, and will likely cause a crash when
accessed from the wrong context or from a different thread than the one on which
they were created.
The context-aware addon can be structured to avoid global static data by
performing the following steps:
<ul>
<li>Define a class which will hold per-addon-instance data and which has a static
member of the form
<pre><code class="language-cpp">static void DeleteInstance(void* data) {
 // Cast `data` to an instance of the class and delete it.
}</code></pre>
</li>
<li>Heap-allocate an instance of this class in the addon initializer. This can be
accomplished using the <code>new</code> keyword.</li>
<li>Call <code>node::AddEnvironmentCleanupHook()</code>, passing it the above-created
instance and a pointer to <code>DeleteInstance()</code>. This will ensure the instance is
deleted when the environment is torn down.</li>
<li>Store the instance of the class in a <code>v8::External</code>, and</li>
<li>Pass the <code>v8::External</code> to all methods exposed to JavaScript by passing it
to <code>v8::FunctionTemplate::New()</code> or <code>v8::Function::New()</code> which creates the
native-backed JavaScript functions. The third parameter of
<code>v8::FunctionTemplate::New()</code> or <code>v8::Function::New()</code> accepts the
<code>v8::External</code> and makes it available in the native callback using the
<code>v8::FunctionCallbackInfo::Data()</code> method.</li>
</ul>
This will ensure that the per-addon-instance data reaches each binding that can
be called from JavaScript. The per-addon-instance data must also be passed into
any asynchronous callbacks the addon may create.
The following example illustrates the implementation of a context-aware addon:
<pre><code class="language-cpp">#include &#x3C;node.h>

using namespace v8;

class AddonData {
 public:
 explicit AddonData(Isolate* isolate):
 call_count(0) {
 // Ensure this per-addon-instance data is deleted at environment cleanup.
 node::AddEnvironmentCleanupHook(isolate, DeleteInstance, this);
 }

// Per-addon data.
 int call_count;

static void DeleteInstance(void* data) {
 delete static_cast&#x3C;AddonData*>(data);
 }
};

static void Method(const v8::FunctionCallbackInfo&#x3C;v8::Value>&#x26; info) {
 // Retrieve the per-addon-instance data.
 AddonData* data =
 reinterpret_cast&#x3C;AddonData*>(info.Data().As&#x3C;External>()->Value());
 data->call_count++;
 info.GetReturnValue().Set((double)data->call_count);
}

// Initialize this addon to be context-aware.
NODE_MODULE_INIT(/* exports, module, context */) {
 Isolate* isolate = context->GetIsolate();

// Create a new instance of `AddonData` for this instance of the addon and
 // tie its life cycle to that of the Node.js environment.
 AddonData* data = new AddonData(isolate);

// Wrap the data in a `v8::External` so we can pass it to the method we
 // expose.
 Local&#x3C;External> external = External::New(isolate, data);

// Expose the method `Method` to JavaScript, and make sure it receives the
 // per-addon-instance data we created above by passing `external` as the
 // third parameter to the `FunctionTemplate` constructor.
 exports->Set(context,
 String::NewFromUtf8(isolate, "method", NewStringType::kNormal)
 .ToLocalChecked(),
 FunctionTemplate::New(isolate, Method, external)
 ->GetFunction(context).ToLocalChecked()).FromJust();
}</code></pre>
<h4>Worker support<a class="mark" href="#addons_worker_support" id="addons_worker_support">#</a></h4>
<div class="api_metadata">
<details class="changelog"><summary>History</summary>
<table>
<tbody><tr><th>Version</th><th>Changes</th></tr>
<tr><td>v12.19.0</td>
<td>Cleanup hooks may now be asynchronous.</td></tr>
</tbody></table>
</details>
</div>
In order to be loaded from multiple Node.js environments,
such as a main thread and a Worker thread, an add-on needs to either:
<ul>
<li>Be an N-API addon, or</li>
<li>Be declared as context-aware using <code>NODE_MODULE_INIT()</code> as described above</li>
</ul>
In order to support <a href="worker_threads.html#worker_threads_class_worker"><code>Worker</code></a> threads, addons need to clean up any resources
they may have allocated when such a thread exists. This can be achieved through
the usage of the <code>AddEnvironmentCleanupHook()</code> function:
<pre><code class="language-cpp">void AddEnvironmentCleanupHook(v8::Isolate* isolate,
 void (*fun)(void* arg),
 void* arg);</code></pre>
This function adds a hook that will run before a given Node.js instance shuts
down. If necessary, such hooks can be removed before they are run using
<code>RemoveEnvironmentCleanupHook()</code>, which has the same signature. Callbacks are
run in last-in first-out order.
If necessary, there is an additional pair of <code>AddEnvironmentCleanupHook()</code>
and <code>RemoveEnvironmentCleanupHook()</code> overloads, where the cleanup hook takes a
callback function. This can be used for shutting down asynchronous resources,
such as any libuv handles registered by the addon.
The following <code>addon.cc</code> uses <code>AddEnvironmentCleanupHook</code>:
<pre><code class="language-cpp">// addon.cc
#include &#x3C;assert.h>
#include &#x3C;stdlib.h>
#include &#x3C;node.h>

using node::AddEnvironmentCleanupHook;
using v8::HandleScope;
using v8::Isolate;
using v8::Local;
using v8::Object;

// Note: In a real-world application, do not rely on static/global data.
static char cookie[] = "yum yum";
static int cleanup_cb1_called = 0;
static int cleanup_cb2_called = 0;

static void cleanup_cb1(void* arg) {
 Isolate* isolate = static_cast&#x3C;Isolate*>(arg);
 HandleScope scope(isolate);
 Local&#x3C;Object> obj = Object::New(isolate);
 assert(!obj.IsEmpty()); // assert VM is still alive
 assert(obj->IsObject());
 cleanup_cb1_called++;
}

static void cleanup_cb2(void* arg) {
 assert(arg == static_cast&#x3C;void*>(cookie));
 cleanup_cb2_called++;
}

static void sanity_check(void*) {
 assert(cleanup_cb1_called == 1);
 assert(cleanup_cb2_called == 1);
}

AddEnvironmentCleanupHook(isolate, sanity_check, nullptr);
 AddEnvironmentCleanupHook(isolate, cleanup_cb2, cookie);
 AddEnvironmentCleanupHook(isolate, cleanup_cb1, isolate);
}</code></pre>
Test in JavaScript by running:
<pre><code class="language-js">// test.js
require('./build/Release/addon');</code></pre>
<h3>Building<a class="mark" href="#addons_building" id="addons_building">#</a></h3>
Once the source code has been written, it must be compiled into the binary
<code>addon.node</code> file. To do so, create a file called <code>binding.gyp</code> in the
top-level of the project describing the build configuration of the module
using a JSON-like format. This file is used by <a href="https://github.com/nodejs/node-gyp">node-gyp</a>, a tool written
specifically to compile Node.js addons.
<pre><code class="language-json">{
 "targets": [
 {
 "target_name": "addon",
 "sources": [ "hello.cc" ]
 }
 ]
}</code></pre>
A version of the <code>node-gyp</code> utility is bundled and distributed with
Node.js as part of <code>npm</code>. This version is not made directly available for
developers to use and is intended only to support the ability to use the
<code>npm install</code> command to compile and install addons. Developers who wish to
use <code>node-gyp</code> directly can install it using the command
<code>npm install -g node-gyp</code>. See the <code>node-gyp</code> <a href="https://github.com/nodejs/node-gyp#installation">installation instructions</a> for
more information, including platform-specific requirements.
Once the <code>binding.gyp</code> file has been created, use <code>node-gyp configure</code> to
generate the appropriate project build files for the current platform. This
will generate either a <code>Makefile</code> (on Unix platforms) or a <code>vcxproj</code> file
(on Windows) in the <code>build/</code> directory.
Next, invoke the <code>node-gyp build</code> command to generate the compiled <code>addon.node</code>
file. This will be put into the <code>build/Release/</code> directory.
When using <code>npm install</code> to install a Node.js addon, npm uses its own bundled
version of <code>node-gyp</code> to perform this same set of actions, generating a
compiled version of the addon for the user's platform on demand.
Once built, the binary addon can be used from within Node.js by pointing
<a href="modules.html#modules_require_id"><code>require()</code></a> to the built <code>addon.node</code> module:
<pre><code class="language-js">// hello.js
const addon = require('./build/Release/addon');

console.log(addon.hello());
// Prints: 'world'</code></pre>
Because the exact path to the compiled addon binary can vary depending on how
it is compiled (i.e. sometimes it may be in <code>./build/Debug/</code>), addons can use
the <a href="https://github.com/TooTallNate/node-bindings">bindings</a> package to load the compiled module.
While the <code>bindings</code> package implementation is more sophisticated in how it
locates addon modules, it is essentially using a <code>try…catch</code> pattern similar to:
<pre><code class="language-js">try {
 return require('./build/Release/addon.node');
} catch (err) {
 return require('./build/Debug/addon.node');
}</code></pre>
<h3>Linking to libraries included with Node.js<a class="mark" href="#addons_linking_to_libraries_included_with_node_js" id="addons_linking_to_libraries_included_with_node_js">#</a></h3>
Node.js uses statically linked libraries such as V8, libuv and OpenSSL. All
addons are required to link to V8 and may link to any of the other dependencies
as well. Typically, this is as simple as including the appropriate
<code>#include &#x3C;...></code> statements (e.g. <code>#include &#x3C;v8.h></code>) and <code>node-gyp</code> will locate
the appropriate headers automatically. However, there are a few caveats to be
aware of:
<ul>
<li>
When <code>node-gyp</code> runs, it will detect the specific release version of Node.js
and download either the full source tarball or just the headers. If the full
source is downloaded, addons will have complete access to the full set of
Node.js dependencies. However, if only the Node.js headers are downloaded, then
only the symbols exported by Node.js will be available.
</li>
<li>
<code>node-gyp</code> can be run using the <code>--nodedir</code> flag pointing at a local Node.js
source image. Using this option, the addon will have access to the full set of
dependencies.
</li>
</ul>
<h3>Loading addons using <code>require()</code><a class="mark" href="#addons_loading_addons_using_require" id="addons_loading_addons_using_require">#</a></h3>
The filename extension of the compiled addon binary is <code>.node</code> (as opposed
to <code>.dll</code> or <code>.so</code>). The <a href="modules.html#modules_require_id"><code>require()</code></a> function is written to look for
files with the <code>.node</code> file extension and initialize those as dynamically-linked
libraries.
When calling <a href="modules.html#modules_require_id"><code>require()</code></a>, the <code>.node</code> extension can usually be
omitted and Node.js will still find and initialize the addon. One caveat,
however, is that Node.js will first attempt to locate and load modules or
JavaScript files that happen to share the same base name. For instance, if
there is a file <code>addon.js</code> in the same directory as the binary <code>addon.node</code>,
then <a href="modules.html#modules_require_id"><code>require('addon')</code></a> will give precedence to the <code>addon.js</code> file
and load it instead.
<h2>Native abstractions for Node.js<a class="mark" href="#addons_native_abstractions_for_node_js" id="addons_native_abstractions_for_node_js">#</a></h2>
Each of the examples illustrated in this document directly use the
Node.js and V8 APIs for implementing addons. The V8 API can, and has, changed
dramatically from one V8 release to the next (and one major Node.js release to
the next). With each change, addons may need to be updated and recompiled in
order to continue functioning. The Node.js release schedule is designed to
minimize the frequency and impact of such changes but there is little that
Node.js can do to ensure stability of the V8 APIs.
The <a href="https://github.com/nodejs/nan">Native Abstractions for Node.js</a> (or <code>nan</code>) provide a set of tools that
addon developers are recommended to use to keep compatibility between past and
future releases of V8 and Node.js. See the <code>nan</code> <a href="https://github.com/nodejs/nan/tree/master/examples/">examples</a> for an
illustration of how it can be used.
<h2>N-API<a class="mark" href="#addons_n_api" id="addons_n_api">#</a></h2>
<div class="api_stability api_stability_2"><a href="documentation.html#documentation_stability_index">Stability: 2</a> - Stable</div>
N-API is an API for building native addons. It is independent from
the underlying JavaScript runtime (e.g. V8) and is maintained as part of
Node.js itself. This API will be Application Binary Interface (ABI) stable
across versions of Node.js. It is intended to insulate addons from
changes in the underlying JavaScript engine and allow modules
compiled for one version to run on later versions of Node.js without
recompilation. Addons are built/packaged with the same approach/tools
outlined in this document (node-gyp, etc.). The only difference is the
set of APIs that are used by the native code. Instead of using the V8
or <a href="https://github.com/nodejs/nan">Native Abstractions for Node.js</a> APIs, the functions available
in the N-API are used.
Creating and maintaining an addon that benefits from the ABI stability
provided by N-API carries with it certain
<a href="n-api.html#n_api_implications_of_abi_stability">implementation considerations</a>.
To use N-API in the above "Hello world" example, replace the content of
<code>hello.cc</code> with the following. All other instructions remain the same.
<pre><code class="language-cpp">// hello.cc using N-API
#include &#x3C;node_api.h>

namespace demo {

napi_value Method(napi_env env, napi_callback_info args) {
 napi_value greeting;
 napi_status status;

status = napi_create_string_utf8(env, "world", NAPI_AUTO_LENGTH, &#x26;greeting);
 if (status != napi_ok) return nullptr;
 return greeting;
}

napi_value init(napi_env env, napi_value exports) {
 napi_status status;
 napi_value fn;

status = napi_create_function(env, nullptr, 0, Method, nullptr, &#x26;fn);
 if (status != napi_ok) return nullptr;

status = napi_set_named_property(env, exports, "hello", fn);
 if (status != napi_ok) return nullptr;
 return exports;
}

NAPI_MODULE(NODE_GYP_MODULE_NAME, init)

} // namespace demo</code></pre>
The functions available and how to use them are documented in
<a href="n-api.html">C/C++ addons with N-API</a>.
<h2>Addon examples<a class="mark" href="#addons_addon_examples" id="addons_addon_examples">#</a></h2>
Following are some example addons intended to help developers get started. The
examples use the V8 APIs. Refer to the online <a href="https://v8docs.nodesource.com/">V8 reference</a>
for help with the various V8 calls, and V8's <a href="https://github.com/v8/v8/wiki/Embedder&#x27;s%20Guide">Embedder's Guide</a> for an
explanation of several concepts used such as handles, scopes, function
templates, etc.
Each of these examples using the following <code>binding.gyp</code> file:
<pre><code class="language-json">{
 "targets": [
 {
 "target_name": "addon",
 "sources": [ "addon.cc" ]
 }
 ]
}</code></pre>
In cases where there is more than one <code>.cc</code> file, simply add the additional
filename to the <code>sources</code> array:
<pre><code class="language-json">"sources": ["addon.cc", "myexample.cc"]</code></pre>
Once the <code>binding.gyp</code> file is ready, the example addons can be configured and
built using <code>node-gyp</code>:
<pre><code class="language-console">$ node-gyp configure build</code></pre>
<h3>Function arguments<a class="mark" href="#addons_function_arguments" id="addons_function_arguments">#</a></h3>
Addons will typically expose objects and functions that can be accessed from
JavaScript running within Node.js. When functions are invoked from JavaScript,
the input arguments and return value must be mapped to and from the C/C++
code.
The following example illustrates how to read function arguments passed from
JavaScript and how to return a result:
<pre><code class="language-cpp">// addon.cc
#include &#x3C;node.h>

namespace demo {

using v8::Exception;
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::NewStringType;
using v8::Number;
using v8::Object;
using v8::String;
using v8::Value;

// This is the implementation of the "add" method
// Input arguments are passed using the
// const FunctionCallbackInfo&#x3C;Value>&#x26; args struct
void Add(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();

// Check the number of arguments passed.
 if (args.Length() &#x3C; 2) {
 // Throw an Error that is passed back to JavaScript
 isolate->ThrowException(Exception::TypeError(
 String::NewFromUtf8(isolate,
 "Wrong number of arguments",
 NewStringType::kNormal).ToLocalChecked()));
 return;
 }

// Check the argument types
 if (!args[0]->IsNumber() || !args[1]->IsNumber()) {
 isolate->ThrowException(Exception::TypeError(
 String::NewFromUtf8(isolate,
 "Wrong arguments",
 NewStringType::kNormal).ToLocalChecked()));
 return;
 }

// Perform the operation
 double value =
 args[0].As&#x3C;Number>()->Value() + args[1].As&#x3C;Number>()->Value();
 Local&#x3C;Number> num = Number::New(isolate, value);

// Set the return value (using the passed in
 // FunctionCallbackInfo&#x3C;Value>&#x26;)
 args.GetReturnValue().Set(num);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Init)

} // namespace demo</code></pre>
Once compiled, the example addon can be required and used from within Node.js:
<pre><code class="language-js">// test.js
const addon = require('./build/Release/addon');

console.log('This should be eight:', addon.add(3, 5));</code></pre>
<h3>Callbacks<a class="mark" href="#addons_callbacks" id="addons_callbacks">#</a></h3>
It is common practice within addons to pass JavaScript functions to a C++
function and execute them from there. The following example illustrates how
to invoke such callbacks:
<pre><code class="language-cpp">// addon.cc
#include &#x3C;node.h>

namespace demo {

using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::NewStringType;
using v8::Null;
using v8::Object;
using v8::String;
using v8::Value;

void RunCallback(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();
 Local&#x3C;Context> context = isolate->GetCurrentContext();
 Local&#x3C;Function> cb = Local&#x3C;Function>::Cast(args[0]);
 const unsigned argc = 1;
 Local&#x3C;Value> argv[argc] = {
 String::NewFromUtf8(isolate,
 "hello world",
 NewStringType::kNormal).ToLocalChecked() };
 cb->Call(context, Null(isolate), argc, argv).ToLocalChecked();
}

void Init(Local&#x3C;Object> exports, Local&#x3C;Object> module) {
 NODE_SET_METHOD(module, "exports", RunCallback);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Init)

} // namespace demo</code></pre>
This example uses a two-argument form of <code>Init()</code> that receives the full
<code>module</code> object as the second argument. This allows the addon to completely
overwrite <code>exports</code> with a single function instead of adding the function as a
property of <code>exports</code>.
To test it, run the following JavaScript:
<pre><code class="language-js">// test.js
const addon = require('./build/Release/addon');

addon((msg) => {
 console.log(msg);
// Prints: 'hello world'
});</code></pre>
In this example, the callback function is invoked synchronously.
<h3>Object factory<a class="mark" href="#addons_object_factory" id="addons_object_factory">#</a></h3>
Addons can create and return new objects from within a C++ function as
illustrated in the following example. An object is created and returned with a
property <code>msg</code> that echoes the string passed to <code>createObject()</code>:
<pre><code class="language-cpp">// addon.cc
#include &#x3C;node.h>

namespace demo {

using v8::Context;
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::NewStringType;
using v8::Object;
using v8::String;
using v8::Value;

void CreateObject(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();
 Local&#x3C;Context> context = isolate->GetCurrentContext();

Local&#x3C;Object> obj = Object::New(isolate);
 obj->Set(context,
 String::NewFromUtf8(isolate,
 "msg",
 NewStringType::kNormal).ToLocalChecked(),
 args[0]->ToString(context).ToLocalChecked())
 .FromJust();

args.GetReturnValue().Set(obj);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Init)

} // namespace demo</code></pre>
To test it in JavaScript:
<pre><code class="language-js">// test.js
const addon = require('./build/Release/addon');

const obj1 = addon('hello');
const obj2 = addon('world');
console.log(obj1.msg, obj2.msg);
// Prints: 'hello world'</code></pre>
<h3>Function factory<a class="mark" href="#addons_function_factory" id="addons_function_factory">#</a></h3>
Another common scenario is creating JavaScript functions that wrap C++
functions and returning those back to JavaScript:
<pre><code class="language-cpp">// addon.cc
#include &#x3C;node.h>

namespace demo {

using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::Isolate;
using v8::Local;
using v8::NewStringType;
using v8::Object;
using v8::String;
using v8::Value;

void MyFunction(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();
 args.GetReturnValue().Set(String::NewFromUtf8(
 isolate, "hello world", NewStringType::kNormal).ToLocalChecked());
}

void CreateFunction(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();

Local&#x3C;Context> context = isolate->GetCurrentContext();
  Local&#x3C;FunctionTemplate> tpl = FunctionTemplate::New(isolate, MyFunction);
  Local&#x3C;Function> fn = tpl->GetFunction(context).ToLocalChecked();

// omit this to make it anonymous
 fn->SetName(String::NewFromUtf8(
 isolate, "theFunction", NewStringType::kNormal).ToLocalChecked());

args.GetReturnValue().Set(fn);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, Init)

} // namespace demo</code></pre>
To test:
<pre><code class="language-js">// test.js
const addon = require('./build/Release/addon');

const fn = addon();
console.log(fn());
// Prints: 'hello world'</code></pre>
<h3>Wrapping C++ objects<a class="mark" href="#addons_wrapping_c_objects" id="addons_wrapping_c_objects">#</a></h3>
It is also possible to wrap C++ objects/classes in a way that allows new
instances to be created using the JavaScript <code>new</code> operator:
<pre><code class="language-cpp">// addon.cc
#include &#x3C;node.h>
#include "myobject.h"

namespace demo {

using v8::Local;
using v8::Object;

void InitAll(Local&#x3C;Object> exports) {
 MyObject::Init(exports);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)

} // namespace demo</code></pre>
Then, in <code>myobject.h</code>, the wrapper class inherits from <code>node::ObjectWrap</code>:
<pre><code class="language-cpp">// myobject.h
#ifndef MYOBJECT_H
#define MYOBJECT_H

#include &#x3C;node.h>
#include &#x3C;node_object_wrap.h>

namespace demo {

private:
 explicit MyObject(double value = 0);
 ~MyObject();

static void New(const v8::FunctionCallbackInfo&#x3C;v8::Value>&#x26; args);
 static void PlusOne(const v8::FunctionCallbackInfo&#x3C;v8::Value>&#x26; args);

double value_;
};

} // namespace demo

#endif</code></pre>
In <code>myobject.cc</code>, implement the various methods that are to be exposed.
Below, the method <code>plusOne()</code> is exposed by adding it to the constructor's
prototype:
<pre><code class="language-cpp">// myobject.cc
#include "myobject.h"

namespace demo {

using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::Isolate;
using v8::Local;
using v8::NewStringType;
using v8::Number;
using v8::Object;
using v8::ObjectTemplate;
using v8::String;
using v8::Value;

MyObject::MyObject(double value) : value_(value) {
}

MyObject::~MyObject() {
}

void MyObject::Init(Local&#x3C;Object> exports) {
 Isolate* isolate = exports->GetIsolate();
 Local&#x3C;Context> context = isolate->GetCurrentContext();

Local&#x3C;ObjectTemplate> addon_data_tpl = ObjectTemplate::New(isolate);
 addon_data_tpl->SetInternalFieldCount(1); // 1 field for the MyObject::New()
 Local&#x3C;Object> addon_data =
 addon_data_tpl->NewInstance(context).ToLocalChecked();

// Prepare constructor template
 Local&#x3C;FunctionTemplate> tpl = FunctionTemplate::New(isolate, New, addon_data);
 tpl->SetClassName(String::NewFromUtf8(
 isolate, "MyObject", NewStringType::kNormal).ToLocalChecked());
 tpl->InstanceTemplate()->SetInternalFieldCount(1);

// Prototype
 NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne);

Local&#x3C;Function> constructor = tpl->GetFunction(context).ToLocalChecked();
 addon_data->SetInternalField(0, constructor);
 exports->Set(context, String::NewFromUtf8(
 isolate, "MyObject", NewStringType::kNormal).ToLocalChecked(),
 constructor).FromJust();
}

void MyObject::New(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();
 Local&#x3C;Context> context = isolate->GetCurrentContext();

if (args.IsConstructCall()) {
 // Invoked as constructor: `new MyObject(...)`
 double value = args[0]->IsUndefined() ?
 0 : args[0]->NumberValue(context).FromMaybe(0);
 MyObject* obj = new MyObject(value);
 obj->Wrap(args.This());
 args.GetReturnValue().Set(args.This());
 } else {
 // Invoked as plain function `MyObject(...)`, turn into construct call.
 const int argc = 1;
 Local&#x3C;Value> argv[argc] = { args[0] };
 Local&#x3C;Function> cons =
 args.Data().As&#x3C;Object>()->GetInternalField(0).As&#x3C;Function>();
 Local&#x3C;Object> result =
 cons->NewInstance(context, argc, argv).ToLocalChecked();
 args.GetReturnValue().Set(result);
 }
}

void MyObject::PlusOne(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();

MyObject* obj = ObjectWrap::Unwrap&#x3C;MyObject>(args.Holder());
 obj->value_ += 1;

args.GetReturnValue().Set(Number::New(isolate, obj->value_));
}

} // namespace demo</code></pre>
To build this example, the <code>myobject.cc</code> file must be added to the
<code>binding.gyp</code>:
<pre><code class="language-json">{
 "targets": [
 {
 "target_name": "addon",
 "sources": [
 "addon.cc",
 "myobject.cc"
 ]
 }
 ]
}</code></pre>
Test it with:
<pre><code class="language-js">// test.js
const addon = require('./build/Release/addon');

const obj = new addon.MyObject(10);
console.log(obj.plusOne());
// Prints: 11
console.log(obj.plusOne());
// Prints: 12
console.log(obj.plusOne());
// Prints: 13</code></pre>
The destructor for a wrapper object will run when the object is
garbage-collected. For destructor testing, there are command-line flags that
can be used to make it possible to force garbage collection. These flags are
provided by the underlying V8 JavaScript engine. They are subject to change
or removal at any time. They are not documented by Node.js or V8, and they
should never be used outside of testing.
<h3>Factory of wrapped objects<a class="mark" href="#addons_factory_of_wrapped_objects" id="addons_factory_of_wrapped_objects">#</a></h3>
Alternatively, it is possible to use a factory pattern to avoid explicitly
creating object instances using the JavaScript <code>new</code> operator:
<pre><code class="language-js">const obj = addon.createObject();
// instead of:
// const obj = new addon.Object();</code></pre>
First, the <code>createObject()</code> method is implemented in <code>addon.cc</code>:
<pre><code class="language-cpp">// addon.cc
#include &#x3C;node.h>
#include "myobject.h"

namespace demo {

using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::Object;
using v8::String;
using v8::Value;

NODE_SET_METHOD(module, "exports", CreateObject);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)

} // namespace demo</code></pre>
In <code>myobject.h</code>, the static method <code>NewInstance()</code> is added to handle
instantiating the object. This method takes the place of using <code>new</code> in
JavaScript:
<pre><code class="language-cpp">// myobject.h
#ifndef MYOBJECT_H
#define MYOBJECT_H

namespace demo {

class MyObject : public node::ObjectWrap {
 public:
 static void Init(v8::Isolate* isolate);
 static void NewInstance(const v8::FunctionCallbackInfo&#x3C;v8::Value>&#x26; args);

} // namespace demo

#endif</code></pre>
The implementation in <code>myobject.cc</code> is similar to the previous example:
<pre><code class="language-cpp">// myobject.cc
#include &#x3C;node.h>
#include "myobject.h"

namespace demo {

using node::AddEnvironmentCleanupHook;
using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::Global;
using v8::Isolate;
using v8::Local;
using v8::NewStringType;
using v8::Number;
using v8::Object;
using v8::String;
using v8::Value;

// Warning! This is not thread-safe, this addon cannot be used for worker
// threads.
Global&#x3C;Function> MyObject::constructor;

MyObject::MyObject(double value) : value_(value) {
}

MyObject::~MyObject() {
}

void MyObject::Init(Isolate* isolate) {
 // Prepare constructor template
 Local&#x3C;FunctionTemplate> tpl = FunctionTemplate::New(isolate, New);
 tpl->SetClassName(String::NewFromUtf8(
 isolate, "MyObject", NewStringType::kNormal).ToLocalChecked());
 tpl->InstanceTemplate()->SetInternalFieldCount(1);

// Prototype
 NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne);

Local&#x3C;Context> context = isolate->GetCurrentContext();
  constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());

AddEnvironmentCleanupHook(isolate, [](void*) {
 constructor.Reset();
 }, nullptr);
}

if (args.IsConstructCall()) {
 // Invoked as constructor: `new MyObject(...)`
 double value = args[0]->IsUndefined() ?
 0 : args[0]->NumberValue(context).FromMaybe(0);
 MyObject* obj = new MyObject(value);
 obj->Wrap(args.This());
 args.GetReturnValue().Set(args.This());
 } else {
 // Invoked as plain function `MyObject(...)`, turn into construct call.
 const int argc = 1;
 Local&#x3C;Value> argv[argc] = { args[0] };
 Local&#x3C;Function> cons = Local&#x3C;Function>::New(isolate, constructor);
 Local&#x3C;Object> instance =
 cons->NewInstance(context, argc, argv).ToLocalChecked();
 args.GetReturnValue().Set(instance);
 }
}

void MyObject::NewInstance(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();

const unsigned argc = 1;
 Local&#x3C;Value> argv[argc] = { args[0] };
 Local&#x3C;Function> cons = Local&#x3C;Function>::New(isolate, constructor);
 Local&#x3C;Context> context = isolate->GetCurrentContext();
 Local&#x3C;Object> instance =
 cons->NewInstance(context, argc, argv).ToLocalChecked();

args.GetReturnValue().Set(instance);
}

MyObject* obj = ObjectWrap::Unwrap&#x3C;MyObject>(args.Holder());
 obj->value_ += 1;

args.GetReturnValue().Set(Number::New(isolate, obj->value_));
}

} // namespace demo</code></pre>
Once again, to build this example, the <code>myobject.cc</code> file must be added to the
<code>binding.gyp</code>:
<pre><code class="language-json">{
 "targets": [
 {
 "target_name": "addon",
 "sources": [
 "addon.cc",
 "myobject.cc"
 ]
 }
 ]
}</code></pre>
Test it with:
<pre><code class="language-js">// test.js
const createObject = require('./build/Release/addon');

const obj = createObject(10);
console.log(obj.plusOne());
// Prints: 11
console.log(obj.plusOne());
// Prints: 12
console.log(obj.plusOne());
// Prints: 13

const obj2 = createObject(20);
console.log(obj2.plusOne());
// Prints: 21
console.log(obj2.plusOne());
// Prints: 22
console.log(obj2.plusOne());
// Prints: 23</code></pre>
<h3>Passing wrapped objects around<a class="mark" href="#addons_passing_wrapped_objects_around" id="addons_passing_wrapped_objects_around">#</a></h3>
In addition to wrapping and returning C++ objects, it is possible to pass
wrapped objects around by unwrapping them with the Node.js helper function
<code>node::ObjectWrap::Unwrap</code>. The following examples shows a function <code>add()</code>
that can take two <code>MyObject</code> objects as input arguments:
<pre><code class="language-cpp">// addon.cc
#include &#x3C;node.h>
#include &#x3C;node_object_wrap.h>
#include "myobject.h"

namespace demo {

using v8::Context;
using v8::FunctionCallbackInfo;
using v8::Isolate;
using v8::Local;
using v8::Number;
using v8::Object;
using v8::String;
using v8::Value;

void Add(const FunctionCallbackInfo&#x3C;Value>&#x26; args) {
 Isolate* isolate = args.GetIsolate();
 Local&#x3C;Context> context = isolate->GetCurrentContext();

MyObject* obj1 = node::ObjectWrap::Unwrap&#x3C;MyObject>(
 args[0]->ToObject(context).ToLocalChecked());
 MyObject* obj2 = node::ObjectWrap::Unwrap&#x3C;MyObject>(
 args[1]->ToObject(context).ToLocalChecked());

double sum = obj1->value() + obj2->value();
 args.GetReturnValue().Set(Number::New(isolate, sum));
}

NODE_SET_METHOD(exports, "createObject", CreateObject);
 NODE_SET_METHOD(exports, "add", Add);
}

NODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)

} // namespace demo</code></pre>
In <code>myobject.h</code>, a new public method is added to allow access to private values
after unwrapping the object.
<pre><code class="language-cpp">// myobject.h
#ifndef MYOBJECT_H
#define MYOBJECT_H

namespace demo {

} // namespace demo

#endif</code></pre>
The implementation of <code>myobject.cc</code> is similar to before:
<pre><code class="language-cpp">// myobject.cc
#include &#x3C;node.h>
#include "myobject.h"

namespace demo {

using node::AddEnvironmentCleanupHook;
using v8::Context;
using v8::Function;
using v8::FunctionCallbackInfo;
using v8::FunctionTemplate;
using v8::Global;
using v8::Isolate;
using v8::Local;
using v8::NewStringType;
using v8::Object;
using v8::String;
using v8::Value;

// Warning! This is not thread-safe, this addon cannot be used for worker
// threads.
Global&#x3C;Function> MyObject::constructor;

MyObject::MyObject(double value) : value_(value) {
}

MyObject::~MyObject() {
}

Local&#x3C;Context> context = isolate->GetCurrentContext();
  constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());

AddEnvironmentCleanupHook(isolate, [](void*) {
 constructor.Reset();
 }, nullptr);
}

if (args.IsConstructCall()) {
 // Invoked as constructor: `new MyObject(...)`
 double value = args[0]->IsUndefined() ?
 0 : args[0]->NumberValue(context).FromMaybe(0);
 MyObject* obj = new MyObject(value);
 obj->Wrap(args.This());
 args.GetReturnValue().Set(args.This());
 } else {
 // Invoked as plain function `MyObject(...)`, turn into construct call.
 const int argc = 1;
 Local&#x3C;Value> argv[argc] = { args[0] };
 Local&#x3C;Function> cons = Local&#x3C;Function>::New(isolate, constructor);
 Local&#x3C;Object> instance =
 cons->NewInstance(context, argc, argv).ToLocalChecked();
 args.GetReturnValue().Set(instance);
 }
}

args.GetReturnValue().Set(instance);
}

} // namespace demo</code></pre>
Test it with:
<pre><code class="language-js">// test.js
const addon = require('./build/Release/addon');

const obj1 = addon.createObject(10);
const obj2 = addon.createObject(20);
const result = addon.add(obj1, obj2);

console.log(result);
// Prints: 30</code></pre>
 
 </div>
 </div>
 </div>
</body>
</html>

cmd: