node-addon-api 1.5.0 → 1.6.3

package/CHANGELOG.md

@@ -1,6 +1,108 @@
 # node-addon-api Changelog
 
-## 2018-10-03 Version 1.5.0 (Current), @NickNasso
+## 2019-04-03 Version 1.6.3, @NickNaso
+
+### Notable changes:
+
+#### API
+
+- Added `SuppressDestruct` method to `Napi::AsyncWorker`.
+- Added new build targets for debug.
+- Exposed macros that throw errors.
+- Fixed memory leaks caused by callback data when a napi error occurs.
+- Fixed missing `void *data` usage in `Napi::PropertyDescriptors`.
+
+#### Documentation
+
+- Some minor corrections all over the documentation
+
+### Commmits
+
+* [[`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)
+* [[`b0f6b601aa`](https://github.com/nodejs/node-addon-api/commit/b0f6b601aa)] - **src**: add AsyncWorker destruction suppression (Gabriel Schulhof) [#407](https://github.com/nodejs/node-addon-api/pull/407)
+* [[`72b1975cff`](https://github.com/nodejs/node-addon-api/commit/72b1975cff)] - **doc**: fix links to the Property Descriptor docs (Ryuichi Okumura) [#458](https://github.com/nodejs/node-addon-api/pull/458)
+* [[`fcfc612728`](https://github.com/nodejs/node-addon-api/commit/fcfc612728)] - **build**: new build targets for debug purposes (Jinho Bang) [#186](https://github.com/nodejs/node-addon-api/pull/186)
+* [[`c629553cd7`](https://github.com/nodejs/node-addon-api/commit/c629553cd7)] - **doc**: minor doc corrections and clarifications (Bruce A. MacNaughton) [#426](https://github.com/nodejs/node-addon-api/pull/426)
+* [[`7b87e0b999`](https://github.com/nodejs/node-addon-api/commit/7b87e0b999)] - **doc**: update number.md (Bernardo Heynemann) [#436](https://github.com/nodejs/node-addon-api/pull/436)
+* [[`fcf173d2a1`](https://github.com/nodejs/node-addon-api/commit/fcf173d2a1)] - **src**: expose macros that throw errors (Gabriel Schulhof) [#448](https://github.com/nodejs/node-addon-api/pull/448)
+* [[`b409a2f987`](https://github.com/nodejs/node-addon-api/commit/b409a2f987)] - **package**: add npm search keywords (Sam Roberts) [#452](https://github.com/nodejs/node-addon-api/pull/452)
+* [[`0bc7987806`](https://github.com/nodejs/node-addon-api/commit/0bc7987806)] - **doc**: fix references to Weak and Persistent (Jake Barnes) [#428](https://github.com/nodejs/node-addon-api/pull/428)
+* [[`ad6f569f85`](https://github.com/nodejs/node-addon-api/commit/ad6f569f85)] - **doc**: dix typo (Abhishek Kumar Singh) [#435](https://github.com/nodejs/node-addon-api/pull/435)
+* [[`28df833a49`](https://github.com/nodejs/node-addon-api/commit/28df833a49)] - Merge pull request #441 from jschlight/master (Jim Schlight)
+* [[`4921e74d83`](https://github.com/nodejs/node-addon-api/commit/4921e74d83)] - Rearranges names to be alphabetical (Jim Schlight)
+* [[`48220335b0`](https://github.com/nodejs/node-addon-api/commit/48220335b0)] - Membership review update (Jim Schlight)
+* [[`44f0695533`](https://github.com/nodejs/node-addon-api/commit/44f0695533)] - Merge pull request #394 from NickNaso/create\_release (Nicola DelGobbo)
+* [[`fa49d68416`](https://github.com/nodejs/node-addon-api/commit/fa49d68416)] - **doc**: fix some `Finalizer` signatures (Philipp Renoth) [#414](https://github.com/nodejs/node-addon-api/pull/414)
+* [[`020ac4a628`](https://github.com/nodejs/node-addon-api/commit/020ac4a628)] - **src**: make `Object::GetPropertyNames()` const (Philipp Renoth)[#415](https://github.com/nodejs/node-addon-api/pull/415)
+* [[`91eaa6f4cb`](https://github.com/nodejs/node-addon-api/commit/91eaa6f4cb)] - **src**: fix callbackData leaks on error napi status (Philipp Renoth) [#417](https://github.com/nodejs/node-addon-api/pull/417)
+* [[`0b40275752`](https://github.com/nodejs/node-addon-api/commit/0b40275752)] - **src**: fix noexcept control flow issues (Philipp Renoth) [#420](https://github.com/nodejs/node-addon-api/pull/420)
+* [[`c1ff2936f9`](https://github.com/nodejs/node-addon-api/commit/c1ff2936f9)] - **src**: fix missing void\*data usage in PropertyDescriptors (Luciano Martorella) [#374](https://github.com/nodejs/node-addon-api/pull/374)
+
+## 2018-11-29 Version 1.6.2, @NickNaso
+
+### Notable changes:
+
+#### API
+
+- Fixed selection logic for version 6.x.
+
+### Commmits
+
+* [[`07a0fc4e95`](https://github.com/nodejs/node-addon-api/commit/07a0fc4e95)] - **src**: fix selection logic for 6.x (Michael Dawson) [#402](https://github.com/nodejs/node-addon-api/pull/402)
+
+## 2018-11-14 Version 1.6.1, @NickNaso
+
+### Notable changes:
+
+#### Documentation
+
+- Updated links for examples to point to node-addon-examples repo.
+- Fixed typos on some parts of documentation.
+
+#### API
+
+- Removed unused member on `Napi::CallbackScope`.
+- Enabled `Napi::CallbackScope` only with N-API v3.
+
+### Commmits
+
+* [[`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)
+* [[`29a0262ab9`](https://github.com/nodejs/node-addon-api/commit/29a0262ab9)] - **doc**: fix typo (Dongjin Na) [#385](https://github.com/nodejs/node-addon-api/pull/385)
+* [[`b6dc15b88d`](https://github.com/nodejs/node-addon-api/commit/b6dc15b88d)] - **doc**: make links point to node-addon-examples repo (Nicola Del Gobbo) [#389](https://github.com/nodejs/node-addon-api/pull/389)
+
+## 2018-11-02 Version 1.6.0, @NickNaso
+
+### Notable changes:
+
+#### Documentation
+
+- Improved documentation about ABI stability.
+
+#### API
+
+- Add `Napi::CallbackScope` class that help to have the equivalent of the scope
+associated with a callback in place when making certain N-API calls
+
+#### TEST
+
+- Added tests for `Napi::Array` class.
+- Added tests for `Napi::ArrayBuffer` class.
+
+### Commmits
+
+* [[`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)
+* [[`2342415463`](https://github.com/nodejs/node-addon-api/commit/2342415463)] - **test**: create test objects in the stack instead of the heap (Dongjin Na) [#371](https://github.com/nodejs/node-addon-api/pull/371)
+* [[`67b7db0a6f`](https://github.com/nodejs/node-addon-api/commit/67b7db0a6f)] - **test**: write tests for Array class (Jaeseok Yoon) [#363](https://github.com/nodejs/node-addon-api/pull/363)
+* [[`729f6dc4ee`](https://github.com/nodejs/node-addon-api/commit/729f6dc4ee)] - **test**: add arraybuffer tests (Dongjin Na) [#369](https://github.com/nodejs/node-addon-api/pull/369)
+* [[`405f3e5b5b`](https://github.com/nodejs/node-addon-api/commit/405f3e5b5b)] - **src**: implement CallbackScope class (Jinho Bang) [#362](https://github.com/nodejs/node-addon-api/pull/362)
+* [[`015d95312f`](https://github.com/nodejs/node-addon-api/commit/015d95312f)] - **doc**: fix Napi::Reference link (Gentilhomme) [#365](https://github.com/nodejs/node-addon-api/pull/365)
+* [[`fd65078e3c`](https://github.com/nodejs/node-addon-api/commit/fd65078e3c)] - README.md: link to new ABI stability guide (Gabriel Schulhof) [#367](https://github.com/nodejs/node-addon-api/pull/367)
+* [[`ffebf9ba9a`](https://github.com/nodejs/node-addon-api/commit/ffebf9ba9a)] - Updates for release 1.5.0 (NickNaso)
+
+## 2018-10-03 Version 1.5.0, @NickNaso
 
 ### Notable changes:
 
@@ -12,7 +114,7 @@
 #### API
 
 - Add `Napi::AsyncContext` class to handle asynchronous operation.
-- Add B`Napi::igInt` class to work with BigInt type.
+- Add `Napi::BigInt` class to work with BigInt type.
 - Add `Napi::VersionManagement` class to retrieve the versions of Node.js and N-API.
 - Fix potential memory leaks.
 - DataView feature is enabled by default
@@ -65,7 +167,7 @@ yet backported in the previous Node.js version.
 * [[`622ffaea76`](https://github.com/nodejs/node-addon-api/commit/622ffaea76)] - **test**: Tighten up compiler warnings (Mikhail Cheshkov) [#315](https://github.com/nodejs/node-addon-api/pull/315)
 * [[`fd3c37b0f2`](https://github.com/nodejs/node-addon-api/commit/fd3c37b0f2)] - **tools**: add tool to check for N-API modules (Gabriel Schulhof) [#346](https://github.com/nodejs/node-addon-api/pull/346)
 
-## 2018-07-19 Version 1.4.0, @NickNasso
+## 2018-07-19 Version 1.4.0, @NickNaso
 
 ### Notable changes:
 

package/README.md

@@ -19,17 +19,19 @@ of Node.js.
 
 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, and addon must use N-API and/or `node-addon-api`
+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
-order to benefit from ABI stability across Node.js major versions.
+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.
 
 As new APIs are added to N-API, node-addon-api must be updated to provide
 wrappers for those new APIs. For this reason node-addon-api provides
 methods that allow callers to obtain the underlying N-API handles so
 direct calls to N-API and the use of the objects/methods provided by
 node-addon-api can be used together. For example, in order to be able
-to use an API for which the node-add-api does not yet provide a wrapper.
+to use an API for which the node-addon-api does not yet provide a wrapper.
 
 APIs exposed by node-addon-api are generally used to create and
 manipulate JavaScript values. Concepts and operations generally map
@@ -44,7 +46,7 @@ to ideas specified in the **ECMA262 Language Specification**.
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 1.5**
+## **Current version: 1.6.3**
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
 
@@ -111,16 +113,16 @@ The following is the documentation for node-addon-api.
 
 ### **Examples**
 
-Are you new to **node-addon-api**? Take a look at our **[examples](https://github.com/nodejs/abi-stable-node-addon-examples)**
+Are you new to **node-addon-api**? Take a look at our **[examples](https://github.com/nodejs/node-addon-examples)**
 
-- **[Hello World](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/1_hello_world/node-addon-api)**
-- **[Pass arguments to a function](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/2_function_arguments/node-addon-api)**
-- **[Callbacks](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/3_callbacks/node-addon-api)**
-- **[Object factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)**
-- **[Function factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/5_function_factory/node-addon-api)**
-- **[Wrapping C++ Object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/6_object_wrap/node-addon-api)**
-- **[Factory of wrapped object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/7_factory_wrap/node-addon-api)**
-- **[Passing wrapped object around](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/8_passing_wrapped/node-addon-api)**
+- **[Hello World](https://github.com/nodejs/node-addon-examples/tree/master/1_hello_world/node-addon-api)**
+- **[Pass arguments to a function](https://github.com/nodejs/node-addon-examples/tree/master/2_function_arguments/node-addon-api)**
+- **[Callbacks](https://github.com/nodejs/node-addon-examples/tree/master/3_callbacks/node-addon-api)**
+- **[Object factory](https://github.com/nodejs/node-addon-examples/tree/master/4_object_factory/node-addon-api)**
+- **[Function factory](https://github.com/nodejs/node-addon-examples/tree/master/5_function_factory/node-addon-api)**
+- **[Wrapping C++ Object](https://github.com/nodejs/node-addon-examples/tree/master/6_object_wrap/node-addon-api)**
+- **[Factory of wrapped object](https://github.com/nodejs/node-addon-examples/tree/master/7_factory_wrap/node-addon-api)**
+- **[Passing wrapped object around](https://github.com/nodejs/node-addon-examples/tree/master/8_passing_wrapped/node-addon-api)**
 
 <a name="tests"></a>
 
@@ -139,6 +141,20 @@ npm install
 npm test --disable-deprecated
 ```
 
+### **Debug**
+
+To run the **node-addon-api** tests with `--debug` option:
+
+```
+npm run-script dev
+```
+
+If you want faster build, you might use the following option:
+
+```
+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>
@@ -150,20 +166,29 @@ Take a look and get inspired by our **[test suite](https://github.com/nodejs/nod
 
 <a name="contributors"></a>
 
-### WG Members / Collaborators
-| Name                | GitHub link                                           |
+## WG Members / Collaborators
+
+### Active
+| Name                | GitHub Link                                           |
 | ------------------- | ----------------------------------------------------- |
 | Anna Henningsen     | [addaleax](https://github.com/addaleax)               |
 | Arunesh Chandra     | [aruneshchandra](https://github.com/aruneshchandra)   |
-| Benjamin Byholm     | [kkoopa](https://github.com/kkoopa)                   |
 | Gabriel Schulhof    | [gabrielschulhof](https://github.com/gabrielschulhof) |
 | Hitesh Kanwathirtha | [digitalinfinity](https://github.com/digitalinfinity) |
-| Jason Ginchereau    | [jasongin](https://github.com/jasongin)               |
+| Jim Schlight        | [jschlight](https://github.com/jschlight)             |
 | Michael Dawson      | [mhdawson](https://github.com/mhdawson)               |
 | Nicola Del Gobbo    | [NickNaso](https://github.com/NickNaso)               |
-| Sampson Gao         | [sampsongao](https://github.com/sampsongao)           |
 | Taylor Woll         | [boingoing](https://github.com/boingoing)             |
 
+### Emeritus
+| Name                | GitHub Link                                           |
+| ------------------- | ----------------------------------------------------- |
+| Benjamin Byholm     | [kkoopa](https://github.com/kkoopa)                   |
+| Jason Ginchereau    | [jasongin](https://github.com/jasongin)               |
+| Sampson Gao         | [sampsongao](https://github.com/sampsongao)           |
+
 <a name="license"></a>
 
 Licensed under [MIT](./LICENSE.md)
+
+[ABI stability guide]: https://nodejs.org/en/docs/guides/abi-stability/

package/doc/async_operations.md

@@ -27,3 +27,5 @@ other asynchronous mechanism, the following API is necessary to ensure an
 asynchronous operation is properly tracked by the runtime:
 
 - **[AsyncContext](async_context.md)**
+
+- **[CallbackScope](callback_scope.md)**

package/doc/async_worker.md

@@ -66,6 +66,15 @@ the computation that happened in the `Napi::AsyncWorker::Execute` method, unless
 the default implementation of `Napi::AsyncWorker::OnOK` or
 `Napi::AsyncWorker::OnError` is overridden.
 
+### SuppressDestruct
+
+```cpp
+void Napi::AsyncWorker::SuppressDestruct();
+```
+
+Prevents the destruction of the `Napi::AsyncWorker` instance upon completion of
+the `Napi::AsyncWorker::OnOK` callback.
+
 ### SetError
 
 Sets the error message for the error that happened during the execution. Setting

package/doc/callback_scope.md

@@ -0,0 +1,54 @@
+# CallbackScope
+
+There are cases (for example, resolving promises) where it is necessary to have
+the equivalent of the scope associated with a callback in place when making
+certain N-API calls.
+
+## Methods
+
+### Constructor
+
+Creates a new callback scope on the stack.
+
+```cpp
+Napi::CallbackScope::CallbackScope(napi_env env, napi_callback_scope scope);
+```
+
+- `[in] env`: The environment in which to create the `Napi::CallbackScope`.
+- `[in] scope`: The pre-existing `napi_callback_scope` or `Napi::CallbackScope`.
+
+### Constructor
+
+Creates a new callback scope on the stack.
+
+```cpp
+Napi::CallbackScope::CallbackScope(napi_env env, napi_async_context context);
+```
+
+- `[in] env`: The environment in which to create the `Napi::CallbackScope`.
+- `[in] async_context`: The pre-existing `napi_async_context` or `Napi::AsyncContext`.
+
+### Destructor
+
+Deletes the instance of `Napi::CallbackScope` object.
+
+```cpp
+virtual Napi::CallbackScope::~CallbackScope();
+```
+
+### Env
+
+```cpp
+Napi::Env Napi::CallbackScope::Env() const;
+```
+
+Returns the `Napi::Env` associated with the `Napi::CallbackScope`.
+
+## Operator
+
+```cpp
+Napi::CallbackScope::operator napi_callback_scope() const;
+```
+
+Returns the N-API `napi_callback_scope` wrapped by the `Napi::CallbackScope`
+object. This can be used to mix usage of the C N-API and node-addon-api.

package/doc/class_property_descriptor.md

@@ -8,7 +8,7 @@ This prevents using descriptors from a different class when defining a new class
 
 ## Methods
 
-### Contructor
+### Constructor
 
 Creates new instance of `Napi::ClassPropertyDescriptor` descriptor object.
 
@@ -33,4 +33,4 @@ Returns the original N-API `napi_property_descriptor` wrapped inside the `Napi::
 operator const napi_property_descriptor&() const { return _desc; }
 ```
 
-Returns the original N-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor`
+Returns the original N-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor`

package/doc/creating_a_release.md

@@ -1,41 +1,62 @@
 # Creating a release
 
-Only collaborators in npm for node-addon-api can create releases.
+Only collaborators in npm for **node-addon-api** can create releases.
 If you want to be able to do releases ask one of the existing
-collaborators to add you.  If necessary you can ask the build
+collaborators to add you. If necessary you can ask the build
 Working Group who manages the Node.js npm user to add you if
 there are no other active collaborators.
 
+## Prerequisites
+
+Before to start creating a new release check if you have installed the following
+tools:
+
+* [Changelog maker](https://www.npmjs.com/package/changelog-maker)
+
+If not please follow the instruction reported in the tool's documentation to 
+install it.
+
+## Publish new release
+
 These are the steps to follow to create a new release:
 
-* Open an issue in the node-addon-api repo documenting
-  the intent to create a new release.  Give people some
-  time to comment or suggest PRs that should land first.
+* Open an issue in the **node-addon-api** repo documenting the intent to create a
+new release. Give people some time to comment or suggest PRs that should land first.
 
 * Validate all tests pass by running npm test on master.
 
-* Use https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api/
-  to validate tests pass for latest 9, 8, 6, 4 releases
-  (note there are still some issues on SmartOS and
-   Windows in the testing).
+* Update the version in **package.json** appropriately.
 
-* Update the version in package.json appropriately.
+* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/master/README.md) 
+to show the new version as the latest.
 
-* Update the 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 
+    > 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)
+following the style used in publishing the previous release.
+
+* Add any new contributors to the "contributors" section in the package.json
+
+* Validate all tests pass by running npm test on master.
 
-* Add any new contributors to the "contributors" section in
-  the package.json
+* 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
+Windows in the testing).
 
-* Do a clean checkout of node-add-api.
+* Do a clean checkout of node-addon-api.
 
 * Login and then run `npm publish`.
 
 * Create a release in Github (look at existing releases for an example).
 
 * Validate that you can run `npm install node-addon-api` successfully
-  and that the correct version is installed.
+and that the correct version is installed.
 
-* Comment on the issue opened in the first step that the
-  release has been created and close the issue.
+* Comment on the issue opened in the first step that the release has been created
+and close the issue.
 
 * Tweet that the release has been created.

package/doc/error_handling.md

@@ -153,3 +153,34 @@ if (env.IsExceptionPending()) {
 
 Since the exception was cleared here, it will not be propagated as a JavaScript
 exception after the native callback returns.
+
+## Calling N-API directly from a **node-addon-api** addon
+
+**node-addon-api** provides macros for throwing errors in response to non-OK
+`napi_status` results when calling [N-API](https://nodejs.org/docs/latest/api/n-api.html)
+functions from within a native addon. These macros are defined differently
+depending on whether C++ exceptions are enabled or not, but are available for
+use in either case.
+
+### `NAPI_THROW(e, ...)`
+
+This macro accepts a `Napi::Error`, throws it, and returns the value given as
+the last parameter. If C++ exceptions are enabled (by defining
+`NAPI_CPP_EXCEPTIONS` during the build), the return value will be ignored.
+
+### `NAPI_THROW_IF_FAILED(env, status, ...)`
+
+This macro accepts a `Napi::Env` and a `napi_status`. It constructs an error
+from the `napi_status`, throws it, and returns the value given as the last
+parameter. If C++ exceptions are enabled (by defining `NAPI_CPP_EXCEPTIONS`
+during the build), the return value will be ignored.
+
+### `NAPI_THROW_IF_FAILED_VOID(env, status)`
+
+This macro accepts a `Napi::Env` and a `napi_status`. It constructs an error
+from the `napi_status`, throws it, and returns.
+
+### `NAPI_FATAL_IF_FAILED(status, location, message)`
+
+This macro accepts a `napi_status`, a C string indicating the location where the
+error occurred, and a second C string for the message to display.

package/doc/function_reference.md

@@ -23,7 +23,7 @@ Creates a "weak" reference to the value, in that the initial reference count is
 set to 0.
 
 ```cpp
-static Napi::FunctionReference Napi::FunctionReference::Weak(const Napi::Function& value);
+static Napi::FunctionReference Napi::Weak(const Napi::Function& value);
 ```
 
 - `[in] value`: The value which is to be referenced.
@@ -36,7 +36,7 @@ Creates a "persistent" reference to the value, in that the initial reference
 count is set to 1.
 
 ```cpp
-static Napi::FunctionReference Napi::FunctionReference::Persistent(const Napi::Function& value);
+static Napi::FunctionReference Napi::Persistent(const Napi::Function& value);
 ```
 
 - `[in] value`: The value which is to be referenced.

package/doc/number.md

@@ -24,8 +24,8 @@ Creates a new instance of a `Napi::Number` object.
 Napi::Number(napi_env env, napi_value value);
 ```
 
- - `[in] env`: The `napi_env` environment in which to construct the `Napi::Nuber` object.
- - `[in] value`: The `napi_value` which is a handle for a JavaScript `Number`.
+ - `[in] env`: The `napi_env` environment in which to construct the `Napi::Number` object.
+ - `[in] value`: The JavaScript value holding a number.
 
  Returns a non-empty `Napi::Number` object.
 
@@ -36,14 +36,14 @@ Napi::Number(napi_env env, napi_value value);
 ```cpp
 Napi::Number Napi::Number::New(napi_env env, double value);
 ```
- - `[in] env`: The `napi_env` environment in which to construct the `Napi::Nuber` object.
- - `[in] value`: The `napi_value` which is a handle for a JavaScript `Number`.
+ - `[in] env`: The `napi_env` environment in which to construct the `Napi::Number` object.
+ - `[in] value`: The C++ primitive from which to instantiate the `Napi::Number`.
 
 Creates a new instance of a `Napi::Number` object.
 
 ### Int32Value
 
-Converts a `Napi::Number` value to a `uint32_t` primitive type.
+Converts a `Napi::Number` value to a `int32_t` primitive type.
 
 ```cpp
 Napi::Number::Int32Value() const;

package/doc/object.md

@@ -108,7 +108,7 @@ Napi::Value Napi::Object::Get(____ key);
 ```
 - `[in] key`: The name of the property to return the value for.
 
-Returns the [`Napi::Value`](value.md) associated with the key property. Returns NULL if no such key exists.
+Returns the [`Napi::Value`](value.md) associated with the key property. Returns the value *undefined* if the key does not exist.
 
 The `key` can be any of the following types:
 - `napi_value`
@@ -142,7 +142,7 @@ Note: This is equivalent to the JavaScript instanceof operator.
 ```cpp
 void Napi::Object::DefineProperty (const Napi::PropertyDescriptor& property);
 ```
-- `[in] property`: A [`Napi::PropertyDescriptor`](propertydescriptor.md).
+- `[in] property`: A [`Napi::PropertyDescriptor`](property_descriptor.md).
 
 Define a property on the object.
 
@@ -151,7 +151,7 @@ Define a property on the object.
 ```cpp
 void Napi::Object::DefineProperties (____ properties)
 ```
-- `[in] properties`: A list of [`Napi::PropertyDescriptor`](propertydescriptor.md). Can be one of the following types:
+- `[in] properties`: A list of [`Napi::PropertyDescriptor`](property_descriptor.md). Can be one of the following types:
 	- const std::initializer_list<Napi::PropertyDescriptor>&
 	- const std::vector<Napi::PropertyDescriptor>&
 

package/doc/object_reference.md

@@ -2,7 +2,7 @@
 
 `Napi::ObjectReference` is a subclass of [`Napi::Reference`](reference.md), and is equivalent to an instance of `Napi::Reference<Object>`. This means that a `Napi::ObjectReference` holds a [`Napi::Object`](object.md), and a count of the number of references to that Object. When the count is greater than 0, an ObjectReference is not eligible for garbage collection. This ensures that the Object being held as a value of the ObjectReference will remain accessible, even if the original Object no longer is. However, ObjectReference is unique from a Reference since properties can be set and get to the Object itself that can be accessed through the ObjectReference.
 
-For more general information on references, please consult [`Napi::Reference`](referenc.md).
+For more general information on references, please consult [`Napi::Reference`](reference.md).
 
 ## Example
 ```cpp
@@ -40,7 +40,7 @@ static Napi::ObjectReference Napi::ObjectReference::New(const Napi::Object& valu
 Returns the newly created reference.
 
 ```cpp
-static Napi::ObjectReference Napi::ObjectReference::Weak(const Napi::Object& value);
+static Napi::ObjectReference Napi::Weak(const Napi::Object& value);
 ```
 
 Creates a "weak" reference to the value, in that the initial count of number of references is set to 0.
@@ -50,7 +50,7 @@ Creates a "weak" reference to the value, in that the initial count of number of
 Returns the newly created reference.
 
 ```cpp
-static Napi::ObjectReference Napi::ObjectReference::Persistent(const Napi::Object& value);
+static Napi::ObjectReference Napi::Persistent(const Napi::Object& value);
 ```
 
 Creates a "persistent" reference to the value, in that the initial count of number of references is set to 1.

package/doc/object_wrap.md

@@ -116,7 +116,7 @@ against the class constructor.
 
 ## Methods
 
-### Contructor
+### Constructor
 
 Creates a new instance of a JavaScript object that wraps native instance.
 

package/doc/property_descriptor.md

@@ -192,7 +192,7 @@ static Napi::PropertyDescriptor Napi::PropertyDescriptor::Function (
 		            void *data = nullptr);
 ```
 
-* `[in] env`: The environemnt in which to create this accessor.
+* `[in] env`: The environment in which to create this accessor.
 * `[in] name`: The name of the Callable function.
 * `[in] cb`: The function
 * `[in] attributes`: Potential attributes for the getter function.

package/doc/setup.md

@@ -55,8 +55,19 @@ To use **N-API** in a native module:
 ```gyp
   'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ],
 ```
-
-  4. Include `napi.h` in the native module code.
+  4. If you would like your native addon to support OSX, please also add the
+  following settings in the `binding.gyp` file:
+
+  ```gyp
+  ['OS=="mac"', {
+      'cflags+': ['-fvisibility=hidden'],
+      'xcode_settings': {
+        'GCC_SYMBOLS_PRIVATE_EXTERN': 'YES', # -fvisibility=hidden
+      }
+  }]
+  ```
+
+  5. Include `napi.h` in the native module code.
      To ensure only ABI-stable APIs are used, DO NOT include
      `node.h`, `nan.h`, or `v8.h`.
 

package/index.js

@@ -17,6 +17,7 @@ var versionArray = process.version
 var isNodeApiBuiltin = (
   versionArray[0] > 8 ||
   (versionArray[0] == 8 && versionArray[1] >= 6) ||
+  (versionArray[0] == 6 && versionArray[1] >= 15) ||
   (versionArray[0] == 6 && versionArray[1] >= 14 && versionArray[2] >= 2));
 
 // The flag is not needed when the Node version is not 8, nor if the API is

package/napi-inl.deprecated.h

@@ -73,7 +73,7 @@ inline PropertyDescriptor PropertyDescriptor::Accessor(const char* utf8name,
                                                        void* /*data*/) {
   typedef details::AccessorCallbackData<Getter, Setter> CbData;
   // TODO: Delete when the function is destroyed
-  auto callbackData = new CbData({ getter, setter });
+  auto callbackData = new CbData({ getter, setter, nullptr });
 
   return PropertyDescriptor({
     utf8name,
@@ -104,7 +104,7 @@ inline PropertyDescriptor PropertyDescriptor::Accessor(napi_value name,
                                                        void* /*data*/) {
   typedef details::AccessorCallbackData<Getter, Setter> CbData;
   // TODO: Delete when the function is destroyed
-  auto callbackData = new CbData({ getter, setter });
+  auto callbackData = new CbData({ getter, setter, nullptr });
 
   return PropertyDescriptor({
     nullptr,

package/napi-inl.h

@@ -17,49 +17,6 @@ namespace Napi {
 // Helpers to handle functions exposed from C++.
 namespace details {
 
-#ifdef NAPI_CPP_EXCEPTIONS
-
-#define NAPI_THROW(e)  throw e
-
-// When C++ exceptions are enabled, Errors are thrown directly. There is no need
-// to return anything after the throw statement. The variadic parameter is an
-// optional return value that is ignored.
-#define NAPI_THROW_IF_FAILED(env, status, ...)           \
-  if ((status) != napi_ok) throw Error::New(env);
-
-#define NAPI_THROW_IF_FAILED_VOID(env, status)           \
-  if ((status) != napi_ok) throw Error::New(env);
-
-#else // NAPI_CPP_EXCEPTIONS
-
-#define NAPI_THROW(e)  (e).ThrowAsJavaScriptException();
-
-// When C++ exceptions are disabled, Errors are thrown as JavaScript exceptions,
-// which are pending until the callback returns to JS.  The variadic parameter
-// is an optional return value; usually it is an empty result.
-#define NAPI_THROW_IF_FAILED(env, status, ...)           \
-  if ((status) != napi_ok) {                             \
-    Error::New(env).ThrowAsJavaScriptException();        \
-    return __VA_ARGS__;                                  \
-  }
-
-// We need a _VOID version of this macro to avoid warnings resulting from
-// leaving the NAPI_THROW_IF_FAILED `...` argument empty.
-#define NAPI_THROW_IF_FAILED_VOID(env, status)           \
-  if ((status) != napi_ok) {                             \
-    Error::New(env).ThrowAsJavaScriptException();        \
-    return;                                              \
-  }
-
-#endif // NAPI_CPP_EXCEPTIONS
-
-#define NAPI_FATAL_IF_FAILED(status, location, message)  \
-  do {                                                   \
-    if ((status) != napi_ok) {                           \
-      Error::Fatal((location), (message));               \
-    }                                                    \
-  } while (0)
-
 // Attach a data item to an object and delete it when the object gets
 // garbage-collected.
 // TODO: Replace this code with `napi_add_finalizer()` whenever it becomes
@@ -176,6 +133,7 @@ struct AccessorCallbackData {
       CallbackInfo callbackInfo(env, info);
       AccessorCallbackData* callbackData =
         static_cast<AccessorCallbackData*>(callbackInfo.Data());
+      callbackInfo.SetData(callbackData->data);
       return callbackData->getterCallback(callbackInfo);
     });
   }
@@ -186,6 +144,7 @@ struct AccessorCallbackData {
       CallbackInfo callbackInfo(env, info);
       AccessorCallbackData* callbackData =
         static_cast<AccessorCallbackData*>(callbackInfo.Data());
+      callbackInfo.SetData(callbackData->data);
       callbackData->setterCallback(callbackInfo);
       return nullptr;
     });
@@ -193,6 +152,7 @@ struct AccessorCallbackData {
 
   Getter getterCallback;
   Setter setterCallback;
+  void* data;
 };
 
 }  // namespace details
@@ -1060,7 +1020,7 @@ inline bool Object::Delete(uint32_t index) {
   return result;
 }
 
-inline Array Object::GetPropertyNames() {
+inline Array Object::GetPropertyNames() const {
   napi_value result;
   napi_status status = napi_get_property_names(_env, _value, &result);
   NAPI_THROW_IF_FAILED(_env, status, Array());
@@ -1309,8 +1269,8 @@ inline DataView DataView::New(napi_env env,
                               size_t byteOffset) {
   if (byteOffset > arrayBuffer.ByteLength()) {
     NAPI_THROW(RangeError::New(env,
-        "Start offset is outside the bounds of the buffer"));
-    return DataView();
+        "Start offset is outside the bounds of the buffer"),
+        DataView());
   }
   return New(env, arrayBuffer, byteOffset,
       arrayBuffer.ByteLength() - byteOffset);
@@ -1321,8 +1281,8 @@ inline DataView DataView::New(napi_env env,
                               size_t byteOffset,
                               size_t byteLength) {
   if (byteOffset + byteLength > arrayBuffer.ByteLength()) {
-    NAPI_THROW(RangeError::New(env, "Invalid DataView length"));
-    return DataView();
+    NAPI_THROW(RangeError::New(env, "Invalid DataView length"),
+               DataView());
   }
   napi_value value;
   napi_status status = napi_create_dataview(
@@ -1448,8 +1408,7 @@ inline T DataView::ReadData(size_t byteOffset) const {
   if (byteOffset + sizeof(T) > _length ||
       byteOffset + sizeof(T) < byteOffset) {  // overflow
     NAPI_THROW(RangeError::New(_env,
-        "Offset is outside the bounds of the DataView"));
-    return 0;
+        "Offset is outside the bounds of the DataView"), 0);
   }
 
   return *reinterpret_cast<T*>(static_cast<uint8_t*>(_data) + byteOffset);
@@ -1459,9 +1418,8 @@ template <typename T>
 inline void DataView::WriteData(size_t byteOffset, T value) const {
   if (byteOffset + sizeof(T) > _length ||
       byteOffset + sizeof(T) < byteOffset) {  // overflow
-    NAPI_THROW(RangeError::New(_env,
+    NAPI_THROW_VOID(RangeError::New(_env,
         "Offset is outside the bounds of the DataView"));
-    return;
   }
 
   *reinterpret_cast<T*>(static_cast<uint8_t*>(_data) + byteOffset) = value;
@@ -1597,7 +1555,7 @@ inline TypedArrayOf<T>::TypedArrayOf(napi_env env,
   : TypedArray(env, value, type, length), _data(data) {
   if (!(type == TypedArrayTypeForPrimitiveType<T>() ||
       (type == napi_uint8_clamped_array && std::is_same<T, uint8_t>::value))) {
-    NAPI_THROW(TypeError::New(env, "Array type must match the template parameter. "
+    NAPI_THROW_VOID(TypeError::New(env, "Array type must match the template parameter. "
       "(Uint8 arrays may optionally have the \"clamped\" array type.)"));
   }
 }
@@ -1657,7 +1615,11 @@ inline Function Function::New(napi_env env,
                                       CbData::Wrapper,
                                       callbackData,
                                       &value);
-  NAPI_THROW_IF_FAILED(env, status, Function());
+  if (status != napi_ok) {
+    delete callbackData;
+    NAPI_THROW_IF_FAILED(env, status, Function());
+  }
+
   return Function(env, value);
 }
 
@@ -2031,8 +1993,20 @@ inline const std::string& Error::Message() const NAPI_NOEXCEPT {
 inline void Error::ThrowAsJavaScriptException() const {
   HandleScope scope(_env);
   if (!IsEmpty()) {
+
+    // We intentionally don't use `NAPI_THROW_*` macros here to ensure
+    // that there is no possible recursion as `ThrowAsJavaScriptException`
+    // is part of `NAPI_THROW_*` macro definition for noexcept.
+
     napi_status status = napi_throw(_env, Value());
-    NAPI_THROW_IF_FAILED_VOID(_env, status);
+
+#ifdef NAPI_CPP_EXCEPTIONS
+    if (status != napi_ok) {
+      throw Error::New(_env);
+    }
+#else // NAPI_CPP_EXCEPTIONS
+    NAPI_FATAL_IF_FAILED(status, "Error::ThrowAsJavaScriptException", "napi_throw");
+#endif // NAPI_CPP_EXCEPTIONS
   }
 }
 
@@ -2603,12 +2577,15 @@ PropertyDescriptor::Accessor(Napi::Env env,
                              const char* utf8name,
                              Getter getter,
                              napi_property_attributes attributes,
-                             void* /*data*/) {
+                             void* data) {
   typedef details::CallbackData<Getter, Napi::Value> CbData;
-  auto callbackData = new CbData({ getter, nullptr });
+  auto callbackData = new CbData({ getter, data });
 
   napi_status status = AttachData(env, object, callbackData);
-  NAPI_THROW_IF_FAILED(env, status, napi_property_descriptor());
+  if (status != napi_ok) {
+    delete callbackData;
+    NAPI_THROW_IF_FAILED(env, status, napi_property_descriptor());
+  }
 
   return PropertyDescriptor({
     utf8name,
@@ -2638,12 +2615,15 @@ inline PropertyDescriptor PropertyDescriptor::Accessor(Napi::Env env,
                                                        Name name,
                                                        Getter getter,
                                                        napi_property_attributes attributes,
-                                                       void* /*data*/) {
+                                                       void* data) {
   typedef details::CallbackData<Getter, Napi::Value> CbData;
-  auto callbackData = new CbData({ getter, nullptr });
+  auto callbackData = new CbData({ getter, data });
 
   napi_status status = AttachData(env, object, callbackData);
-  NAPI_THROW_IF_FAILED(env, status, napi_property_descriptor());
+  if (status != napi_ok) {
+    delete callbackData;
+    NAPI_THROW_IF_FAILED(env, status, napi_property_descriptor());
+  }
 
   return PropertyDescriptor({
     nullptr,
@@ -2664,12 +2644,15 @@ inline PropertyDescriptor PropertyDescriptor::Accessor(Napi::Env env,
                                                        Getter getter,
                                                        Setter setter,
                                                        napi_property_attributes attributes,
-                                                       void* /*data*/) {
+                                                       void* data) {
   typedef details::AccessorCallbackData<Getter, Setter> CbData;
-  auto callbackData = new CbData({ getter, setter });
+  auto callbackData = new CbData({ getter, setter, data });
 
   napi_status status = AttachData(env, object, callbackData);
-  NAPI_THROW_IF_FAILED(env, status, napi_property_descriptor());
+  if (status != napi_ok) {
+    delete callbackData;
+    NAPI_THROW_IF_FAILED(env, status, napi_property_descriptor());
+  }
 
   return PropertyDescriptor({
     utf8name,
@@ -2701,12 +2684,15 @@ inline PropertyDescriptor PropertyDescriptor::Accessor(Napi::Env env,
                                                        Getter getter,
                                                        Setter setter,
                                                        napi_property_attributes attributes,
-                                                       void* /*data*/) {
+                                                       void* data) {
   typedef details::AccessorCallbackData<Getter, Setter> CbData;
-  auto callbackData = new CbData({ getter, setter });
+  auto callbackData = new CbData({ getter, setter, data });
 
   napi_status status = AttachData(env, object, callbackData);
-  NAPI_THROW_IF_FAILED(env, status, napi_property_descriptor());
+  if (status != napi_ok) {
+    delete callbackData;
+    NAPI_THROW_IF_FAILED(env, status, napi_property_descriptor());
+  }
 
   return PropertyDescriptor({
     nullptr,
@@ -3404,6 +3390,36 @@ inline Value EscapableHandleScope::Escape(napi_value escapee) {
   return Value(_env, result);
 }
 
+
+#if (NAPI_VERSION > 2)
+////////////////////////////////////////////////////////////////////////////////
+// CallbackScope class
+////////////////////////////////////////////////////////////////////////////////
+
+inline CallbackScope::CallbackScope(
+  napi_env env, napi_callback_scope scope) : _env(env), _scope(scope) {
+}
+
+inline CallbackScope::CallbackScope(napi_env env, napi_async_context context)
+    : _env(env) {
+  napi_status status = napi_open_callback_scope(
+      _env, Object::New(env), context, &_scope);
+  NAPI_THROW_IF_FAILED_VOID(_env, status);
+}
+
+inline CallbackScope::~CallbackScope() {
+  napi_close_callback_scope(_env, _scope);
+}
+
+inline CallbackScope::operator napi_callback_scope() const {
+  return _scope;
+}
+
+inline Napi::Env CallbackScope::Env() const {
+  return Napi::Env(_env);
+}
+#endif
+
 ////////////////////////////////////////////////////////////////////////////////
 // AsyncContext class
 ////////////////////////////////////////////////////////////////////////////////
@@ -3494,7 +3510,8 @@ inline AsyncWorker::AsyncWorker(const Object& receiver,
                                 const Object& resource)
   : _env(callback.Env()),
     _receiver(Napi::Persistent(receiver)),
-    _callback(Napi::Persistent(callback)) {
+    _callback(Napi::Persistent(callback)),
+    _suppress_destruct(false) {
   napi_value resource_id;
   napi_status status = napi_create_string_latin1(
       _env, resource_name, NAPI_AUTO_LENGTH, &resource_id);
@@ -3520,6 +3537,7 @@ inline AsyncWorker::AsyncWorker(AsyncWorker&& other) {
   _receiver = std::move(other._receiver);
   _callback = std::move(other._callback);
   _error = std::move(other._error);
+  _suppress_destruct = other._suppress_destruct;
 }
 
 inline AsyncWorker& AsyncWorker::operator =(AsyncWorker&& other) {
@@ -3530,6 +3548,7 @@ inline AsyncWorker& AsyncWorker::operator =(AsyncWorker&& other) {
   _receiver = std::move(other._receiver);
   _callback = std::move(other._callback);
   _error = std::move(other._error);
+  _suppress_destruct = other._suppress_destruct;
   return *this;
 }
 
@@ -3559,12 +3578,16 @@ inline FunctionReference& AsyncWorker::Callback() {
   return _callback;
 }
 
+inline void AsyncWorker::SuppressDestruct() {
+  _suppress_destruct = true;
+}
+
 inline void AsyncWorker::OnOK() {
-  _callback.MakeCallback(_receiver.Value(), std::initializer_list<napi_value>{});
+  _callback.Call(_receiver.Value(), std::initializer_list<napi_value>{});
 }
 
 inline void AsyncWorker::OnError(const Error& e) {
-  _callback.MakeCallback(_receiver.Value(), std::initializer_list<napi_value>{ e.Value() });
+  _callback.Call(_receiver.Value(), std::initializer_list<napi_value>{ e.Value() });
 }
 
 inline void AsyncWorker::SetError(const std::string& error) {
@@ -3599,7 +3622,9 @@ inline void AsyncWorker::OnWorkComplete(
       return nullptr;
     });
   }
-  delete self;
+  if (!self->_suppress_destruct) {
+    delete self;
+  }
 }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -3631,10 +3656,6 @@ inline const napi_node_version* VersionManagement::GetNodeVersion(Env env) {
   return result;
 }
 
-// These macros shouldn't be useful in user code.
-#undef NAPI_THROW
-#undef NAPI_THROW_IF_FAILED
-
 } // namespace Napi
 
 #endif // SRC_NAPI_INL_H_

package/napi.h

@@ -38,6 +38,64 @@ static_assert(sizeof(char16_t) == sizeof(wchar_t), "Size mismatch between char16
   #define NAPI_NOEXCEPT noexcept
 #endif
 
+#ifdef NAPI_CPP_EXCEPTIONS
+
+// When C++ exceptions are enabled, Errors are thrown directly. There is no need
+// to return anything after the throw statements. The variadic parameter is an
+// optional return value that is ignored.
+// We need _VOID versions of the macros to avoid warnings resulting from
+// leaving the NAPI_THROW_* `...` argument empty.
+
+#define NAPI_THROW(e, ...)  throw e
+#define NAPI_THROW_VOID(e)  throw e
+
+#define NAPI_THROW_IF_FAILED(env, status, ...)           \
+  if ((status) != napi_ok) throw Error::New(env);
+
+#define NAPI_THROW_IF_FAILED_VOID(env, status)           \
+  if ((status) != napi_ok) throw Error::New(env);
+
+#else // NAPI_CPP_EXCEPTIONS
+
+// When C++ exceptions are disabled, Errors are thrown as JavaScript exceptions,
+// which are pending until the callback returns to JS.  The variadic parameter
+// is an optional return value; usually it is an empty result.
+// We need _VOID versions of the macros to avoid warnings resulting from
+// leaving the NAPI_THROW_* `...` argument empty.
+
+#define NAPI_THROW(e, ...)                               \
+  do {                                                   \
+    (e).ThrowAsJavaScriptException();                    \
+    return __VA_ARGS__;                                  \
+  } while (0)
+
+#define NAPI_THROW_VOID(e)                               \
+  do {                                                   \
+    (e).ThrowAsJavaScriptException();                    \
+    return;                                              \
+  } while (0)
+
+#define NAPI_THROW_IF_FAILED(env, status, ...)           \
+  if ((status) != napi_ok) {                             \
+    Error::New(env).ThrowAsJavaScriptException();        \
+    return __VA_ARGS__;                                  \
+  }
+
+#define NAPI_THROW_IF_FAILED_VOID(env, status)           \
+  if ((status) != napi_ok) {                             \
+    Error::New(env).ThrowAsJavaScriptException();        \
+    return;                                              \
+  }
+
+#endif // NAPI_CPP_EXCEPTIONS
+
+#define NAPI_FATAL_IF_FAILED(status, location, message)  \
+  do {                                                   \
+    if ((status) != napi_ok) {                           \
+      Error::Fatal((location), (message));               \
+    }                                                    \
+  } while (0)
+
 ////////////////////////////////////////////////////////////////////////////////
 /// N-API C++ Wrapper Classes
 ///
@@ -601,7 +659,7 @@ namespace Napi {
       uint32_t index ///< Property / element index
     );
 
-    Array GetPropertyNames(); ///< Get all property names
+    Array GetPropertyNames() const; ///< Get all property names
 
     /// Defines a property on the object.
     void DefineProperty(
@@ -633,12 +691,12 @@ namespace Napi {
   public:
     static External New(napi_env env, T* data);
 
-    // Finalizer must implement operator() accepting a T* and returning void.
+    // Finalizer must implement `void operator()(Env env, T* data)`.
     template <typename Finalizer>
     static External New(napi_env env,
                         T* data,
                         Finalizer finalizeCallback);
-    // Finalizer must implement operator() accepting a T* and Hint* and returning void.
+    // Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
     template <typename Finalizer, typename Hint>
     static External New(napi_env env,
                         T* data,
@@ -686,8 +744,7 @@ namespace Napi {
       size_t byteLength,         ///< Length of the external buffer to be used by the array,
                                  ///  in bytes
       Finalizer finalizeCallback ///< Function to be called when the array buffer is destroyed;
-                                 ///  must implement `operator()`, accept a `void*` (which is the
-                                 ///  data buffer pointer), and return `void`
+                                 ///  must implement `void operator()(Env env, void* externalData)`
     );
 
     /// Creates a new ArrayBuffer instance, using an external buffer with specified byte length.
@@ -698,8 +755,7 @@ namespace Napi {
       size_t byteLength,          ///< Length of the external buffer to be used by the array,
                                   ///  in bytes
       Finalizer finalizeCallback, ///< Function to be called when the array buffer is destroyed;
-                                  ///  must implement `operator()`, accept a `void*` (which is the
-                                  ///  data buffer pointer) and `Hint*`, and return `void`
+                                  ///  must implement `void operator()(Env env, void* externalData, Hint* hint)`
       Hint* finalizeHint          ///< Hint (second parameter) to be passed to the finalize callback
     );
 
@@ -969,12 +1025,12 @@ namespace Napi {
     static Buffer<T> New(napi_env env, size_t length);
     static Buffer<T> New(napi_env env, T* data, size_t length);
 
-    // Finalizer must implement operator() accepting a T* and returning void.
+    // Finalizer must implement `void operator()(Env env, T* data)`.
     template <typename Finalizer>
     static Buffer<T> New(napi_env env, T* data,
                          size_t length,
                          Finalizer finalizeCallback);
-    // Finalizer must implement operator() accepting a T* and Hint* and returning void.
+    // Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
     template <typename Finalizer, typename Hint>
     static Buffer<T> New(napi_env env, T* data,
                          size_t length,
@@ -1671,6 +1727,23 @@ namespace Napi {
     napi_escapable_handle_scope _scope;
   };
 
+#if (NAPI_VERSION > 2)
+  class CallbackScope {
+  public:
+    CallbackScope(napi_env env, napi_callback_scope scope);
+    CallbackScope(napi_env env, napi_async_context context);
+    virtual ~CallbackScope();
+
+    operator napi_callback_scope() const;
+
+    Napi::Env Env() const;
+
+  private:
+    napi_env _env;
+    napi_callback_scope _scope;
+  };
+#endif
+
   class AsyncContext {
   public:
     explicit AsyncContext(napi_env env, const char* resource_name);
@@ -1705,6 +1778,7 @@ namespace Napi {
 
     void Queue();
     void Cancel();
+    void SuppressDestruct();
 
     ObjectReference& Receiver();
     FunctionReference& Callback();
@@ -1743,6 +1817,7 @@ namespace Napi {
     ObjectReference _receiver;
     FunctionReference _callback;
     std::string _error;
+    bool _suppress_destruct;
   };
 
   // Memory management.

package/package.json

@@ -3,6 +3,7 @@
     "url": "https://github.com/nodejs/node-addon-api/issues"
   },
   "contributors": [
+    "Abhishek Kumar Singh (https://github.com/abhi11210646)",
     "Andrew Petersen (https://github.com/kirbysayshi)",
     "Anisha Rohra (https://github.com/anisha-rohra)",
     "Anna Henningsen (https://github.com/addaleax)",
@@ -10,6 +11,8 @@
     "Arunesh Chandra (https://github.com/aruneshchandra)",
     "Ben Berman (https://github.com/rivertam)",
     "Benjamin Byholm (https://github.com/kkoopa)",
+    "Bill Gallafent (https://github.com/gallafent)",
+    "Bruce A. MacNaughton (https://github.com/bmacnaughton)",
     "Cory Mickelson (https://github.com/corymickelson)",
     "David Halls (https://github.com/davedoesdev)",
     "Dongjin Na (https://github.com/nadongguri)",
@@ -17,6 +20,7 @@
     "Gabriel Schulhof (https://github.com/gabrielschulhof)",
     "Gus Caplan (https://github.com/devsnek)",
     "Hitesh Kanwathirtha (https://github.com/digitalinfinity)",
+    "Jake Barnes (https://github.com/DuBistKomisch)",
     "Jake Yoon (https://github.com/yjaeseok)",
     "Jason Ginchereau (https://github.com/jasongin)",
     "Jim Schlight (https://github.com/jschlight)",
@@ -24,6 +28,7 @@
     "joshgarde (https://github.com/joshgarde)",
     "Konstantin Tarkus (https://github.com/koistya)",
     "Kyle Farnung (https://github.com/kfarnung)",
+    "Luciano Martorella (https://github.com/lmartorella)",
     "Matteo Collina (https://github.com/mcollina)",
     "Michael Dawson (https://github.com/mhdawson)",
     "Michele Campus (https://github.com/kYroL01)",
@@ -32,8 +37,11 @@
     "Nick Soggin (https://github.com/iSkore)",
     "Philipp Renoth (https://github.com/DaAitch)",
     "Rolf Timmermans (https://github.com/rolftimmermans)",
+    "Ryuichi Okumura (https://github.com/okuryu)",
     "Sampson Gao (https://github.com/sampsongao)",
-    "Taylor Woll (https://github.com/boingoing)"
+    "Sam Roberts (https://github.com/sam-github)",
+    "Taylor Woll (https://github.com/boingoing)",
+    "Thomas Gentilhomme (https://github.com/fraxken)"
   ],
   "dependencies": {},
   "description": "Node.js API (N-API)",
@@ -42,6 +50,7 @@
   },
   "directories": {},
   "homepage": "https://github.com/nodejs/node-addon-api",
+  "keywords": ["n-api", "napi", "addon", "native", "bindings", "c", "c++", "nan", "node-addon-api"],
   "license": "MIT",
   "main": "index.js",
   "name": "node-addon-api",
@@ -54,7 +63,11 @@
   "scripts": {
     "pretest": "node-gyp rebuild -C test",
     "test": "node test",
+    "predev": "node-gyp rebuild -C test --debug",
+    "dev": "node test",
+    "predev:incremental": "node-gyp configure build -C test --debug",
+    "dev:incremental": "node test",
     "doc": "doxygen doc/Doxyfile"
   },
-  "version": "1.5.0"
+  "version": "1.6.3"
 }

package/tools/README.md

@@ -25,7 +25,7 @@ Here is the list of things that can be fixed easily.
 
 
 ### Major Reconstructions
-The implementation of `Napi::ObjectWrap` is significantly different from NAN's. `Napi::ObjectWrap` takes a pointer to the wrapped object and creates a reference to the wrapped object inside ObjectWrap constructor. `Napi::ObjectWrap` also associated wrapped object's instance methods to Javascript module instead of static methods like NAN.
+The implementation of `Napi::ObjectWrap` is significantly different from NAN's. `Napi::ObjectWrap` takes a pointer to the wrapped object and creates a reference to the wrapped object inside ObjectWrap constructor. `Napi::ObjectWrap` also associates wrapped object's instance methods to Javascript module instead of static methods like NAN.
 
 So if you use Nan::ObjectWrap in your module, you will need to execute the following steps.
 
@@ -39,7 +39,7 @@ and define it as
   ...
 }
 ```
-This way, the `Napi::ObjectWrap` constructor will be invoked after the object has been instanciated and `Napi::ObjectWrap` can use the `this` pointer to create reference to the wrapped object.
+This way, the `Napi::ObjectWrap` constructor will be invoked after the object has been instantiated and `Napi::ObjectWrap` can use the `this` pointer to create a reference to the wrapped object.
 
   2. Move your original constructor code into the new constructor. Delete your original constructor.
   3. In your class initialization function, associate native methods in the following way. The `&` character before methods is required because they are not static methods but instance methods.