node-addon-api 2.0.2 → 3.0.0

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/async_worker.md

@@ -136,6 +136,35 @@ class was created, passing in the error as the first parameter.
 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
@@ -342,7 +371,7 @@ The code below shows a basic example of `Napi::AsyncWorker` the implementation:
 #include <chrono>
 #include <thread>
 
-use namespace Napi;
+using namespace Napi;
 
 class EchoWorker : public AsyncWorker {
     public:
@@ -351,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)});
     }
@@ -380,7 +409,7 @@ The following code shows an example of 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 validate the arguments here.

package/doc/{async_progress_worker.md → async_worker_variants.md}

@@ -272,12 +272,12 @@ called and are executed as part of the event loop.
 The code below shows a basic example of the `Napi::AsyncProgressWorker` implementation:
 
 ```cpp
-#include<napi.h>
+#include <napi.h>
 
 #include <chrono>
 #include <thread>
 
-use namespace Napi;
+using namespace Napi;
 
 class EchoWorker : public AsyncProgressWorker<uint32_t> {
     public:
@@ -323,7 +323,7 @@ The following code shows an example of how to create and use an `Napi::AsyncProg
 // Include EchoWorker class
 // ..
 
-use namespace Napi;
+using namespace Napi;
 
 Value Echo(const CallbackInfo& info) {
     // We need to validate the arguments here
@@ -341,4 +341,116 @@ asynchronous task ends and other data needed for the computation. Once created,
 the only other action needed is to call the `Napi::AsyncProgressWorker::Queue`
 method that will queue the created worker for execution.
 
+# AsyncProgressQueueWorker
+
+`Napi::AsyncProgressQueueWorker` acts exactly like `Napi::AsyncProgressWorker`
+except that each progress committed by `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send`
+during `Napi::AsyncProgressQueueWorker::Execute` is guaranteed to be
+processed by `Napi::AsyncProgressQueueWorker::OnProgress` on the JavaScript
+thread in the order it was committed.
+
+For the most basic use, only the `Napi::AsyncProgressQueueWorker::Execute` and
+`Napi::AsyncProgressQueueWorker::OnProgress` method must be implemented in a subclass.
+
+# AsyncProgressQueueWorker::ExecutionProcess
+
+A bridge class created before the worker thread execution of `Napi::AsyncProgressQueueWorker::Execute`.
+
+## Methods
+
+### Send
+
+`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` takes two arguments, a pointer
+to a generic type of data, and a `size_t` to indicate how many items the pointer is
+pointing to.
+
+The data pointed to will be copied to internal slots of `Napi::AsyncProgressQueueWorker` so
+after the call to `Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` the data can
+be safely released.
+
+`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` guarantees invocation
+of `Napi::AsyncProgressQueueWorker::OnProgress`, which means multiple `Send`
+call will result in the in-order invocation of `Napi::AsyncProgressQueueWorker::OnProgress`
+with each data item.
+
+```cpp
+void Napi::AsyncProgressQueueWorker::ExecutionProcess::Send(const T* data, size_t count) const;
+```
+
+## Example
+
+The code below shows a basic example of the `Napi::AsyncProgressQueueWorker` implementation:
+
+```cpp
+#include <napi.h>
+
+#include <chrono>
+#include <thread>
+
+using namespace Napi;
+
+class EchoWorker : public AsyncProgressQueueWorker<uint32_t> {
+    public:
+        EchoWorker(Function& callback, std::string& echo)
+        : AsyncProgressQueueWorker(callback), echo(echo) {}
+
+        ~EchoWorker() {}
+    // This code will be executed on the worker thread
+    void Execute(const ExecutionProgress& progress) {
+        // Need to simulate cpu heavy task
+        for (uint32_t i = 0; i < 100; ++i) {
+          progress.Send(&i, 1);
+          std::this_thread::sleep_for(std::chrono::seconds(1));
+        }
+    }
+
+    void OnOK() {
+        HandleScope scope(Env());
+        Callback().Call({Env().Null(), String::New(Env(), echo)});
+    }
+
+    void OnProgress(const uint32_t* data, size_t /* count */) {
+        HandleScope scope(Env());
+        Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)});
+    }
+
+    private:
+        std::string echo;
+};
+```
+
+The `EchoWorker`'s constructor calls the base class' constructor to pass in the
+callback that the `Napi::AsyncProgressQueueWorker` base class will store
+persistently. When the work on the `Napi::AsyncProgressQueueWorker::Execute`
+method is done the `Napi::AsyncProgressQueueWorker::OnOk` method is called and
+the results are returned back to JavaScript when the stored callback is invoked
+with its associated environment.
+
+The following code shows an example of how to create and use an
+`Napi::AsyncProgressQueueWorker`.
+
+```cpp
+#include <napi.h>
+
+// Include EchoWorker class
+// ..
+
+using namespace Napi;
+
+Value Echo(const CallbackInfo& info) {
+    // We 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);
+    wk->Queue();
+    return info.Env().Undefined();
+}
+```
+
+The implementation of a `Napi::AsyncProgressQueueWorker` can be used by creating a
+new instance and passing to its constructor the callback to execute when the
+asynchronous task ends and other data needed for the computation. Once created,
+the only other action needed is to call the `Napi::AsyncProgressQueueWorker::Queue`
+method that will queue the created worker for execution.
+
 [`Napi::AsyncWorker`]: ./async_worker.md

package/doc/bigint.md

@@ -8,6 +8,7 @@ A JavaScript BigInt value.
 
 ```cpp
 static Napi::BigInt Napi::BigInt::New(Napi::Env env, int64_t value);
+static Napi::BigInt Napi::BigInt::New(Napi::Env env, uint64_t value);
 ```
 
  - `[in] env`: The environment in which to construct the `Napi::BigInt` object.
@@ -47,7 +48,7 @@ Returns a new empty JavaScript `Napi::BigInt`.
 ### Int64Value
 
 ```cpp
-int64_t Napi::BitInt::Int64Value(bool* lossless) const;
+int64_t Napi::BigInt::Int64Value(bool* lossless) const;
 ```
 
  - `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly.

package/doc/class_property_descriptor.md

@@ -26,9 +26,9 @@ class Example : public Napi::ObjectWrap<Example> {
 Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
     Napi::Function func = DefineClass(env, "Example", {
         // Register a class instance accessor with getter and setter functions.
-        InstanceAccessor("value", &Example::GetValue, &Example::SetValue),
-        // We can also register a readonly accessor by passing nullptr as the setter.
-        InstanceAccessor("readOnlyProp", &Example::GetValue, nullptr)
+        InstanceAccessor<&Example::GetValue, &Example::SetValue>("value"),
+        // We can also register a readonly accessor by omitting the setter.
+        InstanceAccessor<&Example::GetValue>("readOnlyProp")
     });
 
     constructor = Napi::Persistent(func);

package/doc/creating_a_release.md

@@ -13,7 +13,7 @@ tools:
 
 * [Changelog maker](https://www.npmjs.com/package/changelog-maker)
 
-If not please follow the instruction reported in the tool's documentation to 
+If not please follow the instruction reported in the tool's documentation to
 install it.
 
 ## Publish new release
@@ -27,13 +27,13 @@ new release. Give people some time to comment or suggest PRs that should land fi
 
 * Update the version in **package.json** appropriately.
 
-* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/master/README.md) 
+* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/master/README.md)
 to show the new version as the latest.
 
 * Generate the changelog for the new version using **changelog maker** tool. From
 the route folder of the repo launch the following command:
 
-    ```bash 
+    ```bash
     > changelog-maker
     ```
 * Use the output generated by **changelog maker** to pdate the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/master/CHANGELOG.md)
@@ -43,8 +43,8 @@ following the style used in publishing the previous release.
 
 * Validate all tests pass by running npm test on master.
 
-* Use **[CI](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api/)**
-to validate tests pass for latest 11, 10, 8, 6 releases (note there are still some issues on SmartOS and
+* Use **[CI](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api-new/)**
+to validate tests pass (note there are still some issues on SmartOS and
 Windows in the testing).
 
 * Do a clean checkout of node-addon-api.

package/doc/env.md

@@ -61,3 +61,17 @@ Napi::Error Napi::Env::GetAndClearPendingException();
 ```
 
 Returns an `Napi::Error` object representing the environment's pending exception, if any.
+
+### RunScript
+
+```cpp
+Napi::Value Napi::Env::RunScript(____ script);
+```
+- `[in] script`: A string containing JavaScript code to execute.
+
+Runs JavaScript code contained in a string and returns its result.
+
+The `script` can be any of the following types:
+- [`Napi::String`](string.md)
+- `const char *`
+- `const std::string &`

package/doc/function.md

@@ -11,6 +11,10 @@ functions that were created in JavaScript and passed to the native add-on.
 The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info
 see: [`Napi::Object`](object.md)).
 
+> For callbacks that will be called with asynchronous events from a
+> non-JavaScript thread, please refer to [`Napi::ThreadSafeFunction`][] for more
+> examples.
+
 ## Example
 
 ```cpp
@@ -25,7 +29,7 @@ Value Fn(const CallbackInfo& info) {
 }
 
 Object Init(Env env, Object exports) {
-  exports.Set(String::New(env, "fn"), Function::New(env, Fn));
+  exports.Set(String::New(env, "fn"), Function::New<Fn>(env));
 }
 
 NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
@@ -47,6 +51,27 @@ and in general in situations which don't have an existing JavaScript function on
 the stack. The `Call` method is used when there is already a JavaScript function
 on the stack (for example when running a native method called from JavaScript).
 
+## Type definitions
+
+### Napi::Function::VoidCallback
+
+This is the type describing a callback returning `void` that will be invoked
+from JavaScript.
+
+```cpp
+typedef void (*VoidCallback)(const Napi::CallbackInfo& info);
+```
+
+### Napi::Function::Callback
+
+This is the type describing a callback returning a value that will be invoked
+from JavaScript.
+
+
+```cpp
+typedef Value (*Callback)(const Napi::CallbackInfo& info);
+```
+
 ## Methods
 
 ### Constructor
@@ -74,6 +99,86 @@ Returns a non-empty `Napi::Function` instance.
 
 Creates an instance of a `Napi::Function` object.
 
+```cpp
+template <Napi::VoidCallback cb>
+static Napi::Function New(napi_env env,
+                          const char* utf8name = nullptr,
+                          void* data = nullptr);
+```
+
+- `[template] cb`: The native function to invoke when the JavaScript function is
+invoked.
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
+- `[in] utf8name`: Null-terminated string to be used as the name of the function.
+- `[in] data`: User-provided data context. This will be passed back into the
+function when invoked later.
+
+Returns an instance of a `Napi::Function` object.
+
+### New
+
+Creates an instance of a `Napi::Function` object.
+
+```cpp
+template <Napi::Callback cb>
+static Napi::Function New(napi_env env,
+                          const char* utf8name = nullptr,
+                          void* data = nullptr);
+```
+
+- `[template] cb`: The native function to invoke when the JavaScript function is
+invoked.
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
+- `[in] utf8name`: Null-terminated string to be used as the name of the function.
+- `[in] data`: User-provided data context. This will be passed back into the
+function when invoked later.
+
+Returns an instance of a `Napi::Function` object.
+
+### New
+
+Creates an instance of a `Napi::Function` object.
+
+```cpp
+template <Napi::VoidCallback cb>
+static Napi::Function New(napi_env env,
+                          const std::string& utf8name,
+                          void* data = nullptr);
+```
+
+- `[template] cb`: The native function to invoke when the JavaScript function is
+invoked.
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
+- `[in] utf8name`: String to be used as the name of the function.
+- `[in] data`: User-provided data context. This will be passed back into the
+function when invoked later.
+
+Returns an instance of a `Napi::Function` object.
+
+### New
+
+Creates an instance of a `Napi::Function` object.
+
+```cpp
+template <Napi::Callback cb>
+static Napi::Function New(napi_env env,
+                          const std::string& utf8name,
+                          void* data = nullptr);
+```
+
+- `[template] cb`: The native function to invoke when the JavaScript function is
+invoked.
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
+- `[in] utf8name`: String to be used as the name of the function.
+- `[in] data`: User-provided data context. This will be passed back into the
+function when invoked later.
+
+Returns an instance of a `Napi::Function` object.
+
+### New
+
+Creates an instance of a `Napi::Function` object.
+
 ```cpp
 template <typename Callable>
 static Napi::Function Napi::Function::New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr);
@@ -292,3 +397,5 @@ Napi::Value Napi::Function::operator ()(const std::initializer_list<napi_value>&
 - `[in] args`: Initializer list of JavaScript values as `napi_value`.
 
 Returns a `Napi::Value` representing the JavaScript value returned by the function.
+
+[`Napi::ThreadSafeFunction`]: ./threadsafe_function.md

package/doc/object.md

@@ -2,7 +2,7 @@
 
 The `Napi::Object` class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types:
 
-- [`Napi::Value`](value.md) and extends [`Napi::Array`](array.md)
+- [`Napi::Value`](value.md) which is extended by [`Napi::Array`](basic_types.md#array)
 - [`Napi::ArrayBuffer`](array_buffer.md)
 - [`Napi::Buffer<T>`](buffer.md)
 - [`Napi::Function`](function.md)
@@ -101,6 +101,22 @@ While the value must be any of the following types:
 - `bool`
 - `double`
 
+### Delete()
+
+```cpp
+bool Napi::Object::Delete(____ key);
+```
+- `[in] key`: The name of the property to delete.
+
+Deletes the property associated with the given key. Returns `true` if the property was deleted.
+
+The `key` can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char *`
+- `const std::string &`
+- `uint32_t`
+
 ### Get()
 
 ```cpp
@@ -171,6 +187,29 @@ void finalizeCallback(Napi::Env env, T* data, Hint* hint);
 ```
 where `data` and `hint` are the pointers that were passed into the call to `AddFinalizer()`.
 
+### GetPropertyNames()
+```cpp
+Napi::Array Napi::Object::GetPropertyNames() const;
+```
+
+Returns the names of the enumerable properties of the object as a [`Napi::Array`](basic_types.md#array) of strings.
+The properties whose key is a `Symbol` will not be included.
+
+### HasOwnProperty()
+```cpp
+bool Napi::Object::HasOwnProperty(____ key); const
+```
+- `[in] key` The name of the property to check.
+
+Returns a `bool` that is *true* if the object has an own property named `key` and *false* otherwise.
+
+The key can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char*`
+- `const std::string&`
+- `uint32_t`
+
 ### DefineProperty()
 
 ```cpp

package/doc/object_lifetime_management.md

@@ -69,7 +69,7 @@ for (int i = 0; i < LOOP_MAX; i++) {
   Napi::HandleScope scope(info.Env());
   std::string name = std::string("inner-scope") + std::to_string(i);
   Napi::Value newValue = Napi::String::New(info.Env(), name.c_str());
-  // do something with neValue
+  // do something with newValue
 };
 ```