node-addon-api 1.7.2 → 3.0.0

package/benchmark/function_args.js

@@ -0,0 +1,52 @@
+const path = require('path');
+const Benchmark = require('benchmark');
+const addonName = path.basename(__filename, '.js');
+
+[ addonName, addonName + '_noexcept' ]
+  .forEach((addonName) => {
+    const rootAddon = require(`./build/Release/${addonName}`);
+    const implems = Object.keys(rootAddon);
+    const anObject = {};
+
+    console.log(`${addonName}: `);
+
+    console.log('no arguments:');
+    implems.reduce((suite, implem) => {
+      const fn = rootAddon[implem].noArgFunction;
+      return suite.add(implem, () => fn());
+    }, new Benchmark.Suite)
+      .on('cycle', (event) => console.log(String(event.target)))
+      .run();
+
+    console.log('one argument:');
+    implems.reduce((suite, implem) => {
+      const fn = rootAddon[implem].oneArgFunction;
+      return suite.add(implem, () => fn('x'));
+    }, new Benchmark.Suite)
+      .on('cycle', (event) => console.log(String(event.target)))
+      .run();
+
+    console.log('two arguments:');
+    implems.reduce((suite, implem) => {
+      const fn = rootAddon[implem].twoArgFunction;
+      return suite.add(implem, () => fn('x', 12));
+    }, new Benchmark.Suite)
+      .on('cycle', (event) => console.log(String(event.target)))
+      .run();
+
+    console.log('three arguments:');
+    implems.reduce((suite, implem) => {
+      const fn = rootAddon[implem].threeArgFunction;
+      return suite.add(implem, () => fn('x', 12, true));
+    }, new Benchmark.Suite)
+      .on('cycle', (event) => console.log(String(event.target)))
+      .run();
+
+    console.log('four arguments:');
+    implems.reduce((suite, implem) => {
+      const fn = rootAddon[implem].fourArgFunction;
+      return suite.add(implem, () => fn('x', 12, true, anObject));
+    }, new Benchmark.Suite)
+      .on('cycle', (event) => console.log(String(event.target)))
+      .run();
+  });

package/benchmark/index.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const { readdirSync } = require('fs');
+const { spawnSync } = require('child_process');
+const path = require('path');
+
+let benchmarks = [];
+
+if (!!process.env.npm_config_benchmarks) {
+  benchmarks = process.env.npm_config_benchmarks
+    .split(';')
+    .map((item) => (item + '.js'));
+}
+
+// Run each file in this directory or the list given on the command line except
+// index.js as a Node.js process.
+(benchmarks.length > 0 ? benchmarks : readdirSync(__dirname))
+  .filter((item) => (item !== 'index.js' && item.match(/\.js$/)))
+  .map((item) => path.join(__dirname, item))
+  .forEach((item) => {
+    const child = spawnSync(process.execPath, [
+      '--expose-gc',
+      item
+    ], { stdio: 'inherit' });
+    if (child.signal) {
+      console.error(`Tests aborted with ${child.signal}`);
+      process.exitCode = 1;
+    } else {
+      process.exitCode = child.status;
+    }
+    if (child.status !== 0) {
+      process.exit(process.exitCode);
+    }
+  });

package/benchmark/property_descriptor.cc

@@ -0,0 +1,60 @@
+#include "napi.h"
+
+static napi_value Getter_Core(napi_env env, napi_callback_info info) {
+  (void) info;
+  napi_value result;
+  napi_status status = napi_create_uint32(env, 42, &result);
+  NAPI_THROW_IF_FAILED(env, status, nullptr);
+  return result;
+}
+
+static napi_value Setter_Core(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv;
+  napi_status status =
+      napi_get_cb_info(env, info, &argc, &argv, nullptr, nullptr);
+  NAPI_THROW_IF_FAILED(env, status, nullptr);
+  (void) argv;
+  return nullptr;
+}
+
+static Napi::Value Getter(const Napi::CallbackInfo& info) {
+  return Napi::Number::New(info.Env(), 42);
+}
+
+static void Setter(const Napi::CallbackInfo& info) {
+  (void) info[0];
+}
+
+static Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  napi_status status;
+  napi_property_descriptor core_prop = {
+    "core",
+    nullptr,
+    nullptr,
+    Getter_Core,
+    Setter_Core,
+    nullptr,
+    napi_enumerable,
+    nullptr
+  };
+
+  status = napi_define_properties(env, exports, 1, &core_prop);
+  NAPI_THROW_IF_FAILED(env, status, Napi::Object());
+
+  exports.DefineProperty(
+      Napi::PropertyDescriptor::Accessor(env,
+                                         exports,
+                                         "cplusplus",
+                                         Getter,
+                                         Setter,
+                                         napi_enumerable));
+
+  exports.DefineProperty(
+      Napi::PropertyDescriptor::Accessor<Getter, Setter>("templated",
+                                                         napi_enumerable));
+
+  return exports;
+}
+
+NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)

package/benchmark/property_descriptor.js

@@ -0,0 +1,29 @@
+const path = require('path');
+const Benchmark = require('benchmark');
+const addonName = path.basename(__filename, '.js');
+
+[ addonName, addonName + '_noexcept' ]
+  .forEach((addonName) => {
+    const rootAddon = require(`./build/Release/${addonName}`);
+    const getters = new Benchmark.Suite;
+    const setters = new Benchmark.Suite;
+
+    console.log(`${addonName}: `);
+
+    Object.keys(rootAddon).forEach((key) => {
+      getters.add(`${key} getter`, () => {
+        const x = rootAddon[key];
+      });
+      setters.add(`${key} setter`, () => {
+        rootAddon[key] = 5;
+      })
+    });
+
+    getters
+      .on('cycle', (event) => console.log(String(event.target)))
+      .run();
+
+    setters
+      .on('cycle', (event) => console.log(String(event.target)))
+      .run();
+  });

package/common.gypi

@@ -0,0 +1,21 @@
+{
+  'variables': {
+    'NAPI_VERSION%': "<!(node -p \"process.versions.napi\")",
+    'disable_deprecated': "<!(node -p \"process.env['npm_config_disable_deprecated']\")"
+  },
+  'conditions': [
+    ['NAPI_VERSION!=""', { 'defines': ['NAPI_VERSION=<@(NAPI_VERSION)'] } ],
+    ['disable_deprecated=="true"', {
+      'defines': ['NODE_ADDON_API_DISABLE_DEPRECATED']
+    }],
+    ['OS=="mac"', {
+      'cflags+': ['-fvisibility=hidden'],
+      'xcode_settings': {
+        'OTHER_CFLAGS': ['-fvisibility=hidden']
+      }
+    }]
+  ],
+  'include_dirs': ["<!@(node -p \"require('../').include\")"],
+  'cflags': [ '-Werror', '-Wall', '-Wextra', '-Wpedantic', '-Wunused-parameter' ],
+  'cflags_cc': [ '-Werror', '-Wall', '-Wextra', '-Wpedantic', '-Wunused-parameter' ]
+}

package/doc/array_buffer.md

@@ -123,7 +123,7 @@ Returns the length of the wrapped data, in bytes.
 ### Data
 
 ```cpp
-T* Napi::ArrayBuffer::Data() const;
+void* Napi::ArrayBuffer::Data() const;
 ```
 
 Returns a pointer the wrapped data.

package/doc/async_context.md

@@ -45,6 +45,16 @@ The `Napi::AsyncContext` to be destroyed.
 virtual Napi::AsyncContext::~AsyncContext();
 ```
 
+### Env
+
+Requests the environment in which the async context has been initially created.
+
+```cpp
+Napi::Env Env() const;
+```
+
+Returns the `Napi::Env` environment in which the async context has been created.
+
 ## Operator
 
 ```cpp

package/doc/async_operations.md

@@ -4,7 +4,7 @@ Node.js native add-ons often need to execute long running tasks and to avoid
 blocking the **event loop** they have to run them asynchronously from the
 **event loop**.
 In the Node.js model of execution the event loop thread represents the thread
-where JavaScript code is executing. The node.js guidance is to avoid blocking
+where JavaScript code is executing. The Node.js guidance is to avoid blocking
 other work queued on the event loop thread. Therefore, we need to do this work on
 another thread.
 

package/doc/async_worker.md

@@ -7,8 +7,8 @@ operation.
 
 Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When
 a thread is available for execution the `Napi::AsyncWorker::Execute` method will
-be invoked.  Once `Napi::AsyncWorker::Execute` completes either
-`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked.  Once
+be invoked. Once `Napi::AsyncWorker::Execute` completes either
+`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once
 the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are
 complete the `Napi::AsyncWorker` instance is destructed.
 
@@ -38,7 +38,7 @@ void Napi::AsyncWorker::Queue();
 ### Cancel
 
 Cancels queued work if it has not yet been started. If it has already started
-executing, it cannot be cancelled.  If cancelled successfully neither
+executing, it cannot be cancelled. If cancelled successfully neither
 `OnOK` nor `OnError` will be called.
 
 ```cpp
@@ -90,14 +90,14 @@ void Napi::AsyncWorker::SetError(const std::string& error);
 
 ### Execute
 
-This method is used to execute some tasks out of the **event loop** on a libuv
+This method is used to execute some tasks outside of the **event loop** on a libuv
 worker thread. Subclasses must implement this method and the method is run on
-a thread other than that running the main event loop.  As the method is not
+a thread other than that running the main event loop. As the method is not
 running on the main event loop, it must avoid calling any methods from node-addon-api
 or running any code that might invoke JavaScript. Instead, once this method is
 complete any interaction through node-addon-api with JavaScript should be implemented
-in the `Napi::AsyncWorker::OnOK` method which runs on the main thread and is
-invoked when the `Napi::AsyncWorker::Execute` method completes.
+in the `Napi::AsyncWorker::OnOK` method and `Napi::AsyncWorker::OnError` which run
+on the main thread and are invoked when the `Napi::AsyncWorker::Execute` method completes.
 
 ```cpp
 virtual void Napi::AsyncWorker::Execute() = 0;
@@ -106,18 +106,19 @@ virtual void Napi::AsyncWorker::Execute() = 0;
 ### OnOK
 
 This method is invoked when the computation in the `Execute` method ends.
-The default implementation runs the Callback optionally provided when the AsyncWorker class
-was created. The callback will by default receive no arguments. To provide arguments,
-override the `GetResult()` method.
+The default implementation runs the `Callback` optionally provided when the
+`AsyncWorker` class was created. The `Callback` will by default receive no
+arguments. The arguments to the `Callback` can be provided by overriding the
+`GetResult()` method.
 
 ```cpp
 virtual void Napi::AsyncWorker::OnOK();
 ```
 ### GetResult
 
-This method returns the arguments passed to the Callback invoked by the default
+This method returns the arguments passed to the `Callback` invoked by the default
 `OnOK()` implementation. The default implementation returns an empty vector,
-providing no arguments to the Callback.
+providing no arguments to the `Callback`.
 
 ```cpp
 virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
@@ -128,13 +129,42 @@ virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
 This method is invoked after `Napi::AsyncWorker::Execute` completes if an error
 occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are
 enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`.
-The default implementation calls the callback provided when the `Napi::AsyncWorker`
+The default implementation calls the `Callback` provided when the `Napi::AsyncWorker`
 class was created, passing in the error as the first parameter.
 
 ```cpp
 virtual void Napi::AsyncWorker::OnError(const Napi::Error& e);
 ```
 
+### OnWorkComplete
+
+This method is invoked after the work has completed on JavaScript thread.
+The default implementation of this method checks the status of the work and
+tries to dispatch the result to `Napi::AsyncWorker::OnOk` or `Napi::AsyncWorker::Error`
+if the work has committed an error. If the work was cancelled, neither
+`Napi::AsyncWorker::OnOk` nor `Napi::AsyncWorker::Error` will be invoked.
+After the result is dispatched, the default implementation will call into
+`Napi::AsyncWorker::Destroy` if `SuppressDestruct()` was not called.
+
+```cpp
+virtual void OnWorkComplete(Napi::Env env, napi_status status);
+```
+
+### OnExecute
+
+This method is invoked immediately on the work thread when scheduled.
+The default implementation of this method just calls the `Napi::AsyncWorker::Execute`
+and handles exceptions if cpp exceptions were enabled.
+
+The `OnExecute` method receives an `napi_env` argument. However, the `napi_env`
+must NOT be used within this method, as it does not run on the JavaScript
+thread and must not run any method that would cause JavaScript to run. In
+practice, this means that almost any use of `napi_env` will be incorrect.
+
+```cpp
+virtual void OnExecute(Napi::Env env);
+```
+
 ### Destroy
 
 This method is invoked when the instance must be deallocated. If
@@ -172,7 +202,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_
 
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`: Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -189,7 +219,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_
 
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -224,7 +254,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
 - `[in] receiver`: The `this` object passed to the called function.
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -242,7 +272,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
 - `[in] receiver`: The `this` object passed to the called function.
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -274,7 +304,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name);
 ```
 
 - `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
-- `[in] resource_name`: Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -290,7 +320,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi:
 ```
 
 - `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -333,7 +363,7 @@ function runs in the background out of the **event loop** thread and at the end
 the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` function will be
 called and are executed as part of the event loop.
 
-The code below show a basic example of `Napi::AsyncWorker` the implementation:
+The code below shows a basic example of `Napi::AsyncWorker` the implementation:
 
 ```cpp
 #include<napi.h>
@@ -341,7 +371,7 @@ The code below show a basic example of `Napi::AsyncWorker` the implementation:
 #include <chrono>
 #include <thread>
 
-use namespace Napi;
+using namespace Napi;
 
 class EchoWorker : public AsyncWorker {
     public:
@@ -350,12 +380,12 @@ class EchoWorker : public AsyncWorker {
 
         ~EchoWorker() {}
     // This code will be executed on the worker thread
-    void Execute() {
+    void Execute() override {
         // Need to simulate cpu heavy task
         std::this_thread::sleep_for(std::chrono::seconds(1));
     }
 
-    void OnOK() {
+    void OnOK() override {
         HandleScope scope(Env());
         Callback().Call({Env().Null(), String::New(Env(), echo)});
     }
@@ -371,7 +401,7 @@ the work on the `Napi::AsyncWorker::Execute` method is done the
 `Napi::AsyncWorker::OnOk` method is called and the results return back to
 JavaScript invoking the stored callback with its associated environment.
 
-The following code shows an example on how to create and use an `Napi::AsyncWorker`
+The following code shows an example of how to create and use an `Napi::AsyncWorker`.
 
 ```cpp
 #include<napi.h>
@@ -379,10 +409,10 @@ The following code shows an example on how to create and use an `Napi::AsyncWork
 // Include EchoWorker class
 // ..
 
-use namespace Napi;
+using namespace Napi;
 
 Value Echo(const CallbackInfo& info) {
-    // You need to check the input data here
+    // You need to validate the arguments here.
     Function cb = info[1].As<Function>();
     std::string in = info[0].As<String>();
     EchoWorker* wk = new EchoWorker(cb, in);