node-addon-api 3.0.1 → 3.0.2

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # node-addon-api Changelog
 
+## 2020-09-18 Version 3.0.2, @NickNaso
+
+### Notable changes:
+
+#### API
+
+- Introduced `include_dir` for use with **gyp** in a scalar context.
+- Added `Napi::Addon` to help handle the loading of a native add-on into 
+multiple threads and or multiple times in the same thread.
+- Concentrate callbacks provided to core N-API.
+- Make sure wrapcallback is used.
+
+#### Documentation
+
+- Added documentation for `Napi::Addon`.
+- Added documentation that reports the full class hierarchy.
+- Added link to N-API tutorial website.
+- Some minor corrections all over the documentation.
+
+#### TEST
+
+- Added tests to check the build process.
+- Refactored test for threasfafe function using async/await.
+- Converted tests that gc into async functions that await 10 ticks after
+each gc.
+- Some minor corrections all over the test suite.
+
+### Commits
+
+* [[`51e25f7c39`](https://github.com/nodejs/node-addon-api/commit/51e25f7c39)] - **doc**: remove a file (#815) (Gabriel Schulhof)
+* [[`8c9f1809a2`](https://github.com/nodejs/node-addon-api/commit/8c9f1809a2)] - **doc**: add inheritance links and other changes (Gabriel Schulhof) [#798](https://github.com/nodejs/node-addon-api/pull/798)
+* [[`6562e6b0ab`](https://github.com/nodejs/node-addon-api/commit/6562e6b0ab)] - **test**: added tests to check the build process (NickNaso) [#808](https://github.com/nodejs/node-addon-api/pull/808)
+* [[`a13b36c96e`](https://github.com/nodejs/node-addon-api/commit/a13b36c96e)] - **test**: fix the threasfafe function test (NickNaso) [#807](https://github.com/nodejs/node-addon-api/pull/807)
+* [[`f27623ff61`](https://github.com/nodejs/node-addon-api/commit/f27623ff61)] - **build**: introduce include\_dir (Lovell Fuller) [#766](https://github.com/nodejs/node-addon-api/pull/766)
+* [[`9aceea71fc`](https://github.com/nodejs/node-addon-api/commit/9aceea71fc)] - **src**: concentrate callbacks provided to core N-API (Gabriel Schulhof) [#786](https://github.com/nodejs/node-addon-api/pull/786)
+* [[`2bc45bbffd`](https://github.com/nodejs/node-addon-api/commit/2bc45bbffd)] - **test**: refactor test to use async/await (Velmisov) [#787](https://github.com/nodejs/node-addon-api/pull/787)
+* [[`518cfdcdc1`](https://github.com/nodejs/node-addon-api/commit/518cfdcdc1)] - **test**: test ObjectWrap destructor - no HandleScope (David Halls) [#729](https://github.com/nodejs/node-addon-api/pull/729)
+* [[`c2cbbd9191`](https://github.com/nodejs/node-addon-api/commit/c2cbbd9191)] - **doc**: add link to n-api tutorial website (#794) (Jim Schlight) [#794](https://github.com/nodejs/node-addon-api/pull/794)
+* [[`1c2a8d59b5`](https://github.com/nodejs/node-addon-api/commit/1c2a8d59b5)] - **doc**: Added required return to example (#793) (pacop) [#793](https://github.com/nodejs/node-addon-api/pull/793)
+* [[`cec2c76941`](https://github.com/nodejs/node-addon-api/commit/cec2c76941)] - **src**: wrap finalizer callback (Gabriel Schulhof) [#762](https://github.com/nodejs/node-addon-api/pull/762)
+* [[`4ce40d22a6`](https://github.com/nodejs/node-addon-api/commit/4ce40d22a6)] - **test**: use assert.strictEqual() (Koki Nishihara) [#777](https://github.com/nodejs/node-addon-api/pull/777)
+* [[`461e3640c6`](https://github.com/nodejs/node-addon-api/commit/461e3640c6)] - **test**: string tests together (Gabriel Schulhof) [#773](https://github.com/nodejs/node-addon-api/pull/773)
+* [[`5af645f649`](https://github.com/nodejs/node-addon-api/commit/5af645f649)] - **src**: add Addon\<T\> class (Gabriel Schulhof) [#749](https://github.com/nodejs/node-addon-api/pull/749)
+* [[`6148fb4bcc`](https://github.com/nodejs/node-addon-api/commit/6148fb4bcc)] - Synchronise Node.js versions in Appveyor Windows CI with Travis (#768) (Lovell Fuller)
+
 ## 2020-07-13 Version 3.0.1, @NickNaso
 
 ### Notable changes:

package/README.md

@@ -37,6 +37,10 @@ APIs exposed by node-addon-api are generally used to create and
 manipulate JavaScript values. Concepts and operations generally map
 to ideas specified in the **ECMA262 Language Specification**.
 
+The [N-API Resource](http://nodejs.github.io/node-addon-examples/) offers an 
+excellent orientation and tips for developers just getting started with N-API 
+and node-addon-api.
+
 - **[Setup](#setup)**
 - **[API Documentation](#api)**
 - **[Examples](#examples)**
@@ -47,7 +51,7 @@ to ideas specified in the **ECMA262 Language Specification**.
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 3.0.1**
+## **Current version: 3.0.2**
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
 
@@ -77,31 +81,25 @@ The oldest Node.js version supported by the current version of node-addon-api is
 
 The following is the documentation for node-addon-api.
 
- - [Basic Types](doc/basic_types.md)
-    - [Array](doc/basic_types.md#array)
-    - [Symbol](doc/symbol.md)
-    - [String](doc/string.md)
-    - [Name](doc/basic_types.md#name)
-    - [Number](doc/number.md)
-    - [Date](doc/date.md)
-    - [BigInt](doc/bigint.md)
-    - [Boolean](doc/boolean.md)
+ - [Full Class Hierarchy](doc/hierarchy.md)
+ - [Addon Structure](doc/addon.md)
+ - Data Types:
     - [Env](doc/env.md)
-    - [Value](doc/value.md)
     - [CallbackInfo](doc/callbackinfo.md)
     - [Reference](doc/reference.md)
-    - [External](doc/external.md)
-    - [Object](doc/object.md)
-        - [ObjectReference](doc/object_reference.md)
-        - [PropertyDescriptor](doc/property_descriptor.md)
- - [Error Handling](doc/error_handling.md)
-    - [Error](doc/error.md)
-    - [TypeError](doc/type_error.md)
-    - [RangeError](doc/range_error.md)
- - [Object Lifetime Management](doc/object_lifetime_management.md)
-    - [HandleScope](doc/handle_scope.md)
-    - [EscapableHandleScope](doc/escapable_handle_scope.md)
- - [Working with JavaScript Values](doc/working_with_javascript_values.md)
+    - [Value](doc/value.md)
+        - [Name](doc/name.md)
+            - [Symbol](doc/symbol.md)
+            - [String](doc/string.md)
+        - [Number](doc/number.md)
+        - [Date](doc/date.md)
+        - [BigInt](doc/bigint.md)
+        - [Boolean](doc/boolean.md)
+        - [External](doc/external.md)
+        - [Object](doc/object.md)
+            - [Array](doc/array.md)
+            - [ObjectReference](doc/object_reference.md)
+    - [PropertyDescriptor](doc/property_descriptor.md)
     - [Function](doc/function.md)
         - [FunctionReference](doc/function_reference.md)
     - [ObjectWrap](doc/object_wrap.md)
@@ -111,6 +109,13 @@ The following is the documentation for node-addon-api.
     - [TypedArray](doc/typed_array.md)
       - [TypedArrayOf](doc/typed_array_of.md)
     - [DataView](doc/dataview.md)
+ - [Error Handling](doc/error_handling.md)
+    - [Error](doc/error.md)
+      - [TypeError](doc/type_error.md)
+      - [RangeError](doc/range_error.md)
+ - [Object Lifetime Management](doc/object_lifetime_management.md)
+    - [HandleScope](doc/handle_scope.md)
+    - [EscapableHandleScope](doc/escapable_handle_scope.md)
  - [Memory Management](doc/memory_management.md)
  - [Async Operations](doc/async_operations.md)
     - [AsyncWorker](doc/async_worker.md)

package/appveyor.yml

@@ -1,24 +1,13 @@
 environment:
   # https://github.com/jasongin/nvs/blob/master/doc/CI.md
   NVS_VERSION: 1.4.2
-  fast_finish: true
   matrix:
-    - NODEJS_VERSION: node/4
-    - NODEJS_VERSION: node/6
-    - NODEJS_VERSION: node/8
-    - NODEJS_VERSION: node/9
     - NODEJS_VERSION: node/10
-    - NODEJS_VERSION: chakracore/8
-    - NODEJS_VERSION: chakracore/10
+    - NODEJS_VERSION: node/12
+    - NODEJS_VERSION: node/14
     - NODEJS_VERSION: nightly
-    - NODEJS_VERSION: chakracore-nightly
-
-matrix:
-  fast_finish: true
-  allow_failures:
-    - NODEJS_VERSION: nightly
-    - NODEJS_VERSION: chakracore-nightly
 
+os: Visual Studio 2017
 platform:
   - x86
   - x64

package/benchmark/function_args.cc

@@ -78,6 +78,66 @@ static void FourArgFunction(const Napi::CallbackInfo& info) {
   Napi::Value argv3 = info[3]; (void) argv3;
 }
 
+#if NAPI_VERSION > 5
+class FunctionArgsBenchmark : public Napi::Addon<FunctionArgsBenchmark> {
+ public:
+  FunctionArgsBenchmark(Napi::Env env, Napi::Object exports) {
+    DefineAddon(exports, {
+      InstanceValue("addon", DefineProperties(Napi::Object::New(env), {
+        InstanceMethod("noArgFunction", &FunctionArgsBenchmark::NoArgFunction),
+        InstanceMethod("oneArgFunction",
+                       &FunctionArgsBenchmark::OneArgFunction),
+        InstanceMethod("twoArgFunction",
+                       &FunctionArgsBenchmark::TwoArgFunction),
+        InstanceMethod("threeArgFunction",
+                       &FunctionArgsBenchmark::ThreeArgFunction),
+        InstanceMethod("fourArgFunction",
+                       &FunctionArgsBenchmark::FourArgFunction),
+      }), napi_enumerable),
+      InstanceValue("addon_templated",
+        DefineProperties(Napi::Object::New(env), {
+          InstanceMethod<&FunctionArgsBenchmark::NoArgFunction>(
+                                                            "noArgFunction"),
+          InstanceMethod<&FunctionArgsBenchmark::OneArgFunction>(
+                                                            "oneArgFunction"),
+          InstanceMethod<&FunctionArgsBenchmark::TwoArgFunction>(
+                                                            "twoArgFunction"),
+          InstanceMethod<&FunctionArgsBenchmark::ThreeArgFunction>(
+                                                            "threeArgFunction"),
+          InstanceMethod<&FunctionArgsBenchmark::FourArgFunction>(
+                                                            "fourArgFunction"),
+        }), napi_enumerable),
+    });
+  }
+ private:
+  void NoArgFunction(const Napi::CallbackInfo& info) {
+    (void) info;
+  }
+
+  void OneArgFunction(const Napi::CallbackInfo& info) {
+    Napi::Value argv0 = info[0]; (void) argv0;
+  }
+
+  void TwoArgFunction(const Napi::CallbackInfo& info) {
+    Napi::Value argv0 = info[0]; (void) argv0;
+    Napi::Value argv1 = info[1]; (void) argv1;
+  }
+
+  void ThreeArgFunction(const Napi::CallbackInfo& info) {
+    Napi::Value argv0 = info[0]; (void) argv0;
+    Napi::Value argv1 = info[1]; (void) argv1;
+    Napi::Value argv2 = info[2]; (void) argv2;
+  }
+
+  void FourArgFunction(const Napi::CallbackInfo& info) {
+    Napi::Value argv0 = info[0]; (void) argv0;
+    Napi::Value argv1 = info[1]; (void) argv1;
+    Napi::Value argv2 = info[2]; (void) argv2;
+    Napi::Value argv3 = info[3]; (void) argv3;
+  }
+};
+#endif  // NAPI_VERSION > 5
+
 static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   napi_value no_arg_function, one_arg_function, two_arg_function,
       three_arg_function, four_arg_function;
@@ -147,6 +207,10 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
   templated["fourArgFunction"] = Napi::Function::New<FourArgFunction>(env);
   exports["templated"] = templated;
 
+#if NAPI_VERSION > 5
+  FunctionArgsBenchmark::Init(env, exports);
+#endif  // NAPI_VERSION > 5
+
   return exports;
 }
 

package/benchmark/function_args.js

@@ -4,16 +4,22 @@ const addonName = path.basename(__filename, '.js');
 
 [ addonName, addonName + '_noexcept' ]
   .forEach((addonName) => {
-    const rootAddon = require(`./build/Release/${addonName}`);
+    const rootAddon = require('bindings')({
+      bindings: addonName,
+      module_root: __dirname
+    });
+    delete rootAddon.path;
     const implems = Object.keys(rootAddon);
+    const maxNameLength =
+      implems.reduce((soFar, value) => Math.max(soFar, value.length), 0);
     const anObject = {};
 
-    console.log(`${addonName}: `);
+    console.log(`\n${addonName}: `);
 
     console.log('no arguments:');
     implems.reduce((suite, implem) => {
       const fn = rootAddon[implem].noArgFunction;
-      return suite.add(implem, () => fn());
+      return suite.add(implem.padStart(maxNameLength, ' '), () => fn());
     }, new Benchmark.Suite)
       .on('cycle', (event) => console.log(String(event.target)))
       .run();
@@ -21,7 +27,7 @@ const addonName = path.basename(__filename, '.js');
     console.log('one argument:');
     implems.reduce((suite, implem) => {
       const fn = rootAddon[implem].oneArgFunction;
-      return suite.add(implem, () => fn('x'));
+      return suite.add(implem.padStart(maxNameLength, ' '), () => fn('x'));
     }, new Benchmark.Suite)
       .on('cycle', (event) => console.log(String(event.target)))
       .run();
@@ -29,7 +35,7 @@ const addonName = path.basename(__filename, '.js');
     console.log('two arguments:');
     implems.reduce((suite, implem) => {
       const fn = rootAddon[implem].twoArgFunction;
-      return suite.add(implem, () => fn('x', 12));
+      return suite.add(implem.padStart(maxNameLength, ' '), () => fn('x', 12));
     }, new Benchmark.Suite)
       .on('cycle', (event) => console.log(String(event.target)))
       .run();
@@ -37,7 +43,8 @@ const addonName = path.basename(__filename, '.js');
     console.log('three arguments:');
     implems.reduce((suite, implem) => {
       const fn = rootAddon[implem].threeArgFunction;
-      return suite.add(implem, () => fn('x', 12, true));
+      return suite.add(implem.padStart(maxNameLength, ' '),
+        () => fn('x', 12, true));
     }, new Benchmark.Suite)
       .on('cycle', (event) => console.log(String(event.target)))
       .run();
@@ -45,7 +52,8 @@ const addonName = path.basename(__filename, '.js');
     console.log('four arguments:');
     implems.reduce((suite, implem) => {
       const fn = rootAddon[implem].fourArgFunction;
-      return suite.add(implem, () => fn('x', 12, true, anObject));
+      return suite.add(implem.padStart(maxNameLength, ' '),
+        () => fn('x', 12, true, anObject));
     }, new Benchmark.Suite)
       .on('cycle', (event) => console.log(String(event.target)))
       .run();

package/benchmark/property_descriptor.cc

@@ -26,6 +26,33 @@ 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 = {
@@ -54,6 +81,10 @@ static Napi::Object Init(Napi::Env env, Napi::Object exports) {
       Napi::PropertyDescriptor::Accessor<Getter, Setter>("templated",
                                                          napi_enumerable));
 
+#if NAPI_VERSION > 5
+  PropDescBenchmark::Init(env, exports);
+#endif  // NAPI_VERSION > 5
+
   return exports;
 }
 

package/benchmark/property_descriptor.js

@@ -4,17 +4,23 @@ const addonName = path.basename(__filename, '.js');
 
 [ addonName, addonName + '_noexcept' ]
   .forEach((addonName) => {
-    const rootAddon = require(`./build/Release/${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(`${addonName}: `);
+    console.log(`\n${addonName}: `);
 
     Object.keys(rootAddon).forEach((key) => {
-      getters.add(`${key} getter`, () => {
+      getters.add(`${key} getter`.padStart(maxNameLength + 7), () => {
         const x = rootAddon[key];
       });
-      setters.add(`${key} setter`, () => {
+      setters.add(`${key} setter`.padStart(maxNameLength + 7), () => {
         rootAddon[key] = 5;
       })
     });
@@ -23,6 +29,8 @@ const addonName = path.basename(__filename, '.js');
       .on('cycle', (event) => console.log(String(event.target)))
       .run();
 
+    console.log('');
+
     setters
       .on('cycle', (event) => console.log(String(event.target)))
       .run();

package/common.gypi

@@ -15,7 +15,7 @@
       }
     }]
   ],
-  'include_dirs': ["<!@(node -p \"require('../').include\")"],
+  '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 avaialable
+    // 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(), {
+        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
+consnole.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,5 @@ void* Napi::ArrayBuffer::Data() const;
 ```
 
 Returns a pointer the wrapped data.
+
+[`Napi::Object`]: ./object.md

package/doc/bigint.md

@@ -1,5 +1,7 @@
 # BigInt
 
+Class `Napi::Bigint` inherits from class [`Napi::Value`][].
+
 A JavaScript BigInt value.
 
 ## Methods
@@ -91,3 +93,5 @@ void Napi::BigInt::ToWords(int* sign_bit, size_t* word_count, uint64_t* words);
 
 Returns a single `BigInt` value into a sign bit, 64-bit little-endian array,
 and the number of elements in the array.
+
+[`Napi::Value`]: ./value.md