Welcome to the official API reference documentation for Node.js!

Node.js is a JavaScript runtime built on the V8 JavaScript engine.

Report errors in this documentation in the issue tracker. See\nthe contributing guide for directions on how to submit pull requests.

Throughout the documentation are indications of a section's stability. Some APIs\nare so proven and so relied upon that they are unlikely to ever change at all.\nOthers are brand new and experimental, or known to be hazardous.

The stability indexes are as follows:

\n

Stability: 0 - Deprecated. The feature may emit warnings. Backward\ncompatibility is not guaranteed.

\n

\n

Stability: 1 - Experimental. The feature is not subject to\nsemantic versioning rules. Non-backward compatible changes or removal may\noccur in any future release. Use of the feature is not recommended in\nproduction environments.

\n

Experimental features are subdivided into stages:

\n

\n
• 1.0 - Early development. Experimental features at this stage are unfinished\nand subject to substantial change.
\n
• 1.1 - Active development. Experimental features at this stage are nearing\nminimum viability.
\n
• 1.2 - Release candidate. Experimental features at this stage are hopefully\nready to become stable. No further breaking changes are anticipated but may\nstill occur in response to user feedback or the features' underlying\nspecification development. We encourage user testing and feedback so that\nwe can know that this feature is ready to be marked as stable.
\n

\n

Experimental features leave the experimental status typically either by\ngraduating to stable, or are removed without a deprecation cycle.

\n

\n

Stability: 2 - Stable. Compatibility with the npm ecosystem is a high\npriority.

\n

\n

Stability: 3 - Legacy. Although this feature is unlikely to be removed and is\nstill covered by semantic versioning guarantees, it is no longer actively\nmaintained, and other alternatives are available.

\n

Features are marked as legacy rather than being deprecated if their use does no\nharm, and they are widely relied upon within the npm ecosystem. Bugs found in\nlegacy features are unlikely to be fixed.

Use caution when making use of Experimental features, particularly when\nauthoring libraries. Users may not be aware that experimental features are being\nused. Bugs or behavior changes may surprise users when Experimental API\nmodifications occur. To avoid surprises, use of an Experimental feature may need\na command-line flag. Experimental features may also emit a warning.

Every .html document has a corresponding .json document. This is for IDEs\nand other utilities that consume the documentation.

Node.js functions which wrap a system call will document that. The docs link\nto the corresponding man pages which describe how the system call works.

Most Unix system calls have Windows analogues. Still, behavior differences may\nbe unavoidable.

node [options] [V8 options] [script.js | -e \"script\" | - ] [arguments]

Please see the Command-line options document for more information.

An example of a web server written with Node.js which responds with\n'Hello, World!':

Commands in this document start with $ or > to replicate how they would\nappear in a user's terminal. Do not include the $ and > characters. They are\nthere to show the start of each command.

Lines that don't start with $ or > character show the output of the previous\ncommand.

First, make sure to have downloaded and installed Node.js. See\nInstalling Node.js via package manager for further install information.

Now, create an empty project folder called projects, then navigate into it.

Linux and Mac:

mkdir ~/projects\ncd ~/projects\n

Windows CMD:

mkdir %USERPROFILE%\\projects\ncd %USERPROFILE%\\projects\n

Windows PowerShell:

mkdir $env:USERPROFILE\\projects\ncd $env:USERPROFILE\\projects\n

Next, create a new source file in the projects\nfolder and call it hello-world.js.

Open hello-world.js in any preferred text editor and\npaste in the following content:

const http = require('node:http');\n\nconst hostname = '127.0.0.1';\nconst port = 3000;\n\nconst server = http.createServer((req, res) => {\n  res.statusCode = 200;\n  res.setHeader('Content-Type', 'text/plain');\n  res.end('Hello, World!\\n');\n});\n\nserver.listen(port, hostname, () => {\n  console.log(`Server running at http://${hostname}:${port}/`);\n});\n

Save the file. Then, in the terminal window, to run the hello-world.js file,\nenter:

node hello-world.js\n

Output like this should appear in the terminal:

Server running at http://127.0.0.1:3000/\n

Now, open any preferred web browser and visit http://127.0.0.1:3000.

If the browser displays the string Hello, World!, that indicates\nthe server is working.

Addons are dynamically-linked shared objects written in C++. The\nrequire() function can load addons as ordinary Node.js modules.\nAddons provide an interface between JavaScript and C/C++ libraries.

There are three options for implementing addons:

\n
• Node-API
\n
• nan (Native Abstractions for Node.js)
\n
• direct use of internal V8, libuv, and Node.js libraries
\n

Unless there is a need for direct access to functionality which is not
\nexposed by Node-API, use Node-API.\nRefer to C/C++ addons with Node-API for more information on\nNode-API.

When not using Node-API, implementing addons becomes more complex, requiring
\nknowledge of multiple components and APIs:

\n
• \n

  V8: the C++ library Node.js uses to provide the\nJavaScript implementation. It provides the mechanisms for creating objects,\ncalling functions, etc. The V8's API is documented mostly in the\nv8.h header file (deps/v8/include/v8.h in the Node.js source\ntree), and is also available online.

  \n
\n
• \n

  libuv: The C library that implements the Node.js event loop, its worker\nthreads and all of the asynchronous behaviors of the platform. It also\nserves as a cross-platform abstraction library, giving easy, POSIX-like\naccess across all major operating systems to many common system tasks, such\nas interacting with the file system, sockets, timers, and system events. libuv\nalso provides a threading abstraction similar to POSIX threads for\nmore sophisticated asynchronous addons that need to move beyond the\nstandard event loop. Addon authors should\navoid blocking the event loop with I/O or other time-intensive tasks by\noffloading work via libuv to non-blocking system operations, worker threads,\nor a custom use of libuv threads.

  \n
\n
• \n

  Internal Node.js libraries: Node.js itself exports C++ APIs that addons can\nuse, the most important of which is the node::ObjectWrap class.

  \n
\n
• \n

  Other statically linked libraries (including OpenSSL): These\nother libraries are located in the deps/ directory in the Node.js source\ntree. Only the libuv, OpenSSL, V8, and zlib symbols are purposefully\nre-exported by Node.js and may be used to various extents by addons. See\nLinking to libraries included with Node.js for additional information.

  \n
\n

All of the following examples are available for download and may\nbe used as the starting-point for an addon.

This \"Hello world\" example is a simple addon, written in C++, that is the\nequivalent of the following JavaScript code:

module.exports.hello = () => 'world';\n

First, create the file hello.cc:

// hello.cc\n#include <node.h>\n\nnamespace demo {\n\nusing v8::FunctionCallbackInfo;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::NewStringType;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\nvoid Method(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n  args.GetReturnValue().Set(String::NewFromUtf8(\n      isolate, \"world\", NewStringType::kNormal).ToLocalChecked());\n}\n\nvoid Initialize(Local<Object> exports) {\n  NODE_SET_METHOD(exports, \"hello\", Method);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)\n\n}  // namespace demo\n

All Node.js addons must export an initialization function following\nthe pattern:

void Initialize(Local<Object> exports);\nNODE_MODULE(NODE_GYP_MODULE_NAME, Initialize)\n

There is no semi-colon after NODE_MODULE as it's not a function (see\nnode.h).

The module_name must match the filename of the final binary (excluding\nthe .node suffix).

In the hello.cc example, then, the initialization function is Initialize\nand the addon module name is addon.

When building addons with node-gyp, using the macro NODE_GYP_MODULE_NAME as\nthe first parameter of NODE_MODULE() will ensure that the name of the final\nbinary will be passed to NODE_MODULE().

Addons defined with NODE_MODULE() can not be loaded in multiple contexts or\nmultiple threads at the same time.

There are environments in which Node.js addons may need to be loaded multiple\ntimes in multiple contexts. For example, the Electron runtime runs multiple\ninstances of Node.js in a single process. Each instance will have its own\nrequire() cache, and thus each instance will need a native addon to behave\ncorrectly when loaded via require(). This means that the addon\nmust support multiple initializations.

A context-aware addon can be constructed by using the macro\nNODE_MODULE_INITIALIZER, which expands to the name of a function which Node.js\nwill expect to find when it loads an addon. An addon can thus be initialized as\nin the following example:

using namespace v8;\n\nextern \"C\" NODE_MODULE_EXPORT void\nNODE_MODULE_INITIALIZER(Local<Object> exports,\n                        Local<Value> module,\n                        Local<Context> context) {\n  /* Perform addon initialization steps here. */\n}\n

Another option is to use the macro NODE_MODULE_INIT(), which will also\nconstruct a context-aware addon. Unlike NODE_MODULE(), which is used to\nconstruct an addon around a given addon initializer function,\nNODE_MODULE_INIT() serves as the declaration of such an initializer to be\nfollowed by a function body.

The following three variables may be used inside the function body following an\ninvocation of NODE_MODULE_INIT():

\n
• Local<Object> exports,
\n
• Local<Value> module, and
\n
• Local<Context> context
\n

Building a context-aware addon requires careful management of global static data\nto ensure stability and correctness. Since the addon may be loaded multiple\ntimes, potentially even from different threads, any global static data stored\nin the addon must be properly protected, and must not contain any persistent\nreferences to JavaScript objects. The reason for this is that JavaScript\nobjects are only valid in one context, and will likely cause a crash when\naccessed from the wrong context or from a different thread than the one on which\nthey were created.

The context-aware addon can be structured to avoid global static data by\nperforming the following steps:

\n
• Define a class which will hold per-addon-instance data and which has a static\nmember of the form\n

  static void DeleteInstance(void* data) {\n  // Cast `data` to an instance of the class and delete it.\n}\n

  \n
\n
• Heap-allocate an instance of this class in the addon initializer. This can be\naccomplished using the new keyword.
\n
• Call node::AddEnvironmentCleanupHook(), passing it the above-created\ninstance and a pointer to DeleteInstance(). This will ensure the instance is\ndeleted when the environment is torn down.
\n
• Store the instance of the class in a v8::External, and
\n
• Pass the v8::External to all methods exposed to JavaScript by passing it\nto v8::FunctionTemplate::New() or v8::Function::New() which creates the\nnative-backed JavaScript functions. The third parameter of\nv8::FunctionTemplate::New() or v8::Function::New() accepts the\nv8::External and makes it available in the native callback using the\nv8::FunctionCallbackInfo::Data() method.
\n

This will ensure that the per-addon-instance data reaches each binding that can\nbe called from JavaScript. The per-addon-instance data must also be passed into\nany asynchronous callbacks the addon may create.

The following example illustrates the implementation of a context-aware addon:

#include <node.h>\n\nusing namespace v8;\n\nclass AddonData {\n public:\n  explicit AddonData(Isolate* isolate):\n      call_count(0) {\n    // Ensure this per-addon-instance data is deleted at environment cleanup.\n    node::AddEnvironmentCleanupHook(isolate, DeleteInstance, this);\n  }\n\n  // Per-addon data.\n  int call_count;\n\n  static void DeleteInstance(void* data) {\n    delete static_cast<AddonData*>(data);\n  }\n};\n\nstatic void Method(const v8::FunctionCallbackInfo<v8::Value>& info) {\n  // Retrieve the per-addon-instance data.\n  AddonData* data =\n      reinterpret_cast<AddonData*>(info.Data().As<External>()->Value());\n  data->call_count++;\n  info.GetReturnValue().Set((double)data->call_count);\n}\n\n// Initialize this addon to be context-aware.\nNODE_MODULE_INIT(/* exports, module, context */) {\n  Isolate* isolate = Isolate::GetCurrent();\n\n  // Create a new instance of `AddonData` for this instance of the addon and\n  // tie its life cycle to that of the Node.js environment.\n  AddonData* data = new AddonData(isolate);\n\n  // Wrap the data in a `v8::External` so we can pass it to the method we\n  // expose.\n  Local<External> external = External::New(isolate, data);\n\n  // Expose the method `Method` to JavaScript, and make sure it receives the\n  // per-addon-instance data we created above by passing `external` as the\n  // third parameter to the `FunctionTemplate` constructor.\n  exports->Set(context,\n               String::NewFromUtf8(isolate, \"method\").ToLocalChecked(),\n               FunctionTemplate::New(isolate, Method, external)\n                  ->GetFunction(context).ToLocalChecked()).FromJust();\n}\n

In order to be loaded from multiple Node.js environments,\nsuch as a main thread and a Worker thread, an add-on needs to either:

\n
• Be an Node-API addon, or
\n
• Be declared as context-aware using NODE_MODULE_INIT() as described above
\n

In order to support Worker threads, addons need to clean up any resources\nthey may have allocated when such a thread exits. This can be achieved through\nthe usage of the AddEnvironmentCleanupHook() function:

void AddEnvironmentCleanupHook(v8::Isolate* isolate,\n                               void (*fun)(void* arg),\n                               void* arg);\n

This function adds a hook that will run before a given Node.js instance shuts\ndown. If necessary, such hooks can be removed before they are run using\nRemoveEnvironmentCleanupHook(), which has the same signature. Callbacks are\nrun in last-in first-out order.

If necessary, there is an additional pair of AddEnvironmentCleanupHook()\nand RemoveEnvironmentCleanupHook() overloads, where the cleanup hook takes a\ncallback function. This can be used for shutting down asynchronous resources,\nsuch as any libuv handles registered by the addon.

The following addon.cc uses AddEnvironmentCleanupHook:

// addon.cc\n#include <node.h>\n#include <assert.h>\n#include <stdlib.h>\n\nusing node::AddEnvironmentCleanupHook;\nusing v8::HandleScope;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Object;\n\n// Note: In a real-world application, do not rely on static/global data.\nstatic char cookie[] = \"yum yum\";\nstatic int cleanup_cb1_called = 0;\nstatic int cleanup_cb2_called = 0;\n\nstatic void cleanup_cb1(void* arg) {\n  Isolate* isolate = static_cast<Isolate*>(arg);\n  HandleScope scope(isolate);\n  Local<Object> obj = Object::New(isolate);\n  assert(!obj.IsEmpty());  // assert VM is still alive\n  assert(obj->IsObject());\n  cleanup_cb1_called++;\n}\n\nstatic void cleanup_cb2(void* arg) {\n  assert(arg == static_cast<void*>(cookie));\n  cleanup_cb2_called++;\n}\n\nstatic void sanity_check(void*) {\n  assert(cleanup_cb1_called == 1);\n  assert(cleanup_cb2_called == 1);\n}\n\n// Initialize this addon to be context-aware.\nNODE_MODULE_INIT(/* exports, module, context */) {\n  Isolate* isolate = Isolate::GetCurrent();\n\n  AddEnvironmentCleanupHook(isolate, sanity_check, nullptr);\n  AddEnvironmentCleanupHook(isolate, cleanup_cb2, cookie);\n  AddEnvironmentCleanupHook(isolate, cleanup_cb1, isolate);\n}\n

Test in JavaScript by running:

// test.js\nrequire('./build/Release/addon');\n

Once the source code has been written, it must be compiled into the binary\naddon.node file. To do so, create a file called binding.gyp in the\ntop-level of the project describing the build configuration of the module\nusing a JSON-like format. This file is used by node-gyp, a tool written\nspecifically to compile Node.js addons.

{\n  \"targets\": [\n    {\n      \"target_name\": \"addon\",\n      \"sources\": [ \"hello.cc\" ]\n    }\n  ]\n}\n

A version of the node-gyp utility is bundled and distributed with\nNode.js as part of npm. This version is not made directly available for\ndevelopers to use and is intended only to support the ability to use the\nnpm install command to compile and install addons. Developers who wish to\nuse node-gyp directly can install it using the command\nnpm install -g node-gyp. See the node-gyp installation instructions for\nmore information, including platform-specific requirements.

Once the binding.gyp file has been created, use node-gyp configure to\ngenerate the appropriate project build files for the current platform. This\nwill generate either a Makefile (on Unix platforms) or a vcxproj file\n(on Windows) in the build/ directory.

Next, invoke the node-gyp build command to generate the compiled addon.node\nfile. This will be put into the build/Release/ directory.

When using npm install to install a Node.js addon, npm uses its own bundled\nversion of node-gyp to perform this same set of actions, generating a\ncompiled 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\nrequire() to the built addon.node module:

// hello.js\nconst addon = require('./build/Release/addon');\n\nconsole.log(addon.hello());\n// Prints: 'world'\n

Because the exact path to the compiled addon binary can vary depending on how\nit is compiled (i.e. sometimes it may be in ./build/Debug/), addons can use\nthe bindings package to load the compiled module.

While the bindings package implementation is more sophisticated in how it\nlocates addon modules, it is essentially using a try…catch pattern similar to:

try {\n  return require('./build/Release/addon.node');\n} catch (err) {\n  return require('./build/Debug/addon.node');\n}\n

Node.js uses statically linked libraries such as V8, libuv, and OpenSSL. All\naddons are required to link to V8 and may link to any of the other dependencies\nas well. Typically, this is as simple as including the appropriate\n#include <...> statements (e.g. #include <v8.h>) and node-gyp will locate\nthe appropriate headers automatically. However, there are a few caveats to be\naware of:

\n
• \n

  When node-gyp runs, it will detect the specific release version of Node.js\nand download either the full source tarball or just the headers. If the full\nsource is downloaded, addons will have complete access to the full set of\nNode.js dependencies. However, if only the Node.js headers are downloaded,\nthen only the symbols exported by Node.js will be available.

  \n
\n
• \n

  node-gyp can be run using the --nodedir flag pointing at a local Node.js\nsource image. Using this option, the addon will have access to the full set of\ndependencies.

  \n
\n

The filename extension of the compiled addon binary is .node (as opposed\nto .dll or .so). The require() function is written to look for\nfiles with the .node file extension and initialize those as dynamically-linked\nlibraries.

When calling require(), the .node extension can usually be\nomitted and Node.js will still find and initialize the addon. One caveat,\nhowever, is that Node.js will first attempt to locate and load modules or\nJavaScript files that happen to share the same base name. For instance, if\nthere is a file addon.js in the same directory as the binary addon.node,\nthen require('addon') will give precedence to the addon.js file\nand load it instead.

Each of the examples illustrated in this document directly use the\nNode.js and V8 APIs for implementing addons. The V8 API can, and has, changed\ndramatically from one V8 release to the next (and one major Node.js release to\nthe next). With each change, addons may need to be updated and recompiled in\norder to continue functioning. The Node.js release schedule is designed to\nminimize the frequency and impact of such changes but there is little that\nNode.js can do to ensure stability of the V8 APIs.

The Native Abstractions for Node.js (or nan) provide a set of tools that\naddon developers are recommended to use to keep compatibility between past and\nfuture releases of V8 and Node.js. See the nan examples for an\nillustration of how it can be used.

Node-API is an API for building native addons. It is independent from\nthe underlying JavaScript runtime (e.g. V8) and is maintained as part of\nNode.js itself. This API will be Application Binary Interface (ABI) stable\nacross versions of Node.js. It is intended to insulate addons from\nchanges in the underlying JavaScript engine and allow modules\ncompiled for one version to run on later versions of Node.js without\nrecompilation. Addons are built/packaged with the same approach/tools\noutlined in this document (node-gyp, etc.). The only difference is the\nset of APIs that are used by the native code. Instead of using the V8\nor Native Abstractions for Node.js APIs, the functions available\nin the Node-API are used.

Creating and maintaining an addon that benefits from the ABI stability\nprovided by Node-API carries with it certain\nimplementation considerations.

To use Node-API in the above \"Hello world\" example, replace the content of\nhello.cc with the following. All other instructions remain the same.

// hello.cc using Node-API\n#include <node_api.h>\n\nnamespace demo {\n\nnapi_value Method(napi_env env, napi_callback_info args) {\n  napi_value greeting;\n  napi_status status;\n\n  status = napi_create_string_utf8(env, \"world\", NAPI_AUTO_LENGTH, &greeting);\n  if (status != napi_ok) return nullptr;\n  return greeting;\n}\n\nnapi_value init(napi_env env, napi_value exports) {\n  napi_status status;\n  napi_value fn;\n\n  status = napi_create_function(env, nullptr, 0, Method, nullptr, &fn);\n  if (status != napi_ok) return nullptr;\n\n  status = napi_set_named_property(env, exports, \"hello\", fn);\n  if (status != napi_ok) return nullptr;\n  return exports;\n}\n\nNAPI_MODULE(NODE_GYP_MODULE_NAME, init)\n\n}  // namespace demo\n

The functions available and how to use them are documented in\nC/C++ addons with Node-API.

Following are some example addons intended to help developers get started. The\nexamples use the V8 APIs. Refer to the online V8 reference\nfor help with the various V8 calls, and V8's Embedder's Guide for an\nexplanation of several concepts used such as handles, scopes, function\ntemplates, etc.

Each of these examples using the following binding.gyp file:

{\n  \"targets\": [\n    {\n      \"target_name\": \"addon\",\n      \"sources\": [ \"addon.cc\" ]\n    }\n  ]\n}\n

In cases where there is more than one .cc file, simply add the additional\nfilename to the sources array:

\"sources\": [\"addon.cc\", \"myexample.cc\"]\n

Once the binding.gyp file is ready, the example addons can be configured and\nbuilt using node-gyp:

node-gyp configure build\n

Addons will typically expose objects and functions that can be accessed from\nJavaScript running within Node.js. When functions are invoked from JavaScript,\nthe input arguments and return value must be mapped to and from the C/C++\ncode.

The following example illustrates how to read function arguments passed from\nJavaScript and how to return a result:

// addon.cc\n#include <node.h>\n\nnamespace demo {\n\nusing v8::Exception;\nusing v8::FunctionCallbackInfo;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Number;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\n// This is the implementation of the \"add\" method\n// Input arguments are passed using the\n// const FunctionCallbackInfo<Value>& args struct\nvoid Add(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n\n  // Check the number of arguments passed.\n  if (args.Length() < 2) {\n    // Throw an Error that is passed back to JavaScript\n    isolate->ThrowException(Exception::TypeError(\n        String::NewFromUtf8(isolate,\n                            \"Wrong number of arguments\").ToLocalChecked()));\n    return;\n  }\n\n  // Check the argument types\n  if (!args[0]->IsNumber() || !args[1]->IsNumber()) {\n    isolate->ThrowException(Exception::TypeError(\n        String::NewFromUtf8(isolate,\n                            \"Wrong arguments\").ToLocalChecked()));\n    return;\n  }\n\n  // Perform the operation\n  double value =\n      args[0].As<Number>()->Value() + args[1].As<Number>()->Value();\n  Local<Number> num = Number::New(isolate, value);\n\n  // Set the return value (using the passed in\n  // FunctionCallbackInfo<Value>&)\n  args.GetReturnValue().Set(num);\n}\n\nvoid Init(Local<Object> exports) {\n  NODE_SET_METHOD(exports, \"add\", Add);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, Init)\n\n}  // namespace demo\n

Once compiled, the example addon can be required and used from within Node.js:

// test.js\nconst addon = require('./build/Release/addon');\n\nconsole.log('This should be eight:', addon.add(3, 5));\n

It is common practice within addons to pass JavaScript functions to a C++\nfunction and execute them from there. The following example illustrates how\nto invoke such callbacks:

// addon.cc\n#include <node.h>\n\nnamespace demo {\n\nusing v8::Context;\nusing v8::Function;\nusing v8::FunctionCallbackInfo;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Null;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\nvoid RunCallback(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n  Local<Context> context = isolate->GetCurrentContext();\n  Local<Function> cb = Local<Function>::Cast(args[0]);\n  const unsigned argc = 1;\n  Local<Value> argv[argc] = {\n      String::NewFromUtf8(isolate,\n                          \"hello world\").ToLocalChecked() };\n  cb->Call(context, Null(isolate), argc, argv).ToLocalChecked();\n}\n\nvoid Init(Local<Object> exports, Local<Object> module) {\n  NODE_SET_METHOD(module, \"exports\", RunCallback);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, Init)\n\n}  // namespace demo\n

This example uses a two-argument form of Init() that receives the full\nmodule object as the second argument. This allows the addon to completely\noverwrite exports with a single function instead of adding the function as a\nproperty of exports.

To test it, run the following JavaScript:

// test.js\nconst addon = require('./build/Release/addon');\n\naddon((msg) => {\n  console.log(msg);\n// Prints: 'hello world'\n});\n

In this example, the callback function is invoked synchronously.

Addons can create and return new objects from within a C++ function as\nillustrated in the following example. An object is created and returned with a\nproperty msg that echoes the string passed to createObject():

// addon.cc\n#include <node.h>\n\nnamespace demo {\n\nusing v8::Context;\nusing v8::FunctionCallbackInfo;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\nvoid CreateObject(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n  Local<Context> context = isolate->GetCurrentContext();\n\n  Local<Object> obj = Object::New(isolate);\n  obj->Set(context,\n           String::NewFromUtf8(isolate,\n                               \"msg\").ToLocalChecked(),\n                               args[0]->ToString(context).ToLocalChecked())\n           .FromJust();\n\n  args.GetReturnValue().Set(obj);\n}\n\nvoid Init(Local<Object> exports, Local<Object> module) {\n  NODE_SET_METHOD(module, \"exports\", CreateObject);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, Init)\n\n}  // namespace demo\n

To test it in JavaScript:

// test.js\nconst addon = require('./build/Release/addon');\n\nconst obj1 = addon('hello');\nconst obj2 = addon('world');\nconsole.log(obj1.msg, obj2.msg);\n// Prints: 'hello world'\n

Another common scenario is creating JavaScript functions that wrap C++\nfunctions and returning those back to JavaScript:

// addon.cc\n#include <node.h>\n\nnamespace demo {\n\nusing v8::Context;\nusing v8::Function;\nusing v8::FunctionCallbackInfo;\nusing v8::FunctionTemplate;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\nvoid MyFunction(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n  args.GetReturnValue().Set(String::NewFromUtf8(\n      isolate, \"hello world\").ToLocalChecked());\n}\n\nvoid CreateFunction(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n\n  Local<Context> context = isolate->GetCurrentContext();\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, MyFunction);\n  Local<Function> fn = tpl->GetFunction(context).ToLocalChecked();\n\n  // omit this to make it anonymous\n  fn->SetName(String::NewFromUtf8(\n      isolate, \"theFunction\").ToLocalChecked());\n\n  args.GetReturnValue().Set(fn);\n}\n\nvoid Init(Local<Object> exports, Local<Object> module) {\n  NODE_SET_METHOD(module, \"exports\", CreateFunction);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, Init)\n\n}  // namespace demo\n

To test:

// test.js\nconst addon = require('./build/Release/addon');\n\nconst fn = addon();\nconsole.log(fn());\n// Prints: 'hello world'\n

It is also possible to wrap C++ objects/classes in a way that allows new\ninstances to be created using the JavaScript new operator:

// addon.cc\n#include <node.h>\n#include \"myobject.h\"\n\nnamespace demo {\n\nusing v8::Local;\nusing v8::Object;\n\nvoid InitAll(Local<Object> exports) {\n  MyObject::Init(exports);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)\n\n}  // namespace demo\n

Then, in myobject.h, the wrapper class inherits from node::ObjectWrap:

// myobject.h\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n#include <node_object_wrap.h>\n\nnamespace demo {\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init(v8::Local<v8::Object> exports);\n\n private:\n  explicit MyObject(double value = 0);\n  ~MyObject();\n\n  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);\n  static void PlusOne(const v8::FunctionCallbackInfo<v8::Value>& args);\n\n  double value_;\n};\n\n}  // namespace demo\n\n#endif\n

In myobject.cc, implement the various methods that are to be exposed.\nIn the following code, the method plusOne() is exposed by adding it to the\nconstructor's prototype:

// myobject.cc\n#include \"myobject.h\"\n\nnamespace demo {\n\nusing v8::Context;\nusing v8::Function;\nusing v8::FunctionCallbackInfo;\nusing v8::FunctionTemplate;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Number;\nusing v8::Object;\nusing v8::ObjectTemplate;\nusing v8::String;\nusing v8::Value;\n\nMyObject::MyObject(double value) : value_(value) {\n}\n\nMyObject::~MyObject() {\n}\n\nvoid MyObject::Init(Local<Object> exports) {\n  Isolate* isolate = Isolate::GetCurrent();\n  Local<Context> context = isolate->GetCurrentContext();\n\n  Local<ObjectTemplate> addon_data_tpl = ObjectTemplate::New(isolate);\n  addon_data_tpl->SetInternalFieldCount(1);  // 1 field for the MyObject::New()\n  Local<Object> addon_data =\n      addon_data_tpl->NewInstance(context).ToLocalChecked();\n\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New, addon_data);\n  tpl->SetClassName(String::NewFromUtf8(isolate, \"MyObject\").ToLocalChecked());\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n  // Prototype\n  NODE_SET_PROTOTYPE_METHOD(tpl, \"plusOne\", PlusOne);\n\n  Local<Function> constructor = tpl->GetFunction(context).ToLocalChecked();\n  addon_data->SetInternalField(0, constructor);\n  exports->Set(context, String::NewFromUtf8(\n      isolate, \"MyObject\").ToLocalChecked(),\n      constructor).FromJust();\n}\n\nvoid MyObject::New(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n  Local<Context> context = isolate->GetCurrentContext();\n\n  if (args.IsConstructCall()) {\n    // Invoked as constructor: `new MyObject(...)`\n    double value = args[0]->IsUndefined() ?\n        0 : args[0]->NumberValue(context).FromMaybe(0);\n    MyObject* obj = new MyObject(value);\n    obj->Wrap(args.This());\n    args.GetReturnValue().Set(args.This());\n  } else {\n    // Invoked as plain function `MyObject(...)`, turn into construct call.\n    const int argc = 1;\n    Local<Value> argv[argc] = { args[0] };\n    Local<Function> cons =\n        args.Data().As<Object>()->GetInternalField(0)\n            .As<Value>().As<Function>();\n    Local<Object> result =\n        cons->NewInstance(context, argc, argv).ToLocalChecked();\n    args.GetReturnValue().Set(result);\n  }\n}\n\nvoid MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->value_ += 1;\n\n  args.GetReturnValue().Set(Number::New(isolate, obj->value_));\n}\n\n}  // namespace demo\n

To build this example, the myobject.cc file must be added to the\nbinding.gyp:

{\n  \"targets\": [\n    {\n      \"target_name\": \"addon\",\n      \"sources\": [\n        \"addon.cc\",\n        \"myobject.cc\"\n      ]\n    }\n  ]\n}\n

Test it with:

// test.js\nconst addon = require('./build/Release/addon');\n\nconst obj = new addon.MyObject(10);\nconsole.log(obj.plusOne());\n// Prints: 11\nconsole.log(obj.plusOne());\n// Prints: 12\nconsole.log(obj.plusOne());\n// Prints: 13\n

The destructor for a wrapper object will run when the object is\ngarbage-collected. For destructor testing, there are command-line flags that\ncan be used to make it possible to force garbage collection. These flags are\nprovided by the underlying V8 JavaScript engine. They are subject to change\nor removal at any time. They are not documented by Node.js or V8, and they\nshould never be used outside of testing.

During shutdown of the process or worker threads destructors are not called\nby the JS engine. Therefore it's the responsibility of the user to track\nthese objects and ensure proper destruction to avoid resource leaks.

Alternatively, it is possible to use a factory pattern to avoid explicitly\ncreating object instances using the JavaScript new operator:

const obj = addon.createObject();\n// instead of:\n// const obj = new addon.Object();\n

First, the createObject() method is implemented in addon.cc:

// addon.cc\n#include <node.h>\n#include \"myobject.h\"\n\nnamespace demo {\n\nusing v8::FunctionCallbackInfo;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\nvoid CreateObject(const FunctionCallbackInfo<Value>& args) {\n  MyObject::NewInstance(args);\n}\n\nvoid InitAll(Local<Object> exports, Local<Object> module) {\n  MyObject::Init();\n\n  NODE_SET_METHOD(module, \"exports\", CreateObject);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)\n\n}  // namespace demo\n

In myobject.h, the static method NewInstance() is added to handle\ninstantiating the object. This method takes the place of using new in\nJavaScript:

// myobject.h\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n#include <node_object_wrap.h>\n\nnamespace demo {\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static void NewInstance(const v8::FunctionCallbackInfo<v8::Value>& args);\n\n private:\n  explicit MyObject(double value = 0);\n  ~MyObject();\n\n  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);\n  static void PlusOne(const v8::FunctionCallbackInfo<v8::Value>& args);\n  static v8::Global<v8::Function> constructor;\n  double value_;\n};\n\n}  // namespace demo\n\n#endif\n

The implementation in myobject.cc is similar to the previous example:

// myobject.cc\n#include <node.h>\n#include \"myobject.h\"\n\nnamespace demo {\n\nusing node::AddEnvironmentCleanupHook;\nusing v8::Context;\nusing v8::Function;\nusing v8::FunctionCallbackInfo;\nusing v8::FunctionTemplate;\nusing v8::Global;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Number;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\n// Warning! This is not thread-safe, this addon cannot be used for worker\n// threads.\nGlobal<Function> MyObject::constructor;\n\nMyObject::MyObject(double value) : value_(value) {\n}\n\nMyObject::~MyObject() {\n}\n\nvoid MyObject::Init() {\n  Isolate* isolate = Isolate::GetCurrent();\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New);\n  tpl->SetClassName(String::NewFromUtf8(isolate, \"MyObject\").ToLocalChecked());\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n  // Prototype\n  NODE_SET_PROTOTYPE_METHOD(tpl, \"plusOne\", PlusOne);\n\n  Local<Context> context = isolate->GetCurrentContext();\n  constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());\n\n  AddEnvironmentCleanupHook(isolate, [](void*) {\n    constructor.Reset();\n  }, nullptr);\n}\n\nvoid MyObject::New(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n  Local<Context> context = isolate->GetCurrentContext();\n\n  if (args.IsConstructCall()) {\n    // Invoked as constructor: `new MyObject(...)`\n    double value = args[0]->IsUndefined() ?\n        0 : args[0]->NumberValue(context).FromMaybe(0);\n    MyObject* obj = new MyObject(value);\n    obj->Wrap(args.This());\n    args.GetReturnValue().Set(args.This());\n  } else {\n    // Invoked as plain function `MyObject(...)`, turn into construct call.\n    const int argc = 1;\n    Local<Value> argv[argc] = { args[0] };\n    Local<Function> cons = Local<Function>::New(isolate, constructor);\n    Local<Object> instance =\n        cons->NewInstance(context, argc, argv).ToLocalChecked();\n    args.GetReturnValue().Set(instance);\n  }\n}\n\nvoid MyObject::NewInstance(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n\n  const unsigned argc = 1;\n  Local<Value> argv[argc] = { args[0] };\n  Local<Function> cons = Local<Function>::New(isolate, constructor);\n  Local<Context> context = isolate->GetCurrentContext();\n  Local<Object> instance =\n      cons->NewInstance(context, argc, argv).ToLocalChecked();\n\n  args.GetReturnValue().Set(instance);\n}\n\nvoid MyObject::PlusOne(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n\n  MyObject* obj = ObjectWrap::Unwrap<MyObject>(args.This());\n  obj->value_ += 1;\n\n  args.GetReturnValue().Set(Number::New(isolate, obj->value_));\n}\n\n}  // namespace demo\n

Once again, to build this example, the myobject.cc file must be added to the\nbinding.gyp:

{\n  \"targets\": [\n    {\n      \"target_name\": \"addon\",\n      \"sources\": [\n        \"addon.cc\",\n        \"myobject.cc\"\n      ]\n    }\n  ]\n}\n

Test it with:

// test.js\nconst createObject = require('./build/Release/addon');\n\nconst obj = createObject(10);\nconsole.log(obj.plusOne());\n// Prints: 11\nconsole.log(obj.plusOne());\n// Prints: 12\nconsole.log(obj.plusOne());\n// Prints: 13\n\nconst obj2 = createObject(20);\nconsole.log(obj2.plusOne());\n// Prints: 21\nconsole.log(obj2.plusOne());\n// Prints: 22\nconsole.log(obj2.plusOne());\n// Prints: 23\n

In addition to wrapping and returning C++ objects, it is possible to pass\nwrapped objects around by unwrapping them with the Node.js helper function\nnode::ObjectWrap::Unwrap. The following examples shows a function add()\nthat can take two MyObject objects as input arguments:

// addon.cc\n#include <node.h>\n#include <node_object_wrap.h>\n#include \"myobject.h\"\n\nnamespace demo {\n\nusing v8::Context;\nusing v8::FunctionCallbackInfo;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Number;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\nvoid CreateObject(const FunctionCallbackInfo<Value>& args) {\n  MyObject::NewInstance(args);\n}\n\nvoid Add(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n  Local<Context> context = isolate->GetCurrentContext();\n\n  MyObject* obj1 = node::ObjectWrap::Unwrap<MyObject>(\n      args[0]->ToObject(context).ToLocalChecked());\n  MyObject* obj2 = node::ObjectWrap::Unwrap<MyObject>(\n      args[1]->ToObject(context).ToLocalChecked());\n\n  double sum = obj1->value() + obj2->value();\n  args.GetReturnValue().Set(Number::New(isolate, sum));\n}\n\nvoid InitAll(Local<Object> exports) {\n  MyObject::Init();\n\n  NODE_SET_METHOD(exports, \"createObject\", CreateObject);\n  NODE_SET_METHOD(exports, \"add\", Add);\n}\n\nNODE_MODULE(NODE_GYP_MODULE_NAME, InitAll)\n\n}  // namespace demo\n

In myobject.h, a new public method is added to allow access to private values\nafter unwrapping the object.

// myobject.h\n#ifndef MYOBJECT_H\n#define MYOBJECT_H\n\n#include <node.h>\n#include <node_object_wrap.h>\n\nnamespace demo {\n\nclass MyObject : public node::ObjectWrap {\n public:\n  static void Init();\n  static void NewInstance(const v8::FunctionCallbackInfo<v8::Value>& args);\n  inline double value() const { return value_; }\n\n private:\n  explicit MyObject(double value = 0);\n  ~MyObject();\n\n  static void New(const v8::FunctionCallbackInfo<v8::Value>& args);\n  static v8::Global<v8::Function> constructor;\n  double value_;\n};\n\n}  // namespace demo\n\n#endif\n

The implementation of myobject.cc remains similar to the previous version:

// myobject.cc\n#include <node.h>\n#include \"myobject.h\"\n\nnamespace demo {\n\nusing node::AddEnvironmentCleanupHook;\nusing v8::Context;\nusing v8::Function;\nusing v8::FunctionCallbackInfo;\nusing v8::FunctionTemplate;\nusing v8::Global;\nusing v8::Isolate;\nusing v8::Local;\nusing v8::Object;\nusing v8::String;\nusing v8::Value;\n\n// Warning! This is not thread-safe, this addon cannot be used for worker\n// threads.\nGlobal<Function> MyObject::constructor;\n\nMyObject::MyObject(double value) : value_(value) {\n}\n\nMyObject::~MyObject() {\n}\n\nvoid MyObject::Init() {\n  Isolate* isolate = Isolate::GetCurrent();\n  // Prepare constructor template\n  Local<FunctionTemplate> tpl = FunctionTemplate::New(isolate, New);\n  tpl->SetClassName(String::NewFromUtf8(isolate, \"MyObject\").ToLocalChecked());\n  tpl->InstanceTemplate()->SetInternalFieldCount(1);\n\n  Local<Context> context = isolate->GetCurrentContext();\n  constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked());\n\n  AddEnvironmentCleanupHook(isolate, [](void*) {\n    constructor.Reset();\n  }, nullptr);\n}\n\nvoid MyObject::New(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n  Local<Context> context = isolate->GetCurrentContext();\n\n  if (args.IsConstructCall()) {\n    // Invoked as constructor: `new MyObject(...)`\n    double value = args[0]->IsUndefined() ?\n        0 : args[0]->NumberValue(context).FromMaybe(0);\n    MyObject* obj = new MyObject(value);\n    obj->Wrap(args.This());\n    args.GetReturnValue().Set(args.This());\n  } else {\n    // Invoked as plain function `MyObject(...)`, turn into construct call.\n    const int argc = 1;\n    Local<Value> argv[argc] = { args[0] };\n    Local<Function> cons = Local<Function>::New(isolate, constructor);\n    Local<Object> instance =\n        cons->NewInstance(context, argc, argv).ToLocalChecked();\n    args.GetReturnValue().Set(instance);\n  }\n}\n\nvoid MyObject::NewInstance(const FunctionCallbackInfo<Value>& args) {\n  Isolate* isolate = args.GetIsolate();\n\n  const unsigned argc = 1;\n  Local<Value> argv[argc] = { args[0] };\n  Local<Function> cons = Local<Function>::New(isolate, constructor);\n  Local<Context> context = isolate->GetCurrentContext();\n  Local<Object> instance =\n      cons->NewInstance(context, argc, argv).ToLocalChecked();\n\n  args.GetReturnValue().Set(instance);\n}\n\n}  // namespace demo\n

Test it with:

// test.js\nconst addon = require('./build/Release/addon');\n\nconst obj1 = addon.createObject(10);\nconst obj2 = addon.createObject(20);\nconst result = addon.add(obj1, obj2);\n\nconsole.log(result);\n// Prints: 30\n

Node-API (formerly N-API) is an API for building native Addons. It is\nindependent from the underlying JavaScript runtime (for example, V8) and is\nmaintained as part of Node.js itself. This API will be Application Binary\nInterface (ABI) stable across versions of Node.js. It is intended to insulate\naddons from changes in the underlying JavaScript engine and allow modules\ncompiled for one major version to run on later major versions of Node.js without\nrecompilation. The ABI Stability guide provides a more in-depth explanation.

Addons are built/packaged with the same approach/tools outlined in the section\ntitled C++ Addons. The only difference is the set of APIs that are used by\nthe native code. Instead of using the V8 or Native Abstractions for Node.js\nAPIs, the functions available in Node-API are used.

APIs exposed by Node-API are generally used to create and manipulate\nJavaScript values. Concepts and operations generally map to ideas specified\nin the ECMA-262 Language Specification. The APIs have the following\nproperties:

\n
• All Node-API calls return a status code of type napi_status. This\nstatus indicates whether the API call succeeded or failed.
\n
• The API's return value is passed via an out parameter.
\n
• All JavaScript values are abstracted behind an opaque type named\nnapi_value.
\n
• In case of an error status code, additional information can be obtained\nusing napi_get_last_error_info. More information can be found in the error\nhandling section Error handling.
\n

Node-API is a C API that ensures ABI stability across Node.js versions\nand different compiler levels. With this stability guarantee, it is possible\nto write addons in other programming languages on top of Node-API. Refer\nto language and engine bindings for more programming languages and engines\nsupport details.

node-addon-api is the official C++ binding that provides a more efficient way to\nwrite C++ code that calls Node-API. This wrapper is a header-only library that offers an inlinable C++ API.\nBinaries built with node-addon-api will depend on the symbols of the Node-API\nC-based functions exported by Node.js. The following code snippet is an example\nof node-addon-api:

Object obj = Object::New(env);\nobj[\"foo\"] = String::New(env, \"bar\");\n

The above node-addon-api C++ code is equivalent to the following C-based\nNode-API code:

napi_status status;\nnapi_value object, string;\nstatus = napi_create_object(env, &object);\nif (status != napi_ok) {\n  napi_throw_error(env, ...);\n  return;\n}\n\nstatus = napi_create_string_utf8(env, \"bar\", NAPI_AUTO_LENGTH, &string);\nif (status != napi_ok) {\n  napi_throw_error(env, ...);\n  return;\n}\n\nstatus = napi_set_named_property(env, object, \"foo\", string);\nif (status != napi_ok) {\n  napi_throw_error(env, ...);\n  return;\n}\n

The end result is that the addon only uses the exported C APIs. Even though\nthe addon is written in C++, it still gets the benefits of the ABI stability\nprovided by the C Node-API.

When using node-addon-api instead of the C APIs, start with the API docs\nfor node-addon-api.

The Node-API Resource offers\nan excellent orientation and tips for developers just getting started with\nNode-API and node-addon-api. Additional media resources can be found on the\nNode-API Media page.

Although Node-API provides an ABI stability guarantee, other parts of Node.js do\nnot, and any external libraries used from the addon may not. In particular,\nnone of the following APIs provide an ABI stability guarantee across major\nversions:

\n
• \n

  the Node.js C++ APIs available via any of

  \n

  #include <node.h>\n#include <node_buffer.h>\n#include <node_version.h>\n#include <node_object_wrap.h>\n

  \n
\n
• \n

  the libuv APIs which are also included with Node.js and available via

  \n

  #include <uv.h>\n

  \n
\n
• \n

  the V8 API available via

  \n

  #include <v8.h>\n

  \n
\n

Thus, for an addon to remain ABI-compatible across Node.js major versions, it\nmust use Node-API exclusively by restricting itself to using

#include <node_api.h>\n

and by checking, for all external libraries that it uses, that the external\nlibrary makes ABI stability guarantees similar to Node-API.

All enum data types defined in Node-API should be considered as a fixed size\nint32_t value. Bit flag enum types should be explicitly documented, and they\nwork with bit operators like bit-OR (|) as a bit value. Unless otherwise\ndocumented, an enum type should be considered to be extensible.

A new enum value will be added at the end of the enum definition. An enum value\nwill not be removed or renamed.

For an enum type returned from a Node-API function, or provided as an out\nparameter of a Node-API function, the value is an integer value and an addon\nshould handle unknown values. New values are allowed to be introduced without\na version guard. For example, when checking napi_status in switch statements,\nan addon should include a default branch, as new status codes may be introduced\nin newer Node.js versions.

For an enum type used in an in-parameter, the result of passing an unknown\ninteger value to Node-API functions is undefined unless otherwise documented.\nA new value is added with a version guard to indicate the Node-API version in\nwhich it was introduced. For example, napi_get_all_property_names can be\nextended with new enum value of napi_key_filter.

For an enum type used in both in-parameters and out-parameters, new values are\nallowed to be introduced without a version guard.

Unlike modules written in JavaScript, developing and deploying Node.js\nnative addons using Node-API requires an additional set of tools. Besides the\nbasic tools required to develop for Node.js, the native addon developer\nrequires a toolchain that can compile C and C++ code into a binary. In\naddition, depending upon how the native addon is deployed, the user of\nthe native addon will also need to have a C/C++ toolchain installed.

For Linux developers, the necessary C/C++ toolchain packages are readily\navailable. GCC is widely used in the Node.js community to build and\ntest across a variety of platforms. For many developers, the LLVM\ncompiler infrastructure is also a good choice.

For Mac developers, Xcode offers all the required compiler tools.\nHowever, it is not necessary to install the entire Xcode IDE. The following\ncommand installs the necessary toolchain:

xcode-select --install\n

For Windows developers, Visual Studio offers all the required compiler\ntools. However, it is not necessary to install the entire Visual Studio\nIDE. The following command installs the necessary toolchain:

npm install --global windows-build-tools\n

The sections below describe the additional tools available for developing\nand deploying Node.js native addons.

Both the tools listed here require that users of the native\naddon have a C/C++ toolchain installed in order to successfully install\nthe native addon.

node-gyp is a build system based on the gyp-next fork of\nGoogle's GYP tool and comes bundled with npm. GYP, and therefore node-gyp,\nrequires that Python be installed.

Historically, node-gyp has been the tool of choice for building native\naddons. It has widespread adoption and documentation. However, some\ndevelopers have run into limitations in node-gyp.

CMake.js is an alternative build system based on CMake.

CMake.js is a good choice for projects that already use CMake or for\ndevelopers affected by limitations in node-gyp. build_with_cmake is an\nexample of a CMake-based native addon project.

The three tools listed here permit native addon developers and maintainers\nto create and upload binaries to public or private servers. These tools are\ntypically integrated with CI/CD build systems like Travis CI and\nAppVeyor to build and upload binaries for a variety of platforms and\narchitectures. These binaries are then available for download by users who\ndo not need to have a C/C++ toolchain installed.

node-pre-gyp is a tool based on node-gyp that adds the ability to\nupload binaries to a server of the developer's choice. node-pre-gyp has\nparticularly good support for uploading binaries to Amazon S3.

prebuild is a tool that supports builds using either node-gyp or\nCMake.js. Unlike node-pre-gyp which supports a variety of servers, prebuild\nuploads binaries only to GitHub releases. prebuild is a good choice for\nGitHub projects using CMake.js.

prebuildify is a tool based on node-gyp. The advantage of prebuildify is\nthat the built binaries are bundled with the native addon when it's\nuploaded to npm. The binaries are downloaded from npm and are immediately\navailable to the module user when the native addon is installed.

In order to use the Node-API functions, include the file node_api.h which\nis located in the src directory in the node development tree:

#include <node_api.h>\n

This will opt into the default NAPI_VERSION for the given release of Node.js.\nIn order to ensure compatibility with specific versions of Node-API, the version\ncan be specified explicitly when including the header:

#define NAPI_VERSION 3\n#include <node_api.h>\n

This restricts the Node-API surface to just the functionality that was available\nin the specified (and earlier) versions.

Some of the Node-API surface is experimental and requires explicit opt-in:

#define NAPI_EXPERIMENTAL\n#include <node_api.h>\n

In this case the entire API surface, including any experimental APIs, will be\navailable to the module code.

Occasionally, experimental features are introduced that affect already-released\nand stable APIs. These features can be disabled by an opt-out:

#define NAPI_EXPERIMENTAL\n#define NODE_API_EXPERIMENTAL_<FEATURE_NAME>_OPT_OUT\n#include <node_api.h>\n

where <FEATURE_NAME> is the name of an experimental feature that affects both\nexperimental and stable APIs.

Up until version 9, Node-API versions were additive and versioned\nindependently from Node.js. This meant that any version was\nan extension to the previous version in that it had all of\nthe APIs from the previous version with some additions. Each\nNode.js version only supported a single Node-API version.\nFor example v18.15.0 supports only Node-API version 8. ABI stability was\nachieved because 8 was a strict superset of all previous versions.

As of version 9, while Node-API versions continue to be versioned\nindependently, an add-on that ran with Node-API version 9 may need\ncode updates to run with Node-API version 10. ABI stability\nis maintained, however, because Node.js versions that support\nNode-API versions higher than 8 will support all versions\nbetween 8 and the highest version they support and will default\nto providing the version 8 APIs unless an add-on opts into a\nhigher Node-API version. This approach provides the flexibility\nof better optimizing existing Node-API functions while\nmaintaining ABI stability. Existing add-ons can continue to run without\nrecompilation using an earlier version of Node-API. If an add-on\nneeds functionality from a newer Node-API version, changes to existing\ncode and recompilation will be needed to use those new functions anyway.

In versions of Node.js that support Node-API version 9 and later, defining\nNAPI_VERSION=X and using the existing add-on initialization macros\nwill bake in the requested Node-API version that will be used at runtime\ninto the add-on. If NAPI_VERSION is not set it will default to 8.

This table may not be up to date in older streams, the most up to date\ninformation is in the latest API documentation in:\nNode-API version matrix

* Node-API was experimental.

** Node.js 8.0.0 included Node-API as experimental. It was released as\nNode-API version 1 but continued to evolve until Node.js 8.6.0. The API is\ndifferent in versions prior to Node.js 8.6.0. We recommend Node-API version 3 or\nlater.

Each API documented for Node-API will have a header named added in:, and APIs\nwhich are stable will have the additional header Node-API version:.\nAPIs are directly usable when using a Node.js version which supports\nthe Node-API version shown in Node-API version: or higher.\nWhen using a Node.js version that does not support the\nNode-API version: listed or if there is no Node-API version: listed,\nthen the API will only be available if\n#define NAPI_EXPERIMENTAL precedes the inclusion of node_api.h\nor js_native_api.h. If an API appears not to be available on\na version of Node.js which is later than the one shown in added in: then\nthis is most likely the reason for the apparent absence.

The Node-APIs associated strictly with accessing ECMAScript features from native\ncode can be found separately in js_native_api.h and js_native_api_types.h.\nThe APIs defined in these headers are included in node_api.h and\nnode_api_types.h. The headers are structured in this way in order to allow\nimplementations of Node-API outside of Node.js. For those implementations the\nNode.js specific APIs may not be applicable.

The Node.js-specific parts of an addon can be separated from the code that\nexposes the actual functionality to the JavaScript environment so that the\nlatter may be used with multiple implementations of Node-API. In the example\nbelow, addon.c and addon.h refer only to js_native_api.h. This ensures\nthat addon.c can be reused to compile against either the Node.js\nimplementation of Node-API or any implementation of Node-API outside of Node.js.

addon_node.c is a separate file that contains the Node.js specific entry point\nto the addon and which instantiates the addon by calling into addon.c when the\naddon is loaded into a Node.js environment.

// addon.h\n#ifndef _ADDON_H_\n#define _ADDON_H_\n#include <js_native_api.h>\nnapi_value create_addon(napi_env env);\n#endif  // _ADDON_H_\n

// addon.c\n#include \"addon.h\"\n\n#define NODE_API_CALL(env, call)                                  \\\n  do {                                                            \\\n    napi_status status = (call);                                  \\\n    if (status != napi_ok) {                                      \\\n      const napi_extended_error_info* error_info = NULL;          \\\n      napi_get_last_error_info((env), &error_info);               \\\n      const char* err_message = error_info->error_message;        \\\n      bool is_pending;                                            \\\n      napi_is_exception_pending((env), &is_pending);              \\\n      /* If an exception is already pending, don't rethrow it */  \\\n      if (!is_pending) {                                          \\\n        const char* message = (err_message == NULL)               \\\n            ? \"empty error message\"                               \\\n            : err_message;                                        \\\n        napi_throw_error((env), NULL, message);                   \\\n      }                                                           \\\n      return NULL;                                                \\\n    }                                                             \\\n  } while(0)\n\nstatic napi_value\nDoSomethingUseful(napi_env env, napi_callback_info info) {\n  // Do something useful.\n  return NULL;\n}\n\nnapi_value create_addon(napi_env env) {\n  napi_value result;\n  NODE_API_CALL(env, napi_create_object(env, &result));\n\n  napi_value exported_function;\n  NODE_API_CALL(env, napi_create_function(env,\n                                          \"doSomethingUseful\",\n                                          NAPI_AUTO_LENGTH,\n                                          DoSomethingUseful,\n                                          NULL,\n                                          &exported_function));\n\n  NODE_API_CALL(env, napi_set_named_property(env,\n                                             result,\n                                             \"doSomethingUseful\",\n                                             exported_function));\n\n  return result;\n}\n

// addon_node.c\n#include <node_api.h>\n#include \"addon.h\"\n\nNAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {\n  // This function body is expected to return a `napi_value`.\n  // The variables `napi_env env` and `napi_value exports` may be used within\n  // the body, as they are provided by the definition of `NAPI_MODULE_INIT()`.\n  return create_addon(env);\n}\n

Section Agents of the ECMAScript Language Specification defines the concept\nof an \"Agent\" as a self-contained environment in which JavaScript code runs.\nMultiple such Agents may be started and terminated either concurrently or in\nsequence by the process.

A Node.js environment corresponds to an ECMAScript Agent. In the main process,\nan environment is created at startup, and additional environments can be created\non separate threads to serve as worker threads. When Node.js is embedded in\nanother application, the main thread of the application may also construct and\ndestroy a Node.js environment multiple times during the life cycle of the\napplication process such that each Node.js environment created by the\napplication may, in turn, during its life cycle create and destroy additional\nenvironments as worker threads.

From the perspective of a native addon this means that the bindings it provides\nmay be called multiple times, from multiple contexts, and even concurrently from\nmultiple threads.

Native addons may need to allocate global state which they use during\ntheir life cycle of an Node.js environment such that the state can be\nunique to each instance of the addon.

To this end, Node-API provides a way to associate data such that its life cycle\nis tied to the life cycle of a Node.js environment.

napi_status napi_set_instance_data(node_api_basic_env env,\n                                   void* data,\n                                   napi_finalize finalize_cb,\n                                   void* finalize_hint);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] data: The data item to make available to bindings of this instance.
\n
• [in] finalize_cb: The function to call when the environment is being torn\ndown. The function receives data so that it might free it.\nnapi_finalize provides more details.
\n
• [in] finalize_hint: Optional hint to pass to the finalize callback during\ncollection.
\n

Returns napi_ok if the API succeeded.

This API associates data with the currently running Node.js environment. data\ncan later be retrieved using napi_get_instance_data(). Any existing data\nassociated with the currently running Node.js environment which was set by means\nof a previous call to napi_set_instance_data() will be overwritten. If a\nfinalize_cb was provided by the previous call, it will not be called.

napi_status napi_get_instance_data(node_api_basic_env env,\n                                   void** data);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [out] data: The data item that was previously associated with the currently\nrunning Node.js environment by a call to napi_set_instance_data().
\n

Returns napi_ok if the API succeeded.

This API retrieves data that was previously associated with the currently\nrunning Node.js environment via napi_set_instance_data(). If no data is set,\nthe call will succeed and data will be set to NULL.

Node-API exposes the following fundamental data types as abstractions that are\nconsumed by the various APIs. These APIs should be treated as opaque,\nintrospectable only with other Node-API calls.

Integral status code indicating the success or failure of a Node-API call.\nCurrently, the following status codes are supported.

typedef enum {\n  napi_ok,\n  napi_invalid_arg,\n  napi_object_expected,\n  napi_string_expected,\n  napi_name_expected,\n  napi_function_expected,\n  napi_number_expected,\n  napi_boolean_expected,\n  napi_array_expected,\n  napi_generic_failure,\n  napi_pending_exception,\n  napi_cancelled,\n  napi_escape_called_twice,\n  napi_handle_scope_mismatch,\n  napi_callback_scope_mismatch,\n  napi_queue_full,\n  napi_closing,\n  napi_bigint_expected,\n  napi_date_expected,\n  napi_arraybuffer_expected,\n  napi_detachable_arraybuffer_expected,\n  napi_would_deadlock,  /* unused */\n  napi_no_external_buffers_allowed,\n  napi_cannot_run_js\n} napi_status;\n

If additional information is required upon an API returning a failed status,\nit can be obtained by calling napi_get_last_error_info.

typedef struct {\n  const char* error_message;\n  void* engine_reserved;\n  uint32_t engine_error_code;\n  napi_status error_code;\n} napi_extended_error_info;\n

\n
• error_message: UTF8-encoded string containing a VM-neutral description of\nthe error.
\n
• engine_reserved: Reserved for VM-specific error details. This is currently\nnot implemented for any VM.
\n
• engine_error_code: VM-specific error code. This is currently\nnot implemented for any VM.
\n
• error_code: The Node-API status code that originated with the last error.
\n

See the Error handling section for additional information.

napi_env is used to represent a context that the underlying Node-API\nimplementation can use to persist VM-specific state. This structure is passed\nto native functions when they're invoked, and it must be passed back when\nmaking Node-API calls. Specifically, the same napi_env that was passed in when\nthe initial native function was called must be passed to any subsequent\nnested Node-API calls. Caching the napi_env for the purpose of general reuse,\nand passing the napi_env between instances of the same addon running on\ndifferent Worker threads is not allowed. The napi_env becomes invalid\nwhen an instance of a native addon is unloaded. Notification of this event is\ndelivered through the callbacks given to napi_add_env_cleanup_hook and\nnapi_set_instance_data.

This variant of napi_env is passed to synchronous finalizers\n(node_api_basic_finalize). There is a subset of Node-APIs which accept\na parameter of type node_api_basic_env as their first argument. These APIs do\nnot access the state of the JavaScript engine and are thus safe to call from\nsynchronous finalizers. Passing a parameter of type napi_env to these APIs is\nallowed, however, passing a parameter of type node_api_basic_env to APIs that\naccess the JavaScript engine state is not allowed. Attempting to do so without\na cast will produce a compiler warning or an error when add-ons are compiled\nwith flags which cause them to emit warnings and/or errors when incorrect\npointer types are passed into a function. Calling such APIs from a synchronous\nfinalizer will ultimately result in the termination of the application.

This is an opaque pointer that is used to represent a JavaScript value.

This is an opaque pointer that represents a JavaScript function which can be\ncalled asynchronously from multiple threads via\nnapi_call_threadsafe_function().

A value to be given to napi_release_threadsafe_function() to indicate whether\nthe thread-safe function is to be closed immediately (napi_tsfn_abort) or\nmerely released (napi_tsfn_release) and thus available for subsequent use via\nnapi_acquire_threadsafe_function() and napi_call_threadsafe_function().

typedef enum {\n  napi_tsfn_release,\n  napi_tsfn_abort\n} napi_threadsafe_function_release_mode;\n

A value to be given to napi_call_threadsafe_function() to indicate whether\nthe call should block whenever the queue associated with the thread-safe\nfunction is full.

typedef enum {\n  napi_tsfn_nonblocking,\n  napi_tsfn_blocking\n} napi_threadsafe_function_call_mode;\n

This is an abstraction used to control and modify the lifetime of objects\ncreated within a particular scope. In general, Node-API values are created\nwithin the context of a handle scope. When a native method is called from\nJavaScript, a default handle scope will exist. If the user does not explicitly\ncreate a new handle scope, Node-API values will be created in the default handle\nscope. For any invocations of code outside the execution of a native method\n(for instance, during a libuv callback invocation), the module is required to\ncreate a scope before invoking any functions that can result in the creation\nof JavaScript values.

Handle scopes are created using napi_open_handle_scope and are destroyed\nusing napi_close_handle_scope. Closing the scope can indicate to the GC\nthat all napi_values created during the lifetime of the handle scope are no\nlonger referenced from the current stack frame.

For more details, review the Object lifetime management.

Escapable handle scopes are a special type of handle scope to return values\ncreated within a particular handle scope to a parent scope.

This is the abstraction to use to reference a napi_value. This allows for\nusers to manage the lifetimes of JavaScript values, including defining their\nminimum lifetimes explicitly.

For more details, review the Object lifetime management.

A 128-bit value stored as two unsigned 64-bit integers. It serves as a UUID\nwith which JavaScript objects or externals can be \"tagged\" in order to\nensure that they are of a certain type. This is a stronger check than\nnapi_instanceof, because the latter can report a false positive if the\nobject's prototype has been manipulated. Type-tagging is most useful in\nconjunction with napi_wrap because it ensures that the pointer retrieved\nfrom a wrapped object can be safely cast to the native type corresponding to the\ntype tag that had been previously applied to the JavaScript object.

typedef struct {\n  uint64_t lower;\n  uint64_t upper;\n} napi_type_tag;\n

An opaque value returned by napi_add_async_cleanup_hook. It must be passed\nto napi_remove_async_cleanup_hook when the chain of asynchronous cleanup\nevents completes.

Opaque datatype that is passed to a callback function. It can be used for\ngetting additional information about the context in which the callback was\ninvoked.

Function pointer type for user-provided native functions which are to be\nexposed to JavaScript via Node-API. Callback functions should satisfy the\nfollowing signature:

typedef napi_value (*napi_callback)(napi_env, napi_callback_info);\n

Unless for reasons discussed in Object Lifetime Management, creating a\nhandle and/or callback scope inside a napi_callback is not necessary.

Function pointer type for add-on provided functions that allow the user to be\nnotified when externally-owned data is ready to be cleaned up because the\nobject it was associated with has been garbage-collected. The user must provide\na function satisfying the following signature which would get called upon the\nobject's collection. Currently, node_api_basic_finalize can be used for\nfinding out when objects that have external data are collected.

typedef void (*node_api_basic_finalize)(node_api_basic_env env,\n                                      void* finalize_data,\n                                      void* finalize_hint);\n

Unless for reasons discussed in Object Lifetime Management, creating a\nhandle and/or callback scope inside the function body is not necessary.

Since these functions may be called while the JavaScript engine is in a state\nwhere it cannot execute JavaScript code, only Node-APIs which accept a\nnode_api_basic_env as their first parameter may be called.\nnode_api_post_finalizer can be used to schedule Node-API calls that\nrequire access to the JavaScript engine's state to run after the current\ngarbage collection cycle has completed.

In the case of node_api_create_external_string_latin1 and\nnode_api_create_external_string_utf16 the env parameter may be null,\nbecause external strings can be collected during the latter part of environment\nshutdown.

Change History:

\n
• \n

  experimental (NAPI_EXPERIMENTAL):

  \n

  Only Node-API calls that accept a node_api_basic_env as their first\nparameter may be called, otherwise the application will be terminated with an\nappropriate error message. This feature can be turned off by defining\nNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.

  \n
\n

Function pointer type for add-on provided function that allow the user to\nschedule a group of calls to Node-APIs in response to a garbage collection\nevent, after the garbage collection cycle has completed. These function\npointers can be used with node_api_post_finalizer.

typedef void (*napi_finalize)(napi_env env,\n                              void* finalize_data,\n                              void* finalize_hint);\n

Change History:

\n
• \n

  experimental (NAPI_EXPERIMENTAL is defined):

  \n

  A function of this type may no longer be used as a finalizer, except with\nnode_api_post_finalizer. node_api_basic_finalize must be used\ninstead. This feature can be turned off by defining\nNODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT.

  \n
\n

Function pointer used with functions that support asynchronous\noperations. Callback functions must satisfy the following signature:

typedef void (*napi_async_execute_callback)(napi_env env, void* data);\n

Implementations of this function must avoid making Node-API calls that execute\nJavaScript or interact with JavaScript objects. Node-API calls should be in the\nnapi_async_complete_callback instead. Do not use the napi_env parameter as\nit will likely result in execution of JavaScript.

Function pointer used with functions that support asynchronous\noperations. Callback functions must satisfy the following signature:

typedef void (*napi_async_complete_callback)(napi_env env,\n                                             napi_status status,\n                                             void* data);\n

Unless for reasons discussed in Object Lifetime Management, creating a\nhandle and/or callback scope inside the function body is not necessary.

Function pointer used with asynchronous thread-safe function calls. The callback\nwill be called on the main thread. Its purpose is to use a data item arriving\nvia the queue from one of the secondary threads to construct the parameters\nnecessary for a call into JavaScript, usually via napi_call_function, and then\nmake the call into JavaScript.

The data arriving from the secondary thread via the queue is given in the data\nparameter and the JavaScript function to call is given in the js_callback\nparameter.

Node-API sets up the environment prior to calling this callback, so it is\nsufficient to call the JavaScript function via napi_call_function rather than\nvia napi_make_callback.

Callback functions must satisfy the following signature:

typedef void (*napi_threadsafe_function_call_js)(napi_env env,\n                                                 napi_value js_callback,\n                                                 void* context,\n                                                 void* data);\n

\n
• [in] env: The environment to use for API calls, or NULL if the thread-safe\nfunction is being torn down and data may need to be freed.
\n
• [in] js_callback: The JavaScript function to call, or NULL if the\nthread-safe function is being torn down and data may need to be freed. It\nmay also be NULL if the thread-safe function was created without\njs_callback.
\n
• [in] context: The optional data with which the thread-safe function was\ncreated.
\n
• [in] data: Data created by the secondary thread. It is the responsibility of\nthe callback to convert this native data to JavaScript values (with Node-API\nfunctions) that can be passed as parameters when js_callback is invoked.\nThis pointer is managed entirely by the threads and this callback. Thus this\ncallback should free the data.
\n

Unless for reasons discussed in Object Lifetime Management, creating a\nhandle and/or callback scope inside the function body is not necessary.

Function pointer used with napi_add_env_cleanup_hook. It will be called\nwhen the environment is being torn down.

Callback functions must satisfy the following signature:

typedef void (*napi_cleanup_hook)(void* data);\n

\n
• [in] data: The data that was passed to napi_add_env_cleanup_hook.
\n

Function pointer used with napi_add_async_cleanup_hook. It will be called\nwhen the environment is being torn down.

Callback functions must satisfy the following signature:

typedef void (*napi_async_cleanup_hook)(napi_async_cleanup_hook_handle handle,\n                                        void* data);\n

\n
• [in] handle: The handle that must be passed to\nnapi_remove_async_cleanup_hook after completion of the asynchronous\ncleanup.
\n
• [in] data: The data that was passed to napi_add_async_cleanup_hook.
\n

The body of the function should initiate the asynchronous cleanup actions at the\nend of which handle must be passed in a call to\nnapi_remove_async_cleanup_hook.

Node-API uses both return values and JavaScript exceptions for error handling.\nThe following sections explain the approach for each case.

All of the Node-API functions share the same error handling pattern. The\nreturn type of all API functions is napi_status.

The return value will be napi_ok if the request was successful and\nno uncaught JavaScript exception was thrown. If an error occurred AND\nan exception was thrown, the napi_status value for the error\nwill be returned. If an exception was thrown, and no error occurred,\nnapi_pending_exception will be returned.

In cases where a return value other than napi_ok or\nnapi_pending_exception is returned, napi_is_exception_pending\nmust be called to check if an exception is pending.\nSee the section on exceptions for more details.

The full set of possible napi_status values is defined\nin napi_api_types.h.

The napi_status return value provides a VM-independent representation of\nthe error which occurred. In some cases it is useful to be able to get\nmore detailed information, including a string representing the error as well as\nVM (engine)-specific information.

In order to retrieve this information napi_get_last_error_info\nis provided which returns a napi_extended_error_info structure.\nThe format of the napi_extended_error_info structure is as follows:

typedef struct napi_extended_error_info {\n  const char* error_message;\n  void* engine_reserved;\n  uint32_t engine_error_code;\n  napi_status error_code;\n};\n

\n
• error_message: Textual representation of the error that occurred.
\n
• engine_reserved: Opaque handle reserved for engine use only.
\n
• engine_error_code: VM specific error code.
\n
• error_code: Node-API status code for the last error.
\n

napi_get_last_error_info returns the information for the last\nNode-API call that was made.

Do not rely on the content or format of any of the extended information as it\nis not subject to SemVer and may change at any time. It is intended only for\nlogging purposes.

napi_status\nnapi_get_last_error_info(node_api_basic_env env,\n                         const napi_extended_error_info** result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: The napi_extended_error_info structure with more\ninformation about the error.
\n

Returns napi_ok if the API succeeded.

This API retrieves a napi_extended_error_info structure with information\nabout the last error that occurred.

The content of the napi_extended_error_info returned is only valid up until\na Node-API function is called on the same env. This includes a call to\nnapi_is_exception_pending so it may often be necessary to make a copy\nof the information so that it can be used later. The pointer returned\nin error_message points to a statically-defined string so it is safe to use\nthat pointer if you have copied it out of the error_message field (which will\nbe overwritten) before another Node-API function was called.

Do not rely on the content or format of any of the extended information as it\nis not subject to SemVer and may change at any time. It is intended only for\nlogging purposes.

This API can be called even if there is a pending JavaScript exception.

Any Node-API function call may result in a pending JavaScript exception. This is\nthe case for any of the API functions, even those that may not cause the\nexecution of JavaScript.

If the napi_status returned by a function is napi_ok then no\nexception is pending and no additional action is required. If the\nnapi_status returned is anything other than napi_ok or\nnapi_pending_exception, in order to try to recover and continue\ninstead of simply returning immediately, napi_is_exception_pending\nmust be called in order to determine if an exception is pending or not.

In many cases when a Node-API function is called and an exception is\nalready pending, the function will return immediately with a\nnapi_status of napi_pending_exception. However, this is not the case\nfor all functions. Node-API allows a subset of the functions to be\ncalled to allow for some minimal cleanup before returning to JavaScript.\nIn that case, napi_status will reflect the status for the function. It\nwill not reflect previous pending exceptions. To avoid confusion, check\nthe error status after every function call.

When an exception is pending one of two approaches can be employed.

The first approach is to do any appropriate cleanup and then return so that\nexecution will return to JavaScript. As part of the transition back to\nJavaScript, the exception will be thrown at the point in the JavaScript\ncode where the native method was invoked. The behavior of most Node-API calls\nis unspecified while an exception is pending, and many will simply return\nnapi_pending_exception, so do as little as possible and then return to\nJavaScript where the exception can be handled.

The second approach is to try to handle the exception. There will be cases\nwhere the native code can catch the exception, take the appropriate action,\nand then continue. This is only recommended in specific cases\nwhere it is known that the exception can be safely handled. In these\ncases napi_get_and_clear_last_exception can be used to get and\nclear the exception. On success, result will contain the handle to\nthe last JavaScript Object thrown. If it is determined, after\nretrieving the exception, the exception cannot be handled after all\nit can be re-thrown it with napi_throw where error is the\nJavaScript value to be thrown.

The following utility functions are also available in case native code\nneeds to throw an exception or determine if a napi_value is an instance\nof a JavaScript Error object: napi_throw_error,\nnapi_throw_type_error, napi_throw_range_error, node_api_throw_syntax_error and napi_is_error.

The following utility functions are also available in case native\ncode needs to create an Error object: napi_create_error,\nnapi_create_type_error, napi_create_range_error and node_api_create_syntax_error,\nwhere result is the napi_value that refers to the newly created\nJavaScript Error object.

The Node.js project is adding error codes to all of the errors\ngenerated internally. The goal is for applications to use these\nerror codes for all error checking. The associated error messages\nwill remain, but will only be meant to be used for logging and\ndisplay with the expectation that the message can change without\nSemVer applying. In order to support this model with Node-API, both\nin internal functionality and for module specific functionality\n(as its good practice), the throw_ and create_ functions\ntake an optional code parameter which is the string for the code\nto be added to the error object. If the optional parameter is NULL\nthen no code will be associated with the error. If a code is provided,\nthe name associated with the error is also updated to be:

originalName [code]\n

where originalName is the original name associated with the error\nand code is the code that was provided. For example, if the code\nis 'ERR_ERROR_1' and a TypeError is being created the name will be:

TypeError [ERR_ERROR_1]\n

NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] error: The JavaScript value to be thrown.
\n

Returns napi_ok if the API succeeded.

This API throws the JavaScript value provided.

NAPI_EXTERN napi_status napi_throw_error(napi_env env,\n                                         const char* code,\n                                         const char* msg);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] code: Optional error code to be set on the error.
\n
• [in] msg: C string representing the text to be associated with the error.
\n

Returns napi_ok if the API succeeded.

This API throws a JavaScript Error with the text provided.

NAPI_EXTERN napi_status napi_throw_type_error(napi_env env,\n                                              const char* code,\n                                              const char* msg);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] code: Optional error code to be set on the error.
\n
• [in] msg: C string representing the text to be associated with the error.
\n

Returns napi_ok if the API succeeded.

This API throws a JavaScript TypeError with the text provided.

NAPI_EXTERN napi_status napi_throw_range_error(napi_env env,\n                                               const char* code,\n                                               const char* msg);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] code: Optional error code to be set on the error.
\n
• [in] msg: C string representing the text to be associated with the error.
\n

Returns napi_ok if the API succeeded.

This API throws a JavaScript RangeError with the text provided.

NAPI_EXTERN napi_status node_api_throw_syntax_error(napi_env env,\n                                                    const char* code,\n                                                    const char* msg);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] code: Optional error code to be set on the error.
\n
• [in] msg: C string representing the text to be associated with the error.
\n

Returns napi_ok if the API succeeded.

This API throws a JavaScript SyntaxError with the text provided.

NAPI_EXTERN napi_status napi_is_error(napi_env env,\n                                      napi_value value,\n                                      bool* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The napi_value to be checked.
\n
• [out] result: Boolean value that is set to true if napi_value represents\nan error, false otherwise.
\n

Returns napi_ok if the API succeeded.

This API queries a napi_value to check if it represents an error object.

NAPI_EXTERN napi_status napi_create_error(napi_env env,\n                                          napi_value code,\n                                          napi_value msg,\n                                          napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] code: Optional napi_value with the string for the error code to be\nassociated with the error.
\n
• [in] msg: napi_value that references a JavaScript string to be used as\nthe message for the Error.
\n
• [out] result: napi_value representing the error created.
\n

Returns napi_ok if the API succeeded.

This API returns a JavaScript Error with the text provided.

NAPI_EXTERN napi_status napi_create_type_error(napi_env env,\n                                               napi_value code,\n                                               napi_value msg,\n                                               napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] code: Optional napi_value with the string for the error code to be\nassociated with the error.
\n
• [in] msg: napi_value that references a JavaScript string to be used as\nthe message for the Error.
\n
• [out] result: napi_value representing the error created.
\n

Returns napi_ok if the API succeeded.

This API returns a JavaScript TypeError with the text provided.

NAPI_EXTERN napi_status napi_create_range_error(napi_env env,\n                                                napi_value code,\n                                                napi_value msg,\n                                                napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] code: Optional napi_value with the string for the error code to be\nassociated with the error.
\n
• [in] msg: napi_value that references a JavaScript string to be used as\nthe message for the Error.
\n
• [out] result: napi_value representing the error created.
\n

Returns napi_ok if the API succeeded.

This API returns a JavaScript RangeError with the text provided.

NAPI_EXTERN napi_status node_api_create_syntax_error(napi_env env,\n                                                     napi_value code,\n                                                     napi_value msg,\n                                                     napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] code: Optional napi_value with the string for the error code to be\nassociated with the error.
\n
• [in] msg: napi_value that references a JavaScript string to be used as\nthe message for the Error.
\n
• [out] result: napi_value representing the error created.
\n

Returns napi_ok if the API succeeded.

This API returns a JavaScript SyntaxError with the text provided.

napi_status napi_get_and_clear_last_exception(napi_env env,\n                                              napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: The exception if one is pending, NULL otherwise.
\n

Returns napi_ok if the API succeeded.

This API can be called even if there is a pending JavaScript exception.

napi_status napi_is_exception_pending(napi_env env, bool* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: Boolean value that is set to true if an exception is pending.
\n

Returns napi_ok if the API succeeded.

This API can be called even if there is a pending JavaScript exception.

napi_status napi_fatal_exception(napi_env env, napi_value err);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] err: The error that is passed to 'uncaughtException'.
\n

Trigger an 'uncaughtException' in JavaScript. Useful if an async\ncallback throws an exception with no way to recover.

In the event of an unrecoverable error in a native addon, a fatal error can be\nthrown to immediately terminate the process.

NAPI_NO_RETURN void napi_fatal_error(const char* location,\n                                     size_t location_len,\n                                     const char* message,\n                                     size_t message_len);\n

\n
• [in] location: Optional location at which the error occurred.
\n
• [in] location_len: The length of the location in bytes, or\nNAPI_AUTO_LENGTH if it is null-terminated.
\n
• [in] message: The message associated with the error.
\n
• [in] message_len: The length of the message in bytes, or NAPI_AUTO_LENGTH\nif it is null-terminated.
\n

The function call does not return, the process will be terminated.

This API can be called even if there is a pending JavaScript exception.

As Node-API calls are made, handles to objects in the heap for the underlying\nVM may be returned as napi_values. These handles must hold the\nobjects 'live' until they are no longer required by the native code,\notherwise the objects could be collected before the native code was\nfinished using them.

As object handles are returned they are associated with a\n'scope'. The lifespan for the default scope is tied to the lifespan\nof the native method call. The result is that, by default, handles\nremain valid and the objects associated with these handles will be\nheld live for the lifespan of the native method call.

In many cases, however, it is necessary that the handles remain valid for\neither a shorter or longer lifespan than that of the native method.\nThe sections which follow describe the Node-API functions that can be used\nto change the handle lifespan from the default.

It is often necessary to make the lifespan of handles shorter than\nthe lifespan of a native method. For example, consider a native method\nthat has a loop which iterates through the elements in a large array:

for (int i = 0; i < 1000000; i++) {\n  napi_value result;\n  napi_status status = napi_get_element(env, object, i, &result);\n  if (status != napi_ok) {\n    break;\n  }\n  // do something with element\n}\n

This would result in a large number of handles being created, consuming\nsubstantial resources. In addition, even though the native code could only\nuse the most recent handle, all of the associated objects would also be\nkept alive since they all share the same scope.

To handle this case, Node-API provides the ability to establish a new 'scope' to\nwhich newly created handles will be associated. Once those handles\nare no longer required, the scope can be 'closed' and any handles associated\nwith the scope are invalidated. The methods available to open/close scopes are\nnapi_open_handle_scope and napi_close_handle_scope.

Node-API only supports a single nested hierarchy of scopes. There is only one\nactive scope at any time, and all new handles will be associated with that\nscope while it is active. Scopes must be closed in the reverse order from\nwhich they are opened. In addition, all scopes created within a native method\nmust be closed before returning from that method.

Taking the earlier example, adding calls to napi_open_handle_scope and\nnapi_close_handle_scope would ensure that at most a single handle\nis valid throughout the execution of the loop:

for (int i = 0; i < 1000000; i++) {\n  napi_handle_scope scope;\n  napi_status status = napi_open_handle_scope(env, &scope);\n  if (status != napi_ok) {\n    break;\n  }\n  napi_value result;\n  status = napi_get_element(env, object, i, &result);\n  if (status != napi_ok) {\n    break;\n  }\n  // do something with element\n  status = napi_close_handle_scope(env, scope);\n  if (status != napi_ok) {\n    break;\n  }\n}\n

When nesting scopes, there are cases where a handle from an\ninner scope needs to live beyond the lifespan of that scope. Node-API supports\nan 'escapable scope' in order to support this case. An escapable scope\nallows one handle to be 'promoted' so that it 'escapes' the\ncurrent scope and the lifespan of the handle changes from the current\nscope to that of the outer scope.

The methods available to open/close escapable scopes are\nnapi_open_escapable_handle_scope and\nnapi_close_escapable_handle_scope.

The request to promote a handle is made through napi_escape_handle which\ncan only be called once.

NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env,\n                                               napi_handle_scope* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: napi_value representing the new scope.
\n

Returns napi_ok if the API succeeded.

This API opens a new scope.

NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env,\n                                                napi_handle_scope scope);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] scope: napi_value representing the scope to be closed.
\n

Returns napi_ok if the API succeeded.

This API closes the scope passed in. Scopes must be closed in the\nreverse order from which they were created.

This API can be called even if there is a pending JavaScript exception.

NAPI_EXTERN napi_status\n    napi_open_escapable_handle_scope(napi_env env,\n                                     napi_handle_scope* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: napi_value representing the new scope.
\n

Returns napi_ok if the API succeeded.

This API opens a new scope from which one object can be promoted\nto the outer scope.

NAPI_EXTERN napi_status\n    napi_close_escapable_handle_scope(napi_env env,\n                                      napi_handle_scope scope);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] scope: napi_value representing the scope to be closed.
\n

Returns napi_ok if the API succeeded.

This API closes the scope passed in. Scopes must be closed in the\nreverse order from which they were created.

This API can be called even if there is a pending JavaScript exception.

napi_status napi_escape_handle(napi_env env,\n                               napi_escapable_handle_scope scope,\n                               napi_value escapee,\n                               napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] scope: napi_value representing the current scope.
\n
• [in] escapee: napi_value representing the JavaScript Object to be\nescaped.
\n
• [out] result: napi_value representing the handle to the escaped Object\nin the outer scope.
\n

Returns napi_ok if the API succeeded.

This API promotes the handle to the JavaScript object so that it is valid\nfor the lifetime of the outer scope. It can only be called once per scope.\nIf it is called more than once an error will be returned.

This API can be called even if there is a pending JavaScript exception.

In some cases, an addon will need to be able to create and reference values\nwith a lifespan longer than that of a single native method invocation. For\nexample, to create a constructor and later use that constructor\nin a request to create instances, it must be possible to reference\nthe constructor object across many different instance creation requests. This\nwould not be possible with a normal handle returned as a napi_value as\ndescribed in the earlier section. The lifespan of a normal handle is\nmanaged by scopes and all scopes must be closed before the end of a native\nmethod.

Node-API provides methods for creating persistent references to values.\nCurrently Node-API only allows references to be created for a\nlimited set of value types, including object, external, function, and symbol.

Each reference has an associated count with a value of 0 or higher,\nwhich determines whether the reference will keep the corresponding value alive.\nReferences with a count of 0 do not prevent values from being collected.\nValues of object (object, function, external) and symbol types are becoming\n'weak' references and can still be accessed while they are not collected.\nAny count greater than 0 will prevent the values from being collected.

Symbol values have different flavors. The true weak reference behavior is\nonly supported by local symbols created with the napi_create_symbol function\nor the JavaScript Symbol() constructor calls. Globally registered symbols\ncreated with the node_api_symbol_for function or JavaScript Symbol.for()\nfunction calls remain always strong references because the garbage collector\ndoes not collect them. The same is true for well-known symbols such as\nSymbol.iterator. They are also never collected by the garbage collector.

References can be created with an initial reference count. The count can\nthen be modified through napi_reference_ref and\nnapi_reference_unref. If an object is collected while the count\nfor a reference is 0, all subsequent calls to\nget the object associated with the reference napi_get_reference_value\nwill return NULL for the returned napi_value. An attempt to call\nnapi_reference_ref for a reference whose object has been collected\nresults in an error.

References must be deleted once they are no longer required by the addon. When\na reference is deleted, it will no longer prevent the corresponding object from\nbeing collected. Failure to delete a persistent reference results in\na 'memory leak' with both the native memory for the persistent reference and\nthe corresponding object on the heap being retained forever.

There can be multiple persistent references created which refer to the same\nobject, each of which will either keep the object live or not based on its\nindividual count. Multiple persistent references to the same object\ncan result in unexpectedly keeping alive native memory. The native structures\nfor a persistent reference must be kept alive until finalizers for the\nreferenced object are executed. If a new persistent reference is created\nfor the same object, the finalizers for that object will not be\nrun and the native memory pointed by the earlier persistent reference\nwill not be freed. This can be avoided by calling\nnapi_delete_reference in addition to napi_reference_unref when possible.

Change History:

\n
• \n

  Version 10 (NAPI_VERSION is defined as 10 or higher):

  \n

  References can be created for all value types. The new supported value\ntypes do not support weak reference semantic and the values of these types\nare released when the reference count becomes 0 and cannot be accessed from\nthe reference anymore.

  \n
\n

NAPI_EXTERN napi_status napi_create_reference(napi_env env,\n                                              napi_value value,\n                                              uint32_t initial_refcount,\n                                              napi_ref* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The napi_value for which a reference is being created.
\n
• [in] initial_refcount: Initial reference count for the new reference.
\n
• [out] result: napi_ref pointing to the new reference.
\n

Returns napi_ok if the API succeeded.

This API creates a new reference with the specified reference count\nto the value passed in.

NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] ref: napi_ref to be deleted.
\n

Returns napi_ok if the API succeeded.

This API deletes the reference passed in.

This API can be called even if there is a pending JavaScript exception.

NAPI_EXTERN napi_status napi_reference_ref(napi_env env,\n                                           napi_ref ref,\n                                           uint32_t* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] ref: napi_ref for which the reference count will be incremented.
\n
• [out] result: The new reference count.
\n

Returns napi_ok if the API succeeded.

This API increments the reference count for the reference\npassed in and returns the resulting reference count.

NAPI_EXTERN napi_status napi_reference_unref(napi_env env,\n                                             napi_ref ref,\n                                             uint32_t* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] ref: napi_ref for which the reference count will be decremented.
\n
• [out] result: The new reference count.
\n

Returns napi_ok if the API succeeded.

This API decrements the reference count for the reference\npassed in and returns the resulting reference count.

NAPI_EXTERN napi_status napi_get_reference_value(napi_env env,\n                                                 napi_ref ref,\n                                                 napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] ref: The napi_ref for which the corresponding value is\nbeing requested.
\n
• [out] result: The napi_value referenced by the napi_ref.
\n

Returns napi_ok if the API succeeded.

If still valid, this API returns the napi_value representing the\nJavaScript value associated with the napi_ref. Otherwise, result\nwill be NULL.

While a Node.js process typically releases all its resources when exiting,\nembedders of Node.js, or future Worker support, may require addons to register\nclean-up hooks that will be run once the current Node.js environment exits.

Node-API provides functions for registering and un-registering such callbacks.\nWhen those callbacks are run, all resources that are being held by the addon\nshould be freed up.

NODE_EXTERN napi_status napi_add_env_cleanup_hook(node_api_basic_env env,\n                                                  napi_cleanup_hook fun,\n                                                  void* arg);\n

Registers fun as a function to be run with the arg parameter once the\ncurrent Node.js environment exits.

A function can safely be specified multiple times with different\narg values. In that case, it will be called multiple times as well.\nProviding the same fun and arg values multiple times is not allowed\nand will lead the process to abort.

The hooks will be called in reverse order, i.e. the most recently added one\nwill be called first.

Removing this hook can be done by using napi_remove_env_cleanup_hook.\nTypically, that happens when the resource for which this hook was added\nis being torn down anyway.

For asynchronous cleanup, napi_add_async_cleanup_hook is available.

NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(node_api_basic_env env,\n                                                     void (*fun)(void* arg),\n                                                     void* arg);\n

Unregisters fun as a function to be run with the arg parameter once the\ncurrent Node.js environment exits. Both the argument and the function value\nneed to be exact matches.

The function must have originally been registered\nwith napi_add_env_cleanup_hook, otherwise the process will abort.

NAPI_EXTERN napi_status napi_add_async_cleanup_hook(\n    node_api_basic_env env,\n    napi_async_cleanup_hook hook,\n    void* arg,\n    napi_async_cleanup_hook_handle* remove_handle);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] hook: The function pointer to call at environment teardown.
\n
• [in] arg: The pointer to pass to hook when it gets called.
\n
• [out] remove_handle: Optional handle that refers to the asynchronous cleanup\nhook.
\n

Registers hook, which is a function of type napi_async_cleanup_hook, as\na function to be run with the remove_handle and arg parameters once the\ncurrent Node.js environment exits.

Unlike napi_add_env_cleanup_hook, the hook is allowed to be asynchronous.

Otherwise, behavior generally matches that of napi_add_env_cleanup_hook.

If remove_handle is not NULL, an opaque value will be stored in it\nthat must later be passed to napi_remove_async_cleanup_hook,\nregardless of whether the hook has already been invoked.\nTypically, that happens when the resource for which this hook was added\nis being torn down anyway.

NAPI_EXTERN napi_status napi_remove_async_cleanup_hook(\n    napi_async_cleanup_hook_handle remove_handle);\n

\n
• [in] remove_handle: The handle to an asynchronous cleanup hook that was\ncreated with napi_add_async_cleanup_hook.
\n

Unregisters the cleanup hook corresponding to remove_handle. This will prevent\nthe hook from being executed, unless it has already started executing.\nThis must be called on any napi_async_cleanup_hook_handle value obtained\nfrom napi_add_async_cleanup_hook.

The Node.js environment may be torn down at an arbitrary time as soon as\npossible with JavaScript execution disallowed, like on the request of\nworker.terminate(). When the environment is being torn down, the\nregistered napi_finalize callbacks of JavaScript objects, thread-safe\nfunctions and environment instance data are invoked immediately and\nindependently.

The invocation of napi_finalize callbacks is scheduled after the manually\nregistered cleanup hooks. In order to ensure a proper order of addon\nfinalization during environment shutdown to avoid use-after-free in the\nnapi_finalize callback, addons should register a cleanup hook with\nnapi_add_env_cleanup_hook and napi_add_async_cleanup_hook to manually\nrelease the allocated resource in a proper order.

Node-API modules are registered in a manner similar to other modules\nexcept that instead of using the NODE_MODULE macro the following\nis used:

NAPI_MODULE(NODE_GYP_MODULE_NAME, Init)\n

The next difference is the signature for the Init method. For a Node-API\nmodule it is as follows:

napi_value Init(napi_env env, napi_value exports);\n

The return value from Init is treated as the exports object for the module.\nThe Init method is passed an empty object via the exports parameter as a\nconvenience. If Init returns NULL, the parameter passed as exports is\nexported by the module. Node-API modules cannot modify the module object but\ncan specify anything as the exports property of the module.

To add the method hello as a function so that it can be called as a method\nprovided by the addon:

napi_value Init(napi_env env, napi_value exports) {\n  napi_status status;\n  napi_property_descriptor desc = {\n    \"hello\",\n    NULL,\n    Method,\n    NULL,\n    NULL,\n    NULL,\n    napi_writable | napi_enumerable | napi_configurable,\n    NULL\n  };\n  status = napi_define_properties(env, exports, 1, &desc);\n  if (status != napi_ok) return NULL;\n  return exports;\n}\n

To set a function to be returned by the require() for the addon:

napi_value Init(napi_env env, napi_value exports) {\n  napi_value method;\n  napi_status status;\n  status = napi_create_function(env, \"exports\", NAPI_AUTO_LENGTH, Method, NULL, &method);\n  if (status != napi_ok) return NULL;\n  return method;\n}\n

To define a class so that new instances can be created (often used with\nObject wrap):

// NOTE: partial example, not all referenced code is included\nnapi_value Init(napi_env env, napi_value exports) {\n  napi_status status;\n  napi_property_descriptor properties[] = {\n    { \"value\", NULL, NULL, GetValue, SetValue, NULL, napi_writable | napi_configurable, NULL },\n    DECLARE_NAPI_METHOD(\"plusOne\", PlusOne),\n    DECLARE_NAPI_METHOD(\"multiply\", Multiply),\n  };\n\n  napi_value cons;\n  status =\n      napi_define_class(env, \"MyObject\", New, NULL, 3, properties, &cons);\n  if (status != napi_ok) return NULL;\n\n  status = napi_create_reference(env, cons, 1, &constructor);\n  if (status != napi_ok) return NULL;\n\n  status = napi_set_named_property(env, exports, \"MyObject\", cons);\n  if (status != napi_ok) return NULL;\n\n  return exports;\n}\n

You can also use the NAPI_MODULE_INIT macro, which acts as a shorthand\nfor NAPI_MODULE and defining an Init function:

NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) {\n  napi_value answer;\n  napi_status result;\n\n  status = napi_create_int64(env, 42, &answer);\n  if (status != napi_ok) return NULL;\n\n  status = napi_set_named_property(env, exports, \"answer\", answer);\n  if (status != napi_ok) return NULL;\n\n  return exports;\n}\n

The parameters env and exports are provided to the body of the\nNAPI_MODULE_INIT macro.

All Node-API addons are context-aware, meaning they may be loaded multiple\ntimes. There are a few design considerations when declaring such a module.\nThe documentation on context-aware addons provides more details.

The variables env and exports will be available inside the function body\nfollowing the macro invocation.

For more details on setting properties on objects, see the section on\nWorking with JavaScript properties.

For more details on building addon modules in general, refer to the existing\nAPI.

Node-API exposes a set of APIs to create all types of JavaScript values.\nSome of these types are documented under Section language types\nof the ECMAScript Language Specification.

Fundamentally, these APIs are used to do one of the following:

\n
1. Create a new JavaScript object
\n
2. Convert from a primitive C type to a Node-API value
\n
3. Convert from Node-API value to a primitive C type
\n
4. Get global instances including undefined and null
\n

Node-API values are represented by the type napi_value.\nAny Node-API call that requires a JavaScript value takes in a napi_value.\nIn some cases, the API does check the type of the napi_value up-front.\nHowever, for better performance, it's better for the caller to make sure that\nthe napi_value in question is of the JavaScript type expected by the API.

typedef enum {\n  napi_key_include_prototypes,\n  napi_key_own_only\n} napi_key_collection_mode;\n

Describes the Keys/Properties filter enums:

napi_key_collection_mode limits the range of collected properties.

napi_key_own_only limits the collected properties to the given\nobject only. napi_key_include_prototypes will include all keys\nof the objects's prototype chain as well.

typedef enum {\n  napi_key_all_properties = 0,\n  napi_key_writable = 1,\n  napi_key_enumerable = 1 << 1,\n  napi_key_configurable = 1 << 2,\n  napi_key_skip_strings = 1 << 3,\n  napi_key_skip_symbols = 1 << 4\n} napi_key_filter;\n

Property filter bit flag. This works with bit operators to build a composite filter.

typedef enum {\n  napi_key_keep_numbers,\n  napi_key_numbers_to_strings\n} napi_key_conversion;\n

napi_key_numbers_to_strings will convert integer indexes to\nstrings. napi_key_keep_numbers will return numbers for integer\nindexes.

typedef enum {\n  // ES6 types (corresponds to typeof)\n  napi_undefined,\n  napi_null,\n  napi_boolean,\n  napi_number,\n  napi_string,\n  napi_symbol,\n  napi_object,\n  napi_function,\n  napi_external,\n  napi_bigint,\n} napi_valuetype;\n

Describes the type of a napi_value. This generally corresponds to the types\ndescribed in Section language types of the ECMAScript Language Specification.\nIn addition to types in that section, napi_valuetype can also represent\nFunctions and Objects with external data.

A JavaScript value of type napi_external appears in JavaScript as a plain\nobject such that no properties can be set on it, and no prototype.

typedef enum {\n  napi_int8_array,\n  napi_uint8_array,\n  napi_uint8_clamped_array,\n  napi_int16_array,\n  napi_uint16_array,\n  napi_int32_array,\n  napi_uint32_array,\n  napi_float32_array,\n  napi_float64_array,\n  napi_bigint64_array,\n  napi_biguint64_array,\n  napi_float16_array,\n} napi_typedarray_type;\n

This represents the underlying binary scalar datatype of the TypedArray.\nElements of this enum correspond to\nSection TypedArray objects of the ECMAScript Language Specification.

napi_status napi_create_array(napi_env env, napi_value* result)\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [out] result: A napi_value representing a JavaScript Array.
\n

Returns napi_ok if the API succeeded.

This API returns a Node-API value corresponding to a JavaScript Array type.\nJavaScript arrays are described in\nSection Array objects of the ECMAScript Language Specification.

napi_status napi_create_array_with_length(napi_env env,\n                                          size_t length,\n                                          napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] length: The initial length of the Array.
\n
• [out] result: A napi_value representing a JavaScript Array.
\n

Returns napi_ok if the API succeeded.

This API returns a Node-API value corresponding to a JavaScript Array type.\nThe Array's length property is set to the passed-in length parameter.\nHowever, the underlying buffer is not guaranteed to be pre-allocated by the VM\nwhen the array is created. That behavior is left to the underlying VM\nimplementation. If the buffer must be a contiguous block of memory that can be\ndirectly read and/or written via C, consider using\nnapi_create_external_arraybuffer.

JavaScript arrays are described in\nSection Array objects of the ECMAScript Language Specification.

napi_status napi_create_arraybuffer(napi_env env,\n                                    size_t byte_length,\n                                    void** data,\n                                    napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] length: The length in bytes of the array buffer to create.
\n
• [out] data: Pointer to the underlying byte buffer of the ArrayBuffer.\ndata can optionally be ignored by passing NULL.
\n
• [out] result: A napi_value representing a JavaScript ArrayBuffer.
\n

Returns napi_ok if the API succeeded.

This API returns a Node-API value corresponding to a JavaScript ArrayBuffer.\nArrayBuffers are used to represent fixed-length binary data buffers. They are\nnormally used as a backing-buffer for TypedArray objects.\nThe ArrayBuffer allocated will have an underlying byte buffer whose size is\ndetermined by the length parameter that's passed in.\nThe underlying buffer is optionally returned back to the caller in case the\ncaller wants to directly manipulate the buffer. This buffer can only be\nwritten to directly from native code. To write to this buffer from JavaScript,\na typed array or DataView object would need to be created.

JavaScript ArrayBuffer objects are described in\nSection ArrayBuffer objects of the ECMAScript Language Specification.

napi_status napi_create_buffer(napi_env env,\n                               size_t size,\n                               void** data,\n                               napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] size: Size in bytes of the underlying buffer.
\n
• [out] data: Raw pointer to the underlying buffer.\ndata can optionally be ignored by passing NULL.
\n
• [out] result: A napi_value representing a node::Buffer.
\n

Returns napi_ok if the API succeeded.

This API allocates a node::Buffer object. While this is still a\nfully-supported data structure, in most cases using a TypedArray will suffice.

napi_status napi_create_buffer_copy(napi_env env,\n                                    size_t length,\n                                    const void* data,\n                                    void** result_data,\n                                    napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] size: Size in bytes of the input buffer (should be the same as the size\nof the new buffer).
\n
• [in] data: Raw pointer to the underlying buffer to copy from.
\n
• [out] result_data: Pointer to the new Buffer's underlying data buffer.\nresult_data can optionally be ignored by passing NULL.
\n
• [out] result: A napi_value representing a node::Buffer.
\n

Returns napi_ok if the API succeeded.

This API allocates a node::Buffer object and initializes it with data copied\nfrom the passed-in buffer. While this is still a fully-supported data\nstructure, in most cases using a TypedArray will suffice.

napi_status napi_create_date(napi_env env,\n                             double time,\n                             napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] time: ECMAScript time value in milliseconds since 01 January, 1970 UTC.
\n
• [out] result: A napi_value representing a JavaScript Date.
\n

Returns napi_ok if the API succeeded.

This API does not observe leap seconds; they are ignored, as\nECMAScript aligns with POSIX time specification.

This API allocates a JavaScript Date object.

JavaScript Date objects are described in\nSection Date objects of the ECMAScript Language Specification.

napi_status napi_create_external(napi_env env,\n                                 void* data,\n                                 napi_finalize finalize_cb,\n                                 void* finalize_hint,\n                                 napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] data: Raw pointer to the external data.
\n
• [in] finalize_cb: Optional callback to call when the external value is being\ncollected. napi_finalize provides more details.
\n
• [in] finalize_hint: Optional hint to pass to the finalize callback during\ncollection.
\n
• [out] result: A napi_value representing an external value.
\n

Returns napi_ok if the API succeeded.

This API allocates a JavaScript value with external data attached to it. This\nis used to pass external data through JavaScript code, so it can be retrieved\nlater by native code using napi_get_value_external.

The API adds a napi_finalize callback which will be called when the JavaScript\nobject just created has been garbage collected.

The created value is not an object, and therefore does not support additional\nproperties. It is considered a distinct value type: calling napi_typeof() with\nan external value yields napi_external.

napi_status\nnapi_create_external_arraybuffer(napi_env env,\n                                 void* external_data,\n                                 size_t byte_length,\n                                 napi_finalize finalize_cb,\n                                 void* finalize_hint,\n                                 napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] external_data: Pointer to the underlying byte buffer of the\nArrayBuffer.
\n
• [in] byte_length: The length in bytes of the underlying buffer.
\n
• [in] finalize_cb: Optional callback to call when the ArrayBuffer is being\ncollected. napi_finalize provides more details.
\n
• [in] finalize_hint: Optional hint to pass to the finalize callback during\ncollection.
\n
• [out] result: A napi_value representing a JavaScript ArrayBuffer.
\n

Returns napi_ok if the API succeeded.

Some runtimes other than Node.js have dropped support for external buffers.\nOn runtimes other than Node.js this method may return\nnapi_no_external_buffers_allowed to indicate that external\nbuffers are not supported. One such runtime is Electron as\ndescribed in this issue\nelectron/issues/35801.

In order to maintain broadest compatibility with all runtimes\nyou may define NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED in your addon before\nincludes for the node-api headers. Doing so will hide the 2 functions\nthat create external buffers. This will ensure a compilation error\noccurs if you accidentally use one of these methods.

This API returns a Node-API value corresponding to a JavaScript ArrayBuffer.\nThe underlying byte buffer of the ArrayBuffer is externally allocated and\nmanaged. The caller must ensure that the byte buffer remains valid until the\nfinalize callback is called.

The API adds a napi_finalize callback which will be called when the JavaScript\nobject just created has been garbage collected.

JavaScript ArrayBuffers are described in\nSection ArrayBuffer objects of the ECMAScript Language Specification.

napi_status napi_create_external_buffer(napi_env env,\n                                        size_t length,\n                                        void* data,\n                                        napi_finalize finalize_cb,\n                                        void* finalize_hint,\n                                        napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] length: Size in bytes of the input buffer (should be the same as the\nsize of the new buffer).
\n
• [in] data: Raw pointer to the underlying buffer to expose to JavaScript.
\n
• [in] finalize_cb: Optional callback to call when the ArrayBuffer is being\ncollected. napi_finalize provides more details.
\n
• [in] finalize_hint: Optional hint to pass to the finalize callback during\ncollection.
\n
• [out] result: A napi_value representing a node::Buffer.
\n

Returns napi_ok if the API succeeded.

Some runtimes other than Node.js have dropped support for external buffers.\nOn runtimes other than Node.js this method may return\nnapi_no_external_buffers_allowed to indicate that external\nbuffers are not supported. One such runtime is Electron as\ndescribed in this issue\nelectron/issues/35801.

In order to maintain broadest compatibility with all runtimes\nyou may define NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED in your addon before\nincludes for the node-api headers. Doing so will hide the 2 functions\nthat create external buffers. This will ensure a compilation error\noccurs if you accidentally use one of these methods.

This API allocates a node::Buffer object and initializes it with data\nbacked by the passed in buffer. While this is still a fully-supported data\nstructure, in most cases using a TypedArray will suffice.

The API adds a napi_finalize callback which will be called when the JavaScript\nobject just created has been garbage collected.

For Node.js >=4 Buffers are Uint8Arrays.

napi_status napi_create_object(napi_env env, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: A napi_value representing a JavaScript Object.
\n

Returns napi_ok if the API succeeded.

This API allocates a default JavaScript Object.\nIt is the equivalent of doing new Object() in JavaScript.

The JavaScript Object type is described in Section object type of the\nECMAScript Language Specification.

napi_status node_api_create_object_with_properties(napi_env env,\n                                                   napi_value prototype_or_null,\n                                                   const napi_value* property_names,\n                                                   const napi_value* property_values,\n                                                   size_t property_count,\n                                                   napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] prototype_or_null: The prototype object for the new object. Can be a\nnapi_value representing a JavaScript object to use as the prototype, a\nnapi_value representing JavaScript null, or a nullptr that will be converted to null.
\n
• [in] property_names: Array of napi_value representing the property names.
\n
• [in] property_values: Array of napi_value representing the property values.
\n
• [in] property_count: Number of properties in the arrays.
\n
• [out] result: A napi_value representing a JavaScript Object.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript Object with the specified prototype and\nproperties. This is more efficient than calling napi_create_object followed\nby multiple napi_set_property calls, as it can create the object with all\nproperties atomically, avoiding potential V8 map transitions.

The arrays property_names and property_values must have the same length\nspecified by property_count. The properties are added to the object in the\norder they appear in the arrays.

napi_status napi_create_symbol(napi_env env,\n                               napi_value description,\n                               napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] description: Optional napi_value which refers to a JavaScript\nstring to be set as the description for the symbol.
\n
• [out] result: A napi_value representing a JavaScript symbol.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript symbol value from a UTF8-encoded C string.

The JavaScript symbol type is described in Section symbol type\nof the ECMAScript Language Specification.

napi_status node_api_symbol_for(napi_env env,\n                                const char* utf8description,\n                                size_t length,\n                                napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] utf8description: UTF-8 C string representing the text to be used as the\ndescription for the symbol.
\n
• [in] length: The length of the description string in bytes, or\nNAPI_AUTO_LENGTH if it is null-terminated.
\n
• [out] result: A napi_value representing a JavaScript symbol.
\n

Returns napi_ok if the API succeeded.

This API searches in the global registry for an existing symbol with the given\ndescription. If the symbol already exists it will be returned, otherwise a new\nsymbol will be created in the registry.

The JavaScript symbol type is described in Section symbol type of the ECMAScript\nLanguage Specification.

napi_status napi_create_typedarray(napi_env env,\n                                   napi_typedarray_type type,\n                                   size_t length,\n                                   napi_value arraybuffer,\n                                   size_t byte_offset,\n                                   napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] type: Scalar datatype of the elements within the TypedArray.
\n
• [in] length: Number of elements in the TypedArray.
\n
• [in] arraybuffer: ArrayBuffer underlying the typed array.
\n
• [in] byte_offset: The byte offset within the ArrayBuffer from which to\nstart projecting the TypedArray.
\n
• [out] result: A napi_value representing a JavaScript TypedArray.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript TypedArray object over an existing\nArrayBuffer. TypedArray objects provide an array-like view over an\nunderlying data buffer where each element has the same underlying binary scalar\ndatatype.

It's required that (length * size_of_element) + byte_offset should\nbe <= the size in bytes of the array passed in. If not, a RangeError exception\nis raised.

JavaScript TypedArray objects are described in\nSection TypedArray objects of the ECMAScript Language Specification.

napi_status NAPI_CDECL node_api_create_buffer_from_arraybuffer(napi_env env,\n                                                              napi_value arraybuffer,\n                                                              size_t byte_offset,\n                                                              size_t byte_length,\n                                                              napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] arraybuffer: The ArrayBuffer from which the buffer will be created.
\n
• [in] byte_offset: The byte offset within the ArrayBuffer from which to start creating the buffer.
\n
• [in] byte_length: The length in bytes of the buffer to be created from the ArrayBuffer.
\n
• [out] result: A napi_value representing the created JavaScript Buffer object.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript Buffer object from an existing ArrayBuffer.\nThe Buffer object is a Node.js-specific class that provides a way to work with binary data directly in JavaScript.

The byte range [byte_offset, byte_offset + byte_length)\nmust be within the bounds of the ArrayBuffer. If byte_offset + byte_length\nexceeds the size of the ArrayBuffer, a RangeError exception is raised.

napi_status napi_create_dataview(napi_env env,\n                                 size_t byte_length,\n                                 napi_value arraybuffer,\n                                 size_t byte_offset,\n                                 napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] length: Number of elements in the DataView.
\n
• [in] arraybuffer: ArrayBuffer or SharedArrayBuffer underlying the\nDataView.
\n
• [in] byte_offset: The byte offset within the ArrayBuffer from which to\nstart projecting the DataView.
\n
• [out] result: A napi_value representing a JavaScript DataView.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript DataView object over an existing ArrayBuffer\nor SharedArrayBuffer. DataView objects provide an array-like view over an\nunderlying data buffer, but one which allows items of different size and type in\nthe ArrayBuffer or SharedArrayBuffer.

It is required that byte_length + byte_offset is less than or equal to the\nsize in bytes of the array passed in. If not, a RangeError exception is\nraised.

JavaScript DataView objects are described in\nSection DataView objects of the ECMAScript Language Specification.

napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: Integer value to be represented in JavaScript.
\n
• [out] result: A napi_value representing a JavaScript number.
\n

Returns napi_ok if the API succeeded.

This API is used to convert from the C int32_t type to the JavaScript\nnumber type.

The JavaScript number type is described in\nSection number type of the ECMAScript Language Specification.

napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: Unsigned integer value to be represented in JavaScript.
\n
• [out] result: A napi_value representing a JavaScript number.
\n

Returns napi_ok if the API succeeded.

This API is used to convert from the C uint32_t type to the JavaScript\nnumber type.

The JavaScript number type is described in\nSection number type of the ECMAScript Language Specification.

napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: Integer value to be represented in JavaScript.
\n
• [out] result: A napi_value representing a JavaScript number.
\n

Returns napi_ok if the API succeeded.

This API is used to convert from the C int64_t type to the JavaScript\nnumber type.

The JavaScript number type is described in Section number type\nof the ECMAScript Language Specification. Note the complete range of int64_t\ncannot be represented with full precision in JavaScript. Integer values\noutside the range of Number.MIN_SAFE_INTEGER -(2**53 - 1) -\nNumber.MAX_SAFE_INTEGER (2**53 - 1) will lose precision.

napi_status napi_create_double(napi_env env, double value, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: Double-precision value to be represented in JavaScript.
\n
• [out] result: A napi_value representing a JavaScript number.
\n

Returns napi_ok if the API succeeded.

This API is used to convert from the C double type to the JavaScript\nnumber type.

The JavaScript number type is described in\nSection number type of the ECMAScript Language Specification.

napi_status napi_create_bigint_int64(napi_env env,\n                                     int64_t value,\n                                     napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: Integer value to be represented in JavaScript.
\n
• [out] result: A napi_value representing a JavaScript BigInt.
\n

Returns napi_ok if the API succeeded.

This API converts the C int64_t type to the JavaScript BigInt type.

napi_status napi_create_bigint_uint64(napi_env env,\n                                      uint64_t value,\n                                      napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: Unsigned integer value to be represented in JavaScript.
\n
• [out] result: A napi_value representing a JavaScript BigInt.
\n

Returns napi_ok if the API succeeded.

This API converts the C uint64_t type to the JavaScript BigInt type.

napi_status napi_create_bigint_words(napi_env env,\n                                     int sign_bit,\n                                     size_t word_count,\n                                     const uint64_t* words,\n                                     napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] sign_bit: Determines if the resulting BigInt will be positive or\nnegative.
\n
• [in] word_count: The length of the words array.
\n
• [in] words: An array of uint64_t little-endian 64-bit words.
\n
• [out] result: A napi_value representing a JavaScript BigInt.
\n

Returns napi_ok if the API succeeded.

This API converts an array of unsigned 64-bit words into a single BigInt\nvalue.

The resulting BigInt is calculated as: (–1)^sign_bit (words[0]\n× (2⁶⁴)⁰ + words[1] × (2⁶⁴)¹ + …)

napi_status napi_create_string_latin1(napi_env env,\n                                      const char* str,\n                                      size_t length,\n                                      napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] str: Character buffer representing an ISO-8859-1-encoded string.
\n
• [in] length: The length of the string in bytes, or NAPI_AUTO_LENGTH if it\nis null-terminated.
\n
• [out] result: A napi_value representing a JavaScript string.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript string value from an ISO-8859-1-encoded C\nstring. The native string is copied.

The JavaScript string type is described in\nSection string type of the ECMAScript Language Specification.

napi_status\nnode_api_create_external_string_latin1(napi_env env,\n                                       char* str,\n                                       size_t length,\n                                       napi_finalize finalize_callback,\n                                       void* finalize_hint,\n                                       napi_value* result,\n                                       bool* copied);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] str: Character buffer representing an ISO-8859-1-encoded string.
\n
• [in] length: The length of the string in bytes, or NAPI_AUTO_LENGTH if it\nis null-terminated.
\n
• [in] finalize_callback: The function to call when the string is being\ncollected. The function will be called with the following parameters:\n
  \n
  • [in] env: The environment in which the add-on is running. This value\nmay be null if the string is being collected as part of the termination\nof the worker or the main Node.js instance.
  \n
  • [in] data: This is the value str as a void* pointer.
  \n
  • [in] finalize_hint: This is the value finalize_hint that was given\nto the API.\nnapi_finalize provides more details.\nThis parameter is optional. Passing a null value means that the add-on\ndoesn't need to be notified when the corresponding JavaScript string is\ncollected.
  \n
  \n
\n
• [in] finalize_hint: Optional hint to pass to the finalize callback during\ncollection.
\n
• [out] result: A napi_value representing a JavaScript string.
\n
• [out] copied: Whether the string was copied. If it was, the finalizer will\nalready have been invoked to destroy str.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript string value from an ISO-8859-1-encoded C\nstring. The native string may not be copied and must thus exist for the entire\nlife cycle of the JavaScript value.

The JavaScript string type is described in\nSection string type of the ECMAScript Language Specification.

napi_status napi_create_string_utf16(napi_env env,\n                                     const char16_t* str,\n                                     size_t length,\n                                     napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] str: Character buffer representing a UTF16-LE-encoded string.
\n
• [in] length: The length of the string in two-byte code units, or\nNAPI_AUTO_LENGTH if it is null-terminated.
\n
• [out] result: A napi_value representing a JavaScript string.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript string value from a UTF16-LE-encoded C string.\nThe native string is copied.

The JavaScript string type is described in\nSection string type of the ECMAScript Language Specification.

napi_status\nnode_api_create_external_string_utf16(napi_env env,\n                                      char16_t* str,\n                                      size_t length,\n                                      napi_finalize finalize_callback,\n                                      void* finalize_hint,\n                                      napi_value* result,\n                                      bool* copied);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] str: Character buffer representing a UTF16-LE-encoded string.
\n
• [in] length: The length of the string in two-byte code units, or\nNAPI_AUTO_LENGTH if it is null-terminated.
\n
• [in] finalize_callback: The function to call when the string is being\ncollected. The function will be called with the following parameters:\n
  \n
  • [in] env: The environment in which the add-on is running. This value\nmay be null if the string is being collected as part of the termination\nof the worker or the main Node.js instance.
  \n
  • [in] data: This is the value str as a void* pointer.
  \n
  • [in] finalize_hint: This is the value finalize_hint that was given\nto the API.\nnapi_finalize provides more details.\nThis parameter is optional. Passing a null value means that the add-on\ndoesn't need to be notified when the corresponding JavaScript string is\ncollected.
  \n
  \n
\n
• [in] finalize_hint: Optional hint to pass to the finalize callback during\ncollection.
\n
• [out] result: A napi_value representing a JavaScript string.
\n
• [out] copied: Whether the string was copied. If it was, the finalizer will\nalready have been invoked to destroy str.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript string value from a UTF16-LE-encoded C string.\nThe native string may not be copied and must thus exist for the entire life\ncycle of the JavaScript value.

The JavaScript string type is described in\nSection string type of the ECMAScript Language Specification.

napi_status napi_create_string_utf8(napi_env env,\n                                    const char* str,\n                                    size_t length,\n                                    napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] str: Character buffer representing a UTF8-encoded string.
\n
• [in] length: The length of the string in bytes, or NAPI_AUTO_LENGTH if it\nis null-terminated.
\n
• [out] result: A napi_value representing a JavaScript string.
\n

Returns napi_ok if the API succeeded.

This API creates a JavaScript string value from a UTF8-encoded C string.\nThe native string is copied.

The JavaScript string type is described in\nSection string type of the ECMAScript Language Specification.

Many JavaScript engines including V8 use internalized strings as keys\nto set and get property values. They typically use a hash table to create\nand lookup such strings. While it adds some cost per key creation, it improves\nthe performance after that by enabling comparison of string pointers instead\nof the whole strings.

If a new JavaScript string is intended to be used as a property key, then for\nsome JavaScript engines it will be more efficient to use the functions in this\nsection. Otherwise, use the napi_create_string_utf8 or\nnode_api_create_external_string_utf8 series functions as there may be\nadditional overhead in creating/storing strings with the property key\ncreation methods.

napi_status NAPI_CDECL node_api_create_property_key_latin1(napi_env env,\n                                                           const char* str,\n                                                           size_t length,\n                                                           napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] str: Character buffer representing an ISO-8859-1-encoded string.
\n
• [in] length: The length of the string in bytes, or NAPI_AUTO_LENGTH if it\nis null-terminated.
\n
• [out] result: A napi_value representing an optimized JavaScript string\nto be used as a property key for objects.
\n

Returns napi_ok if the API succeeded.

This API creates an optimized JavaScript string value from\nan ISO-8859-1-encoded C string to be used as a property key for objects.\nThe native string is copied. In contrast with napi_create_string_latin1,\nsubsequent calls to this function with the same str pointer may benefit from a speedup\nin the creation of the requested napi_value, depending on the engine.

The JavaScript string type is described in\nSection string type of the ECMAScript Language Specification.

napi_status NAPI_CDECL node_api_create_property_key_utf16(napi_env env,\n                                                          const char16_t* str,\n                                                          size_t length,\n                                                          napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] str: Character buffer representing a UTF16-LE-encoded string.
\n
• [in] length: The length of the string in two-byte code units, or\nNAPI_AUTO_LENGTH if it is null-terminated.
\n
• [out] result: A napi_value representing an optimized JavaScript string\nto be used as a property key for objects.
\n

Returns napi_ok if the API succeeded.

This API creates an optimized JavaScript string value from\na UTF16-LE-encoded C string to be used as a property key for objects.\nThe native string is copied.

The JavaScript string type is described in\nSection string type of the ECMAScript Language Specification.

napi_status NAPI_CDECL node_api_create_property_key_utf8(napi_env env,\n                                                         const char* str,\n                                                         size_t length,\n                                                         napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] str: Character buffer representing a UTF8-encoded string.
\n
• [in] length: The length of the string in two-byte code units, or\nNAPI_AUTO_LENGTH if it is null-terminated.
\n
• [out] result: A napi_value representing an optimized JavaScript string\nto be used as a property key for objects.
\n

Returns napi_ok if the API succeeded.

This API creates an optimized JavaScript string value from\na UTF8-encoded C string to be used as a property key for objects.\nThe native string is copied.

The JavaScript string type is described in\nSection string type of the ECMAScript Language Specification.

napi_status napi_get_array_length(napi_env env,\n                                  napi_value value,\n                                  uint32_t* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing the JavaScript Array whose length is\nbeing queried.
\n
• [out] result: uint32 representing length of the array.
\n

Returns napi_ok if the API succeeded.

This API returns the length of an array.

Array length is described in Section Array instance length of the ECMAScript Language\nSpecification.

napi_status napi_get_arraybuffer_info(napi_env env,\n                                      napi_value arraybuffer,\n                                      void** data,\n                                      size_t* byte_length)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] arraybuffer: napi_value representing the ArrayBuffer or SharedArrayBuffer being queried.
\n
• [out] data: The underlying data buffer of the ArrayBuffer or SharedArrayBuffer\nis 0, this may be NULL or any other pointer value.
\n
• [out] byte_length: Length in bytes of the underlying data buffer.
\n

Returns napi_ok if the API succeeded.

This API is used to retrieve the underlying data buffer of an ArrayBuffer or SharedArrayBuffer and its length.

WARNING: Use caution while using this API. The lifetime of the underlying data\nbuffer is managed by the ArrayBuffer or SharedArrayBuffer even after it's returned. A\npossible safe way to use this API is in conjunction with\nnapi_create_reference, which can be used to guarantee control over the\nlifetime of the ArrayBuffer or SharedArrayBuffer. It's also safe to use the returned data buffer\nwithin the same callback as long as there are no calls to other APIs that might\ntrigger a GC.

napi_status napi_get_buffer_info(napi_env env,\n                                 napi_value value,\n                                 void** data,\n                                 size_t* length)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing the node::Buffer or Uint8Array\nbeing queried.
\n
• [out] data: The underlying data buffer of the node::Buffer or\nUint8Array. If length is 0, this may be NULL or any other pointer value.
\n
• [out] length: Length in bytes of the underlying data buffer.
\n

Returns napi_ok if the API succeeded.

This method returns the identical data and byte_length as\nnapi_get_typedarray_info. And napi_get_typedarray_info accepts a\nnode::Buffer (a Uint8Array) as the value too.

This API is used to retrieve the underlying data buffer of a node::Buffer\nand its length.

Warning: Use caution while using this API since the underlying data buffer's\nlifetime is not guaranteed if it's managed by the VM.

napi_status napi_get_prototype(napi_env env,\n                               napi_value object,\n                               napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] object: napi_value representing JavaScript Object whose prototype\nto return. This returns the equivalent of Object.getPrototypeOf (which is\nnot the same as the function's prototype property).
\n
• [out] result: napi_value representing prototype of the given object.
\n

Returns napi_ok if the API succeeded.

napi_status napi_get_typedarray_info(napi_env env,\n                                     napi_value typedarray,\n                                     napi_typedarray_type* type,\n                                     size_t* length,\n                                     void** data,\n                                     napi_value* arraybuffer,\n                                     size_t* byte_offset)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] typedarray: napi_value representing the TypedArray whose\nproperties to query.
\n
• [out] type: Scalar datatype of the elements within the TypedArray.
\n
• [out] length: The number of elements in the TypedArray.
\n
• [out] data: The data buffer underlying the TypedArray adjusted by\nthe byte_offset value so that it points to the first element in the\nTypedArray. If the length of the array is 0, this may be NULL or\nany other pointer value.
\n
• [out] arraybuffer: The ArrayBuffer underlying the TypedArray.
\n
• [out] byte_offset: The byte offset within the underlying native array\nat which the first element of the arrays is located. The value for the data\nparameter has already been adjusted so that data points to the first element\nin the array. Therefore, the first byte of the native array would be at\ndata - byte_offset.
\n

Returns napi_ok if the API succeeded.

This API returns various properties of a typed array.

Any of the out parameters may be NULL if that property is unneeded.

Warning: Use caution while using this API since the underlying data buffer\nis managed by the VM.

napi_status napi_get_dataview_info(napi_env env,\n                                   napi_value dataview,\n                                   size_t* byte_length,\n                                   void** data,\n                                   napi_value* arraybuffer,\n                                   size_t* byte_offset)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] dataview: napi_value representing the DataView whose\nproperties to query.
\n
• [out] byte_length: Number of bytes in the DataView.
\n
• [out] data: The data buffer underlying the DataView.\nIf byte_length is 0, this may be NULL or any other pointer value.
\n
• [out] arraybuffer: ArrayBuffer underlying the DataView.
\n
• [out] byte_offset: The byte offset within the data buffer from which\nto start projecting the DataView.
\n

Returns napi_ok if the API succeeded.

Any of the out parameters may be NULL if that property is unneeded.

This API returns various properties of a DataView.

napi_status napi_get_date_value(napi_env env,\n                                napi_value value,\n                                double* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing a JavaScript Date.
\n
• [out] result: Time value as a double represented as milliseconds since\nmidnight at the beginning of 01 January, 1970 UTC.
\n

This API does not observe leap seconds; they are ignored, as\nECMAScript aligns with POSIX time specification.

Returns napi_ok if the API succeeded. If a non-date napi_value is passed\nin it returns napi_date_expected.

This API returns the C double primitive of time value for the given JavaScript\nDate.

napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript Boolean.
\n
• [out] result: C boolean primitive equivalent of the given JavaScript\nBoolean.
\n

Returns napi_ok if the API succeeded. If a non-boolean napi_value is\npassed in it returns napi_boolean_expected.

This API returns the C boolean primitive equivalent of the given JavaScript\nBoolean.

napi_status napi_get_value_double(napi_env env,\n                                  napi_value value,\n                                  double* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript number.
\n
• [out] result: C double primitive equivalent of the given JavaScript\nnumber.
\n

Returns napi_ok if the API succeeded. If a non-number napi_value is passed\nin it returns napi_number_expected.

This API returns the C double primitive equivalent of the given JavaScript\nnumber.

napi_status napi_get_value_bigint_int64(napi_env env,\n                                        napi_value value,\n                                        int64_t* result,\n                                        bool* lossless);\n

\n
• [in] env: The environment that the API is invoked under
\n
• [in] value: napi_value representing JavaScript BigInt.
\n
• [out] result: C int64_t primitive equivalent of the given JavaScript\nBigInt.
\n
• [out] lossless: Indicates whether the BigInt value was converted\nlosslessly.
\n

Returns napi_ok if the API succeeded. If a non-BigInt is passed in it\nreturns napi_bigint_expected.

This API returns the C int64_t primitive equivalent of the given JavaScript\nBigInt. If needed it will truncate the value, setting lossless to false.

napi_status napi_get_value_bigint_uint64(napi_env env,\n                                        napi_value value,\n                                        uint64_t* result,\n                                        bool* lossless);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript BigInt.
\n
• [out] result: C uint64_t primitive equivalent of the given JavaScript\nBigInt.
\n
• [out] lossless: Indicates whether the BigInt value was converted\nlosslessly.
\n

Returns napi_ok if the API succeeded. If a non-BigInt is passed in it\nreturns napi_bigint_expected.

This API returns the C uint64_t primitive equivalent of the given JavaScript\nBigInt. If needed it will truncate the value, setting lossless to false.

napi_status napi_get_value_bigint_words(napi_env env,\n                                        napi_value value,\n                                        int* sign_bit,\n                                        size_t* word_count,\n                                        uint64_t* words);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript BigInt.
\n
• [out] sign_bit: Integer representing if the JavaScript BigInt is positive\nor negative.
\n
• [in/out] word_count: Must be initialized to the length of the words\narray. Upon return, it will be set to the actual number of words that\nwould be needed to store this BigInt.
\n
• [out] words: Pointer to a pre-allocated 64-bit word array.
\n

Returns napi_ok if the API succeeded.

This API converts a single BigInt value into a sign bit, 64-bit little-endian\narray, and the number of elements in the array. sign_bit and words may be\nboth set to NULL, in order to get only word_count.

napi_status napi_get_value_external(napi_env env,\n                                    napi_value value,\n                                    void** result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript external value.
\n
• [out] result: Pointer to the data wrapped by the JavaScript external value.
\n

Returns napi_ok if the API succeeded. If a non-external napi_value is\npassed in it returns napi_invalid_arg.

This API retrieves the external data pointer that was previously passed to\nnapi_create_external().

napi_status napi_get_value_int32(napi_env env,\n                                 napi_value value,\n                                 int32_t* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript number.
\n
• [out] result: C int32 primitive equivalent of the given JavaScript\nnumber.
\n

Returns napi_ok if the API succeeded. If a non-number napi_value\nis passed in napi_number_expected.

This API returns the C int32 primitive equivalent\nof the given JavaScript number.

If the number exceeds the range of the 32 bit integer, then the result is\ntruncated to the equivalent of the bottom 32 bits. This can result in a large\npositive number becoming a negative number if the value is > 2³¹ - 1.

Non-finite number values (NaN, +Infinity, or -Infinity) set the\nresult to zero.

napi_status napi_get_value_int64(napi_env env,\n                                 napi_value value,\n                                 int64_t* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript number.
\n
• [out] result: C int64 primitive equivalent of the given JavaScript\nnumber.
\n

Returns napi_ok if the API succeeded. If a non-number napi_value\nis passed in it returns napi_number_expected.

This API returns the C int64 primitive equivalent of the given JavaScript\nnumber.

number values outside the range of Number.MIN_SAFE_INTEGER\n-(2**53 - 1) - Number.MAX_SAFE_INTEGER (2**53 - 1) will lose\nprecision.

Non-finite number values (NaN, +Infinity, or -Infinity) set the\nresult to zero.

napi_status napi_get_value_string_latin1(napi_env env,\n                                         napi_value value,\n                                         char* buf,\n                                         size_t bufsize,\n                                         size_t* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript string.
\n
• [in] buf: Buffer to write the ISO-8859-1-encoded string into. If NULL is\npassed in, the length of the string in bytes and excluding the null terminator\nis returned in result.
\n
• [in] bufsize: Size of the destination buffer. When this value is\ninsufficient, the returned string is truncated and null-terminated.\nIf this value is zero, then the string is not returned and no changes are done\nto the buffer.
\n
• [out] result: Number of bytes copied into the buffer, excluding the null\nterminator.
\n

Returns napi_ok if the API succeeded. If a non-string napi_value\nis passed in it returns napi_string_expected.

This API returns the ISO-8859-1-encoded string corresponding the value passed\nin.

napi_status napi_get_value_string_utf8(napi_env env,\n                                       napi_value value,\n                                       char* buf,\n                                       size_t bufsize,\n                                       size_t* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript string.
\n
• [in] buf: Buffer to write the UTF8-encoded string into. If NULL is passed\nin, the length of the string in bytes and excluding the null terminator is\nreturned in result.
\n
• [in] bufsize: Size of the destination buffer. When this value is\ninsufficient, the returned string is truncated and null-terminated.\nIf this value is zero, then the string is not returned and no changes are done\nto the buffer.
\n
• [out] result: Number of bytes copied into the buffer, excluding the null\nterminator.
\n

Returns napi_ok if the API succeeded. If a non-string napi_value\nis passed in it returns napi_string_expected.

This API returns the UTF8-encoded string corresponding the value passed in.

napi_status napi_get_value_string_utf16(napi_env env,\n                                        napi_value value,\n                                        char16_t* buf,\n                                        size_t bufsize,\n                                        size_t* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript string.
\n
• [in] buf: Buffer to write the UTF16-LE-encoded string into. If NULL is\npassed in, the length of the string in 2-byte code units and excluding the\nnull terminator is returned.
\n
• [in] bufsize: Size of the destination buffer. When this value is\ninsufficient, the returned string is truncated and null-terminated.\nIf this value is zero, then the string is not returned and no changes are done\nto the buffer.
\n
• [out] result: Number of 2-byte code units copied into the buffer, excluding\nthe null terminator.
\n

Returns napi_ok if the API succeeded. If a non-string napi_value\nis passed in it returns napi_string_expected.

This API returns the UTF16-encoded string corresponding the value passed in.

napi_status napi_get_value_uint32(napi_env env,\n                                  napi_value value,\n                                  uint32_t* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: napi_value representing JavaScript number.
\n
• [out] result: C primitive equivalent of the given napi_value as a\nuint32_t.
\n

Returns napi_ok if the API succeeded. If a non-number napi_value\nis passed in it returns napi_number_expected.

This API returns the C primitive equivalent of the given napi_value as a\nuint32_t.

napi_status napi_get_boolean(napi_env env, bool value, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The value of the boolean to retrieve.
\n
• [out] result: napi_value representing JavaScript Boolean singleton to\nretrieve.
\n

Returns napi_ok if the API succeeded.

This API is used to return the JavaScript singleton object that is used to\nrepresent the given boolean value.

napi_status napi_get_global(napi_env env, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: napi_value representing JavaScript global object.
\n

Returns napi_ok if the API succeeded.

This API returns the global object.

napi_status napi_get_null(napi_env env, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: napi_value representing JavaScript null object.
\n

Returns napi_ok if the API succeeded.

This API returns the null object.

napi_status napi_get_undefined(napi_env env, napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: napi_value representing JavaScript Undefined value.
\n

Returns napi_ok if the API succeeded.

This API returns the Undefined object.

Node-API exposes a set of APIs to perform some abstract operations on JavaScript\nvalues.

These APIs support doing one of the following:

\n
1. Coerce JavaScript values to specific JavaScript types (such as number or\nstring).
\n
2. Check the type of a JavaScript value.
\n
3. Check for equality between two JavaScript values.
\n

napi_status napi_coerce_to_bool(napi_env env,\n                                napi_value value,\n                                napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to coerce.
\n
• [out] result: napi_value representing the coerced JavaScript Boolean.
\n

Returns napi_ok if the API succeeded.

This API implements the abstract operation ToBoolean() as defined in\nSection ToBoolean of the ECMAScript Language Specification.

napi_status napi_coerce_to_number(napi_env env,\n                                  napi_value value,\n                                  napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to coerce.
\n
• [out] result: napi_value representing the coerced JavaScript number.
\n

Returns napi_ok if the API succeeded.

This API implements the abstract operation ToNumber() as defined in\nSection ToNumber of the ECMAScript Language Specification.\nThis function potentially runs JS code if the passed-in value is an\nobject.

napi_status napi_coerce_to_object(napi_env env,\n                                  napi_value value,\n                                  napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to coerce.
\n
• [out] result: napi_value representing the coerced JavaScript Object.
\n

Returns napi_ok if the API succeeded.

This API implements the abstract operation ToObject() as defined in\nSection ToObject of the ECMAScript Language Specification.

napi_status napi_coerce_to_string(napi_env env,\n                                  napi_value value,\n                                  napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to coerce.
\n
• [out] result: napi_value representing the coerced JavaScript string.
\n

Returns napi_ok if the API succeeded.

This API implements the abstract operation ToString() as defined in\nSection ToString of the ECMAScript Language Specification.\nThis function potentially runs JS code if the passed-in value is an\nobject.

napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value whose type to query.
\n
• [out] result: The type of the JavaScript value.
\n

Returns napi_ok if the API succeeded.

\n
• napi_invalid_arg if the type of value is not a known ECMAScript type and\nvalue is not an External value.
\n

This API represents behavior similar to invoking the typeof Operator on\nthe object as defined in Section typeof operator of the ECMAScript Language\nSpecification. However, there are some differences:

\n
1. It has support for detecting an External value.
\n
2. It detects null as a separate type, while ECMAScript typeof would detect\nobject.
\n

If value has a type that is invalid, an error is returned.

napi_status napi_instanceof(napi_env env,\n                            napi_value object,\n                            napi_value constructor,\n                            bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] object: The JavaScript value to check.
\n
• [in] constructor: The JavaScript function object of the constructor function\nto check against.
\n
• [out] result: Boolean that is set to true if object instanceof constructor\nis true.
\n

Returns napi_ok if the API succeeded.

This API represents invoking the instanceof Operator on the object as\ndefined in Section instanceof operator of the ECMAScript Language Specification.

napi_status napi_is_array(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to check.
\n
• [out] result: Whether the given object is an array.
\n

Returns napi_ok if the API succeeded.

This API represents invoking the IsArray operation on the object\nas defined in Section IsArray of the ECMAScript Language Specification.

napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to check.
\n
• [out] result: Whether the given object is an ArrayBuffer.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in is an array buffer.

napi_status napi_is_buffer(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to check.
\n
• [out] result: Whether the given napi_value represents a node::Buffer or\nUint8Array object.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in is a buffer or Uint8Array.\nnapi_is_typedarray should be preferred if the caller needs to check if the\nvalue is a Uint8Array.

napi_status napi_is_date(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to check.
\n
• [out] result: Whether the given napi_value represents a JavaScript Date\nobject.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in is a date.

napi_status napi_is_error(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to check.
\n
• [out] result: Whether the given napi_value represents an Error object.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in is an Error.

napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to check.
\n
• [out] result: Whether the given napi_value represents a TypedArray.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in is a typed array.

napi_status napi_is_dataview(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to check.
\n
• [out] result: Whether the given napi_value represents a DataView.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in is a DataView.

napi_status napi_strict_equals(napi_env env,\n                               napi_value lhs,\n                               napi_value rhs,\n                               bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] lhs: The JavaScript value to check.
\n
• [in] rhs: The JavaScript value to check against.
\n
• [out] result: Whether the two napi_value objects are equal.
\n

Returns napi_ok if the API succeeded.

This API represents the invocation of the Strict Equality algorithm as\ndefined in Section IsStrctEqual of the ECMAScript Language Specification.

napi_status napi_detach_arraybuffer(napi_env env,\n                                    napi_value arraybuffer)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] arraybuffer: The JavaScript ArrayBuffer to be detached.
\n

Returns napi_ok if the API succeeded. If a non-detachable ArrayBuffer is\npassed in it returns napi_detachable_arraybuffer_expected.

Generally, an ArrayBuffer is non-detachable if it has been detached before.\nThe engine may impose additional conditions on whether an ArrayBuffer is\ndetachable. For example, V8 requires that the ArrayBuffer be external,\nthat is, created with napi_create_external_arraybuffer.

This API represents the invocation of the ArrayBuffer detach operation as\ndefined in Section detachArrayBuffer of the ECMAScript Language Specification.

napi_status napi_is_detached_arraybuffer(napi_env env,\n                                         napi_value arraybuffer,\n                                         bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] arraybuffer: The JavaScript ArrayBuffer to be checked.
\n
• [out] result: Whether the arraybuffer is detached.
\n

Returns napi_ok if the API succeeded.

The ArrayBuffer is considered detached if its internal data is null.

This API represents the invocation of the ArrayBuffer IsDetachedBuffer\noperation as defined in Section isDetachedBuffer of the ECMAScript Language\nSpecification.

napi_status node_api_is_sharedarraybuffer(napi_env env, napi_value value, bool* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The JavaScript value to check.
\n
• [out] result: Whether the given napi_value represents a SharedArrayBuffer.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in is a SharedArrayBuffer.

napi_status node_api_create_sharedarraybuffer(napi_env env,\n                                             size_t byte_length,\n                                             void** data,\n                                             napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] byte_length: The length in bytes of the shared array buffer to create.
\n
• [out] data: Pointer to the underlying byte buffer of the SharedArrayBuffer.\ndata can optionally be ignored by passing NULL.
\n
• [out] result: A napi_value representing a JavaScript SharedArrayBuffer.
\n

Returns napi_ok if the API succeeded.

This API returns a Node-API value corresponding to a JavaScript SharedArrayBuffer.\nSharedArrayBuffers are used to represent fixed-length binary data buffers that\ncan be shared across multiple workers.

The SharedArrayBuffer allocated will have an underlying byte buffer whose size is\ndetermined by the byte_length parameter that's passed in.\nThe underlying buffer is optionally returned back to the caller in case the\ncaller wants to directly manipulate the buffer. This buffer can only be\nwritten to directly from native code. To write to this buffer from JavaScript,\na typed array or DataView object would need to be created.

JavaScript SharedArrayBuffer objects are described in\nSection SharedArrayBuffer objects of the ECMAScript Language Specification.

Node-API exposes a set of APIs to get and set properties on JavaScript\nobjects.

Properties in JavaScript are represented as a tuple of a key and a value.\nFundamentally, all property keys in Node-API can be represented in one of the\nfollowing forms:

\n
• Named: a simple UTF8-encoded string
\n
• Integer-Indexed: an index value represented by uint32_t
\n
• JavaScript value: these are represented in Node-API by napi_value. This can\nbe a napi_value representing a string, number, or symbol.
\n

Node-API values are represented by the type napi_value.\nAny Node-API call that requires a JavaScript value takes in a napi_value.\nHowever, it's the caller's responsibility to make sure that the\nnapi_value in question is of the JavaScript type expected by the API.

The APIs documented in this section provide a simple interface to\nget and set properties on arbitrary JavaScript objects represented by\nnapi_value.

For instance, consider the following JavaScript code snippet:

const obj = {};\nobj.myProp = 123;\n

The equivalent can be done using Node-API values with the following snippet:

napi_status status = napi_generic_failure;\n\n// const obj = {}\nnapi_value obj, value;\nstatus = napi_create_object(env, &obj);\nif (status != napi_ok) return status;\n\n// Create a napi_value for 123\nstatus = napi_create_int32(env, 123, &value);\nif (status != napi_ok) return status;\n\n// obj.myProp = 123\nstatus = napi_set_named_property(env, obj, \"myProp\", value);\nif (status != napi_ok) return status;\n

Indexed properties can be set in a similar manner. Consider the following\nJavaScript snippet:

const arr = [];\narr[123] = 'hello';\n

The equivalent can be done using Node-API values with the following snippet:

napi_status status = napi_generic_failure;\n\n// const arr = [];\nnapi_value arr, value;\nstatus = napi_create_array(env, &arr);\nif (status != napi_ok) return status;\n\n// Create a napi_value for 'hello'\nstatus = napi_create_string_utf8(env, \"hello\", NAPI_AUTO_LENGTH, &value);\nif (status != napi_ok) return status;\n\n// arr[123] = 'hello';\nstatus = napi_set_element(env, arr, 123, value);\nif (status != napi_ok) return status;\n

Properties can be retrieved using the APIs described in this section.\nConsider the following JavaScript snippet:

const arr = [];\nconst value = arr[123];\n

The following is the approximate equivalent of the Node-API counterpart:

napi_status status = napi_generic_failure;\n\n// const arr = []\nnapi_value arr, value;\nstatus = napi_create_array(env, &arr);\nif (status != napi_ok) return status;\n\n// const value = arr[123]\nstatus = napi_get_element(env, arr, 123, &value);\nif (status != napi_ok) return status;\n

Finally, multiple properties can also be defined on an object for performance\nreasons. Consider the following JavaScript:

const obj = {};\nObject.defineProperties(obj, {\n  'foo': { value: 123, writable: true, configurable: true, enumerable: true },\n  'bar': { value: 456, writable: true, configurable: true, enumerable: true },\n});\n

The following is the approximate equivalent of the Node-API counterpart:

napi_status status = napi_status_generic_failure;\n\n// const obj = {};\nnapi_value obj;\nstatus = napi_create_object(env, &obj);\nif (status != napi_ok) return status;\n\n// Create napi_values for 123 and 456\nnapi_value fooValue, barValue;\nstatus = napi_create_int32(env, 123, &fooValue);\nif (status != napi_ok) return status;\nstatus = napi_create_int32(env, 456, &barValue);\nif (status != napi_ok) return status;\n\n// Set the properties\nnapi_property_descriptor descriptors[] = {\n  { \"foo\", NULL, NULL, NULL, NULL, fooValue, napi_writable | napi_configurable, NULL },\n  { \"bar\", NULL, NULL, NULL, NULL, barValue, napi_writable | napi_configurable, NULL }\n}\nstatus = napi_define_properties(env,\n                                obj,\n                                sizeof(descriptors) / sizeof(descriptors[0]),\n                                descriptors);\nif (status != napi_ok) return status;\n

typedef enum {\n  napi_default = 0,\n  napi_writable = 1 << 0,\n  napi_enumerable = 1 << 1,\n  napi_configurable = 1 << 2,\n\n  // Used with napi_define_class to distinguish static properties\n  // from instance properties. Ignored by napi_define_properties.\n  napi_static = 1 << 10,\n\n  // Default for class methods.\n  napi_default_method = napi_writable | napi_configurable,\n\n  // Default for object properties, like in JS obj[prop].\n  napi_default_jsproperty = napi_writable |\n                          napi_enumerable |\n                          napi_configurable,\n} napi_property_attributes;\n

napi_property_attributes are bit flags used to control the behavior of\nproperties set on a JavaScript object. Other than napi_static they\ncorrespond to the attributes listed in Section property attributes\nof the ECMAScript Language Specification.\nThey can be one or more of the following bit flags:

\n
• napi_default: No explicit attributes are set on the property. By default, a\nproperty is read only, not enumerable and not configurable.
\n
• napi_writable: The property is writable.
\n
• napi_enumerable: The property is enumerable.
\n
• napi_configurable: The property is configurable as defined in\nSection property attributes of the ECMAScript Language Specification.
\n
• napi_static: The property will be defined as a static property on a class as\nopposed to an instance property, which is the default. This is used only by\nnapi_define_class. It is ignored by napi_define_properties.
\n
• napi_default_method: Like a method in a JS class, the property is\nconfigurable and writeable, but not enumerable.
\n
• napi_default_jsproperty: Like a property set via assignment in JavaScript,\nthe property is writable, enumerable, and configurable.
\n

typedef struct {\n  // One of utf8name or name should be NULL.\n  const char* utf8name;\n  napi_value name;\n\n  napi_callback method;\n  napi_callback getter;\n  napi_callback setter;\n  napi_value value;\n\n  napi_property_attributes attributes;\n  void* data;\n} napi_property_descriptor;\n

\n
• utf8name: Optional string describing the key for the property,\nencoded as UTF8. One of utf8name or name must be provided for the\nproperty.
\n
• name: Optional napi_value that points to a JavaScript string or symbol\nto be used as the key for the property. One of utf8name or name must\nbe provided for the property.
\n
• value: The value that's retrieved by a get access of the property if the\nproperty is a data property. If this is passed in, set getter, setter,\nmethod and data to NULL (since these members won't be used).
\n
• getter: A function to call when a get access of the property is performed.\nIf this is passed in, set value and method to NULL (since these members\nwon't be used). The given function is called implicitly by the runtime when\nthe property is accessed from JavaScript code (or if a get on the property is\nperformed using a Node-API call). napi_callback provides more details.
\n
• setter: A function to call when a set access of the property is performed.\nIf this is passed in, set value and method to NULL (since these members\nwon't be used). The given function is called implicitly by the runtime when\nthe property is set from JavaScript code (or if a set on the property is\nperformed using a Node-API call). napi_callback provides more details.
\n
• method: Set this to make the property descriptor object's value\nproperty to be a JavaScript function represented by method. If this is\npassed in, set value, getter and setter to NULL (since these members\nwon't be used). napi_callback provides more details.
\n
• attributes: The attributes associated with the particular property. See\nnapi_property_attributes.
\n
• data: The callback data passed into method, getter and setter if this\nfunction is invoked.
\n

napi_status napi_get_property_names(napi_env env,\n                                    napi_value object,\n                                    napi_value* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object from which to retrieve the properties.
\n
• [out] result: A napi_value representing an array of JavaScript values\nthat represent the property names of the object. The API can be used to\niterate over result using napi_get_array_length\nand napi_get_element.
\n

Returns napi_ok if the API succeeded.

This API returns the names of the enumerable properties of object as an array\nof strings. The properties of object whose key is a symbol will not be\nincluded.

napi_get_all_property_names(napi_env env,\n                            napi_value object,\n                            napi_key_collection_mode key_mode,\n                            napi_key_filter key_filter,\n                            napi_key_conversion key_conversion,\n                            napi_value* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object from which to retrieve the properties.
\n
• [in] key_mode: Whether to retrieve prototype properties as well.
\n
• [in] key_filter: Which properties to retrieve\n(enumerable/readable/writable).
\n
• [in] key_conversion: Whether to convert numbered property keys to strings.
\n
• [out] result: A napi_value representing an array of JavaScript values\nthat represent the property names of the object. napi_get_array_length\nand napi_get_element can be used to iterate over result.
\n

Returns napi_ok if the API succeeded.

This API returns an array containing the names of the available properties\nof this object.

napi_status napi_set_property(napi_env env,\n                              napi_value object,\n                              napi_value key,\n                              napi_value value);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object on which to set the property.
\n
• [in] key: The name of the property to set.
\n
• [in] value: The property value.
\n

Returns napi_ok if the API succeeded.

This API set a property on the Object passed in.

napi_status napi_get_property(napi_env env,\n                              napi_value object,\n                              napi_value key,\n                              napi_value* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object from which to retrieve the property.
\n
• [in] key: The name of the property to retrieve.
\n
• [out] result: The value of the property.
\n

Returns napi_ok if the API succeeded.

This API gets the requested property from the Object passed in.

napi_status napi_has_property(napi_env env,\n                              napi_value object,\n                              napi_value key,\n                              bool* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object to query.
\n
• [in] key: The name of the property whose existence to check.
\n
• [out] result: Whether the property exists on the object or not.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in has the named property.

napi_status napi_delete_property(napi_env env,\n                                 napi_value object,\n                                 napi_value key,\n                                 bool* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object to query.
\n
• [in] key: The name of the property to delete.
\n
• [out] result: Whether the property deletion succeeded or not. result can\noptionally be ignored by passing NULL.
\n

Returns napi_ok if the API succeeded.

This API attempts to delete the key own property from object.

napi_status napi_has_own_property(napi_env env,\n                                  napi_value object,\n                                  napi_value key,\n                                  bool* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object to query.
\n
• [in] key: The name of the own property whose existence to check.
\n
• [out] result: Whether the own property exists on the object or not.
\n

Returns napi_ok if the API succeeded.

This API checks if the Object passed in has the named own property. key must\nbe a string or a symbol, or an error will be thrown. Node-API will not\nperform any conversion between data types.

napi_status napi_set_named_property(napi_env env,\n                                    napi_value object,\n                                    const char* utf8Name,\n                                    napi_value value);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object on which to set the property.
\n
• [in] utf8Name: The name of the property to set.
\n
• [in] value: The property value.
\n

Returns napi_ok if the API succeeded.

This method is equivalent to calling napi_set_property with a napi_value\ncreated from the string passed in as utf8Name.

napi_status napi_get_named_property(napi_env env,\n                                    napi_value object,\n                                    const char* utf8Name,\n                                    napi_value* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object from which to retrieve the property.
\n
• [in] utf8Name: The name of the property to get.
\n
• [out] result: The value of the property.
\n

Returns napi_ok if the API succeeded.

This method is equivalent to calling napi_get_property with a napi_value\ncreated from the string passed in as utf8Name.

napi_status napi_has_named_property(napi_env env,\n                                    napi_value object,\n                                    const char* utf8Name,\n                                    bool* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object to query.
\n
• [in] utf8Name: The name of the property whose existence to check.
\n
• [out] result: Whether the property exists on the object or not.
\n

Returns napi_ok if the API succeeded.

This method is equivalent to calling napi_has_property with a napi_value\ncreated from the string passed in as utf8Name.

napi_status napi_set_element(napi_env env,\n                             napi_value object,\n                             uint32_t index,\n                             napi_value value);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object from which to set the properties.
\n
• [in] index: The index of the property to set.
\n
• [in] value: The property value.
\n

Returns napi_ok if the API succeeded.

This API sets an element on the Object passed in.

napi_status napi_get_element(napi_env env,\n                             napi_value object,\n                             uint32_t index,\n                             napi_value* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object from which to retrieve the property.
\n
• [in] index: The index of the property to get.
\n
• [out] result: The value of the property.
\n

Returns napi_ok if the API succeeded.

This API gets the element at the requested index.

napi_status napi_has_element(napi_env env,\n                             napi_value object,\n                             uint32_t index,\n                             bool* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object to query.
\n
• [in] index: The index of the property whose existence to check.
\n
• [out] result: Whether the property exists on the object or not.
\n

Returns napi_ok if the API succeeded.

This API returns if the Object passed in has an element at the\nrequested index.

napi_status napi_delete_element(napi_env env,\n                                napi_value object,\n                                uint32_t index,\n                                bool* result);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object to query.
\n
• [in] index: The index of the property to delete.
\n
• [out] result: Whether the element deletion succeeded or not. result can\noptionally be ignored by passing NULL.
\n

Returns napi_ok if the API succeeded.

This API attempts to delete the specified index from object.

napi_status napi_define_properties(napi_env env,\n                                   napi_value object,\n                                   size_t property_count,\n                                   const napi_property_descriptor* properties);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object from which to retrieve the properties.
\n
• [in] property_count: The number of elements in the properties array.
\n
• [in] properties: The array of property descriptors.
\n

Returns napi_ok if the API succeeded.

This method allows the efficient definition of multiple properties on a given\nobject. The properties are defined using property descriptors (see\nnapi_property_descriptor). Given an array of such property descriptors,\nthis API will set the properties on the object one at a time, as defined by\nDefineOwnProperty() (described in Section DefineOwnProperty of the ECMA-262\nspecification).

napi_status napi_object_freeze(napi_env env,\n                               napi_value object);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object to freeze.
\n

Returns napi_ok if the API succeeded.

This method freezes a given object. This prevents new properties from\nbeing added to it, existing properties from being removed, prevents\nchanging the enumerability, configurability, or writability of existing\nproperties, and prevents the values of existing properties from being changed.\nIt also prevents the object's prototype from being changed. This is described\nin Section 19.1.2.6 of the\nECMA-262 specification.

napi_status napi_object_seal(napi_env env,\n                             napi_value object);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object to seal.
\n

Returns napi_ok if the API succeeded.

This method seals a given object. This prevents new properties from being\nadded to it, as well as marking all existing properties as non-configurable.\nThis is described in Section 19.1.2.20\nof the ECMA-262 specification.

napi_status node_api_set_prototype(napi_env env,\n                                   napi_value object,\n                                   napi_value value);\n

\n
• [in] env: The environment that the Node-API call is invoked under.
\n
• [in] object: The object on which to set the prototype.
\n
• [in] value: The prototype value.
\n

Returns napi_ok if the API succeeded.

This API sets the prototype of the Object passed in.

Node-API provides a set of APIs that allow JavaScript code to\ncall back into native code. Node-APIs that support calling back\ninto native code take in a callback functions represented by\nthe napi_callback type. When the JavaScript VM calls back to\nnative code, the napi_callback function provided is invoked. The APIs\ndocumented in this section allow the callback function to do the\nfollowing:

\n
• Get information about the context in which the callback was invoked.
\n
• Get the arguments passed into the callback.
\n
• Return a napi_value back from the callback.
\n

Additionally, Node-API provides a set of functions which allow calling\nJavaScript functions from native code. One can either call a function\nlike a regular JavaScript function call, or as a constructor\nfunction.

Any non-NULL data which is passed to this API via the data field of the\nnapi_property_descriptor items can be associated with object and freed\nwhenever object is garbage-collected by passing both object and the data to\nnapi_add_finalizer.

NAPI_EXTERN napi_status napi_call_function(napi_env env,\n                                           napi_value recv,\n                                           napi_value func,\n                                           size_t argc,\n                                           const napi_value* argv,\n                                           napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] recv: The this value passed to the called function.
\n
• [in] func: napi_value representing the JavaScript function to be invoked.
\n
• [in] argc: The count of elements in the argv array.
\n
• [in] argv: Array of napi_values representing JavaScript values passed in\nas arguments to the function.
\n
• [out] result: napi_value representing the JavaScript object returned.
\n

Returns napi_ok if the API succeeded.

This method allows a JavaScript function object to be called from a native\nadd-on. This is the primary mechanism of calling back from the add-on's\nnative code into JavaScript. For the special case of calling into JavaScript\nafter an async operation, see napi_make_callback.

A sample use case might look as follows. Consider the following JavaScript\nsnippet:

function AddTwo(num) {\n  return num + 2;\n}\nglobal.AddTwo = AddTwo;\n

Then, the above function can be invoked from a native add-on using the\nfollowing code:

// Get the function named \"AddTwo\" on the global object\nnapi_value global, add_two, arg;\nnapi_status status = napi_get_global(env, &global);\nif (status != napi_ok) return;\n\nstatus = napi_get_named_property(env, global, \"AddTwo\", &add_two);\nif (status != napi_ok) return;\n\n// const arg = 1337\nstatus = napi_create_int32(env, 1337, &arg);\nif (status != napi_ok) return;\n\nnapi_value* argv = &arg;\nsize_t argc = 1;\n\n// AddTwo(arg);\nnapi_value return_val;\nstatus = napi_call_function(env, global, add_two, argc, argv, &return_val);\nif (status != napi_ok) return;\n\n// Convert the result back to a native type\nint32_t result;\nstatus = napi_get_value_int32(env, return_val, &result);\nif (status != napi_ok) return;\n

napi_status napi_create_function(napi_env env,\n                                 const char* utf8name,\n                                 size_t length,\n                                 napi_callback cb,\n                                 void* data,\n                                 napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] utf8Name: Optional name of the function encoded as UTF8. This is\nvisible within JavaScript as the new function object's name property.
\n
• [in] length: The length of the utf8name in bytes, or NAPI_AUTO_LENGTH if\nit is null-terminated.
\n
• [in] cb: The native function which should be called when this function\nobject is invoked. napi_callback provides more details.
\n
• [in] data: User-provided data context. This will be passed back into the\nfunction when invoked later.
\n
• [out] result: napi_value representing the JavaScript function object for\nthe newly created function.
\n

Returns napi_ok if the API succeeded.

This API allows an add-on author to create a function object in native code.\nThis is the primary mechanism to allow calling into the add-on's native code\nfrom JavaScript.

The newly created function is not automatically visible from script after this\ncall. Instead, a property must be explicitly set on any object that is visible\nto JavaScript, in order for the function to be accessible from script.

In order to expose a function as part of the\nadd-on's module exports, set the newly created function on the exports\nobject. A sample module might look as follows:

napi_value SayHello(napi_env env, napi_callback_info info) {\n  printf(\"Hello\\n\");\n  return NULL;\n}\n\nnapi_value Init(napi_env env, napi_value exports) {\n  napi_status status;\n\n  napi_value fn;\n  status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn);\n  if (status != napi_ok) return NULL;\n\n  status = napi_set_named_property(env, exports, \"sayHello\", fn);\n  if (status != napi_ok) return NULL;\n\n  return exports;\n}\n\nNAPI_MODULE(NODE_GYP_MODULE_NAME, Init)\n

Given the above code, the add-on can be used from JavaScript as follows:

const myaddon = require('./addon');\nmyaddon.sayHello();\n

The string passed to require() is the name of the target in binding.gyp\nresponsible for creating the .node file.

Any non-NULL data which is passed to this API via the data parameter can\nbe associated with the resulting JavaScript function (which is returned in the\nresult parameter) and freed whenever the function is garbage-collected by\npassing both the JavaScript function and the data to napi_add_finalizer.

JavaScript Functions are described in Section Function objects of the ECMAScript\nLanguage Specification.

napi_status napi_get_cb_info(napi_env env,\n                             napi_callback_info cbinfo,\n                             size_t* argc,\n                             napi_value* argv,\n                             napi_value* thisArg,\n                             void** data)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] cbinfo: The callback info passed into the callback function.
\n
• [in-out] argc: Specifies the length of the provided argv array and\nreceives the actual count of arguments. argc can\noptionally be ignored by passing NULL.
\n
• [out] argv: C array of napi_values to which the arguments will be\ncopied. If there are more arguments than the provided count, only the\nrequested number of arguments are copied. If there are fewer arguments\nprovided than claimed, the rest of argv is filled with napi_value values\nthat represent undefined. argv can optionally be ignored by\npassing NULL.
\n
• [out] thisArg: Receives the JavaScript this argument for the call.\nthisArg can optionally be ignored by passing NULL.
\n
• [out] data: Receives the data pointer for the callback. data can\noptionally be ignored by passing NULL.
\n

Returns napi_ok if the API succeeded.

This method is used within a callback function to retrieve details about the\ncall like the arguments and the this pointer from a given callback info.

napi_status napi_get_new_target(napi_env env,\n                                napi_callback_info cbinfo,\n                                napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] cbinfo: The callback info passed into the callback function.
\n
• [out] result: The new.target of the constructor call.
\n

Returns napi_ok if the API succeeded.

This API returns the new.target of the constructor call. If the current\ncallback is not a constructor call, the result is NULL.

napi_status napi_new_instance(napi_env env,\n                              napi_value cons,\n                              size_t argc,\n                              napi_value* argv,\n                              napi_value* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] cons: napi_value representing the JavaScript function to be invoked\nas a constructor.
\n
• [in] argc: The count of elements in the argv array.
\n
• [in] argv: Array of JavaScript values as napi_value representing the\narguments to the constructor. If argc is zero this parameter may be\nomitted by passing in NULL.
\n
• [out] result: napi_value representing the JavaScript object returned,\nwhich in this case is the constructed object.
\n

This method is used to instantiate a new JavaScript value using a given\nnapi_value that represents the constructor for the object. For example,\nconsider the following snippet:

function MyObject(param) {\n  this.param = param;\n}\n\nconst arg = 'hello';\nconst value = new MyObject(arg);\n

The following can be approximated in Node-API using the following snippet:

// Get the constructor function MyObject\nnapi_value global, constructor, arg, value;\nnapi_status status = napi_get_global(env, &global);\nif (status != napi_ok) return;\n\nstatus = napi_get_named_property(env, global, \"MyObject\", &constructor);\nif (status != napi_ok) return;\n\n// const arg = \"hello\"\nstatus = napi_create_string_utf8(env, \"hello\", NAPI_AUTO_LENGTH, &arg);\nif (status != napi_ok) return;\n\nnapi_value* argv = &arg;\nsize_t argc = 1;\n\n// const value = new MyObject(arg)\nstatus = napi_new_instance(env, constructor, argc, argv, &value);\n

Returns napi_ok if the API succeeded.

Node-API offers a way to \"wrap\" C++ classes and instances so that the class\nconstructor and methods can be called from JavaScript.

\n
1. The napi_define_class API defines a JavaScript class with constructor,\nstatic properties and methods, and instance properties and methods that\ncorrespond to the C++ class.
\n
2. When JavaScript code invokes the constructor, the constructor callback\nuses napi_wrap to wrap a new C++ instance in a JavaScript object,\nthen returns the wrapper object.
\n
3. When JavaScript code invokes a method or property accessor on the class,\nthe corresponding napi_callback C++ function is invoked. For an instance\ncallback, napi_unwrap obtains the C++ instance that is the target of\nthe call.
\n

For wrapped objects it may be difficult to distinguish between a function\ncalled on a class prototype and a function called on an instance of a class.\nA common pattern used to address this problem is to save a persistent\nreference to the class constructor for later instanceof checks.

napi_value MyClass_constructor = NULL;\nstatus = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor);\nassert(napi_ok == status);\nbool is_instance = false;\nstatus = napi_instanceof(env, es_this, MyClass_constructor, &is_instance);\nassert(napi_ok == status);\nif (is_instance) {\n  // napi_unwrap() ...\n} else {\n  // otherwise...\n}\n

The reference must be freed once it is no longer needed.

There are occasions where napi_instanceof() is insufficient for ensuring that\na JavaScript object is a wrapper for a certain native type. This is the case\nespecially when wrapped JavaScript objects are passed back into the addon via\nstatic methods rather than as the this value of prototype methods. In such\ncases there is a chance that they may be unwrapped incorrectly.

const myAddon = require('./build/Release/my_addon.node');\n\n// `openDatabase()` returns a JavaScript object that wraps a native database\n// handle.\nconst dbHandle = myAddon.openDatabase();\n\n// `query()` returns a JavaScript object that wraps a native query handle.\nconst queryHandle = myAddon.query(dbHandle, 'Gimme ALL the things!');\n\n// There is an accidental error in the line below. The first parameter to\n// `myAddon.queryHasRecords()` should be the database handle (`dbHandle`), not\n// the query handle (`query`), so the correct condition for the while-loop\n// should be\n//\n// myAddon.queryHasRecords(dbHandle, queryHandle)\n//\nwhile (myAddon.queryHasRecords(queryHandle, dbHandle)) {\n  // retrieve records\n}\n

In the above example myAddon.queryHasRecords() is a method that accepts two\narguments. The first is a database handle and the second is a query handle.\nInternally, it unwraps the first argument and casts the resulting pointer to a\nnative database handle. It then unwraps the second argument and casts the\nresulting pointer to a query handle. If the arguments are passed in the wrong\norder, the casts will work, however, there is a good chance that the underlying\ndatabase operation will fail, or will even cause an invalid memory access.

To ensure that the pointer retrieved from the first argument is indeed a pointer\nto a database handle and, similarly, that the pointer retrieved from the second\nargument is indeed a pointer to a query handle, the implementation of\nqueryHasRecords() has to perform a type validation. Retaining the JavaScript\nclass constructor from which the database handle was instantiated and the\nconstructor from which the query handle was instantiated in napi_refs can\nhelp, because napi_instanceof() can then be used to ensure that the instances\npassed into queryHashRecords() are indeed of the correct type.

Unfortunately, napi_instanceof() does not protect against prototype\nmanipulation. For example, the prototype of the database handle instance can be\nset to the prototype of the constructor for query handle instances. In this\ncase, the database handle instance can appear as a query handle instance, and it\nwill pass the napi_instanceof() test for a query handle instance, while still\ncontaining a pointer to a database handle.

To this end, Node-API provides type-tagging capabilities.

A type tag is a 128-bit integer unique to the addon. Node-API provides the\nnapi_type_tag structure for storing a type tag. When such a value is passed\nalong with a JavaScript object or external stored in a napi_value to\nnapi_type_tag_object(), the JavaScript object will be \"marked\" with the\ntype tag. The \"mark\" is invisible on the JavaScript side. When a JavaScript\nobject arrives into a native binding, napi_check_object_type_tag() can be used\nalong with the original type tag to determine whether the JavaScript object was\npreviously \"marked\" with the type tag. This creates a type-checking capability\nof a higher fidelity than napi_instanceof() can provide, because such type-\ntagging survives prototype manipulation and addon unloading/reloading.

Continuing the above example, the following skeleton addon implementation\nillustrates the use of napi_type_tag_object() and\nnapi_check_object_type_tag().

// This value is the type tag for a database handle. The command\n//\n//   uuidgen | sed -r -e 's/-//g' -e 's/(.{16})(.*)/0x\\1, 0x\\2/'\n//\n// can be used to obtain the two values with which to initialize the structure.\nstatic const napi_type_tag DatabaseHandleTypeTag = {\n  0x1edf75a38336451d, 0xa5ed9ce2e4c00c38\n};\n\n// This value is the type tag for a query handle.\nstatic const napi_type_tag QueryHandleTypeTag = {\n  0x9c73317f9fad44a3, 0x93c3920bf3b0ad6a\n};\n\nstatic napi_value\nopenDatabase(napi_env env, napi_callback_info info) {\n  napi_status status;\n  napi_value result;\n\n  // Perform the underlying action which results in a database handle.\n  DatabaseHandle* dbHandle = open_database();\n\n  // Create a new, empty JS object.\n  status = napi_create_object(env, &result);\n  if (status != napi_ok) return NULL;\n\n  // Tag the object to indicate that it holds a pointer to a `DatabaseHandle`.\n  status = napi_type_tag_object(env, result, &DatabaseHandleTypeTag);\n  if (status != napi_ok) return NULL;\n\n  // Store the pointer to the `DatabaseHandle` structure inside the JS object.\n  status = napi_wrap(env, result, dbHandle, NULL, NULL, NULL);\n  if (status != napi_ok) return NULL;\n\n  return result;\n}\n\n// Later when we receive a JavaScript object purporting to be a database handle\n// we can use `napi_check_object_type_tag()` to ensure that it is indeed such a\n// handle.\n\nstatic napi_value\nquery(napi_env env, napi_callback_info info) {\n  napi_status status;\n  size_t argc = 2;\n  napi_value argv[2];\n  bool is_db_handle;\n\n  status = napi_get_cb_info(env, info, &argc, argv, NULL, NULL);\n  if (status != napi_ok) return NULL;\n\n  // Check that the object passed as the first parameter has the previously\n  // applied tag.\n  status = napi_check_object_type_tag(env,\n                                      argv[0],\n                                      &DatabaseHandleTypeTag,\n                                      &is_db_handle);\n  if (status != napi_ok) return NULL;\n\n  // Throw a `TypeError` if it doesn't.\n  if (!is_db_handle) {\n    // Throw a TypeError.\n    return NULL;\n  }\n}\n

napi_status napi_define_class(napi_env env,\n                              const char* utf8name,\n                              size_t length,\n                              napi_callback constructor,\n                              void* data,\n                              size_t property_count,\n                              const napi_property_descriptor* properties,\n                              napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] utf8name: Name of the JavaScript constructor function. For clarity,\nit is recommended to use the C++ class name when wrapping a C++ class.
\n
• [in] length: The length of the utf8name in bytes, or NAPI_AUTO_LENGTH\nif it is null-terminated.
\n
• [in] constructor: Callback function that handles constructing instances\nof the class. When wrapping a C++ class, this method must be a static member\nwith the napi_callback signature. A C++ class constructor cannot be\nused. napi_callback provides more details.
\n
• [in] data: Optional data to be passed to the constructor callback as\nthe data property of the callback info.
\n
• [in] property_count: Number of items in the properties array argument.
\n
• [in] properties: Array of property descriptors describing static and\ninstance data properties, accessors, and methods on the class\nSee napi_property_descriptor.
\n
• [out] result: A napi_value representing the constructor function for\nthe class.
\n

Returns napi_ok if the API succeeded.

Defines a JavaScript class, including:

\n
• A JavaScript constructor function that has the class name. When wrapping a\ncorresponding C++ class, the callback passed via constructor can be used to\ninstantiate a new C++ class instance, which can then be placed inside the\nJavaScript object instance being constructed using napi_wrap.
\n
• Properties on the constructor function whose implementation can call\ncorresponding static data properties, accessors, and methods of the C++\nclass (defined by property descriptors with the napi_static attribute).
\n
• Properties on the constructor function's prototype object. When wrapping a\nC++ class, non-static data properties, accessors, and methods of the C++\nclass can be called from the static functions given in the property\ndescriptors without the napi_static attribute after retrieving the C++ class\ninstance placed inside the JavaScript object instance by using\nnapi_unwrap.
\n

When wrapping a C++ class, the C++ constructor callback passed via constructor\nshould be a static method on the class that calls the actual class constructor,\nthen wraps the new C++ instance in a JavaScript object, and returns the wrapper\nobject. See napi_wrap for details.

The JavaScript constructor function returned from napi_define_class is\noften saved and used later to construct new instances of the class from native\ncode, and/or to check whether provided values are instances of the class. In\nthat case, to prevent the function value from being garbage-collected, a\nstrong persistent reference to it can be created using\nnapi_create_reference, ensuring that the reference count is kept >= 1.

Any non-NULL data which is passed to this API via the data parameter or via\nthe data field of the napi_property_descriptor array items can be associated\nwith the resulting JavaScript constructor (which is returned in the result\nparameter) and freed whenever the class is garbage-collected by passing both\nthe JavaScript function and the data to napi_add_finalizer.

napi_status napi_wrap(napi_env env,\n                      napi_value js_object,\n                      void* native_object,\n                      napi_finalize finalize_cb,\n                      void* finalize_hint,\n                      napi_ref* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] js_object: The JavaScript object that will be the wrapper for the\nnative object.
\n
• [in] native_object: The native instance that will be wrapped in the\nJavaScript object.
\n
• [in] finalize_cb: Optional native callback that can be used to free the\nnative instance when the JavaScript object has been garbage-collected.\nnapi_finalize provides more details.
\n
• [in] finalize_hint: Optional contextual hint that is passed to the\nfinalize callback.
\n
• [out] result: Optional reference to the wrapped object.
\n

Returns napi_ok if the API succeeded.

Wraps a native instance in a JavaScript object. The native instance can be\nretrieved later using napi_unwrap().

When JavaScript code invokes a constructor for a class that was defined using\nnapi_define_class(), the napi_callback for the constructor is invoked.\nAfter constructing an instance of the native class, the callback must then call\nnapi_wrap() to wrap the newly constructed instance in the already-created\nJavaScript object that is the this argument to the constructor callback.\n(That this object was created from the constructor function's prototype,\nso it already has definitions of all the instance properties and methods.)

Typically when wrapping a class instance, a finalize callback should be\nprovided that simply deletes the native instance that is received as the data\nargument to the finalize callback.

The optional returned reference is initially a weak reference, meaning it\nhas a reference count of 0. Typically this reference count would be incremented\ntemporarily during async operations that require the instance to remain valid.

Caution: The optional returned reference (if obtained) should be deleted via\nnapi_delete_reference ONLY in response to the finalize callback\ninvocation. If it is deleted before then, then the finalize callback may never\nbe invoked. Therefore, when obtaining a reference a finalize callback is also\nrequired in order to enable correct disposal of the reference.

Finalizer callbacks may be deferred, leaving a window where the object has\nbeen garbage collected (and the weak reference is invalid) but the finalizer\nhasn't been called yet. When using napi_get_reference_value() on weak\nreferences returned by napi_wrap(), you should still handle an empty result.

Calling napi_wrap() a second time on an object will return an error. To\nassociate another native instance with the object, use napi_remove_wrap()\nfirst.

napi_status napi_unwrap(napi_env env,\n                        napi_value js_object,\n                        void** result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] js_object: The object associated with the native instance.
\n
• [out] result: Pointer to the wrapped native instance.
\n

Returns napi_ok if the API succeeded.

Retrieves a native instance that was previously wrapped in a JavaScript\nobject using napi_wrap().

When JavaScript code invokes a method or property accessor on the class, the\ncorresponding napi_callback is invoked. If the callback is for an instance\nmethod or accessor, then the this argument to the callback is the wrapper\nobject; the wrapped C++ instance that is the target of the call can be obtained\nthen by calling napi_unwrap() on the wrapper object.

napi_status napi_remove_wrap(napi_env env,\n                             napi_value js_object,\n                             void** result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] js_object: The object associated with the native instance.
\n
• [out] result: Pointer to the wrapped native instance.
\n

Returns napi_ok if the API succeeded.

Retrieves a native instance that was previously wrapped in the JavaScript\nobject js_object using napi_wrap() and removes the wrapping. If a finalize\ncallback was associated with the wrapping, it will no longer be called when the\nJavaScript object becomes garbage-collected.

napi_status napi_type_tag_object(napi_env env,\n                                 napi_value js_object,\n                                 const napi_type_tag* type_tag);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] js_object: The JavaScript object or external to be marked.
\n
• [in] type_tag: The tag with which the object is to be marked.
\n

Returns napi_ok if the API succeeded.

Associates the value of the type_tag pointer with the JavaScript object or\nexternal. napi_check_object_type_tag() can then be used to compare the tag\nthat was attached to the object with one owned by the addon to ensure that the\nobject has the right type.

If the object already has an associated type tag, this API will return\nnapi_invalid_arg.

napi_status napi_check_object_type_tag(napi_env env,\n                                       napi_value js_object,\n                                       const napi_type_tag* type_tag,\n                                       bool* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] js_object: The JavaScript object or external whose type tag to\nexamine.
\n
• [in] type_tag: The tag with which to compare any tag found on the object.
\n
• [out] result: Whether the type tag given matched the type tag on the\nobject. false is also returned if no type tag was found on the object.
\n

Returns napi_ok if the API succeeded.

Compares the pointer given as type_tag with any that can be found on\njs_object. If no tag is found on js_object or, if a tag is found but it does\nnot match type_tag, then result is set to false. If a tag is found and it\nmatches type_tag, then result is set to true.

napi_status napi_add_finalizer(napi_env env,\n                               napi_value js_object,\n                               void* finalize_data,\n                               node_api_basic_finalize finalize_cb,\n                               void* finalize_hint,\n                               napi_ref* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] js_object: The JavaScript object to which the native data will be\nattached.
\n
• [in] finalize_data: Optional data to be passed to finalize_cb.
\n
• [in] finalize_cb: Native callback that will be used to free the\nnative data when the JavaScript object has been garbage-collected.\nnapi_finalize provides more details.
\n
• [in] finalize_hint: Optional contextual hint that is passed to the\nfinalize callback.
\n
• [out] result: Optional reference to the JavaScript object.
\n

Returns napi_ok if the API succeeded.

Adds a napi_finalize callback which will be called when the JavaScript object\nin js_object has been garbage-collected.

This API can be called multiple times on a single JavaScript object.

Caution: The optional returned reference (if obtained) should be deleted via\nnapi_delete_reference ONLY in response to the finalize callback\ninvocation. If it is deleted before then, then the finalize callback may never\nbe invoked. Therefore, when obtaining a reference a finalize callback is also\nrequired in order to enable correct disposal of the reference.

napi_status node_api_post_finalizer(node_api_basic_env env,\n                                    napi_finalize finalize_cb,\n                                    void* finalize_data,\n                                    void* finalize_hint);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] finalize_cb: Native callback that will be used to free the\nnative data when the JavaScript object has been garbage-collected.\nnapi_finalize provides more details.
\n
• [in] finalize_data: Optional data to be passed to finalize_cb.
\n
• [in] finalize_hint: Optional contextual hint that is passed to the\nfinalize callback.
\n

Returns napi_ok if the API succeeded.

Schedules a napi_finalize callback to be called asynchronously in the\nevent loop.

Normally, finalizers are called while the GC (garbage collector) collects\nobjects. At that point calling any Node-API that may cause changes in the GC\nstate will be disabled and will crash Node.js.

node_api_post_finalizer helps to work around this limitation by allowing the\nadd-on to defer calls to such Node-APIs to a point in time outside of the GC\nfinalization.

Addon modules often need to leverage async helpers from libuv as part of their\nimplementation. This allows them to schedule work to be executed asynchronously\nso that their methods can return in advance of the work being completed. This\nallows them to avoid blocking overall execution of the Node.js application.

Node-API provides an ABI-stable interface for these\nsupporting functions which covers the most common asynchronous use cases.

Node-API defines the napi_async_work structure which is used to manage\nasynchronous workers. Instances are created/deleted with\nnapi_create_async_work and napi_delete_async_work.

The execute and complete callbacks are functions that will be\ninvoked when the executor is ready to execute and when it completes its\ntask respectively.

The execute function should avoid making any Node-API calls\nthat could result in the execution of JavaScript or interaction with\nJavaScript objects. Most often, any code that needs to make Node-API\ncalls should be made in complete callback instead.\nAvoid using the napi_env parameter in the execute callback as\nit will likely execute JavaScript.

These functions implement the following interfaces:

typedef void (*napi_async_execute_callback)(napi_env env,\n                                            void* data);\ntypedef void (*napi_async_complete_callback)(napi_env env,\n                                             napi_status status,\n                                             void* data);\n

When these methods are invoked, the data parameter passed will be the\naddon-provided void* data that was passed into the\nnapi_create_async_work call.

Once created the async worker can be queued\nfor execution using the napi_queue_async_work function:

napi_status napi_queue_async_work(node_api_basic_env env,\n                                  napi_async_work work);\n

napi_cancel_async_work can be used if the work needs\nto be cancelled before the work has started execution.

After calling napi_cancel_async_work, the complete callback\nwill be invoked with a status value of napi_cancelled.\nThe work should not be deleted before the complete\ncallback invocation, even when it was cancelled.

napi_status napi_create_async_work(napi_env env,\n                                   napi_value async_resource,\n                                   napi_value async_resource_name,\n                                   napi_async_execute_callback execute,\n                                   napi_async_complete_callback complete,\n                                   void* data,\n                                   napi_async_work* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] async_resource: An optional object associated with the async work\nthat will be passed to possible async_hooks init hooks.
\n
• [in] async_resource_name: Identifier for the kind of resource that is being\nprovided for diagnostic information exposed by the async_hooks API.
\n
• [in] execute: The native function which should be called to execute the\nlogic asynchronously. The given function is called from a worker pool thread\nand can execute in parallel with the main event loop thread.
\n
• [in] complete: The native function which will be called when the\nasynchronous logic is completed or is cancelled. The given function is called\nfrom the main event loop thread. napi_async_complete_callback provides\nmore details.
\n
• [in] data: User-provided data context. This will be passed back into the\nexecute and complete functions.
\n
• [out] result: napi_async_work* which is the handle to the newly created\nasync work.
\n

Returns napi_ok if the API succeeded.

This API allocates a work object that is used to execute logic asynchronously.\nIt should be freed using napi_delete_async_work once the work is no longer\nrequired.

async_resource_name should be a null-terminated, UTF-8-encoded string.

The async_resource_name identifier is provided by the user and should be\nrepresentative of the type of async work being performed. It is also recommended\nto apply namespacing to the identifier, e.g. by including the module name. See\nthe async_hooks documentation for more information.

napi_status napi_delete_async_work(napi_env env,\n                                   napi_async_work work);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] work: The handle returned by the call to napi_create_async_work.
\n

Returns napi_ok if the API succeeded.

This API frees a previously allocated work object.

This API can be called even if there is a pending JavaScript exception.

napi_status napi_queue_async_work(node_api_basic_env env,\n                                  napi_async_work work);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] work: The handle returned by the call to napi_create_async_work.
\n

Returns napi_ok if the API succeeded.

This API requests that the previously allocated work be scheduled\nfor execution. Once it returns successfully, this API must not be called again\nwith the same napi_async_work item or the result will be undefined.

napi_status napi_cancel_async_work(node_api_basic_env env,\n                                   napi_async_work work);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] work: The handle returned by the call to napi_create_async_work.
\n

Returns napi_ok if the API succeeded.

This API cancels queued work if it has not yet\nbeen started. If it has already started executing, it cannot be\ncancelled and napi_generic_failure will be returned. If successful,\nthe complete callback will be invoked with a status value of\nnapi_cancelled. The work should not be deleted before the complete\ncallback invocation, even if it has been successfully cancelled.

This API can be called even if there is a pending JavaScript exception.

The simple asynchronous work APIs above may not be appropriate for every\nscenario. When using any other asynchronous mechanism, the following APIs\nare necessary to ensure an asynchronous operation is properly tracked by\nthe runtime.

napi_status napi_async_init(napi_env env,\n                            napi_value async_resource,\n                            napi_value async_resource_name,\n                            napi_async_context* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] async_resource: Object associated with the async work\nthat will be passed to possible async_hooks init hooks and can be\naccessed by async_hooks.executionAsyncResource().
\n
• [in] async_resource_name: Identifier for the kind of resource that is being\nprovided for diagnostic information exposed by the async_hooks API.
\n
• [out] result: The initialized async context.
\n

Returns napi_ok if the API succeeded.

In order to retain ABI compatibility with previous versions, passing NULL\nfor async_resource does not result in an error. However, this is not\nrecommended as this will result in undesirable behavior with async_hooks\ninit hooks and async_hooks.executionAsyncResource() as the resource is\nnow required by the underlying async_hooks implementation in order to provide\nthe linkage between async callbacks.

Previous versions of this API were not maintaining a strong reference to\nasync_resource while the napi_async_context object existed and instead\nexpected the caller to hold a strong reference. This has been changed, as a\ncorresponding call to napi_async_destroy for every call to\nnapi_async_init() is a requirement in any case to avoid memory leaks.

napi_status napi_async_destroy(napi_env env,\n                               napi_async_context async_context);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] async_context: The async context to be destroyed.
\n

Returns napi_ok if the API succeeded.

This API can be called even if there is a pending JavaScript exception.

NAPI_EXTERN napi_status napi_make_callback(napi_env env,\n                                           napi_async_context async_context,\n                                           napi_value recv,\n                                           napi_value func,\n                                           size_t argc,\n                                           const napi_value* argv,\n                                           napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] async_context: Context for the async operation that is\ninvoking the callback. This should normally be a value previously\nobtained from napi_async_init.\nIn order to retain ABI compatibility with previous versions, passing NULL\nfor async_context does not result in an error. However, this results\nin incorrect operation of async hooks. Potential issues include loss of\nasync context when using the AsyncLocalStorage API.
\n
• [in] recv: The this value passed to the called function.
\n
• [in] func: napi_value representing the JavaScript function to be invoked.
\n
• [in] argc: The count of elements in the argv array.
\n
• [in] argv: Array of JavaScript values as napi_value representing the\narguments to the function. If argc is zero this parameter may be\nomitted by passing in NULL.
\n
• [out] result: napi_value representing the JavaScript object returned.
\n

Returns napi_ok if the API succeeded.

This method allows a JavaScript function object to be called from a native\nadd-on. This API is similar to napi_call_function. However, it is used to call\nfrom native code back into JavaScript after returning from an async\noperation (when there is no other script on the stack). It is a fairly simple\nwrapper around node::MakeCallback.

Note it is not necessary to use napi_make_callback from within a\nnapi_async_complete_callback; in that situation the callback's async\ncontext has already been set up, so a direct call to napi_call_function\nis sufficient and appropriate. Use of the napi_make_callback function\nmay be required when implementing custom async behavior that does not use\nnapi_create_async_work.

Any process.nextTicks or Promises scheduled on the microtask queue by\nJavaScript during the callback are ran before returning back to C/C++.

NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,\n                                                 napi_value resource_object,\n                                                 napi_async_context context,\n                                                 napi_callback_scope* result)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] resource_object: An object associated with the async work\nthat will be passed to possible async_hooks init hooks. This\nparameter has been deprecated and is ignored at runtime. Use the\nasync_resource parameter in napi_async_init instead.
\n
• [in] context: Context for the async operation that is invoking the callback.\nThis should be a value previously obtained from napi_async_init.
\n
• [out] result: The newly created scope.
\n

There are cases (for example, resolving promises) where it is\nnecessary to have the equivalent of the scope associated with a callback\nin place when making certain Node-API calls. If there is no other script on\nthe stack the napi_open_callback_scope and\nnapi_close_callback_scope functions can be used to open/close\nthe required scope.

NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,\n                                                  napi_callback_scope scope)\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] scope: The scope to be closed.
\n

This API can be called even if there is a pending JavaScript exception.

typedef struct {\n  uint32_t major;\n  uint32_t minor;\n  uint32_t patch;\n  const char* release;\n} napi_node_version;\n\nnapi_status napi_get_node_version(node_api_basic_env env,\n                                  const napi_node_version** version);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] version: A pointer to version information for Node.js itself.
\n

Returns napi_ok if the API succeeded.

This function fills the version struct with the major, minor, and patch\nversion of Node.js that is currently running, and the release field with the\nvalue of process.release.name.

The returned buffer is statically allocated and does not need to be freed.

napi_status napi_get_version(node_api_basic_env env,\n                             uint32_t* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: The highest version of Node-API supported.
\n

Returns napi_ok if the API succeeded.

This API returns the highest Node-API version supported by the\nNode.js runtime. Node-API is planned to be additive such that\nnewer releases of Node.js may support additional API functions.\nIn order to allow an addon to use a newer function when running with\nversions of Node.js that support it, while providing\nfallback behavior when running with Node.js versions that don't\nsupport it:

\n
• Call napi_get_version() to determine if the API is available.
\n
• If available, dynamically load a pointer to the function using uv_dlsym().
\n
• Use the dynamically loaded pointer to invoke the function.
\n
• If the function is not available, provide an alternate implementation\nthat does not use the function.
\n

NAPI_EXTERN napi_status napi_adjust_external_memory(node_api_basic_env env,\n                                                    int64_t change_in_bytes,\n                                                    int64_t* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] change_in_bytes: The change in externally allocated memory that is kept\nalive by JavaScript objects.
\n
• [out] result: The adjusted value. This value should reflect the\ntotal amount of external memory with the given change_in_bytes included.\nThe absolute value of the returned value should not be depended on.\nFor example, implementations may use a single counter for all addons, or a\ncounter for each addon.
\n

Returns napi_ok if the API succeeded.

This function gives the runtime an indication of the amount of externally\nallocated memory that is kept alive by JavaScript objects\n(i.e. a JavaScript object that points to its own memory allocated by a\nnative addon). Registering externally allocated memory may, but is not\nguaranteed to, trigger global garbage collections more\noften than it would otherwise.

This function is expected to be called in a manner such that an\naddon does not decrease the external memory more than it has\nincreased the external memory.

Node-API provides facilities for creating Promise objects as described in\nSection Promise objects of the ECMA specification. It implements promises as a pair of\nobjects. When a promise is created by napi_create_promise(), a \"deferred\"\nobject is created and returned alongside the Promise. The deferred object is\nbound to the created Promise and is the only means to resolve or reject the\nPromise using napi_resolve_deferred() or napi_reject_deferred(). The\ndeferred object that is created by napi_create_promise() is freed by\nnapi_resolve_deferred() or napi_reject_deferred(). The Promise object may\nbe returned to JavaScript where it can be used in the usual fashion.

For example, to create a promise and pass it to an asynchronous worker:

napi_deferred deferred;\nnapi_value promise;\nnapi_status status;\n\n// Create the promise.\nstatus = napi_create_promise(env, &deferred, &promise);\nif (status != napi_ok) return NULL;\n\n// Pass the deferred to a function that performs an asynchronous action.\ndo_something_asynchronous(deferred);\n\n// Return the promise to JS\nreturn promise;\n

The above function do_something_asynchronous() would perform its asynchronous\naction and then it would resolve or reject the deferred, thereby concluding the\npromise and freeing the deferred:

napi_deferred deferred;\nnapi_value undefined;\nnapi_status status;\n\n// Create a value with which to conclude the deferred.\nstatus = napi_get_undefined(env, &undefined);\nif (status != napi_ok) return NULL;\n\n// Resolve or reject the promise associated with the deferred depending on\n// whether the asynchronous action succeeded.\nif (asynchronous_action_succeeded) {\n  status = napi_resolve_deferred(env, deferred, undefined);\n} else {\n  status = napi_reject_deferred(env, deferred, undefined);\n}\nif (status != napi_ok) return NULL;\n\n// At this point the deferred has been freed, so we should assign NULL to it.\ndeferred = NULL;\n

napi_status napi_create_promise(napi_env env,\n                                napi_deferred* deferred,\n                                napi_value* promise);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] deferred: A newly created deferred object which can later be passed to\nnapi_resolve_deferred() or napi_reject_deferred() to resolve resp. reject\nthe associated promise.
\n
• [out] promise: The JavaScript promise associated with the deferred object.
\n

Returns napi_ok if the API succeeded.

This API creates a deferred object and a JavaScript promise.

napi_status napi_resolve_deferred(napi_env env,\n                                  napi_deferred deferred,\n                                  napi_value resolution);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] deferred: The deferred object whose associated promise to resolve.
\n
• [in] resolution: The value with which to resolve the promise.
\n

This API resolves a JavaScript promise by way of the deferred object\nwith which it is associated. Thus, it can only be used to resolve JavaScript\npromises for which the corresponding deferred object is available. This\neffectively means that the promise must have been created using\nnapi_create_promise() and the deferred object returned from that call must\nhave been retained in order to be passed to this API.

The deferred object is freed upon successful completion.

napi_status napi_reject_deferred(napi_env env,\n                                 napi_deferred deferred,\n                                 napi_value rejection);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] deferred: The deferred object whose associated promise to resolve.
\n
• [in] rejection: The value with which to reject the promise.
\n

This API rejects a JavaScript promise by way of the deferred object\nwith which it is associated. Thus, it can only be used to reject JavaScript\npromises for which the corresponding deferred object is available. This\neffectively means that the promise must have been created using\nnapi_create_promise() and the deferred object returned from that call must\nhave been retained in order to be passed to this API.

The deferred object is freed upon successful completion.

napi_status napi_is_promise(napi_env env,\n                            napi_value value,\n                            bool* is_promise);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] value: The value to examine
\n
• [out] is_promise: Flag indicating whether promise is a native promise\nobject (that is, a promise object created by the underlying engine).
\n

Node-API provides an API for executing a string containing JavaScript using the\nunderlying JavaScript engine.

NAPI_EXTERN napi_status napi_run_script(napi_env env,\n                                        napi_value script,\n                                        napi_value* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] script: A JavaScript string containing the script to execute.
\n
• [out] result: The value resulting from having executed the script.
\n

This function executes a string of JavaScript code and returns its result with\nthe following caveats:

\n
• Unlike eval, this function does not allow the script to access the current\nlexical scope, and therefore also does not allow to access the\nmodule scope, meaning that pseudo-globals such as require will not be\navailable.
\n
• The script can access the global scope. Function and var declarations\nin the script will be added to the global object. Variable declarations\nmade using let and const will be visible globally, but will not be added\nto the global object.
\n
• The value of this is global within the script.
\n

Node-API provides a function for getting the current event loop associated with\na specific napi_env.

NAPI_EXTERN napi_status napi_get_uv_event_loop(node_api_basic_env env,\n                                               struct uv_loop_s** loop);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] loop: The current libuv loop instance.
\n

Note: While libuv has been relatively stable over time, it does\nnot provide an ABI stability guarantee. Use of this function should be avoided.\nIts use may result in an addon that does not work across Node.js versions.\nasynchronous-thread-safe-function-calls\nare an alternative for many use cases.

JavaScript functions can normally only be called from a native addon's main\nthread. If an addon creates additional threads, then Node-API functions that\nrequire a napi_env, napi_value, or napi_ref must not be called from those\nthreads.

When an addon has additional threads and JavaScript functions need to be invoked\nbased on the processing completed by those threads, those threads must\ncommunicate with the addon's main thread so that the main thread can invoke the\nJavaScript function on their behalf. The thread-safe function APIs provide an\neasy way to do this.

These APIs provide the type napi_threadsafe_function as well as APIs to\ncreate, destroy, and call objects of this type.\nnapi_create_threadsafe_function() creates a persistent reference to a\nnapi_value that holds a JavaScript function which can be called from multiple\nthreads. The calls happen asynchronously. This means that values with which the\nJavaScript callback is to be called will be placed in a queue, and, for each\nvalue in the queue, a call will eventually be made to the JavaScript function.

Upon creation of a napi_threadsafe_function a napi_finalize callback can be\nprovided. This callback will be invoked on the main thread when the thread-safe\nfunction is about to be destroyed. It receives the context and the finalize data\ngiven during construction, and provides an opportunity for cleaning up after the\nthreads e.g. by calling uv_thread_join(). Aside from the main loop thread,\nno threads should be using the thread-safe function after the finalize callback\ncompletes.

The context given during the call to napi_create_threadsafe_function() can\nbe retrieved from any thread with a call to\nnapi_get_threadsafe_function_context().

napi_call_threadsafe_function() can be used for initiating a call into\nJavaScript. napi_call_threadsafe_function() accepts a parameter which controls\nwhether the API behaves blockingly. If set to napi_tsfn_nonblocking, the API\nbehaves non-blockingly, returning napi_queue_full if the queue was full,\npreventing data from being successfully added to the queue. If set to\nnapi_tsfn_blocking, the API blocks until space becomes available in the queue.\nnapi_call_threadsafe_function() never blocks if the thread-safe function was\ncreated with a maximum queue size of 0.

napi_call_threadsafe_function() should not be called with napi_tsfn_blocking\nfrom a JavaScript thread, because, if the queue is full, it may cause the\nJavaScript thread to deadlock.

The actual call into JavaScript is controlled by the callback given via the\ncall_js_cb parameter. call_js_cb is invoked on the main thread once for each\nvalue that was placed into the queue by a successful call to\nnapi_call_threadsafe_function(). If such a callback is not given, a default\ncallback will be used, and the resulting JavaScript call will have no arguments.\nThe call_js_cb callback receives the JavaScript function to call as a\nnapi_value in its parameters, as well as the void* context pointer used when\ncreating the napi_threadsafe_function, and the next data pointer that was\ncreated by one of the secondary threads. The callback can then use an API such\nas napi_call_function() to call into JavaScript.

The callback may also be invoked with env and call_js_cb both set to NULL\nto indicate that calls into JavaScript are no longer possible, while items\nremain in the queue that may need to be freed. This normally occurs when the\nNode.js process exits while there is a thread-safe function still active.

It is not necessary to call into JavaScript via napi_make_callback() because\nNode-API runs call_js_cb in a context appropriate for callbacks.

Zero or more queued items may be invoked in each tick of the event loop.\nApplications should not depend on a specific behavior other than progress in\ninvoking callbacks will be made and events will be invoked\nas time moves forward.

Threads can be added to and removed from a napi_threadsafe_function object\nduring its existence. Thus, in addition to specifying an initial number of\nthreads upon creation, napi_acquire_threadsafe_function can be called to\nindicate that a new thread will start making use of the thread-safe function.\nSimilarly, napi_release_threadsafe_function can be called to indicate that an\nexisting thread will stop making use of the thread-safe function.

napi_threadsafe_function objects are destroyed when every thread which uses\nthe object has called napi_release_threadsafe_function() or has received a\nreturn status of napi_closing in response to a call to\nnapi_call_threadsafe_function. The queue is emptied before the\nnapi_threadsafe_function is destroyed. napi_release_threadsafe_function()\nshould be the last API call made in conjunction with a given\nnapi_threadsafe_function, because after the call completes, there is no\nguarantee that the napi_threadsafe_function is still allocated. For the same\nreason, do not use a thread-safe function\nafter receiving a return value of napi_closing in response to a call to\nnapi_call_threadsafe_function. Data associated with the\nnapi_threadsafe_function can be freed in its napi_finalize callback which\nwas passed to napi_create_threadsafe_function(). The parameter\ninitial_thread_count of napi_create_threadsafe_function marks the initial\nnumber of acquisitions of the thread-safe functions, instead of calling\nnapi_acquire_threadsafe_function multiple times at creation.

Once the number of threads making use of a napi_threadsafe_function reaches\nzero, no further threads can start making use of it by calling\nnapi_acquire_threadsafe_function(). In fact, all subsequent API calls\nassociated with it, except napi_release_threadsafe_function(), will return an\nerror value of napi_closing.

The thread-safe function can be \"aborted\" by giving a value of napi_tsfn_abort\nto napi_release_threadsafe_function(). This will cause all subsequent APIs\nassociated with the thread-safe function except\nnapi_release_threadsafe_function() to return napi_closing even before its\nreference count reaches zero. In particular, napi_call_threadsafe_function()\nwill return napi_closing, thus informing the threads that it is no longer\npossible to make asynchronous calls to the thread-safe function. This can be\nused as a criterion for terminating the thread. Upon receiving a return value\nof napi_closing from napi_call_threadsafe_function() a thread must not use\nthe thread-safe function anymore because it is no longer guaranteed to\nbe allocated.

Similarly to libuv handles, thread-safe functions can be \"referenced\" and\n\"unreferenced\". A \"referenced\" thread-safe function will cause the event loop on\nthe thread on which it is created to remain alive until the thread-safe function\nis destroyed. In contrast, an \"unreferenced\" thread-safe function will not\nprevent the event loop from exiting. The APIs napi_ref_threadsafe_function and\nnapi_unref_threadsafe_function exist for this purpose.

Neither does napi_unref_threadsafe_function mark the thread-safe functions as\nable to be destroyed nor does napi_ref_threadsafe_function prevent it from\nbeing destroyed.

NAPI_EXTERN napi_status\nnapi_create_threadsafe_function(napi_env env,\n                                napi_value func,\n                                napi_value async_resource,\n                                napi_value async_resource_name,\n                                size_t max_queue_size,\n                                size_t initial_thread_count,\n                                void* thread_finalize_data,\n                                napi_finalize thread_finalize_cb,\n                                void* context,\n                                napi_threadsafe_function_call_js call_js_cb,\n                                napi_threadsafe_function* result);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] func: An optional JavaScript function to call from another thread. It\nmust be provided if NULL is passed to call_js_cb.
\n
• [in] async_resource: An optional object associated with the async work that\nwill be passed to possible async_hooks init hooks.
\n
• [in] async_resource_name: A JavaScript string to provide an identifier for\nthe kind of resource that is being provided for diagnostic information exposed\nby the async_hooks API.
\n
• [in] max_queue_size: Maximum size of the queue. 0 for no limit.
\n
• [in] initial_thread_count: The initial number of acquisitions, i.e. the\ninitial number of threads, including the main thread, which will be making use\nof this function.
\n
• [in] thread_finalize_data: Optional data to be passed to thread_finalize_cb.
\n
• [in] thread_finalize_cb: Optional function to call when the\nnapi_threadsafe_function is being destroyed.
\n
• [in] context: Optional data to attach to the resulting\nnapi_threadsafe_function.
\n
• [in] call_js_cb: Optional callback which calls the JavaScript function in\nresponse to a call on a different thread. This callback will be called on the\nmain thread. If not given, the JavaScript function will be called with no\nparameters and with undefined as its this value.\nnapi_threadsafe_function_call_js provides more details.
\n
• [out] result: The asynchronous thread-safe JavaScript function.
\n

Change History:

\n
• \n

  Version 10 (NAPI_VERSION is defined as 10 or higher):

  \n

  Uncaught exceptions thrown in call_js_cb are handled with the\n'uncaughtException' event, instead of being ignored.

  \n
\n

NAPI_EXTERN napi_status\nnapi_get_threadsafe_function_context(napi_threadsafe_function func,\n                                     void** result);\n

\n
• [in] func: The thread-safe function for which to retrieve the context.
\n
• [out] result: The location where to store the context.
\n

This API may be called from any thread which makes use of func.

NAPI_EXTERN napi_status\nnapi_call_threadsafe_function(napi_threadsafe_function func,\n                              void* data,\n                              napi_threadsafe_function_call_mode is_blocking);\n

\n
• [in] func: The asynchronous thread-safe JavaScript function to invoke.
\n
• [in] data: Data to send into JavaScript via the callback call_js_cb\nprovided during the creation of the thread-safe JavaScript function.
\n
• [in] is_blocking: Flag whose value can be either napi_tsfn_blocking to\nindicate that the call should block if the queue is full or\nnapi_tsfn_nonblocking to indicate that the call should return immediately\nwith a status of napi_queue_full whenever the queue is full.
\n

This API should not be called with napi_tsfn_blocking from a JavaScript\nthread, because, if the queue is full, it may cause the JavaScript thread to\ndeadlock.

This API will return napi_closing if napi_release_threadsafe_function() was\ncalled with abort set to napi_tsfn_abort from any thread. The value is only\nadded to the queue if the API returns napi_ok.

This API may be called from any thread which makes use of func.

NAPI_EXTERN napi_status\nnapi_acquire_threadsafe_function(napi_threadsafe_function func);\n

\n
• [in] func: The asynchronous thread-safe JavaScript function to start making\nuse of.
\n

A thread should call this API before passing func to any other thread-safe\nfunction APIs to indicate that it will be making use of func. This prevents\nfunc from being destroyed when all other threads have stopped making use of\nit.

This API may be called from any thread which will start making use of func.

NAPI_EXTERN napi_status\nnapi_release_threadsafe_function(napi_threadsafe_function func,\n                                 napi_threadsafe_function_release_mode mode);\n

\n
• [in] func: The asynchronous thread-safe JavaScript function whose reference\ncount to decrement.
\n
• [in] mode: Flag whose value can be either napi_tsfn_release to indicate\nthat the current thread will make no further calls to the thread-safe\nfunction, or napi_tsfn_abort to indicate that in addition to the current\nthread, no other thread should make any further calls to the thread-safe\nfunction. If set to napi_tsfn_abort, further calls to\nnapi_call_threadsafe_function() will return napi_closing, and no further\nvalues will be placed in the queue.
\n

A thread should call this API when it stops making use of func. Passing func\nto any thread-safe APIs after having called this API has undefined results, as\nfunc may have been destroyed.

This API may be called from any thread which will stop making use of func.

NAPI_EXTERN napi_status\nnapi_ref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] func: The thread-safe function to reference.
\n

This API is used to indicate that the event loop running on the main thread\nshould not exit until func has been destroyed. Similar to uv_ref it is\nalso idempotent.

Neither does napi_unref_threadsafe_function mark the thread-safe functions as\nable to be destroyed nor does napi_ref_threadsafe_function prevent it from\nbeing destroyed. napi_acquire_threadsafe_function and\nnapi_release_threadsafe_function are available for that purpose.

This API may only be called from the main thread.

NAPI_EXTERN napi_status\nnapi_unref_threadsafe_function(node_api_basic_env env, napi_threadsafe_function func);\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [in] func: The thread-safe function to unreference.
\n

This API is used to indicate that the event loop running on the main thread\nmay exit before func is destroyed. Similar to uv_unref it is also\nidempotent.

This API may only be called from the main thread.

NAPI_EXTERN napi_status\nnode_api_get_module_file_name(node_api_basic_env env, const char** result);\n\n

\n
• [in] env: The environment that the API is invoked under.
\n
• [out] result: A URL containing the absolute path of the\nlocation from which the add-on was loaded. For a file on the local\nfile system it will start with file://. The string is null-terminated and\nowned by env and must thus not be modified or freed.
\n

result may be an empty string if the add-on loading process fails to establish\nthe add-on's file name during loading.

Node.js comes with a variety of CLI options. These options expose built-in\ndebugging, multiple ways to execute scripts, and other helpful runtime options.

To view this documentation as a manual page in a terminal, run man node.

node [options] [V8 options] [<program-entry-point> | -e \"script\" | -] [--] [arguments]

node inspect [<program-entry-point> | -e \"script\" | <host>:<port>] …

node --v8-options

Execute without arguments to start the REPL.

For more info about node inspect, see the debugger documentation.

The program entry point is a specifier-like string. If the string is not an\nabsolute path, it's resolved as a relative path from the current working\ndirectory. That entry point string is then resolved as if it's been requested\nby require() from the current working directory. If no corresponding file\nis found, an error is thrown.

By default, the resolved path is also loaded as if it's been requested by require(),\nunless one of the conditions below apply—then it's loaded as if it's been requested\nby import():

\n
• The program was started with a command-line flag that forces the entry\npoint to be loaded with ECMAScript module loader, such as --import.
\n
• The file has an .mjs, .mts or .wasm extension.
\n
• The file does not have a .cjs extension, and the nearest parent\npackage.json file contains a top-level \"type\" field with a value of\n\"module\".
\n

See module resolution and loading for more details.

All options, including V8 options, allow words to be separated by both\ndashes (-) or underscores (_). For example, --pending-deprecation is\nequivalent to --pending_deprecation.

If an option that takes a single value (such as --max-http-header-size) is\npassed more than once, then the last passed value is used. Options from the\ncommand line take precedence over options passed through the NODE_OPTIONS\nenvironment variable.

Alias for stdin. Analogous to the use of - in other command-line utilities,\nmeaning that the script is read from stdin, and the rest of the options\nare passed to that script.

Indicate the end of node options. Pass the rest of the arguments to the script.\nIf no script filename or eval/print script is supplied prior to this, then\nthe next argument is used as a script filename.

Aborting instead of exiting causes a core file to be generated for post-mortem\nanalysis using a debugger (such as lldb, gdb, and mdb).

If this flag is passed, the behavior can still be set to not abort through\nprocess.setUncaughtExceptionCaptureCallback() (and through usage of the\nnode:domain module that uses it).

When using the Permission Model, the process will not be able to use\nnative addons by default.\nAttempts to do so will throw an ERR_DLOPEN_DISABLED unless the\nuser explicitly passes the --allow-addons flag when starting Node.js.

Example:

// Attempt to require an native addon\nrequire('nodejs-addon-example');\n

$ node --permission --allow-fs-read=* index.js\nnode:internal/modules/cjs/loader:1319\n  return process.dlopen(module, path.toNamespacedPath(filename));\n                 ^\n\nError: Cannot load native addon because loading addons is disabled.\n    at Module._extensions..node (node:internal/modules/cjs/loader:1319:18)\n    at Module.load (node:internal/modules/cjs/loader:1091:32)\n    at Module._load (node:internal/modules/cjs/loader:938:12)\n    at Module.require (node:internal/modules/cjs/loader:1115:19)\n    at require (node:internal/modules/helpers:130:18)\n    at Object.<anonymous> (/home/index.js:1:15)\n    at Module._compile (node:internal/modules/cjs/loader:1233:14)\n    at Module._extensions..js (node:internal/modules/cjs/loader:1287:10)\n    at Module.load (node:internal/modules/cjs/loader:1091:32)\n    at Module._load (node:internal/modules/cjs/loader:938:12) {\n  code: 'ERR_DLOPEN_DISABLED'\n}\n

When using the Permission Model, the process will not be able to spawn any\nchild process by default.\nAttempts to do so will throw an ERR_ACCESS_DENIED unless the\nuser explicitly passes the --allow-child-process flag when starting Node.js.

Example:

const childProcess = require('node:child_process');\n// Attempt to bypass the permission\nchildProcess.spawn('node', ['-e', 'require(\"fs\").writeFileSync(\"/new-file\", \"example\")']);\n

$ node --permission --allow-fs-read=* index.js\nnode:internal/child_process:388\n  const err = this._handle.spawn(options);\n                           ^\nError: Access to this API has been restricted\n    at ChildProcess.spawn (node:internal/child_process:388:28)\n    at node:internal/main/run_main_module:17:47 {\n  code: 'ERR_ACCESS_DENIED',\n  permission: 'ChildProcess'\n}\n

The child_process.fork() API inherits the execution arguments from the\nparent process. This means that if Node.js is started with the Permission\nModel enabled and the --allow-child-process flag is set, any child process\ncreated using child_process.fork() will automatically receive all relevant\nPermission Model flags.

This behavior also applies to child_process.spawn(), but in that case, the\nflags are propagated via the NODE_OPTIONS environment variable rather than\ndirectly through the process arguments.

This flag configures file system read permissions using\nthe Permission Model.

The valid arguments for the --allow-fs-read flag are:

\n
• * - To allow all FileSystemRead operations.
\n
• Multiple paths can be allowed using multiple --allow-fs-read flags.\nExample --allow-fs-read=/folder1/ --allow-fs-read=/folder1/
\n

Examples can be found in the File System Permissions documentation.

The initializer module and custom --require modules has a implicit\nread permission.

$ node --permission -r custom-require.js -r custom-require-2.js index.js\n

\n
• The custom-require.js, custom-require-2.js, and index.js will be\nby default in the allowed read list.
\n

process.has('fs.read', 'index.js'); // true\nprocess.has('fs.read', 'custom-require.js'); // true\nprocess.has('fs.read', 'custom-require-2.js'); // true\n

This flag configures file system write permissions using\nthe Permission Model.

The valid arguments for the --allow-fs-write flag are:

\n
• * - To allow all FileSystemWrite operations.
\n
• Multiple paths can be allowed using multiple --allow-fs-write flags.\nExample --allow-fs-write=/folder1/ --allow-fs-write=/folder1/
\n

Paths delimited by comma (,) are no longer allowed.\nWhen passing a single flag with a comma a warning will be displayed.

Examples can be found in the File System Permissions documentation.

When using the Permission Model, the process will not be able to connect\nthrough inspector protocol.

Attempts to do so will throw an ERR_ACCESS_DENIED unless the\nuser explicitly passes the --allow-inspector flag when starting Node.js.

Example:

const { Session } = require('node:inspector/promises');\n\nconst session = new Session();\nsession.connect();\n

$ node --permission index.js\nError: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-inspector to manage permissions.\n  code: 'ERR_ACCESS_DENIED',\n}\n

When using the Permission Model, the process will not be able to access\nnetwork by default.\nAttempts to do so will throw an ERR_ACCESS_DENIED unless the\nuser explicitly passes the --allow-net flag when starting Node.js.

Example:

const http = require('node:http');\n// Attempt to bypass the permission\nconst req = http.get('http://example.com', () => {});\n\nreq.on('error', (err) => {\n  console.log('err', err);\n});\n

$ node --permission index.js\nError: connect ERR_ACCESS_DENIED Access to this API has been restricted. Use --allow-net to manage permissions.\n  code: 'ERR_ACCESS_DENIED',\n}\n

When using the Permission Model, the process will not be capable of creating\nany WASI instances by default.\nFor security reasons, the call will throw an ERR_ACCESS_DENIED unless the\nuser explicitly passes the flag --allow-wasi in the main Node.js process.

Example:

const { WASI } = require('node:wasi');\n// Attempt to bypass the permission\nnew WASI({\n  version: 'preview1',\n  // Attempt to mount the whole filesystem\n  preopens: {\n    '/': '/',\n  },\n});\n

$ node --permission --allow-fs-read=* index.js\n\nError: Access to this API has been restricted\n    at node:internal/main/run_main_module:30:49 {\n  code: 'ERR_ACCESS_DENIED',\n  permission: 'WASI',\n}\n

When using the Permission Model, the process will not be able to create any\nworker threads by default.\nFor security reasons, the call will throw an ERR_ACCESS_DENIED unless the\nuser explicitly pass the flag --allow-worker in the main Node.js process.

Example:

const { Worker } = require('node:worker_threads');\n// Attempt to bypass the permission\nnew Worker(__filename);\n

$ node --permission --allow-fs-read=* index.js\n\nError: Access to this API has been restricted\n    at node:internal/main/run_main_module:17:47 {\n  code: 'ERR_ACCESS_DENIED',\n  permission: 'WorkerThreads'\n}\n

Generates a single executable application from a JSON\nconfiguration file. The argument must be a path to the configuration file. If\nthe path is not absolute, it is resolved relative to the current working\ndirectory.

For configuration fields, cross-platform notes, and asset APIs, see\nthe single executable application documentation.

Generates a snapshot blob when the process exits and writes it to\ndisk, which can be loaded later with --snapshot-blob.

When building the snapshot, if --snapshot-blob is not specified,\nthe generated blob will be written, by default, to snapshot.blob\nin the current working directory. Otherwise it will be written to\nthe path specified by --snapshot-blob.

$ echo \"globalThis.foo = 'I am from the snapshot'\" > snapshot.js\n\n# Run snapshot.js to initialize the application and snapshot the\n# state of it into snapshot.blob.\n$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js\n\n$ echo \"console.log(globalThis.foo)\" > index.js\n\n# Load the generated snapshot and start the application from index.js.\n$ node --snapshot-blob snapshot.blob index.js\nI am from the snapshot\n

The v8.startupSnapshot API can be used to specify an entry point at\nsnapshot building time, thus avoiding the need of an additional entry\nscript at deserialization time:

$ echo \"require('v8').startupSnapshot.setDeserializeMainFunction(() => console.log('I am from the snapshot'))\" > snapshot.js\n$ node --snapshot-blob snapshot.blob --build-snapshot snapshot.js\n$ node --snapshot-blob snapshot.blob\nI am from the snapshot\n

For more information, check out the v8.startupSnapshot API documentation.

The snapshot currently only supports loding a single entrypoint during the\nsnapshot building process, which can load built-in modules, but not additional user-land modules.\nUsers can bundle their applications into a single script with their bundler\nof choice before building a snapshot.

As it's complicated to ensure the serializablility of all built-in modules,\nwhich are also growing over time, only a subset of the built-in modules are\nwell tested to be serializable during the snapshot building process.\nThe Node.js core test suite checks that a few fairly complex applications\ncan be snapshotted. The list of built-in modules being\ncaptured by the built-in snapshot of Node.js is considered supported.\nWhen the snapshot builder encounters a built-in module that cannot be\nserialized, it may crash the snapshot building process. In that case a typical\nworkaround would be to delay loading that module until\nruntime, using either v8.startupSnapshot.setDeserializeMainFunction() or\nv8.startupSnapshot.addDeserializeCallback(). If serialization for\nan additional module during the snapshot building process is needed,\nplease file a request in the Node.js issue tracker and link to it in the\ntracking issue for user-land snapshots.

Specifies the path to a JSON configuration file which configures snapshot\ncreation behavior.

The following options are currently supported:

\n
• builder <string> Required. Provides the name to the script that is executed\nbefore building the snapshot, as if --build-snapshot had been passed\nwith builder as the main script name.
\n
• withoutCodeCache <boolean> Optional. Including the code cache reduces the\ntime spent on compiling functions included in the snapshot at the expense\nof a bigger snapshot size and potentially breaking portability of the\nsnapshot.
\n

When using this flag, additional script files provided on the command line will\nnot be executed and instead be interpreted as regular command line arguments.

Syntax check the script without executing.

Print source-able bash completion script for Node.js.

node --completion-bash > node_bash_completion\nsource node_bash_completion\n

Provide custom conditional exports resolution conditions.

Any number of custom string condition names are permitted.

The default Node.js conditions of \"node\", \"default\", \"import\", and\n\"require\" will always apply as defined.

For example, to run a module with \"development\" resolutions:

node -C development app.js\n

Starts the V8 CPU profiler on start up, and writes the CPU profile to disk\nbefore exit.

If --cpu-prof-dir is not specified, the generated profile is placed\nin the current working directory.

If --cpu-prof-name is not specified, the generated profile is\nnamed CPU.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.cpuprofile.

$ node --cpu-prof index.js\n$ ls *.cpuprofile\nCPU.20190409.202950.15293.0.0.cpuprofile\n

If --cpu-prof-name is specified, the provided value is used as a template\nfor the file name. The following placeholder is supported and will be\nsubstituted at runtime:

\n
• ${pid} — the current process ID
\n

$ node --cpu-prof --cpu-prof-name 'CPU.${pid}.cpuprofile' index.js\n$ ls *.cpuprofile\nCPU.15293.cpuprofile\n

Specify the directory where the CPU profiles generated by --cpu-prof will\nbe placed.

The default value is controlled by the\n--diagnostic-dir command-line option.

Specify the sampling interval in microseconds for the CPU profiles generated\nby --cpu-prof. The default is 1000 microseconds.

Specify the file name of the CPU profile generated by --cpu-prof.

Set the directory to which all diagnostic output files are written.\nDefaults to current working directory.

Affects the default output directory of:

\n
• --cpu-prof-dir
\n
• --heap-prof-dir
\n
• --redirect-warnings
\n

Disable the Object.prototype.__proto__ property. If mode is delete, the\nproperty is removed entirely. If mode is throw, accesses to the\nproperty throw an exception with the code ERR_PROTO_ACCESS.

Disable the ability of starting a debugging session by sending a\nSIGUSR1 signal to the process.

Disable specific process warnings by code or type.

Warnings emitted from process.emitWarning() may contain a\ncode and a type. This option will not-emit warnings that have a matching\ncode or type.

List of deprecation warnings.

The Node.js core warning types are: DeprecationWarning and\nExperimentalWarning

For example, the following script will not emit\nDEP0025 require('node:sys') when executed with\nnode --disable-warning=DEP0025:

import sys from 'node:sys';\n

const sys = require('node:sys');\n

For example, the following script will emit the\nDEP0025 require('node:sys'), but not any Experimental\nWarnings (such as\nExperimentalWarning: vm.measureMemory is an experimental feature\nin <=v21) when executed with node --disable-warning=ExperimentalWarning:

import sys from 'node:sys';\nimport vm from 'node:vm';\n\nvm.measureMemory();\n

const sys = require('node:sys');\nconst vm = require('node:vm');\n\nvm.measureMemory();\n

By default, Node.js enables trap-handler-based WebAssembly bound\nchecks. As a result, V8 does not need to insert inline bound checks\nin the code compiled from WebAssembly which may speed up WebAssembly\nexecution significantly, but this optimization requires allocating\na big virtual memory cage (currently 10GB). If the Node.js process\ndoes not have access to a large enough virtual memory address space\ndue to system configurations or hardware limitations, users won't\nbe able to run any WebAssembly that involves allocation in this\nvirtual memory cage and will see an out-of-memory error.

$ ulimit -v 5000000\n$ node -p \"new WebAssembly.Memory({ initial: 10, maximum: 100 });\"\n[eval]:1\nnew WebAssembly.Memory({ initial: 10, maximum: 100 });\n^\n\nRangeError: WebAssembly.Memory(): could not allocate memory\n    at [eval]:1:1\n    at runScriptInThisContext (node:internal/vm:209:10)\n    at node:internal/process/execution:118:14\n    at [eval]-wrapper:6:24\n    at runScript (node:internal/process/execution:101:62)\n    at evalScript (node:internal/process/execution:136:3)\n    at node:internal/main/eval_string:49:3\n\n

--disable-wasm-trap-handler disables this optimization so that\nusers can at least run WebAssembly (with less optimal performance)\nwhen the virtual memory address space available to their Node.js\nprocess is lower than what the V8 WebAssembly memory cage needs.

Make built-in language features like eval and new Function that generate\ncode from strings throw an exception instead. This does not affect the Node.js\nnode:vm module.

Set the default value of order in dns.lookup() and\ndnsPromises.lookup(). The value could be:

\n
• ipv4first: sets default order to ipv4first.
\n
• ipv6first: sets default order to ipv6first.
\n
• verbatim: sets default order to verbatim.
\n

The default is verbatim and dns.setDefaultResultOrder() have higher\npriority than --dns-result-order.

Enable FIPS-compliant crypto at startup. (Requires Node.js to be built\nagainst FIPS-compatible OpenSSL.)

Enable Source Map support for stack traces.

When using a transpiler, such as TypeScript, stack traces thrown by an\napplication reference the transpiled code, not the original source position.\n--enable-source-maps enables caching of Source Maps and makes a best\neffort to report stack traces relative to the original source file.

Overriding Error.prepareStackTrace may prevent --enable-source-maps from\nmodifying the stack trace. Call and return the results of the original\nError.prepareStackTrace in the overriding function to modify the stack trace\nwith source maps.

const originalPrepareStackTrace = Error.prepareStackTrace;\nError.prepareStackTrace = (error, trace) => {\n  // Modify error and trace and format stack trace with\n  // original Error.prepareStackTrace.\n  return originalPrepareStackTrace(error, trace);\n};\n

Note, enabling source maps can introduce latency to your application\nwhen Error.stack is accessed. If you access Error.stack frequently\nin your application, take into account the performance implications\nof --enable-source-maps.

When present, Node.js will interpret the entry point as a URL, rather than a\npath.

Follows ECMAScript module resolution rules.

Any query parameter or hash in the URL will be accessible via import.meta.url.

node --entry-url 'file:///path/to/file.js?queryparams=work#and-hashes-too'\nnode --entry-url 'file.ts?query#hash'\nnode --entry-url 'data:text/javascript,console.log(\"Hello\")'\n

Behavior is the same as --env-file, but an error is not thrown if the file\ndoes not exist.

Loads environment variables from a file relative to the current directory,\nmaking them available to applications on process.env. The environment\nvariables which configure Node.js, such as NODE_OPTIONS,\nare parsed and applied. If the same variable is defined in the environment and\nin the file, the value from the environment takes precedence.

You can pass multiple --env-file arguments. Subsequent files override\npre-existing variables defined in previous files.

An error is thrown if the file does not exist.

node --env-file=.env --env-file=.development.env index.js\n

The format of the file should be one line per key-value pair of environment\nvariable name and value separated by =:

PORT=3000\n

Any text after a # is treated as a comment:

# This is a comment\nPORT=3000 # This is also a comment\n

Values can start and end with the following quotes: `, \" or '.\nThey are omitted from the values.

USERNAME=\"nodejs\" # will result in `nodejs` as the value.\n

Multi-line values are supported:

MULTI_LINE=\"THIS IS\nA MULTILINE\"\n# will result in `THIS IS\\nA MULTILINE` as the value.\n

Export keyword before a key is ignored:

export USERNAME=\"nodejs\" # will result in `nodejs` as the value.\n

If you want to load environment variables from a file that may not exist, you\ncan use the --env-file-if-exists flag instead.

Evaluate the following argument as JavaScript. The modules which are\npredefined in the REPL can also be used in script.

On Windows, using cmd.exe a single quote will not work correctly because it\nonly recognizes double \" for quoting. In Powershell or Git bash, both '\nand \" are usable.

It is possible to run code containing inline types unless the\n--no-strip-types flag is provided.

Enable experimental import support for .node addons.

If present, Node.js will look for a configuration file at the specified path.\nNode.js will read the configuration file and apply the settings. The\nconfiguration file should be a JSON file with the following structure. vX.Y.Z\nin the $schema must be replaced with the version of Node.js you are using.

{\n  \"$schema\": \"https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json\",\n  \"nodeOptions\": {\n    \"import\": [\n      \"amaro/strip\"\n    ],\n    \"watch-path\": \"src\",\n    \"watch-preserve-output\": true\n  },\n  \"test\": {\n    \"test-isolation\": \"process\"\n  },\n  \"watch\": {\n    \"watch-preserve-output\": true\n  }\n}\n

The configuration file supports namespace-specific options:

\n
• \n

  The nodeOptions field contains CLI flags that are allowed in NODE_OPTIONS.

  \n
\n
• \n

  Namespace fields like test, watch, and permission contain configuration specific to that subsystem.

  \n
\n

When a namespace is present in the\nconfiguration file, Node.js automatically enables the corresponding flag\n(e.g., --test, --watch, --permission). This allows you to configure\nsubsystem-specific options without explicitly passing the flag on the command line.

For example:

{\n  \"test\": {\n    \"test-isolation\": \"process\"\n  }\n}\n

is equivalent to:

node --test --test-isolation=process\n

To disable the automatic flag while still using namespace options, you can\nexplicitly set the flag to false within the namespace:

{\n  \"test\": {\n    \"test\": false,\n    \"test-isolation\": \"process\"\n  }\n}\n

No-op flags are not supported.\nNot all V8 flags are currently supported.

It is possible to use the official JSON schema\nto validate the configuration file, which may vary depending on the Node.js version.\nEach key in the configuration file corresponds to a flag that can be passed\nas a command-line argument. The value of the key is the value that would be\npassed to the flag.

For example, the configuration file above is equivalent to\nthe following command-line arguments:

node --import amaro/strip --watch-path=src --watch-preserve-output --test-isolation=process\n

The priority in configuration is as follows:

\n
1. NODE_OPTIONS and command-line options
\n
2. Configuration file
\n
3. Dotenv NODE_OPTIONS
\n

Values in the configuration file will not override the values in the environment\nvariables and command-line options, but will override the values in the NODE_OPTIONS\nenv file parsed by the --env-file flag.

Keys cannot be duplicated within the same or different namespaces.

The configuration parser will throw an error if the configuration file contains\nunknown keys or keys that cannot be used in a namespace.

Node.js will not sanitize or perform validation on the user-provided configuration,\nso NEVER use untrusted configuration files.

If the --experimental-default-config-file flag is present, Node.js will look for a\nnode.config.json file in the current working directory and load it as a\nas configuration file.

Enable exposition of EventSource Web API on the global scope.

Enable experimental import.meta.resolve() parent URL support, which allows\npassing a second parentURL argument for contextual resolution.

Previously gated the entire import.meta.resolve feature.

Enable experimental support for inspector network resources.

\n

This flag is discouraged and may be removed in a future version of Node.js.\nPlease use\n--import with register() instead.

\n

Specify the module containing exported asynchronous module customization hooks.\nmodule may be any string accepted as an import specifier.

This feature requires --allow-worker if used with the Permission Model.

Enable experimental support for the network inspection with Chrome DevTools.

If the ES module being require()'d contains top-level await, this flag\nallows Node.js to evaluate the module, try to locate the\ntop-level awaits, and print their location to help users find them.

Enable experimental support for the QUIC protocol.

Use this flag to generate a blob that can be injected into the Node.js\nbinary to produce a single executable application. See the documentation\nabout this configuration for details.

Use this flag to enable ShadowRealm support.

Enable experimental support for storage inspection

When used in conjunction with the node:test module, a code coverage report is\ngenerated as part of the test runner output. If no tests are run, a coverage\nreport is not generated. See the documentation on\ncollecting code coverage from tests for more details.

Enable module mocking in the test runner.

This feature requires --allow-worker if used with the Permission Model.

Enables the transformation of TypeScript-only syntax into JavaScript code.\nImplies --enable-source-maps.

Enable experimental ES Module support in the node:vm module.

Enable experimental WebAssembly System Interface (WASI) support.

Enable experimental support for the worker inspection with Chrome DevTools.

This flag will expose the gc extension from V8.

if (globalThis.gc) {\n  globalThis.gc();\n}\n

Disable loading native addons that are not context-aware.

Force FIPS-compliant crypto on startup. (Cannot be disabled from script code.)\n(Same requirements as --enable-fips.)

Enforces uncaughtException event on Node-API asynchronous callbacks.

To prevent from an existing add-on from crashing the process, this flag is not\nenabled by default. In the future, this flag will be enabled by default to\nenforce the correct behavior.

Enable experimental frozen intrinsics like Array and Object.

Only the root context is supported. There is no guarantee that\nglobalThis.Array is indeed the default intrinsic reference. Code may break\nunder this flag.

To allow polyfills to be added,\n--require and --import both run before freezing intrinsics.

Starts the V8 heap profiler on start up, and writes the heap profile to disk\nbefore exit.

If --heap-prof-dir is not specified, the generated profile is placed\nin the current working directory.

If --heap-prof-name is not specified, the generated profile is\nnamed Heap.${yyyymmdd}.${hhmmss}.${pid}.${tid}.${seq}.heapprofile.

$ node --heap-prof index.js\n$ ls *.heapprofile\nHeap.20190409.202950.15293.0.001.heapprofile\n

Specify the directory where the heap profiles generated by --heap-prof will\nbe placed.

The default value is controlled by the\n--diagnostic-dir command-line option.

Specify the average sampling interval in bytes for the heap profiles generated\nby --heap-prof. The default is 512 * 1024 bytes.

Specify the file name of the heap profile generated by --heap-prof.

Writes a V8 heap snapshot to disk when the V8 heap usage is approaching the\nheap limit. count should be a non-negative integer (in which case\nNode.js will write no more than max_count snapshots to disk).

When generating snapshots, garbage collection may be triggered and bring\nthe heap usage down. Therefore multiple snapshots may be written to disk\nbefore the Node.js instance finally runs out of memory. These heap snapshots\ncan be compared to determine what objects are being allocated during the\ntime consecutive snapshots are taken. It's not guaranteed that Node.js will\nwrite exactly max_count snapshots to disk, but it will try\nits best to generate at least one and up to max_count snapshots before the\nNode.js instance runs out of memory when max_count is greater than 0.

Generating V8 snapshots takes time and memory (both memory managed by the\nV8 heap and native memory outside the V8 heap). The bigger the heap is,\nthe more resources it needs. Node.js will adjust the V8 heap to accommodate\nthe additional V8 heap memory overhead, and try its best to avoid using up\nall the memory available to the process. When the process uses\nmore memory than the system deems appropriate, the process may be terminated\nabruptly by the system, depending on the system configuration.

$ node --max-old-space-size=100 --heapsnapshot-near-heap-limit=3 index.js\nWrote snapshot to Heap.20200430.100036.49580.0.001.heapsnapshot\nWrote snapshot to Heap.20200430.100037.49580.0.002.heapsnapshot\nWrote snapshot to Heap.20200430.100038.49580.0.003.heapsnapshot\n\n<--- Last few GCs --->\n\n[49580:0x110000000]     4826 ms: Mark-sweep 130.6 (147.8) -> 130.5 (147.8) MB, 27.4 / 0.0 ms  (average mu = 0.126, current mu = 0.034) allocation failure scavenge might not succeed\n[49580:0x110000000]     4845 ms: Mark-sweep 130.6 (147.8) -> 130.6 (147.8) MB, 18.8 / 0.0 ms  (average mu = 0.088, current mu = 0.031) allocation failure scavenge might not succeed\n\n\n<--- JS stacktrace --->\n\nFATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory\n....\n

Enables a signal handler that causes the Node.js process to write a heap dump\nwhen the specified signal is received. signal must be a valid signal name.\nDisabled by default.

$ node --heapsnapshot-signal=SIGUSR2 index.js &\n$ ps aux\nUSER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND\nnode         1  5.5  6.1 787252 247004 ?       Ssl  16:43   0:02 node --heapsnapshot-signal=SIGUSR2 index.js\n$ kill -USR2 1\n$ ls\nHeap.20190718.133405.15554.0.001.heapsnapshot\n

Print node command-line options.\nThe output of this option is less detailed than this document.

Specify ICU data load path. (Overrides NODE_ICU_DATA.)

Preload the specified module at startup. If the flag is provided several times,\neach module will be executed sequentially in the order they appear, starting\nwith the ones provided in NODE_OPTIONS.

Follows ECMAScript module resolution rules.\nUse --require to load a CommonJS module.\nModules preloaded with --require will run before modules preloaded with --import.

Modules are preloaded into the main thread as well as any worker threads,\nforked processes, or clustered processes.

This configures Node.js to interpret --eval or STDIN input as CommonJS or\nas an ES module. Valid values are \"commonjs\", \"module\", \"module-typescript\" and \"commonjs-typescript\".\nThe \"-typescript\" values are not available with the flag --no-strip-types.\nThe default is no value, or \"commonjs\" if --no-experimental-detect-module is passed.

If --input-type is not provided,\nNode.js will try to detect the syntax with the following steps:

\n
1. Run the input as CommonJS.
\n
2. If step 1 fails, run the input as an ES module.
\n
3. If step 2 fails with a SyntaxError, strip the types.
\n
4. If step 3 fails with an error code ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX\nor ERR_INVALID_TYPESCRIPT_SYNTAX,\nthrow the error from step 2, including the TypeScript error in the message,\nelse run as CommonJS.
\n
5. If step 4 fails, run the input as an ES module.
\n

To avoid the delay of multiple syntax detection passes, the --input-type=type flag can be used to specify\nhow the --eval input should be interpreted.

The REPL does not support this option. Usage of --input-type=module with\n--print will throw an error, as --print does not support ES module\nsyntax.

Enable leniency flags on the HTTP parser. This may allow\ninteroperability with non-conformant HTTP implementations.

When enabled, the parser will accept the following:

\n
• Invalid HTTP headers values.
\n
• Invalid HTTP versions.
\n
• Allow message containing both Transfer-Encoding\nand Content-Length headers.
\n
• Allow extra data after message when Connection: close is present.
\n
• Allow extra transfer encodings after chunked has been provided.
\n
• Allow \\n to be used as token separator instead of \\r\\n.
\n
• Allow \\r\\n not to be provided after a chunk.
\n
• Allow spaces to be present after a chunk size and before \\r\\n.
\n

All the above will expose your application to request smuggling\nor poisoning attack. Avoid using this option.

Activate inspector on host:port and break at start of user script.\nDefault host:port is 127.0.0.1:9229. If port 0 is specified,\na random available port will be used.

See V8 Inspector integration for Node.js for further explanation on Node.js debugger.

See the security warning below regarding the host\nparameter usage.

Set the host:port to be used when the inspector is activated.\nUseful when activating the inspector by sending the SIGUSR1 signal.\nExcept when --disable-sigusr1 is passed.

Default host is 127.0.0.1. If port 0 is specified,\na random available port will be used.

See the security warning below regarding the host\nparameter usage.

Specify ways of the inspector web socket url exposure.

By default inspector websocket url is available in stderr and under /json/list\nendpoint on http://host:port/json/list.

Activate inspector on host:port and wait for debugger to be attached.\nDefault host:port is 127.0.0.1:9229. If port 0 is specified,\na random available port will be used.

See V8 Inspector integration for Node.js for further explanation on Node.js debugger.

See the security warning below regarding the host\nparameter usage.

Activate inspector on host:port. Default is 127.0.0.1:9229. If port 0 is\nspecified, a random available port will be used.

V8 inspector integration allows tools such as Chrome DevTools and IDEs to debug\nand profile Node.js instances. The tools attach to Node.js instances via a\ntcp port and communicate using the Chrome DevTools Protocol.\nSee V8 Inspector integration for Node.js for further explanation on Node.js debugger.

Binding the inspector to a public IP (including 0.0.0.0) with an open port is\ninsecure, as it allows external hosts to connect to the inspector and perform\na remote code execution attack.

If specifying a host, make sure that either:

\n
• The host is not accessible from public networks.
\n
• A firewall disallows unwanted connections on the port.
\n

More specifically, --inspect=0.0.0.0 is insecure if the port (9229 by\ndefault) is not firewall-protected.

See the debugging security implications section for more information.

Opens the REPL even if stdin does not appear to be a terminal.

Disable runtime allocation of executable memory. This may be\nrequired on some platforms for security reasons. It can also reduce attack\nsurface on other platforms, but the performance impact may be severe.

The file used to store localStorage data. If the file does not exist, it is\ncreated the first time localStorage is accessed. The same file may be shared\nbetween multiple Node.js processes concurrently.

Specify the maximum size, in bytes, of HTTP headers. Defaults to 16 KiB.

Sets the maximum memory size of V8's old memory section as a percentage of available system memory.\nThis flag takes precedence over --max-old-space-size when both are specified.

The percentage parameter must be a number greater than 0 and up to 100, representing the percentage\nof available system memory to allocate to the V8 heap.

Note: This flag utilizes --max-old-space-size, which may be unreliable on 32-bit platforms due to\ninteger overflow issues.

# Using 50% of available system memory\nnode --max-old-space-size-percentage=50 index.js\n\n# Using 75% of available system memory\nnode --max-old-space-size-percentage=75 index.js\n

This option is a no-op. It is kept for compatibility.

Sets the default value for the network family autoselection attempt timeout.\nFor more information, see net.getDefaultAutoSelectFamilyAttemptTimeout().

Disable the node-addons exports condition as well as disable loading\nnative addons. When --no-addons is specified, calling process.dlopen or\nrequiring a native C++ addon will fail and throw an exception.

Disables the use of AsyncLocalStorage backed by AsyncContextFrame and\nuses the prior implementation which relied on async_hooks. The previous model\nis retained for compatibility with Electron and for cases where the context\nflow may differ. However, if a difference in flow is found please report it.

Silence deprecation warnings.

Disable using syntax detection to determine module type.

Disable exposition of Navigator API on the global scope.

Use this flag to disable top-level await in REPL.

Legacy alias for --no-require-module.

Disable the experimental node:sqlite module.

Disable exposition of <WebSocket> on the global scope.

Disable Web Storage support.

Hide extra information on fatal exception that causes exit.

Disables runtime checks for async_hooks. These will still be enabled\ndynamically when async_hooks is enabled.

Do not search modules from global paths like $HOME/.node_modules and\n$NODE_PATH.

Disables the family autoselection algorithm unless connection options explicitly\nenables it.

Disable support for loading a synchronous ES module graph in require().

See Loading ECMAScript modules using require().

Disable type-stripping for TypeScript files.\nFor more information, see the TypeScript type-stripping documentation.

Silence all process warnings (including deprecations).

Enable extra debug checks for memory leaks in Node.js internals. This is\nusually only useful for developers debugging Node.js itself.

Load an OpenSSL configuration file on startup. Among other uses, this can be\nused to enable FIPS-compliant crypto if Node.js is built\nagainst FIPS-enabled OpenSSL.

Enable OpenSSL 3.0 legacy provider. For more information please see\nOSSL_PROVIDER-legacy.

Enable OpenSSL default configuration section, openssl_conf to be read from\nthe OpenSSL configuration file. The default configuration file is named\nopenssl.cnf but this can be changed using the environment variable\nOPENSSL_CONF, or by using the command line option --openssl-config.\nThe location of the default OpenSSL configuration file depends on how OpenSSL\nis being linked to Node.js. Sharing the OpenSSL configuration may have unwanted\nimplications and it is recommended to use a configuration section specific to\nNode.js which is nodejs_conf and is default when this option is not used.

Emit pending deprecation warnings.

Pending deprecations are generally identical to a runtime deprecation with the\nnotable exception that they are turned off by default and will not be emitted\nunless either the --pending-deprecation command-line flag, or the\nNODE_PENDING_DEPRECATION=1 environment variable, is set. Pending deprecations\nare used to provide a kind of selective \"early warning\" mechanism that\ndevelopers may leverage to detect deprecated API usage.

Enable the Permission Model for current process. When enabled, the\nfollowing permissions are restricted:

\n
• File System - manageable through\n--allow-fs-read, --allow-fs-write flags
\n
• Network - manageable through --allow-net flag
\n
• Child Process - manageable through --allow-child-process flag
\n
• Worker Threads - manageable through --allow-worker flag
\n
• WASI - manageable through --allow-wasi flag
\n
• Addons - manageable through --allow-addons flag
\n

Enable audit only for the permission model. When enabled, permission checks\nare performed but access is not denied. Instead, a warning is emitted for\neach permission violation via diagnostics channel.

Instructs the module loader to preserve symbolic links when resolving and\ncaching modules.

By default, when Node.js loads a module from a path that is symbolically linked\nto a different on-disk location, Node.js will dereference the link and use the\nactual on-disk \"real path\" of the module as both an identifier and as a root\npath to locate other dependency modules. In most cases, this default behavior\nis acceptable. However, when using symbolically linked peer dependencies, as\nillustrated in the example below, the default behavior causes an exception to\nbe thrown if moduleA attempts to require moduleB as a peer dependency:

{appDir}\n ├── app\n │   ├── index.js\n │   └── node_modules\n │       ├── moduleA -> {appDir}/moduleA\n │       └── moduleB\n │           ├── index.js\n │           └── package.json\n └── moduleA\n     ├── index.js\n     └── package.json\n

The --preserve-symlinks command-line flag instructs Node.js to use the\nsymlink path for modules as opposed to the real path, allowing symbolically\nlinked peer dependencies to be found.

Note, however, that using --preserve-symlinks can have other side effects.\nSpecifically, symbolically linked native modules can fail to load if those\nare linked from more than one location in the dependency tree (Node.js would\nsee those as two separate modules and would attempt to load the module multiple\ntimes, causing an exception to be thrown).

The --preserve-symlinks flag does not apply to the main module, which allows\nnode --preserve-symlinks node_module/.bin/<foo> to work. To apply the same\nbehavior for the main module, also use --preserve-symlinks-main.

Instructs the module loader to preserve symbolic links when resolving and\ncaching the main module (require.main).

This flag exists so that the main module can be opted-in to the same behavior\nthat --preserve-symlinks gives to all other imports; they are separate flags,\nhowever, for backward compatibility with older Node.js versions.

--preserve-symlinks-main does not imply --preserve-symlinks; use\n--preserve-symlinks-main in addition to\n--preserve-symlinks when it is not desirable to follow symlinks before\nresolving relative paths.

See --preserve-symlinks for more information.

Identical to -e but prints the result.

Generate V8 profiler output.

Process V8 profiler output generated using the V8 option --prof.

Write process warnings to the given file instead of printing to stderr. The\nfile will be created if it does not exist, and will be appended to if it does.\nIf an error occurs while attempting to write the warning to the file, the\nwarning will be written to stderr instead.

The file name may be an absolute path. If it is not, the default directory it\nwill be written to is controlled by the\n--diagnostic-dir command-line option.

Write reports in a compact format, single-line JSON, more easily consumable\nby log processing systems than the default multi-line format designed for\nhuman consumption.

Location at which the report will be generated.

When --report-exclude-env is passed the diagnostic report generated will not\ncontain the environmentVariables data.

Exclude header.networkInterfaces from the diagnostic report. By default\nthis is not set and the network interfaces are included.

Name of the file to which the report will be written.

If the filename is set to 'stdout' or 'stderr', the report is written to\nthe stdout or stderr of the process respectively.

Enables the report to be triggered on fatal errors (internal errors within\nthe Node.js runtime such as out of memory) that lead to termination of the\napplication. Useful to inspect various diagnostic data elements such as heap,\nstack, event loop state, resource consumption etc. to reason about the fatal\nerror.

Enables report to be generated upon receiving the specified (or predefined)\nsignal to the running Node.js process. The signal to trigger the report is\nspecified through --report-signal.

Sets or resets the signal for report generation (not supported on Windows).\nDefault signal is SIGUSR2.

Enables report to be generated when the process exits due to an uncaught\nexception. Useful when inspecting the JavaScript stack in conjunction with\nnative stack and other runtime environment data.

Preload the specified module at startup.

Follows require()'s module resolution\nrules. module may be either a path to a file, or a node module name.

Modules preloaded with --require will run before modules preloaded with --import.

Modules are preloaded into the main thread as well as any worker threads,\nforked processes, or clustered processes.

This runs a specified command from a package.json's \"scripts\" object.\nIf a missing \"command\" is provided, it will list the available scripts.

--run will traverse up to the root directory and finds a package.json\nfile to run the command from.

--run prepends ./node_modules/.bin for each ancestor of\nthe current directory, to the PATH in order to execute the binaries from\ndifferent folders where multiple node_modules directories are present, if\nancestor-folder/node_modules/.bin is a directory.

--run executes the command in the directory containing the related package.json.

For example, the following command will run the test script of\nthe package.json in the current folder:

$ node --run test\n

You can also pass arguments to the command. Any argument after -- will\nbe appended to the script:

$ node --run test -- --verbose\n

node --run is not meant to match the behaviors of npm run or of the run\ncommands of other package managers. The Node.js implementation is intentionally\nmore limited, in order to focus on top performance for the most common use\ncases.\nSome features of other run implementations that are intentionally excluded\nare:

\n
• Running pre or post scripts in addition to the specified script.
\n
• Defining package manager-specific environment variables.
\n

The following environment variables are set when running a script with --run:

\n
• NODE_RUN_SCRIPT_NAME: The name of the script being run. For example, if\n--run is used to run test, the value of this variable will be test.
\n
• NODE_RUN_PACKAGE_JSON_PATH: The path to the package.json that is being\nprocessed.
\n

When using --secure-heap, the --secure-heap-min flag specifies the\nminimum allocation from the secure heap. The minimum value is 2.\nThe maximum value is the lesser of --secure-heap or 2147483647.\nThe value given must be a power of two.

Initializes an OpenSSL secure heap of n bytes. When initialized, the\nsecure heap is used for selected types of allocations within OpenSSL\nduring key generation and other operations. This is useful, for instance,\nto prevent sensitive information from leaking due to pointer overruns\nor underruns.

The secure heap is a fixed size and cannot be resized at runtime so,\nif used, it is important to select a large enough heap to cover all\napplication uses.

The heap size given must be a power of two. Any value less than 2\nwill disable the secure heap.

The secure heap is disabled by default.

The secure heap is not available on Windows.

See CRYPTO_secure_malloc_init for more details.

When used with --build-snapshot, --snapshot-blob specifies the path\nwhere the generated snapshot blob is written to. If not specified, the\ngenerated blob is written to snapshot.blob in the current working directory.

When used without --build-snapshot, --snapshot-blob specifies the\npath to the blob that is used to restore the application state.

When loading a snapshot, Node.js checks that:

\n
1. The version, architecture, and platform of the running Node.js binary\nare exactly the same as that of the binary that generates the snapshot.
\n
2. The V8 flags and CPU features are compatible with that of the binary\nthat generates the snapshot.
\n

If they don't match, Node.js refuses to load the snapshot and exits with\nstatus code 1.

Starts the Node.js command line test runner. This flag cannot be combined with\n--watch-path, --check, --eval, --interactive, or the inspector.\nSee the documentation on running tests from the command line\nfor more details.

The maximum number of test files that the test runner CLI will execute\nconcurrently. If --test-isolation is set to 'none', this flag is ignored and\nconcurrency is one. Otherwise, concurrency defaults to\nos.availableParallelism() - 1.

Require a minimum percent of covered branches. If code coverage does not reach\nthe threshold specified, the process will exit with code 1.

Excludes specific files from code coverage using a glob pattern, which can match\nboth absolute and relative file paths.

This option may be specified multiple times to exclude multiple glob patterns.

If both --test-coverage-exclude and --test-coverage-include are provided,\nfiles must meet both criteria to be included in the coverage report.

By default all the matching test files are excluded from the coverage report.\nSpecifying this option will override the default behavior.

Require a minimum percent of covered functions. If code coverage does not reach\nthe threshold specified, the process will exit with code 1.

Includes specific files in code coverage using a glob pattern, which can match\nboth absolute and relative file paths.

This option may be specified multiple times to include multiple glob patterns.

If both --test-coverage-exclude and --test-coverage-include are provided,\nfiles must meet both criteria to be included in the coverage report.

Require a minimum percent of covered lines. If code coverage does not reach\nthe threshold specified, the process will exit with code 1.

Configures the test runner to exit the process once all known tests have\nfinished executing even if the event loop would otherwise remain active.

Specify a module that will be evaluated before all tests are executed and\ncan be used to setup global state or fixtures for tests.

See the documentation on global setup and teardown for more details.

Configures the type of test isolation used in the test runner. When mode is\n'process', each test file is run in a separate child process. When mode is\n'none', all test files run in the same process as the test runner. The default\nisolation mode is 'process'. This flag is ignored if the --test flag is not\npresent. See the test runner execution model section for more information.

A regular expression that configures the test runner to only execute tests\nwhose name matches the provided pattern. See the documentation on\nfiltering tests by name for more details.

If both --test-name-pattern and --test-skip-pattern are supplied,\ntests must satisfy both requirements in order to be executed.

Configures the test runner to only execute top level tests that have the only\noption set. This flag is not necessary when test isolation is disabled.

A test reporter to use when running tests. See the documentation on\ntest reporters for more details.

The destination for the corresponding test reporter. See the documentation on\ntest reporters for more details.

A path to a file allowing the test runner to persist the state of the test\nsuite between runs. The test runner will use this file to determine which tests\nhave already succeeded or failed, allowing for re-running of failed tests\nwithout having to re-run the entire test suite. The test runner will create this\nfile if it does not exist.\nSee the documentation on test reruns for more details.

Test suite shard to execute in a format of <index>/<total>, where

\n
• index is a positive integer, index of divided parts.
\n
• total is a positive integer, total of divided part.
\n

This command will divide all tests files into total equal parts,\nand will run only those that happen to be in an index part.

For example, to split your tests suite into three parts, use this:

node --test --test-shard=1/3\nnode --test --test-shard=2/3\nnode --test --test-shard=3/3\n

A regular expression that configures the test runner to skip tests\nwhose name matches the provided pattern. See the documentation on\nfiltering tests by name for more details.

If both --test-name-pattern and --test-skip-pattern are supplied,\ntests must satisfy both requirements in order to be executed.

A number of milliseconds the test execution will fail after. If unspecified,\nsubtests inherit this value from their parent. The default value is Infinity.

Regenerates the snapshot files used by the test runner for snapshot testing.

Throw errors for deprecations.

Set process.title on startup.

Specify an alternative default TLS cipher list. Requires Node.js to be built\nwith crypto support (default).

Log TLS key material to a file. The key material is in NSS SSLKEYLOGFILE\nformat and can be used by software (such as Wireshark) to decrypt the TLS\ntraffic.

Set tls.DEFAULT_MAX_VERSION to 'TLSv1.2'. Use to disable support for\nTLSv1.3.

Set default tls.DEFAULT_MAX_VERSION to 'TLSv1.3'. Use to enable support\nfor TLSv1.3.

Set default tls.DEFAULT_MIN_VERSION to 'TLSv1'. Use for compatibility with\nold TLS clients or servers.

Set default tls.DEFAULT_MIN_VERSION to 'TLSv1.1'. Use for compatibility\nwith old TLS clients or servers.

Set default tls.DEFAULT_MIN_VERSION to 'TLSv1.2'. This is the default for\n12.x and later, but the option is supported for compatibility with older Node.js\nversions.

Set default tls.DEFAULT_MIN_VERSION to 'TLSv1.3'. Use to disable support\nfor TLSv1.2, which is not as secure as TLSv1.3.

Print stack traces for deprecations.

Print information about any access to environment variables done in the current Node.js\ninstance to stderr, including:

\n
• The environment variable reads that Node.js does internally.
\n
• Writes in the form of process.env.KEY = \"SOME VALUE\".
\n
• Reads in the form of process.env.KEY.
\n
• Definitions in the form of Object.defineProperty(process.env, 'KEY', {...}).
\n
• Queries in the form of Object.hasOwn(process.env, 'KEY'),\nprocess.env.hasOwnProperty('KEY') or 'KEY' in process.env.
\n
• Deletions in the form of delete process.env.KEY.
\n
• Enumerations inf the form of ...process.env or Object.keys(process.env).
\n

Only the names of the environment variables being accessed are printed. The values are not printed.

To print the stack trace of the access, use --trace-env-js-stack and/or\n--trace-env-native-stack.

In addition to what --trace-env does, this prints the JavaScript stack trace of the access.

In addition to what --trace-env does, this prints the native stack trace of the access.

A comma separated list of categories that should be traced when trace event\ntracing is enabled using --trace-events-enabled.

Template string specifying the filepath for the trace event data, it\nsupports ${rotation} and ${pid}.

Enables the collection of trace event tracing information.

Prints a stack trace whenever an environment is exited proactively,\ni.e. invoking process.exit().

Prints information about usage of Loading ECMAScript modules using require().

When mode is all, all usage is printed. When mode is no-node-modules, usage\nfrom the node_modules folder is excluded.

Prints a stack trace on SIGINT.

Prints a stack trace whenever synchronous I/O is detected after the first turn\nof the event loop.

Prints TLS packet trace information to stderr. This can be used to debug TLS\nconnection problems.

Print stack traces for uncaught exceptions; usually, the stack trace associated\nwith the creation of an Error is printed, whereas this makes Node.js also\nprint the stack trace associated with throwing the value (which does not need\nto be an Error instance).

Enabling this option may affect garbage collection behavior negatively.

Print stack traces for process warnings (including deprecations).

Track heap object allocations for heap snapshots.

Using this flag allows to change what should happen when an unhandled rejection\noccurs. One of the following modes can be chosen:

\n
• throw: Emit unhandledRejection. If this hook is not set, raise the\nunhandled rejection as an uncaught exception. This is the default.
\n
• strict: Raise the unhandled rejection as an uncaught exception. If the\nexception is handled, unhandledRejection is emitted.
\n
• warn: Always trigger a warning, no matter if the unhandledRejection\nhook is set or not but do not print the deprecation warning.
\n
• warn-with-error-code: Emit unhandledRejection. If this hook is not\nset, trigger a warning, and set the process exit code to 1.
\n
• none: Silence all warnings.
\n

If a rejection happens during the command line entry point's ES module static\nloading phase, it will always raise it as an uncaught exception.

Use bundled Mozilla CA store as supplied by current Node.js version\nor use OpenSSL's default CA store. The default store is selectable\nat build-time.

The bundled CA store, as supplied by Node.js, is a snapshot of Mozilla CA store\nthat is fixed at release time. It is identical on all supported platforms.

Using OpenSSL store allows for external modifications of the store. For most\nLinux and BSD distributions, this store is maintained by the distribution\nmaintainers and system administrators. OpenSSL CA store location is dependent on\nconfiguration of the OpenSSL library but this can be altered at runtime using\nenvironment variables.

See SSL_CERT_DIR and SSL_CERT_FILE.

When enabled, Node.js parses the HTTP_PROXY, HTTPS_PROXY and NO_PROXY\nenvironment variables during startup, and tunnels requests over the\nspecified proxy.

This is equivalent to setting the NODE_USE_ENV_PROXY=1 environment variable.\nWhen both are set, --use-env-proxy takes precedence.

Re-map the Node.js static code to large memory pages at startup. If supported on\nthe target system, this will cause the Node.js static code to be moved onto 2\nMiB pages instead of 4 KiB pages.

The following values are valid for mode:

\n
• off: No mapping will be attempted. This is the default.
\n
• on: If supported by the OS, mapping will be attempted. Failure to map will\nbe ignored and a message will be printed to standard error.
\n
• silent: If supported by the OS, mapping will be attempted. Failure to map\nwill be ignored and will not be reported.
\n

Node.js uses the trusted CA certificates present in the system store along with\nthe --use-bundled-ca option and the NODE_EXTRA_CA_CERTS environment variable.\nOn platforms other than Windows and macOS, this loads certificates from the directory\nand file trusted by OpenSSL, similar to --use-openssl-ca, with the difference being\nthat it caches the certificates after first load.

On Windows and macOS, the certificate trust policy is similar to\nChromium's policy for locally trusted certificates, but with some differences:

On macOS, the following settings are respected:

\n
• Default and System Keychains\n
  \n
  • Trust:\n
    \n
    • Any certificate where the “When using this certificate” flag is set to “Always Trust” or
    \n
    • Any certificate where the “Secure Sockets Layer (SSL)” flag is set to “Always Trust”.
    \n
    \n
  \n
  • The certificate must also be valid, with \"X.509 Basic Policy\" set to “Always Trust”.
  \n
  \n
\n

On Windows, the following settings are respected:

\n
• Local Machine (accessed via certlm.msc)\n
  \n
  • Trust:\n
    \n
    • Trusted Root Certification Authorities
    \n
    • Trusted People
    \n
    • Enterprise Trust -> Enterprise -> Trusted Root Certification Authorities
    \n
    • Enterprise Trust -> Enterprise -> Trusted People
    \n
    • Enterprise Trust -> Group Policy -> Trusted Root Certification Authorities
    \n
    • Enterprise Trust -> Group Policy -> Trusted People
    \n
    \n
  \n
  \n
\n
• Current User (accessed via certmgr.msc)\n
  \n
  • Trust:\n
    \n
    • Trusted Root Certification Authorities
    \n
    • Enterprise Trust -> Group Policy -> Trusted Root Certification Authorities
    \n
    \n
  \n
  \n
\n

On Windows and macOS, Node.js would check that the user settings for the trusted\ncertificates do not forbid them for TLS server authentication before using them.

Node.js currently does not support distrust/revocation of certificates\nfrom another source based on system settings.

On other systems, Node.js loads certificates from the default certificate file\n(typically /etc/ssl/cert.pem) and default certificate directory (typically\n/etc/ssl/certs) that the version of OpenSSL that Node.js links to respects.\nThis typically works with the convention on major Linux distributions and other\nUnix-like systems. If the overriding OpenSSL environment variables\n(typically SSL_CERT_FILE and SSL_CERT_DIR, depending on the configuration\nof the OpenSSL that Node.js links to) are set, the specified paths will be used to load\ncertificates instead. These environment variables can be used as workarounds\nif the conventional paths used by the version of OpenSSL Node.js links to are\nnot consistent with the system configuration that the users have for some reason.

Print V8 command-line options.

Set V8's thread pool size which will be used to allocate background jobs.

If set to 0 then Node.js will choose an appropriate size of the thread pool\nbased on an estimate of the amount of parallelism.

The amount of parallelism refers to the number of computations that can be\ncarried out simultaneously in a given machine. In general, it's the same as the\namount of CPUs, but it may diverge in environments such as VMs or containers.

Print node's version.

Starts Node.js in watch mode.\nWhen in watch mode, changes in the watched files cause the Node.js process to\nrestart.\nBy default, watch mode will watch the entry point\nand any required or imported module.\nUse --watch-path to specify what paths to watch.

This flag cannot be combined with\n--check, --eval, --interactive, or the REPL.

Note: The --watch flag requires a file path as an argument and is incompatible\nwith --run or inline script input, as --run takes precedence and ignores watch\nmode. If no file is provided, Node.js will exit with status code 9.

node --watch index.js\n

Customizes the signal sent to the process on watch mode restarts.

node --watch --watch-kill-signal SIGINT test.js\n

Starts Node.js in watch mode and specifies what paths to watch.\nWhen in watch mode, changes in the watched paths cause the Node.js process to\nrestart.\nThis will turn off watching of required or imported modules, even when used in\ncombination with --watch.

This flag cannot be combined with\n--check, --eval, --interactive, --test, or the REPL.

Note: Using --watch-path implicitly enables --watch, which requires a file path\nand is incompatible with --run, as --run takes precedence and ignores watch mode.

node --watch-path=./src --watch-path=./tests index.js\n

This option is only supported on macOS and Windows.\nAn ERR_FEATURE_UNAVAILABLE_ON_PLATFORM exception will be thrown\nwhen the option is used on a platform that does not support it.

Disable the clearing of the console when watch mode restarts the process.

node --watch --watch-preserve-output test.js\n

Automatically zero-fills all newly allocated Buffer instances.

The FORCE_COLOR environment variable is used to\nenable ANSI colorized output. The value may be:

\n
• 1, true, or the empty string '' indicate 16-color support,
\n
• 2 to indicate 256-color support, or
\n
• 3 to indicate 16 million-color support.
\n

When FORCE_COLOR is used and set to a supported value, both the NO_COLOR,\nand NODE_DISABLE_COLORS environment variables are ignored.

Any other value will result in colorized output being disabled.

Enable the module compile cache for the Node.js instance. See the documentation of\nmodule compile cache for details.

When set to 1, the module compile cache can be reused across different directory\nlocations as long as the module layout relative to the cache directory remains the same.

','-separated list of core modules that should print debug information.

','-separated list of core C++ modules that should print debug information.

When set, colors will not be used in the REPL.

Disable the module compile cache for the Node.js instance. See the documentation of\nmodule compile cache for details.

When set, the well known \"root\" CAs (like VeriSign) will be extended with the\nextra certificates in file. The file should consist of one or more trusted\ncertificates in PEM format. A message will be emitted (once) with\nprocess.emitWarning() if the file is missing or\nmalformed, but any errors are otherwise ignored.

Neither the well known nor extra certificates are used when the ca\noptions property is explicitly specified for a TLS or HTTPS client or server.

This environment variable is ignored when node runs as setuid root or\nhas Linux file capabilities set.

The NODE_EXTRA_CA_CERTS environment variable is only read when the Node.js\nprocess is first launched. Changing the value at runtime using\nprocess.env.NODE_EXTRA_CA_CERTS has no effect on the current process.

Data path for ICU (Intl object) data. Will extend linked-in data when compiled\nwith small-icu support.

When set to 1, process warnings are silenced.

A space-separated list of command-line options. options... are interpreted\nbefore command-line options, so command-line options will override or\ncompound after anything in options.... Node.js will exit with an error if\nan option that is not allowed in the environment is used, such as -p or a\nscript file.

If an option value contains a space, it can be escaped using double quotes:

NODE_OPTIONS='--require \"./my path/file.js\"'\n

A singleton flag passed as a command-line option will override the same flag\npassed into NODE_OPTIONS:

# The inspector will be available on port 5555\nNODE_OPTIONS='--inspect=localhost:4444' node --inspect=localhost:5555\n

A flag that can be passed multiple times will be treated as if its\nNODE_OPTIONS instances were passed first, and then its command-line\ninstances afterwards:

NODE_OPTIONS='--require \"./a.js\"' node --require \"./b.js\"\n# is equivalent to:\nnode --require \"./a.js\" --require \"./b.js\"\n

Node.js options that are allowed are in the following list. If an option\nsupports both --XX and --no-XX variants, they are both supported but only\none is included in the list below.

\n
• --allow-addons
\n
• --allow-child-process
\n
• --allow-fs-read
\n
• --allow-fs-write
\n
• --allow-inspector
\n
• --allow-net
\n
• --allow-wasi
\n
• --allow-worker
\n
• --conditions, -C
\n
• --cpu-prof-dir
\n
• --cpu-prof-interval
\n
• --cpu-prof-name
\n
• --cpu-prof
\n
• --diagnostic-dir
\n
• --disable-proto
\n
• --disable-sigusr1
\n
• --disable-warning
\n
• --disable-wasm-trap-handler
\n
• --dns-result-order
\n
• --enable-fips
\n
• --enable-network-family-autoselection
\n
• --enable-source-maps
\n
• --entry-url
\n
• --experimental-abortcontroller
\n
• --experimental-addon-modules
\n
• --experimental-detect-module
\n
• --experimental-eventsource
\n
• --experimental-import-meta-resolve
\n
• --experimental-json-modules
\n
• --experimental-loader
\n
• --experimental-modules
\n
• --experimental-print-required-tla
\n
• --experimental-quic
\n
• --experimental-require-module
\n
• --experimental-shadow-realm
\n
• --experimental-specifier-resolution
\n
• --experimental-test-isolation
\n
• --experimental-top-level-await
\n
• --experimental-transform-types
\n
• --experimental-vm-modules
\n
• --experimental-wasi-unstable-preview1
\n
• --force-context-aware
\n
• --force-fips
\n
• --force-node-api-uncaught-exceptions-policy
\n
• --frozen-intrinsics
\n
• --heap-prof-dir
\n
• --heap-prof-interval
\n
• --heap-prof-name
\n
• --heap-prof
\n
• --heapsnapshot-near-heap-limit
\n
• --heapsnapshot-signal
\n
• --http-parser
\n
• --icu-data-dir
\n
• --import
\n
• --input-type
\n
• --insecure-http-parser
\n
• --inspect-brk
\n
• --inspect-port, --debug-port
\n
• --inspect-publish-uid
\n
• --inspect-wait
\n
• --inspect
\n
• --localstorage-file
\n
• --max-http-header-size
\n
• --max-old-space-size-percentage
\n
• --napi-modules
\n
• --network-family-autoselection-attempt-timeout
\n
• --no-addons
\n
• --no-async-context-frame
\n
• --no-deprecation
\n
• --no-experimental-global-navigator
\n
• --no-experimental-repl-await
\n
• --no-experimental-sqlite
\n
• --no-experimental-strip-types
\n
• --no-experimental-websocket
\n
• --no-experimental-webstorage
\n
• --no-extra-info-on-fatal-exception
\n
• --no-force-async-hooks-checks
\n
• --no-global-search-paths
\n
• --no-network-family-autoselection
\n
• --no-strip-types
\n
• --no-warnings
\n
• --no-webstorage
\n
• --node-memory-debug
\n
• --openssl-config
\n
• --openssl-legacy-provider
\n
• --openssl-shared-config
\n
• --pending-deprecation
\n
• --permission-audit
\n
• --permission
\n
• --preserve-symlinks-main
\n
• --preserve-symlinks
\n
• --prof-process
\n
• --redirect-warnings
\n
• --report-compact
\n
• --report-dir, --report-directory
\n
• --report-exclude-env
\n
• --report-exclude-network
\n
• --report-filename
\n
• --report-on-fatalerror
\n
• --report-on-signal
\n
• --report-signal
\n
• --report-uncaught-exception
\n
• --require-module
\n
• --require, -r
\n
• --secure-heap-min
\n
• --secure-heap
\n
• --snapshot-blob
\n
• --test-coverage-branches
\n
• --test-coverage-exclude
\n
• --test-coverage-functions
\n
• --test-coverage-include
\n
• --test-coverage-lines
\n
• --test-global-setup
\n
• --test-isolation
\n
• --test-name-pattern
\n
• --test-only
\n
• --test-reporter-destination
\n
• --test-reporter
\n
• --test-rerun-failures
\n
• --test-shard
\n
• --test-skip-pattern
\n
• --throw-deprecation
\n
• --title
\n
• --tls-cipher-list
\n
• --tls-keylog
\n
• --tls-max-v1.2
\n
• --tls-max-v1.3
\n
• --tls-min-v1.0
\n
• --tls-min-v1.1
\n
• --tls-min-v1.2
\n
• --tls-min-v1.3
\n
• --trace-deprecation
\n
• --trace-env-js-stack
\n
• --trace-env-native-stack
\n
• --trace-env
\n
• --trace-event-categories
\n
• --trace-event-file-pattern
\n
• --trace-events-enabled
\n
• --trace-exit
\n
• --trace-require-module
\n
• --trace-sigint
\n
• --trace-sync-io
\n
• --trace-tls
\n
• --trace-uncaught
\n
• --trace-warnings
\n
• --track-heap-objects
\n
• --unhandled-rejections
\n
• --use-bundled-ca
\n
• --use-env-proxy
\n
• --use-largepages
\n
• --use-openssl-ca
\n
• --use-system-ca
\n
• --v8-pool-size
\n
• --watch-kill-signal
\n
• --watch-path
\n
• --watch-preserve-output
\n
• --watch
\n
• --zero-fill-buffers
\n

V8 options that are allowed are:

\n
• --abort-on-uncaught-exception
\n
• --disallow-code-generation-from-strings
\n
• --enable-etw-stack-walking
\n
• --expose-gc
\n
• --interpreted-frames-native-stack
\n
• --jitless
\n
• --max-old-space-size
\n
• --max-semi-space-size
\n
• --perf-basic-prof-only-functions
\n
• --perf-basic-prof
\n
• --perf-prof-unwinding-info
\n
• --perf-prof
\n
• --stack-trace-limit
\n

--perf-basic-prof-only-functions, --perf-basic-prof,\n--perf-prof-unwinding-info, and --perf-prof are only available on Linux.

--enable-etw-stack-walking is only available on Windows.

':'-separated list of directories prefixed to the module search path.

On Windows, this is a ';'-separated list instead.

When set to 1, emit pending deprecation warnings.

Pending deprecations are generally identical to a runtime deprecation with the\nnotable exception that they are turned off by default and will not be emitted\nunless either the --pending-deprecation command-line flag, or the\nNODE_PENDING_DEPRECATION=1 environment variable, is set. Pending deprecations\nare used to provide a kind of selective \"early warning\" mechanism that\ndevelopers may leverage to detect deprecated API usage.

Set the number of pending pipe instance handles when the pipe server is waiting\nfor connections. This setting applies to Windows only.

When set to 1, instructs the module loader to preserve symbolic links when\nresolving and caching modules.

When set, process warnings will be emitted to the given file instead of\nprinting to stderr. The file will be created if it does not exist, and will be\nappended to if it does. If an error occurs while attempting to write the\nwarning to the file, the warning will be written to stderr instead. This is\nequivalent to using the --redirect-warnings=file command-line flag.

Path to a Node.js module which will be loaded in place of the built-in REPL.\nOverriding this value to an empty string ('') will use the built-in REPL.

Path to the file used to store the persistent REPL history. The default path is\n~/.node_repl_history, which is overridden by this variable. Setting the value\nto an empty string ('' or ' ') disables persistent REPL history.

If value equals '1', the check for a supported platform is skipped during\nNode.js startup. Node.js might not execute correctly. Any issues encountered\non unsupported platforms will not be fixed.

If value equals 'child', test reporter options will be overridden and test\noutput will be sent to stdout in the TAP format. If any other value is provided,\nNode.js makes no guarantees about the reporter format used or its stability.

If value equals '0', certificate validation is disabled for TLS connections.\nThis makes TLS, and HTTPS by extension, insecure. The use of this environment\nvariable is strongly discouraged.

When enabled, Node.js parses the HTTP_PROXY, HTTPS_PROXY and NO_PROXY\nenvironment variables during startup, and tunnels requests over the\nspecified proxy.

This can also be enabled using the --use-env-proxy command-line flag.\nWhen both are set, --use-env-proxy takes precedence.

Node.js uses the trusted CA certificates present in the system store along with\nthe --use-bundled-ca option and the NODE_EXTRA_CA_CERTS environment variable.

This can also be enabled using the --use-system-ca command-line flag.\nWhen both are set, --use-system-ca takes precedence.

When set, Node.js will begin outputting V8 JavaScript code coverage and\nSource Map data to the directory provided as an argument (coverage\ninformation is written as JSON to files with a coverage prefix).

NODE_V8_COVERAGE will automatically propagate to subprocesses, making it\neasier to instrument applications that call the child_process.spawn() family\nof functions. NODE_V8_COVERAGE can be set to an empty string, to prevent\npropagation.

Coverage is output as an array of ScriptCoverage objects on the top-level\nkey result:

{\n  \"result\": [\n    {\n      \"scriptId\": \"67\",\n      \"url\": \"internal/tty.js\",\n      \"functions\": []\n    }\n  ]\n}\n

If found, source map data is appended to the top-level key source-map-cache\non the JSON coverage object.

source-map-cache is an object with keys representing the files source maps\nwere extracted from, and values which include the raw source-map URL\n(in the key url), the parsed Source Map v3 information (in the key data),\nand the line lengths of the source file (in the key lineLengths).

{\n  \"result\": [\n    {\n      \"scriptId\": \"68\",\n      \"url\": \"file:///absolute/path/to/source.js\",\n      \"functions\": []\n    }\n  ],\n  \"source-map-cache\": {\n    \"file:///absolute/path/to/source.js\": {\n      \"url\": \"./path-to-map.json\",\n      \"data\": {\n        \"version\": 3,\n        \"sources\": [\n          \"file:///absolute/path/to/original.js\"\n        ],\n        \"names\": [\n          \"Foo\",\n          \"console\",\n          \"info\"\n        ],\n        \"mappings\": \"MAAMA,IACJC,YAAaC\",\n        \"sourceRoot\": \"./\"\n      },\n      \"lineLengths\": [\n        13,\n        62,\n        38,\n        27\n      ]\n    }\n  }\n}\n

$ TZ=Europe/Dublin node -pe \"new Date().toString()\"\nWed May 12 2021 20:30:48 GMT+0100 (Irish Standard Time)\n

node --max-old-space-size=1536 index.js\n

for MiB in 16 32 64 128; do\n    node --max-semi-space-size=$MiB index.js\ndone\n

node --stack-trace-limit=12 -p -e \"Error.stackTraceLimit\" # prints 12\n

$ node inspect myscript.js\n< Debugger listening on ws://127.0.0.1:9229/621111f9-ffcb-4e82-b718-48a145fa5db8\n< For help, see: https://nodejs.org/en/docs/inspector\n<\nconnecting to 127.0.0.1:9229 ... ok\n< Debugger attached.\n<\n ok\nBreak on start in myscript.js:2\n  1 // myscript.js\n> 2 global.x = 5;\n  3 setTimeout(() => {\n  4   debugger;\ndebug>\n

$ cat myscript.js\n// myscript.js\nglobal.x = 5;\nsetTimeout(() => {\n  debugger;\n  console.log('world');\n}, 1000);\nconsole.log('hello');\n$ NODE_INSPECT_RESUME_ON_START=1 node inspect myscript.js\n< Debugger listening on ws://127.0.0.1:9229/f1ed133e-7876-495b-83ae-c32c6fc319c2\n< For help, see: https://nodejs.org/en/docs/inspector\n<\nconnecting to 127.0.0.1:9229 ... ok\n< Debugger attached.\n<\n< hello\n<\nbreak in myscript.js:4\n  2 global.x = 5;\n  3 setTimeout(() => {\n> 4   debugger;\n  5   console.log('world');\n  6 }, 1000);\ndebug> next\nbreak in myscript.js:5\n  3 setTimeout(() => {\n  4   debugger;\n> 5   console.log('world');\n  6 }, 1000);\n  7 console.log('hello');\ndebug> repl\nPress Ctrl+C to leave debug repl\n> x\n5\n> 2 + 2\n4\ndebug> next\n< world\n<\nbreak in myscript.js:6\n  4   debugger;\n  5   console.log('world');\n> 6 }, 1000);\n  7 console.log('hello');\n  8\ndebug> .exit\n$\n

$ node inspect main.js\n< Debugger listening on ws://127.0.0.1:9229/48a5b28a-550c-471b-b5e1-d13dd7165df9\n< For help, see: https://nodejs.org/en/docs/inspector\n<\nconnecting to 127.0.0.1:9229 ... ok\n< Debugger attached.\n<\nBreak on start in main.js:1\n> 1 const mod = require('./mod.js');\n  2 mod.hello();\n  3 mod.hello();\ndebug> setBreakpoint('mod.js', 22)\nWarning: script 'mod.js' was not loaded yet.\ndebug> c\nbreak in mod.js:22\n 20 // USE OR OTHER DEALINGS IN THE SOFTWARE.\n 21\n>22 exports.hello = function() {\n 23   return 'hello from module';\n 24 };\ndebug>\n

$ node inspect main.js\n< Debugger listening on ws://127.0.0.1:9229/ce24daa8-3816-44d4-b8ab-8273c8a66d35\n< For help, see: https://nodejs.org/en/docs/inspector\n<\nconnecting to 127.0.0.1:9229 ... ok\n< Debugger attached.\nBreak on start in main.js:7\n  5 }\n  6\n> 7 addOne(10);\n  8 addOne(-1);\n  9\ndebug> setBreakpoint('main.js', 4, 'num < 0')\n  1 'use strict';\n  2\n  3 function addOne(num) {\n> 4   return num + 1;\n  5 }\n  6\n  7 addOne(10);\n  8 addOne(-1);\n  9\ndebug> cont\nbreak in main.js:4\n  2\n  3 function addOne(num) {\n> 4   return num + 1;\n  5 }\n  6\ndebug> exec('num')\n-1\ndebug>\n

$ node --inspect index.js\nDebugger listening on ws://127.0.0.1:9229/dc9010dd-f8b8-4ac5-a510-c1a114ec7d29\nFor help, see: https://nodejs.org/en/docs/inspector\n

npx codemod@latest @nodejs/tmpDir-to-tmpdir\n

npx codemod@latest @nodejs/util-print-to-console-log\n

npx codemod@latest @nodejs/util-print-to-console-log\n

npx codemod@latest @nodejs/util-print-to-console-log\n

npx codemod@latest @nodejs/util-print-to-console-log\n

npx codemod@latest @nodejs/slow-buffer-to-buffer-alloc-unsafe-slow\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-is\n

npx codemod@latest @nodejs/util-log-to-console-log\n

npx codemod@latest @nodejs/util-extend-to-object-assign\n

npx codemod@latest @nodejs/http-outgoingmessage-headers\n

npx codemod@latest @nodejs/fs-truncate-fd-deprecation\n

npx codemod@latest @nodejs/crypto-fips-to-getFips\n

npx codemod@latest @nodejs/process-assert-to-node-assert\n

npx codemod@latest @nodejs/zlib-bytesread-to-byteswritten\n

npx codemod@latest @nodejs/node-url-to-whatwg-url\n

npx codemod@latest @nodejs/create-require-from-path\n

const fsPromises = require('node:fs').promises;\nasync function openAndClose() {\n  let filehandle;\n  try {\n    filehandle = await fsPromises.open('thefile.txt', 'r');\n  } finally {\n    if (filehandle !== undefined)\n      await filehandle.close();\n  }\n}\n

npx codemod@latest @nodejs/process-main-module\n

npx codemod@latest @nodejs/repl-builtin-modules\n

if (require.main === module) {\n  // Code section that will run only if current file is the entry point.\n}\n

const moduleParents = Object.values(require.cache)\n  .filter((m) => m.children.includes(module));\n

npx codemod@latest @nodejs/rmdir\n

npx codemod@latest @nodejs/crypto-rsa-pss-update\n

const w = new Writable({\n  async final(callback) {\n    await someOp();\n    callback();\n  },\n});\n

npx codemod@latest @nodejs/fs-access-mode-constants\n

npx codemod@latest @nodejs/dirent-path-to-parent-path\n

npx codemod@latest @nodejs/repl-classes-with-new\n

npx codemod@latest @nodejs/repl-builtin-modules\n

npx codemod@latest @nodejs/http-classes-with-new\n

npx codemod@latest @nodejs/types-is-native-error\n