node-addon-api 2.0.2 → 3.1.0

package/benchmark/property_descriptor.cc

@@ -0,0 +1,91 @@
+#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];
+}
+
+#if NAPI_VERSION > 5
+class PropDescBenchmark : public Napi::Addon<PropDescBenchmark> {
+ public:
+  PropDescBenchmark(Napi::Env, Napi::Object exports) {
+    DefineAddon(exports, {
+      InstanceAccessor("addon",
+                       &PropDescBenchmark::Getter,
+                       &PropDescBenchmark::Setter,
+                       napi_enumerable),
+      InstanceAccessor<&PropDescBenchmark::Getter,
+                       &PropDescBenchmark::Setter>("addon_templated",
+                                                   napi_enumerable),
+    });
+  }
+
+ private:
+  Napi::Value Getter(const Napi::CallbackInfo& info) {
+    return Napi::Number::New(info.Env(), 42);
+  }
+
+  void Setter(const Napi::CallbackInfo& info, const Napi::Value& val) {
+    (void) info[0];
+    (void) val;
+  }
+};
+#endif  // NAPI_VERSION > 5
+
+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));
+
+#if NAPI_VERSION > 5
+  PropDescBenchmark::Init(env, exports);
+#endif  // NAPI_VERSION > 5
+
+  return exports;
+}
+
+NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)

package/benchmark/property_descriptor.js

@@ -0,0 +1,37 @@
+const path = require('path');
+const Benchmark = require('benchmark');
+const addonName = path.basename(__filename, '.js');
+
+[ addonName, addonName + '_noexcept' ]
+  .forEach((addonName) => {
+    const rootAddon = require('bindings')({
+      bindings: addonName,
+      module_root: __dirname
+    });
+    delete rootAddon.path;
+    const getters = new Benchmark.Suite;
+    const setters = new Benchmark.Suite;
+    const maxNameLength = Object.keys(rootAddon)
+      .reduce((soFar, value) => Math.max(soFar, value.length), 0);
+
+    console.log(`\n${addonName}: `);
+
+    Object.keys(rootAddon).forEach((key) => {
+      getters.add(`${key} getter`.padStart(maxNameLength + 7), () => {
+        const x = rootAddon[key];
+      });
+      setters.add(`${key} setter`.padStart(maxNameLength + 7), () => {
+        rootAddon[key] = 5;
+      })
+    });
+
+    getters
+      .on('cycle', (event) => console.log(String(event.target)))
+      .run();
+
+    console.log('');
+
+    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_dir\")"],
+  'cflags': [ '-Werror', '-Wall', '-Wextra', '-Wpedantic', '-Wunused-parameter' ],
+  'cflags_cc': [ '-Werror', '-Wall', '-Wextra', '-Wpedantic', '-Wunused-parameter' ]
+}

package/doc/addon.md

@@ -0,0 +1,157 @@
+# Add-on Structure
+
+Class `Napi::Addon<T>` inherits from class [`Napi::InstanceWrap<T>`][].
+
+Creating add-ons that work correctly when loaded multiple times from the same
+source package into multiple Node.js threads and/or multiple times into the same
+Node.js thread requires that all global data they hold be associated with the
+environment in which they run. It is not safe to store global data in static
+variables because doing so does not take into account the fact that an add-on
+may be loaded into multiple threads nor that an add-on may be loaded multiple
+times into a single thread.
+
+The `Napi::Addon<T>` class can be used to define an entire add-on. Instances of
+`Napi::Addon<T>` subclasses become instances of the add-on, stored safely by
+Node.js on its various threads and into its various contexts. Thus, any data
+stored in the instance variables of a `Napi::Addon<T>` subclass instance are
+stored safely by Node.js. Functions exposed to JavaScript using
+`Napi::Addon<T>::InstanceMethod` and/or `Napi::Addon<T>::DefineAddon` are
+instance methods of the `Napi::Addon` subclass and thus have access to data
+stored inside the instance.
+
+`Napi::Addon<T>::DefineProperties` may be used to attach `Napi::Addon<T>`
+subclass instance methods to objects other than the one that will be returned to
+Node.js as the add-on instance.
+
+The `Napi::Addon<T>` class can be used together with the `NODE_API_ADDON()` and
+`NODE_API_NAMED_ADDON()` macros to define add-ons.
+
+## Example
+
+```cpp
+#include <napi.h>
+
+class ExampleAddon : public Napi::Addon<ExampleAddon> {
+ public:
+  ExampleAddon(Napi::Env env, Napi::Object exports) {
+    // In the constructor we declare the functions the add-on makes available
+    // to JavaScript.
+    DefineAddon(exports, {
+      InstanceMethod("increment", &ExampleAddon::Increment),
+
+      // We can also attach plain objects to `exports`, and instance methods as
+      // properties of those sub-objects.
+      InstanceValue("subObject", DefineProperties(Napi::Object::New(env), {
+        InstanceMethod("decrement", &ExampleAddon::Decrement)
+      }), napi_enumerable)
+    });
+  }
+ private:
+
+  // This method has access to the data stored in the environment because it is
+  // an instance method of `ExampleAddon` and because it was listed among the
+  // property descriptors passed to `DefineAddon()` in the constructor.
+  Napi::Value Increment(const Napi::CallbackInfo& info) {
+    return Napi::Number::New(info.Env(), ++value);
+  }
+
+  // This method has access to the data stored in the environment because it is
+  // an instance method of `ExampleAddon` and because it was exposed to
+  // JavaScript by calling `DefineProperties()` with the object onto which it is
+  // attached.
+  Napi::Value Decrement(const Napi::CallbackInfo& info) {
+    return Napi::Number::New(info.Env(), --value);
+  }
+
+  // Data stored in these variables is unique to each instance of the add-on.
+  uint32_t value = 42;
+};
+
+// The macro announces that instances of the class `ExampleAddon` will be
+// created for each instance of the add-on that must be loaded into Node.js.
+NODE_API_ADDON(ExampleAddon)
+```
+
+The above code can be used from JavaScript as follows:
+
+```js
+'use strict'
+
+const exampleAddon = require('bindings')('example_addon');
+console.log(exampleAddon.increment()); // prints 43
+console.log(exampleAddon.increment()); // prints 44
+console.log(exampleAddon.subObject.decrement()); // prints 43
+```
+
+When Node.js loads an instance of the add-on, a new instance of the class is
+created. Its constructor receives the environment `Napi::Env env` and the
+exports object `Napi::Object exports`. It can then use the method `DefineAddon`
+to either attach methods, accessors, and/or values to the `exports` object or to
+create its own `exports` object and attach methods, accessors, and/or values to
+it.
+
+Functions created with `Napi::Function::New()`, accessors created with
+`PropertyDescriptor::Accessor()`, and values can also be attached. If their
+implementation requires the `ExampleAddon` instance, it can be retrieved from
+the `Napi::Env env` with `GetInstanceData()`:
+
+```cpp
+void ExampleBinding(const Napi::CallbackInfo& info) {
+  ExampleAddon* addon = info.Env().GetInstanceData<ExampleAddon>();
+}
+```
+
+## Methods
+
+### Constructor
+
+Creates a new instance of the add-on.
+
+```cpp
+Napi::Addon(Napi::Env env, Napi::Object exports);
+```
+
+- `[in] env`: The environment into which the add-on is being loaded.
+- `[in] exports`: The exports object received from JavaScript.
+
+Typically, the constructor calls `DefineAddon()` to attach methods, accessors,
+and/or values to `exports`. The constructor may also create a new object and
+pass it to `DefineAddon()` as its first parameter if it wishes to replace the
+`exports` object as provided by Node.js.
+
+### DefineAddon
+
+Defines an add-on instance with functions, accessors, and/or values.
+
+```cpp
+template <typename T>
+void Napi::Addon<T>::DefineAddon(Napi::Object exports,
+                   const std::initializer_list<PropertyDescriptor>& properties);
+```
+
+* `[in] exports`: The object to return to Node.js as an instance of the add-on.
+* `[in] properties`: Initializer list of add-on property descriptors of the
+methods, property accessors, and values that define the add-on. They will be
+set on `exports`.
+See: [`Class property and descriptor`](class_property_descriptor.md).
+
+### DefineProperties
+
+Defines function, accessor, and/or value properties on an object using add-on
+instance methods.
+
+```cpp
+template <typename T>
+Napi::Object
+Napi::Addon<T>::DefineProperties(Napi::Object object,
+                   const std::initializer_list<PropertyDescriptor>& properties);
+```
+
+* `[in] object`: The object that will receive the new properties.
+* `[in] properties`: Initializer list of property descriptors of the methods,
+property accessors, and values to attach to `object`.
+See: [`Class property and descriptor`](class_property_descriptor.md).
+
+Returns `object`.
+
+[`Napi::InstanceWrap<T>`]: ./instance_wrap.md

package/doc/array.md

@@ -0,0 +1,81 @@
+# Array
+
+Class [`Napi::Array`][] inherits from class [`Napi::Object`][].
+
+Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper
+around `napi_value` representing a JavaScript Array.
+
+[`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data
+types such as [`Napi::Int32Array`][] and [`Napi::ArrayBuffer`][], respectively,
+that can be used for transferring large amounts of data from JavaScript to the
+native side. An example illustrating the use of a JavaScript-provided
+`ArrayBuffer` in native code is available [here](https://github.com/nodejs/node-addon-examples/tree/master/array_buffer_to_native/node-addon-api).
+
+## Constructor
+```cpp
+Napi::Array::Array();
+```
+
+Returns an empty array.
+
+If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+```cpp
+Napi::Array::Array(napi_env env, napi_value value);
+```
+- `[in] env` - The environment in which to create the array.
+- `[in] value` - The primitive to wrap.
+
+Returns a `Napi::Array` wrapping a `napi_value`.
+
+If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+## Methods
+
+### New
+```cpp
+static Napi::Array Napi::Array::New(napi_env env);
+```
+- `[in] env` - The environment in which to create the array.
+
+Returns a new `Napi::Array`.
+
+If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+### New
+
+```cpp
+static Napi::Array Napi::Array::New(napi_env env, size_t length);
+```
+- `[in] env` - The environment in which to create the array.
+- `[in] length` - The length of the array.
+
+Returns a new `Napi::Array` with the given length.
+
+If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+### Length
+```cpp
+uint32_t Napi::Array::Length() const;
+```
+
+Returns the length of the array.
+
+Note:
+This can execute JavaScript code implicitly according to JavaScript semantics.
+If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+[`Napi::ArrayBuffer`]: ./array_buffer.md
+[`Napi::Int32Array`]: ./typed_array_of.md
+[`Napi::Object`]: ./object.md
+[`Napi::TypedArray`]: ./typed_array.md

package/doc/array_buffer.md

@@ -1,5 +1,7 @@
 # ArrayBuffer
 
+Class `Napi::ArrayBuffer` inherits from class [`Napi::Object`][].
+
 The `Napi::ArrayBuffer` class corresponds to the
 [JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
 class.
@@ -127,3 +129,21 @@ void* Napi::ArrayBuffer::Data() const;
 ```
 
 Returns a pointer the wrapped data.
+
+### Detach
+
+```cpp
+void Napi::ArrayBuffer::Detach();
+```
+
+Invokes the `ArrayBuffer` detach operation on a detachable `ArrayBuffer`.
+
+### IsDetached
+
+```cpp
+bool Napi::ArrayBuffer::IsDetached() const;
+```
+
+Returns `true` if this `ArrayBuffer` has been detached.
+
+[`Napi::Object`]: ./object.md

package/doc/async_context.md

@@ -73,7 +73,7 @@ void MakeCallbackWithAsyncContext(const Napi::CallbackInfo& info) {
   Napi::Function callback = info[0].As<Napi::Function>();
   Napi::Object resource = info[1].As<Napi::Object>();
 
-  // Creat a new async context instance.
+  // Create a new async context instance.
   Napi::AsyncContext context(info.Env(), "async_context_test", resource);
 
   // Invoke the callback with the async context instance.

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)});
     }
@@ -366,7 +395,7 @@ class EchoWorker : public AsyncWorker {
 };
 ```
 
-The `EchoWorker`'s contructor calls the base class' constructor to pass in the
+The `EchoWorker`'s constructor calls the base class' constructor to pass in the
 callback that the `Napi::AsyncWorker` base class will store persistently. When
 the work on the `Napi::AsyncWorker::Execute` method is done the
 `Napi::AsyncWorker::OnOk` method is called and the results return back to
@@ -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.