node-addon-api 2.0.2 → 3.0.0

package/.travis.yml

@@ -12,17 +12,14 @@ env:
     # https://github.com/jasongin/nvs/blob/master/doc/CI.md
     - NVS_VERSION=1.4.2
   matrix:
-    - NODEJS_VERSION=node/6
-    - NODEJS_VERSION=node/8
     - NODEJS_VERSION=node/10
     - NODEJS_VERSION=node/12
-    - NODEJS_VERSION=node/13
+    - NODEJS_VERSION=node/14
     - NODEJS_VERSION=nightly
 matrix:
   fast_finish: true
   allow_failures:
     - env: NODEJS_VERSION=nightly
-    - env: NODEJS_VERSION=node/6
 sudo: false
 cache:
   directories:

package/CHANGELOG.md

@@ -1,40 +1,98 @@
 # node-addon-api Changelog
 
-## 2020-07-01 Version 2.0.2, @NickNaso
+## 2020-04-30 Version 3.0.0, @NickNaso
 
 ### Notable changes:
 
 #### API
 
-- `Napi::ObjectWrap`: avoid double-free on old Node.js.
-- `Napi::ObjectWrap`: remove wrap only on failure.
-- `Napi::ObjectWrap`: gracefully handle constructor exceptions
-- `Napi::ObjectWrap`: call `napi_remove_wrap()` in destructor.
+- `Napi::Object` added templated property descriptors.
+- `Napi::ObjectWrap` added templated methods.
+- `Napi::ObjectWrap` the wrap is removed only on failure.
+- `Napi::ObjectWrap` the constructor's exceptions are gracefully handled.
+- `Napi::Function` added templated factory functions.
+- Added `Env::RunScript` method to run JavaScript code contained in a string.
+- Added templated version of `Napi::Function`.
+- Added benchmarking framework.
+- Added support for natove addon instance data.
+- Added `Napi::AsyncProgressQueueWorker` api.
+- Changed the guards to `NAPI_VERSION > 5`.
+- Removed N-API implementation (v6.x and v8.x support).
+- `Napi::AsyncWorker::OnWorkComplete` and `Napi::AsyncWorker::OnExecute` methods
+are override-able.
+- Removed erroneous finalizer cleanup in `Napi::ThreadSafeFunction`.
+- Disabled cahcing in `Napi::ArrayBuffer`.
+- Explicitly disallow assign and copy operator.
+- Some minor corrections and improvements.
 
-#### TEST
-
-- Updated `Napi::BigInt` test for recent change in core.
-
-### Commmits
-
-* [[`5abf60257d`](https://github.com/nodejs/node-addon-api/commit/5abf60257d)] - Merge pull request #723 from gabrielschulhof/backport-4e885069-pr-475 (Nicola Del Gobbo)
-* [[`470f130666`](https://github.com/nodejs/node-addon-api/commit/470f130666)] - **objectwrap**: avoid double-free on old Node.js (Gabriel Schulhof)
-* [[`81e2eac7ba`](https://github.com/nodejs/node-addon-api/commit/81e2eac7ba)] - **test**: update BigInt test for recent change in core (Michael Dawson) [#649](https://github.com/nodejs/node-addon-api/pull/649)
-* [[`204f07252c`](https://github.com/nodejs/node-addon-api/commit/204f07252c)] - **objectwrap**: remove wrap only on failure (Gabriel Schulhof)
-* [[`a552a384dd`](https://github.com/nodejs/node-addon-api/commit/a552a384dd)] - **src**: call `napi\_remove\_wrap()` in `ObjectWrap` dtor (Anna Henningsen) [#475](https://github.com/nodejs/node-addon-api/pull/475)
-* [[`1a51067438`](https://github.com/nodejs/node-addon-api/commit/1a51067438)] - **objectwrap**: gracefully handle constructor exceptions (Gabriel Schulhof)
-
-## 2020-06-02 Version 2.0.1, @NickNaso
+#### Documentation
 
-### Notable changes:
+- Updated documentation for `Napi::Object`.
+- Updated documentation for `Napi::Function`.
+- Updated documentation for `Napi::ObjectWrap`.
+- Added documentation on how to add benchmark.
+- Added documentation for `Napi::AsyncProgressQueueWorker`.
+- Added suggestion about tags to use on NPM.
+- Added reference to N-API badges.
+- Some minor corrections all over the documentation.
 
-#### API
+#### TEST
 
-- Fix memory corruption vulnerability
+- Updated test cases for `Napi::Object`.
+- Updated test cases for `Napi::Function`.
+- Updated test cases for `Napi::ObjectWrap`.
+- Updated test cases for `Napi::Env`.
+- Added test cases for `Napi::AsyncProgressQueueWorker`.
+- Some minor corrections all over the test suite.
 
-### Commmits
+### Commits
 
-* [[`265fea9edd`](https://github.com/nodejs/node-addon-api/commit/265fea9edd)] - **napi**: fix memory corruption vulnerability (Tobias Nießen )
+* [[`187318e37f`](https://github.com/nodejs/node-addon-api/commit/187318e37f)] - **doc**: Removed references to Node.js lower than 10.x. (#709) (Nicola Del Gobbo)
+* [[`9c9accfbbe`](https://github.com/nodejs/node-addon-api/commit/9c9accfbbe)] - **src**: add support for addon instance data (Gabriel Schulhof) [#663](https://github.com/nodejs/node-addon-api/pull/663)
+* [[`82a96502a4`](https://github.com/nodejs/node-addon-api/commit/82a96502a4)] - **src**: change guards to NAPI\_VERSION \> 5 (Gabriel Schulhof) [#697](https://github.com/nodejs/node-addon-api/pull/697)
+* [[`a64e8a5641`](https://github.com/nodejs/node-addon-api/commit/a64e8a5641)] - **ci**: move travis from 13 to 14 (#707) (Gabriel Schulhof)
+* [[`4de23c9d6b`](https://github.com/nodejs/node-addon-api/commit/4de23c9d6b)] - **doc**: fix support bigint64/biguint64 guards (Yulong Wang) [#705](https://github.com/nodejs/node-addon-api/pull/705)
+* [[`fedc8195e3`](https://github.com/nodejs/node-addon-api/commit/fedc8195e3)] - **doc**: fix semicolon missing in async\_worker.md (Azlan Mukhtar) [#701](https://github.com/nodejs/node-addon-api/pull/701)
+* [[`cdb662506c`](https://github.com/nodejs/node-addon-api/commit/cdb662506c)] - **doc**: fix typo in bigint.md (#700) (Kelvin)
+* [[`e1a827ae29`](https://github.com/nodejs/node-addon-api/commit/e1a827ae29)] - **src**: fix AsyncProgressQueueWorker compilation (#696) (Gabriel Schulhof) [#696](https://github.com/nodejs/node-addon-api/pull/696)
+* [[`2c3d5df463`](https://github.com/nodejs/node-addon-api/commit/2c3d5df463)] - Merge pull request #692 from kelvinhammond/patch-1 (Nicola Del Gobbo)
+* [[`623e876949`](https://github.com/nodejs/node-addon-api/commit/623e876949)] - Merge pull request #688 from NickNaso/badges (Nicola Del Gobbo)
+* [[`6c97913d1f`](https://github.com/nodejs/node-addon-api/commit/6c97913d1f)] - Fix minor typo in object\_lifetime\_management.md (Kelvin)
+* [[`6b8dd47c55`](https://github.com/nodejs/node-addon-api/commit/6b8dd47c55)] - Added badge section to documentation. (NickNaso)
+* [[`89e62a9154`](https://github.com/nodejs/node-addon-api/commit/89e62a9154)] - **doc**: recommend tags of addon helpers (legendecas) [#683](https://github.com/nodejs/node-addon-api/pull/683)
+* [[`ab018444ae`](https://github.com/nodejs/node-addon-api/commit/ab018444ae)] - **src**: implement AsyncProgressQueueWorker (legendecas) [#585](https://github.com/nodejs/node-addon-api/pull/585)
+* [[`d43da6ac2b`](https://github.com/nodejs/node-addon-api/commit/d43da6ac2b)] - **doc**: add @legendecas to active member list (legendecas)
+* [[`cb498bbe7f`](https://github.com/nodejs/node-addon-api/commit/cb498bbe7f)] - **doc**: Add Napi::BigInt::New() overload for uint64\_t (ikokostya)
+* [[`baaaa8452c`](https://github.com/nodejs/node-addon-api/commit/baaaa8452c)] - **doc**: link threadsafe function from JS function (legendecas)
+* [[`7f56a78ff7`](https://github.com/nodejs/node-addon-api/commit/7f56a78ff7)] - **objectwrap**: remove wrap only on failure (Gabriel Schulhof)
+* [[`4d816183da`](https://github.com/nodejs/node-addon-api/commit/4d816183da)] - **doc**: fix example code (András Timár, Dr) [#657](https://github.com/nodejs/node-addon-api/pull/657)
+* [[`7ac6e21801`](https://github.com/nodejs/node-addon-api/commit/7ac6e21801)] - **gyp**: fix gypfile name in index.js (Anna Henningsen) [#658](https://github.com/nodejs/node-addon-api/pull/658)
+* [[`46484202ca`](https://github.com/nodejs/node-addon-api/commit/46484202ca)] - **test**: user data in function property descriptor (Kevin Eady) [#652](https://github.com/nodejs/node-addon-api/pull/652)
+* [[`0f8d730483`](https://github.com/nodejs/node-addon-api/commit/0f8d730483)] - **doc**: fix syntax error in example (András Timár, Dr) [#650](https://github.com/nodejs/node-addon-api/pull/650)
+* [[`4e885069f1`](https://github.com/nodejs/node-addon-api/commit/4e885069f1)] - **src**: call `napi\_remove\_wrap()` in `ObjectWrap` dtor (Anna Henningsen) [#475](https://github.com/nodejs/node-addon-api/pull/475)
+* [[`2fde5c3ca3`](https://github.com/nodejs/node-addon-api/commit/2fde5c3ca3)] - **test**: update BigInt test for recent change in core (Michael Dawson) [#649](https://github.com/nodejs/node-addon-api/pull/649)
+* [[`e8935bd8d9`](https://github.com/nodejs/node-addon-api/commit/e8935bd8d9)] - **test**: add test for own properties on ObjectWrap (Guenter Sandner) [#645](https://github.com/nodejs/node-addon-api/pull/645)
+* [[`23ff7f0b24`](https://github.com/nodejs/node-addon-api/commit/23ff7f0b24)] - **src**: make OnWorkComplete and OnExecute override-able (legendecas) [#589](https://github.com/nodejs/node-addon-api/pull/589)
+* [[`86384f94d3`](https://github.com/nodejs/node-addon-api/commit/86384f94d3)] - **objectwrap**: gracefully handle constructor exceptions (Gabriel Schulhof)
+* [[`9af69da01f`](https://github.com/nodejs/node-addon-api/commit/9af69da01f)] - remove N-API implementation, v6.x and v8.x support (Gabriel Schulhof) [#643](https://github.com/nodejs/node-addon-api/pull/643)
+* [[`920d544779`](https://github.com/nodejs/node-addon-api/commit/920d544779)] - **benchmark**: add templated version of Function (Gabriel Schulhof) [#637](https://github.com/nodejs/node-addon-api/pull/637)
+* [[`03759f7759`](https://github.com/nodejs/node-addon-api/commit/03759f7759)] - ignore benchmark built archives (legendecas) [#631](https://github.com/nodejs/node-addon-api/pull/631)
+* [[`5eeabb0214`](https://github.com/nodejs/node-addon-api/commit/5eeabb0214)] - **tsfn**: Remove erroneous finalizer cleanup (Kevin Eady) [#636](https://github.com/nodejs/node-addon-api/pull/636)
+* [[`9e0e0f31e4`](https://github.com/nodejs/node-addon-api/commit/9e0e0f31e4)] - **src**: remove unnecessary forward declarations (Gabriel Schulhof) [#633](https://github.com/nodejs/node-addon-api/pull/633)
+* [[`79deefb6f3`](https://github.com/nodejs/node-addon-api/commit/79deefb6f3)] - **src**: explicitly disallow assign and copy (legendecas) [#590](https://github.com/nodejs/node-addon-api/pull/590)
+* [[`af50ac281b`](https://github.com/nodejs/node-addon-api/commit/af50ac281b)] - **error**: do not replace pending exception (Gabriel Schulhof) [#629](https://github.com/nodejs/node-addon-api/pull/629)
+* [[`b72f1d6978`](https://github.com/nodejs/node-addon-api/commit/b72f1d6978)] - Disable caching in ArrayBuffer (Tobias Nießen) [#611](https://github.com/nodejs/node-addon-api/pull/611)
+* [[`0e7483eb7b`](https://github.com/nodejs/node-addon-api/commit/0e7483eb7b)] - Fix code format in tests (Tobias Nießen) [#617](https://github.com/nodejs/node-addon-api/pull/617)
+* [[`6a0646356d`](https://github.com/nodejs/node-addon-api/commit/6a0646356d)] - add benchmarking framework (Gabriel Schulhof) [#623](https://github.com/nodejs/node-addon-api/pull/623)
+* [[`ffc71edd54`](https://github.com/nodejs/node-addon-api/commit/ffc71edd54)] - Add Env::RunScript (Tobias Nießen) [#616](https://github.com/nodejs/node-addon-api/pull/616)
+* [[`a1b106066e`](https://github.com/nodejs/node-addon-api/commit/a1b106066e)] - **src**: add templated function factories (Gabriel Schulhof) [#608](https://github.com/nodejs/node-addon-api/pull/608)
+* [[`c584343217`](https://github.com/nodejs/node-addon-api/commit/c584343217)] - Add GetPropertyNames, HasOwnProperty, Delete (#615) (Tobias Nießen) [#615](https://github.com/nodejs/node-addon-api/pull/615)
+* [[`3acc4b32f5`](https://github.com/nodejs/node-addon-api/commit/3acc4b32f5)] - Fix std::string encoding (#619) (Tobias Nießen) [#619](https://github.com/nodejs/node-addon-api/pull/619)
+* [[`e71d0eadcc`](https://github.com/nodejs/node-addon-api/commit/e71d0eadcc)] - \[doc\] Fixed links to array documentation (#613) (Nicola Del Gobbo)
+* [[`3dfb1f0591`](https://github.com/nodejs/node-addon-api/commit/3dfb1f0591)] - Change "WG" to "team" (Tobias Nießen)
+* [[`ce91e14860`](https://github.com/nodejs/node-addon-api/commit/ce91e14860)] - **objectwrap**: add template methods (Dmitry Ashkadov) [#604](https://github.com/nodejs/node-addon-api/pull/604)
+* [[`cfa71b60f7`](https://github.com/nodejs/node-addon-api/commit/cfa71b60f7)] - **object**: add templated property descriptors (Gabriel Schulhof) [#610](https://github.com/nodejs/node-addon-api/pull/610)
+* [[`734725e971`](https://github.com/nodejs/node-addon-api/commit/734725e971)] - Correctly define copy assignment operators. (Rolf Timmermans)
 
 ## 2019-11-21 Version 2.0.0, @NickNaso
 
@@ -66,7 +124,7 @@
 - Added test cases for `Napi::Date` api.
 - Added test cases for new features added to `Napi::ThreadSafeFunction`.
 
-### Commmits
+### Commits
 
 * [[`c881168d49`](https://github.com/nodejs/node-addon-api/commit/c881168d49)] - **tsfn**: add error checking on GetContext (#583) (Kevin Eady) [#583](https://github.com/nodejs/node-addon-api/pull/583)
 * [[`24d75dd82f`](https://github.com/nodejs/node-addon-api/commit/24d75dd82f)] - Merge pull request #588 from NickNaso/add-asyncprogress-worker-readme (Nicola Del Gobbo)
@@ -107,7 +165,7 @@
 
 - Fixed compilation problems that happen on Node.js with N-API version less than 4.
 
-### Commmits
+### Commits
 
 * [[`c20bcbd069`](https://github.com/nodejs/node-addon-api/commit/c20bcbd069)] - Merge pull request #518 from NickNaso/master (Nicola Del Gobbo)
 * [[`6720d57253`](https://github.com/nodejs/node-addon-api/commit/6720d57253)] - Create the native threadsafe\_function for test only for N-API greater than 3. (NickNaso)
@@ -135,7 +193,7 @@
 - Added test case for bool operator.
 - Fixed test case for `Napi::ObjectWrap`.
 
-### Commmits
+### Commits
 
 * [[`717c9ab163`](https://github.com/nodejs/node-addon-api/commit/717c9ab163)] - **AsyncWorker**: add GetResult() method (Kevin Eady) [#512](https://github.com/nodejs/node-addon-api/pull/512)
 * [[`d9d991bbc9`](https://github.com/nodejs/node-addon-api/commit/d9d991bbc9)] - **doc**: add ThreadSafeFunction to main README (#513) (Kevin Eady) [#513](https://github.com/nodejs/node-addon-api/pull/513)
@@ -172,7 +230,7 @@
 
 - Some minor corrections all over the documentation.
 
-### Commmits
+### Commits
 
 * [[`83b41c2fe4`](https://github.com/nodejs/node-addon-api/commit/83b41c2fe4)] - Document adding -fvisibility=hidden flag for macOS users (Nicola Del Gobbo) [#460](https://github.com/nodejs/node-addon-api/pull/460)
 * [[`1ed7ad8769`](https://github.com/nodejs/node-addon-api/commit/1ed7ad8769)] - **doc**: correct return type of Int32Value to int32\_t (Bill Gallafent) [#459](https://github.com/nodejs/node-addon-api/pull/459)
@@ -221,7 +279,7 @@
 - Removed unused member on `Napi::CallbackScope`.
 - Enabled `Napi::CallbackScope` only with N-API v3.
 
-### Commmits
+### Commits
 
 * [[`e7cd292a74`](https://github.com/nodejs/node-addon-api/commit/e7cd292a74)] - **src**: remove unused CallbackScope member (Gabriel Schulhof) [#391](https://github.com/nodejs/node-addon-api/pull/391)
 * [[`d47399fe25`](https://github.com/nodejs/node-addon-api/commit/d47399fe25)] - **src**: guard CallbackScope with N-API v3 (Michael Dawson) [#395](https://github.com/nodejs/node-addon-api/pull/395)
@@ -246,7 +304,7 @@ associated with a callback in place when making certain N-API calls
 - Added tests for `Napi::Array` class.
 - Added tests for `Napi::ArrayBuffer` class.
 
-### Commmits
+### Commits
 
 * [[`8ce605c657`](https://github.com/nodejs/node-addon-api/commit/8ce605c657)] - **build**: avoid using package-lock.json (Jaeseok Yoon) [#359](https://github.com/nodejs/node-addon-api/pull/359)
 * [[`fa3a6150b3`](https://github.com/nodejs/node-addon-api/commit/fa3a6150b3)] - **src**: use MakeCallback() -\> Call() in AsyncWorker (Jinho Bang) [#361](https://github.com/nodejs/node-addon-api/pull/361)

package/README.md

@@ -21,7 +21,7 @@ It is important to remember that *other* Node.js interfaces such as
 `libuv` (included in a project via `#include <uv.h>`) are not ABI-stable across
 Node.js major versions. Thus, an addon must use N-API and/or `node-addon-api`
 exclusively and build against a version of Node.js that includes an
-implementation of N-API (meaning a version of Node.js newer than 6.14.2) in
+implementation of N-API (meaning an active LTS version of Node.js) in
 order to benefit from ABI stability across Node.js major versions. Node.js
 provides an [ABI stability guide][] containing a detailed explanation of ABI
 stability in general, and the N-API ABI stability guarantee in particular.
@@ -42,11 +42,12 @@ to ideas specified in the **ECMA262 Language Specification**.
 - **[Examples](#examples)**
 - **[Tests](#tests)**
 - **[More resource and info about native Addons](#resources)**
+- **[Badges](#badges)**
 - **[Code of Conduct](CODE_OF_CONDUCT.md)**
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 2.0.2**
+## **Current version: 3.0.0**
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
 
@@ -54,6 +55,13 @@ to ideas specified in the **ECMA262 Language Specification**.
 
 <a name="setup"></a>
 
+node-addon-api is based on [N-API](https://nodejs.org/api/n-api.html) and supports using different N-API versions. 
+This allows addons built with it to run with Node.js versions which support the targeted N-API version. 
+**However** the node-addon-api support model is to support only the active LTS Node.js versions. This means that
+every year there will be a new major which drops support for the Node.js LTS version which has gone out of service.
+
+The oldest Node.js version supported by the current version of node-addon-api is Node.js 10.x.
+
 ## Setup
   - [Installation and usage](doc/setup.md)
   - [node-gyp](doc/node-gyp.md)
@@ -160,26 +168,63 @@ npm run-script dev:incremental
 
 Take a look and get inspired by our **[test suite](https://github.com/nodejs/node-addon-api/tree/master/test)**
 
-<a name="resources"></a>
+### **Benchmarks**
 
-## **Contributing**
+You can run the available benchmarks using the following command:
 
-We love contributions from the community to **node-addon-api**.
-See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on our philosophy around extending this module.
+```
+npm run-script benchmark
+```
+
+See [benchmark/README.md](benchmark/README.md) for more details about running and adding benchmarks.
+
+<a name="resources"></a>
 
 ### **More resource and info about native Addons**
 - **[C++ Addons](https://nodejs.org/dist/latest/docs/api/addons.html)**
 - **[N-API](https://nodejs.org/dist/latest/docs/api/n-api.html)**
 - **[N-API - Next Generation Node API for Native Modules](https://youtu.be/-Oniup60Afs)**
 
+As node-addon-api's core mission is to expose the plain C N-API as C++
+wrappers, tools that facilitate n-api/node-addon-api providing more
+convenient patterns on developing a Node.js add-ons with n-api/node-addon-api
+can be published to NPM as standalone packages. It is also recommended to tag
+such packages with `node-addon-api` to provide more visibility to the community.
+
+Quick links to NPM searches: [keywords:node-addon-api](https://www.npmjs.com/search?q=keywords%3Anode-addon-api).
+
+<a name="badges"></a>
+
+### **Badges**
+
+The use of badges is recommended to indicate the minimum version of N-API
+required for the module. This helps to determine which Node.js major versions are
+supported. Addon maintainers can consult the [N-API support matrix][] to determine
+which Node.js versions provide a given N-API version. The following badges are
+available:
+
+![N-API v1 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/N-API%20v1%20Badge.svg)
+![N-API v2 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/N-API%20v2%20Badge.svg)
+![N-API v3 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/N-API%20v3%20Badge.svg)
+![N-API v4 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/N-API%20v4%20Badge.svg)
+![N-API v5 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/N-API%20v5%20Badge.svg)
+![N-API v6 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/N-API%20v6%20Badge.svg)
+![N-API Experimental Version Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/N-API%20Experimental%20Version%20Badge.svg)
+
+## **Contributing**
+
+We love contributions from the community to **node-addon-api**!
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on our philosophy around extending this module.
+
 <a name="contributors"></a>
 
-## WG Members / Collaborators
+## Team members
 
 ### Active
 | Name                | GitHub Link                                           |
 | ------------------- | ----------------------------------------------------- |
 | Anna Henningsen     | [addaleax](https://github.com/addaleax)               |
+| Chengzhong Wu       | [legendecas](https://github.com/legendecas)           |
 | Gabriel Schulhof    | [gabrielschulhof](https://github.com/gabrielschulhof) |
 | Hitesh Kanwathirtha | [digitalinfinity](https://github.com/digitalinfinity) |
 | Jim Schlight        | [jschlight](https://github.com/jschlight)             |
@@ -201,3 +246,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on our philosophy around
 Licensed under [MIT](./LICENSE.md)
 
 [ABI stability guide]: https://nodejs.org/en/docs/guides/abi-stability/
+[N-API support matrix]: https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api_version_matrix

package/benchmark/README.md

@@ -0,0 +1,47 @@
+# Benchmarks
+
+## Running the benchmarks
+
+From the parent directory, run
+
+```bash
+npm run-script benchmark
+```
+
+The above script supports the following arguments:
+
+* `--benchmarks=...`: A semicolon-separated list of benchmark names. These names
+    will be mapped to file names in this directory by appending `.js`.
+
+## Adding benchmarks
+
+The steps below should be followed when adding new benchmarks.
+
+0. Decide on a name for the benchmark. This name will be used in several places.
+   This example will use the name `new_benchmark`.
+
+0. Create files `new_benchmark.cc` and `new_benchmark.js` in this directory.
+
+0. Copy an existing benchmark in `binding.gyp` and change the target name prefix
+    and the source file name to `new_benchmark`. This should result in two new
+    targets which look like this:
+
+    ```gyp
+      {
+        'target_name': 'new_benchmark',
+        'sources': [ 'new_benchmark.cc' ],
+        'includes': [ '../except.gypi' ],
+      },
+      {
+        'target_name': 'new_benchmark_noexcept',
+        'sources': [ 'new_benchmark.cc' ],
+        'includes': [ '../noexcept.gypi' ],
+      },
+    ```
+
+    There should always be a pair of targets: one bearing the name of the
+    benchmark and configured with C++ exceptions enabled, and one bearing the
+    same name followed by the suffix `_noexcept` and configured with C++
+    exceptions disabled. This will ensure that the benchmark can be written to
+    cover both the case where C++ exceptions are enabled and the case where they
+    are disabled.

package/benchmark/binding.gyp

@@ -0,0 +1,25 @@
+{
+  'target_defaults': { 'includes': ['../common.gypi'] },
+  'targets': [
+    {
+      'target_name': 'function_args',
+      'sources': [ 'function_args.cc' ],
+      'includes': [ '../except.gypi' ],
+    },
+    {
+      'target_name': 'function_args_noexcept',
+      'sources': [ 'function_args.cc' ],
+      'includes': [ '../noexcept.gypi' ],
+    },
+    {
+      'target_name': 'property_descriptor',
+      'sources': [ 'property_descriptor.cc' ],
+      'includes': [ '../except.gypi' ],
+    },
+    {
+      'target_name': 'property_descriptor_noexcept',
+      'sources': [ 'property_descriptor.cc' ],
+      'includes': [ '../noexcept.gypi' ],
+    },
+  ]
+}

package/benchmark/function_args.cc

@@ -0,0 +1,153 @@
+#include "napi.h"
+
+static napi_value NoArgFunction_Core(napi_env env, napi_callback_info info) {
+  (void) env;
+  (void) info;
+  return nullptr;
+}
+
+static napi_value OneArgFunction_Core(napi_env env, napi_callback_info info) {
+  size_t argc = 1;
+  napi_value argv;
+  if (napi_get_cb_info(env, info, &argc, &argv, nullptr, nullptr) != napi_ok) {
+    return nullptr;
+  }
+  (void) argv;
+  return nullptr;
+}
+
+static napi_value TwoArgFunction_Core(napi_env env, napi_callback_info info) {
+  size_t argc = 2;
+  napi_value argv[2];
+  if (napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr) != napi_ok) {
+    return nullptr;
+  }
+  (void) argv[0];
+  (void) argv[1];
+  return nullptr;
+}
+
+static napi_value ThreeArgFunction_Core(napi_env env, napi_callback_info info) {
+  size_t argc = 3;
+  napi_value argv[3];
+  if (napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr) != napi_ok) {
+    return nullptr;
+  }
+  (void) argv[0];
+  (void) argv[1];
+  (void) argv[2];
+  return nullptr;
+}
+
+static napi_value FourArgFunction_Core(napi_env env, napi_callback_info info) {
+  size_t argc = 4;
+  napi_value argv[4];
+  if (napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr) != napi_ok) {
+    return nullptr;
+  }
+  (void) argv[0];
+  (void) argv[1];
+  (void) argv[2];
+  (void) argv[3];
+  return nullptr;
+}
+
+static void NoArgFunction(const Napi::CallbackInfo& info) {
+  (void) info;
+}
+
+static void OneArgFunction(const Napi::CallbackInfo& info) {
+  Napi::Value argv0 = info[0]; (void) argv0;
+}
+
+static void TwoArgFunction(const Napi::CallbackInfo& info) {
+  Napi::Value argv0 = info[0]; (void) argv0;
+  Napi::Value argv1 = info[1]; (void) argv1;
+}
+
+static 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;
+}
+
+static 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;
+}
+
+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;
+  napi_status status;
+
+  status = napi_create_function(env,
+                                "noArgFunction",
+                                NAPI_AUTO_LENGTH,
+                                NoArgFunction_Core,
+                                nullptr,
+                                &no_arg_function);
+  NAPI_THROW_IF_FAILED(env, status, Napi::Object());
+
+  status = napi_create_function(env,
+                                "oneArgFunction",
+                                NAPI_AUTO_LENGTH,
+                                OneArgFunction_Core,
+                                nullptr,
+                                &one_arg_function);
+  NAPI_THROW_IF_FAILED(env, status, Napi::Object());
+
+  status = napi_create_function(env,
+                                "twoArgFunction",
+                                NAPI_AUTO_LENGTH,
+                                TwoArgFunction_Core,
+                                nullptr,
+                                &two_arg_function);
+  NAPI_THROW_IF_FAILED(env, status, Napi::Object());
+
+  status = napi_create_function(env,
+                                "threeArgFunction",
+                                NAPI_AUTO_LENGTH,
+                                ThreeArgFunction_Core,
+                                nullptr,
+                                &three_arg_function);
+  NAPI_THROW_IF_FAILED(env, status, Napi::Object());
+
+  status = napi_create_function(env,
+                                "fourArgFunction",
+                                NAPI_AUTO_LENGTH,
+                                FourArgFunction_Core,
+                                nullptr,
+                                &four_arg_function);
+  NAPI_THROW_IF_FAILED(env, status, Napi::Object());
+
+  Napi::Object core = Napi::Object::New(env);
+  core["noArgFunction"] = Napi::Value(env, no_arg_function);
+  core["oneArgFunction"] = Napi::Value(env, one_arg_function);
+  core["twoArgFunction"] = Napi::Value(env, two_arg_function);
+  core["threeArgFunction"] = Napi::Value(env, three_arg_function);
+  core["fourArgFunction"] = Napi::Value(env, four_arg_function);
+  exports["core"] = core;
+
+  Napi::Object cplusplus = Napi::Object::New(env);
+  cplusplus["noArgFunction"] = Napi::Function::New(env, NoArgFunction);
+  cplusplus["oneArgFunction"] = Napi::Function::New(env, OneArgFunction);
+  cplusplus["twoArgFunction"] = Napi::Function::New(env, TwoArgFunction);
+  cplusplus["threeArgFunction"] = Napi::Function::New(env, ThreeArgFunction);
+  cplusplus["fourArgFunction"] = Napi::Function::New(env, FourArgFunction);
+  exports["cplusplus"] = cplusplus;
+
+  Napi::Object templated = Napi::Object::New(env);
+  templated["noArgFunction"] = Napi::Function::New<NoArgFunction>(env);
+  templated["oneArgFunction"] = Napi::Function::New<OneArgFunction>(env);
+  templated["twoArgFunction"] = Napi::Function::New<TwoArgFunction>(env);
+  templated["threeArgFunction"] = Napi::Function::New<ThreeArgFunction>(env);
+  templated["fourArgFunction"] = Napi::Function::New<FourArgFunction>(env);
+  exports["templated"] = templated;
+
+  return exports;
+}
+
+NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)

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);
+    }
+  });