node-addon-api 1.6.2 → 1.6.3

package/CHANGELOG.md

@@ -1,6 +1,45 @@
 # node-addon-api Changelog
 
-## 2018-11-29 Version 1.6.2 (Current), @NickNaso
+## 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:
 
@@ -12,7 +51,7 @@
 
 * [[`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 (Current), @NickNaso
+## 2018-11-14 Version 1.6.1, @NickNaso
 
 ### Notable changes:
 
@@ -33,7 +72,7 @@
 * [[`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 (Current), @NickNaso
+## 2018-11-02 Version 1.6.0, @NickNaso
 
 ### Notable changes:
 
@@ -63,7 +102,7 @@ associated with a callback in place when making certain N-API calls
 * [[`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 (Current), @NickNaso
+## 2018-10-03 Version 1.5.0, @NickNaso
 
 ### Notable changes:
 

package/README.md

@@ -46,7 +46,7 @@ to ideas specified in the **ECMA262 Language Specification**.
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 1.6.2**
+## **Current version: 1.6.3**
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
 
@@ -141,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>
@@ -152,20 +166,27 @@ 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)

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/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,30 +1,51 @@
 # 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-addon-api.
 
@@ -33,9 +54,9 @@ These are the steps to follow to create a new release:
 * 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

@@ -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/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,
@@ -3524,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);
@@ -3550,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) {
@@ -3560,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;
 }
 
@@ -3589,6 +3578,10 @@ inline FunctionReference& AsyncWorker::Callback() {
   return _callback;
 }
 
+inline void AsyncWorker::SuppressDestruct() {
+  _suppress_destruct = true;
+}
+
 inline void AsyncWorker::OnOK() {
   _callback.Call(_receiver.Value(), std::initializer_list<napi_value>{});
 }
@@ -3629,7 +3622,9 @@ inline void AsyncWorker::OnWorkComplete(
       return nullptr;
     });
   }
-  delete self;
+  if (!self->_suppress_destruct) {
+    delete self;
+  }
 }
 
 ////////////////////////////////////////////////////////////////////////////////
@@ -3661,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,
@@ -1722,6 +1778,7 @@ namespace Napi {
 
     void Queue();
     void Cancel();
+    void SuppressDestruct();
 
     ObjectReference& Receiver();
     FunctionReference& Callback();
@@ -1760,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,7 +37,9 @@
     "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)",
+    "Sam Roberts (https://github.com/sam-github)",
     "Taylor Woll (https://github.com/boingoing)",
     "Thomas Gentilhomme (https://github.com/fraxken)"
   ],
@@ -43,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",
@@ -55,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.6.2"
+  "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.