node-addon-api - npm Package Compare versions

Comparing version 3.0.2 to 3.1.0

CHANGELOG.md

 # node-addon-api Changelog
 
+## 2020-12-17 Version 3.1.0, @NickNaso
+
+### Notable changes:
+
+#### API
+
+- Added `Napi::TypedThreadSafeFunction` class that is a new implementation for
+thread-safe functions. 
+- Fixed leak on `Napi::AsyncProgressWorkerBase`.
+- Fixed empty data on `Napi::AsyncProgressWorker::OnProgress` caused by race 
+conditions of `Napi::AsyncProgressWorker`.
+- Added `Napi::ArrayBuffer::Detach()` and `Napi::ArrayBuffer::IsDetached()`.
+- Fixed problem on `Napi::FinalizeCallback` it needs to create a 
+`Napi::HandleScope` when it calls `Napi::ObjectWrap::~ObjectWrap()`.
+
+#### Documentation
+
+- Added documentation for `Napi::TypedThreadSafeFunction`.
+- Removed unsued Doxygen file.
+- Clarified when to use N-API.
+- Added support information.
+- Some minor corrections all over the documentation.
+
+#### TEST
+
+- Added test for `Napi::TypedThreadSafeFunction`.
+- Fixed testing for specific N-API version.
+- Some minor corrections all over the test suite.
+
+### TOOL
+
+- Setup github actions for tests.
+- Added stale action.
+- Removed `sudo` tag from Travis CI.
+- Added clang-format.
+- Added pre-commit package for linting.
+
+### Commits
+
+* [[`ff642c5b85`](https://github.com/nodejs/node-addon-api/commit/ff642c5b85)] - **doc**: fix tsfn docs to reflect true implementation (#860) (Kevin Eady)
+* [[`86feeebf54`](https://github.com/nodejs/node-addon-api/commit/86feeebf54)] - **src**: empty data OnProgress in AsyncProgressWorker (legendecas) [#853](https://github.com/nodejs/node-addon-api/pull/853)
+* [[`a7fb5fb31c`](https://github.com/nodejs/node-addon-api/commit/a7fb5fb31c)] - **action**: add stale action (#856) (Michael Dawson)
+* [[`fd44609885`](https://github.com/nodejs/node-addon-api/commit/fd44609885)] - **chore**: setup github actions for tests (#854) (legendecas) [#854](https://github.com/nodejs/node-addon-api/pull/854)
+* [[`c52ace4813`](https://github.com/nodejs/node-addon-api/commit/c52ace4813)] - **script**: fix complains that js files are not supported on npm run lint:fix (#852) (legendecas)
+* [[`b4a3364ad5`](https://github.com/nodejs/node-addon-api/commit/b4a3364ad5)] - **doc**: remove unused Doxygen file (#851) (Michael Dawson)
+* [[`b810466ae2`](https://github.com/nodejs/node-addon-api/commit/b810466ae2)] - **doc**: clarify when to use N-API (#849) (Michael Dawson)
+* [[`528b9f6832`](https://github.com/nodejs/node-addon-api/commit/528b9f6832)] - **test**: remove sudo from travis (#850) (Michael Dawson)
+* [[`4bb680de4e`](https://github.com/nodejs/node-addon-api/commit/4bb680de4e)] - Remove misleading sentence (#847) (Nikolai Vavilov) [#847](https://github.com/nodejs/node-addon-api/pull/847)
+* [[`48e6b584a3`](https://github.com/nodejs/node-addon-api/commit/48e6b584a3)] - Merge pull request #742 from KevinEady/contexted-tsfn-api-gcc-4 (Gabriel Schulhof)
+* [[`d5e37210cc`](https://github.com/nodejs/node-addon-api/commit/d5e37210cc)] - **tools**: print more instructions on clang-format check failed (#846) (legendecas) [#846](https://github.com/nodejs/node-addon-api/pull/846)
+* [[`d9e11ff2c9`](https://github.com/nodejs/node-addon-api/commit/d9e11ff2c9)] - **doc**: add support info (#843) (Michael Dawson) [#843](https://github.com/nodejs/node-addon-api/pull/843)
+* [[`356e93d69a`](https://github.com/nodejs/node-addon-api/commit/356e93d69a)] - **test**: fixup testing for specific N-API version (#840) (Michael Dawson) [#840](https://github.com/nodejs/node-addon-api/pull/840)
+* [[`5e5b9ce1b7`](https://github.com/nodejs/node-addon-api/commit/5e5b9ce1b7)] - Apply formatting changes (Kevin Eady)
+* [[`559ad8c0c0`](https://github.com/nodejs/node-addon-api/commit/559ad8c0c0)] - Merge remote-tracking branch 'upstream/master' into contexted-tsfn-api-gcc-4 (Kevin Eady)
+* [[`c24c455ced`](https://github.com/nodejs/node-addon-api/commit/c24c455ced)] - Rename to TypedThreadSafeFunction (Kevin Eady)
+* [[`63b43f4125`](https://github.com/nodejs/node-addon-api/commit/63b43f4125)] - **test**: fix buildType bug objectwrap\_worker\_thread (raisinten) [#837](https://github.com/nodejs/node-addon-api/pull/837)
+* [[`6321f2ba1a`](https://github.com/nodejs/node-addon-api/commit/6321f2ba1a)] - **test**: fix typos in addon\_build/index.js (raisinten) [#838](https://github.com/nodejs/node-addon-api/pull/838)
+* [[`59c6a6aeb0`](https://github.com/nodejs/node-addon-api/commit/59c6a6aeb0)] - **fix**: git-clang-format doesn't recognize no changes requested on given files (#835) (legendecas)
+* [[`1427b3ef78`](https://github.com/nodejs/node-addon-api/commit/1427b3ef78)] - **src**: create a HandleScope in FinalizeCallback (blagoev) [#832](https://github.com/nodejs/node-addon-api/pull/832)
+* [[`8fb5820557`](https://github.com/nodejs/node-addon-api/commit/8fb5820557)] - **build**: add incremental clang-format checks (legendecas) [#819](https://github.com/nodejs/node-addon-api/pull/819)
+* [[`2c02d317e5`](https://github.com/nodejs/node-addon-api/commit/2c02d317e5)] - **build**: add pre-commit package for linting (#823) (Kevin Eady)
+* [[`1b52c28eb8`](https://github.com/nodejs/node-addon-api/commit/1b52c28eb8)] - Clean up AsyncProgressWorker documentation (#831) (mastergberry)
+* [[`4abe7cfe30`](https://github.com/nodejs/node-addon-api/commit/4abe7cfe30)] - **test**: rename tsfnex test files (Kevin Eady)
+* [[`c9563caa25`](https://github.com/nodejs/node-addon-api/commit/c9563caa25)] - **src**: add ArrayBuffer::Detach() and ::IsDetached() (Tobias Nießen) [#659](https://github.com/nodejs/node-addon-api/pull/659)
+* [[`c79cabaed2`](https://github.com/nodejs/node-addon-api/commit/c79cabaed2)] - **doc**: avoid directing users to HTTP (#828) (Tobias Nießen)
+* [[`7a13f861ab`](https://github.com/nodejs/node-addon-api/commit/7a13f861ab)] - **doc**: fix additional typo (Kevin Eady)
+* [[`7ec9741dd2`](https://github.com/nodejs/node-addon-api/commit/7ec9741dd2)] - Merge remote-tracking branch 'upstream/master' into contexted-tsfn-api-gcc-4 (Kevin Eady)
+* [[`f5fad239fa`](https://github.com/nodejs/node-addon-api/commit/f5fad239fa)] - Update object\_reference.md (#827) (kidneysolo)
+* [[`35b65712c2`](https://github.com/nodejs/node-addon-api/commit/35b65712c2)] - **Fix**: some typos in documentation (#826) (Helio Frota)
+* [[`8983383000`](https://github.com/nodejs/node-addon-api/commit/8983383000)] - **Fix**: some typos in the document (#825) (Ziqiu Zhao)
+* [[`826e466ef6`](https://github.com/nodejs/node-addon-api/commit/826e466ef6)] - Fixed example in addon.md. (#820) (nempoBu4) [#820](https://github.com/nodejs/node-addon-api/pull/820)
+* [[`b54f5eb788`](https://github.com/nodejs/node-addon-api/commit/b54f5eb788)] - Additional changes from review (Kevin Eady)
+* [[`59f27dac9a`](https://github.com/nodejs/node-addon-api/commit/59f27dac9a)] - Fix common.gypi (Kevin Eady)
+* [[`151a914c99`](https://github.com/nodejs/node-addon-api/commit/151a914c99)] - Apply documentation suggestions from code review (Kevin Eady)
+* [[`ceb27d4949`](https://github.com/nodejs/node-addon-api/commit/ceb27d4949)] - **src**: fix leak in AsyncProgressWorkerBase\<DataType\> (Ferdinand Holzer) [#795](https://github.com/nodejs/node-addon-api/pull/795)
+
 ## 2020-09-18 Version 3.0.2, @NickNaso
@@ -4,0 +80,0 @@

doc/addon.md

@@ -37,3 +37,3 @@ # Add-on Structure
   ExampleAddon(Napi::Env env, Napi::Object exports) {
-    // In the constructor we declare the functions the add-on makes avaialable
+    // In the constructor we declare the functions the add-on makes available
     // to JavaScript.
@@ -45,5 +45,5 @@ DefineAddon(exports, {
       // properties of those sub-objects.
-      InstanceValue("subObject", DefineProperties(Napi::Object::New(), {
-        InstanceMethod("decrement", &ExampleAddon::Decrement
-      })), napi_enumerable)
+      InstanceValue("subObject", DefineProperties(Napi::Object::New(env), {
+        InstanceMethod("decrement", &ExampleAddon::Decrement)
+      }), napi_enumerable)
     });
@@ -85,3 +85,3 @@ }
 console.log(exampleAddon.increment()); // prints 44
-consnole.log(exampleAddon.subObject.decrement()); // prints 43
+console.log(exampleAddon.subObject.decrement()); // prints 43
 ```
@@ -88,0 +88,0 @@

doc/array_buffer.md

@@ -133,2 +133,18 @@ # ArrayBuffer
 
+### Detach
+
+```cpp
+void Napi::ArrayBuffer::Detach();
+```
+
+Invokes the `ArrayBuffer` detach operation on a detachable `ArrayBuffer`.
+
+### IsDetached
+
+```cpp
+bool Napi::ArrayBuffer::IsDetached() const;
+```
+
+Returns `true` if this `ArrayBuffer` has been detached.
+
 [`Napi::Object`]: ./object.md

doc/async_context.md

@@ -76,3 +76,3 @@ # AsyncContext
 
-  // Creat a new async context instance.
+  // Create a new async context instance.
   Napi::AsyncContext context(info.Env(), "async_context_test", resource);
@@ -79,0 +79,0 @@

doc/async_worker_variants.md

@@ -246,3 +246,5 @@ # AsyncProgressWorker
 multiple send might be coalesced into single invocation of `Napi::AsyncProgressWorker::OnProgress`
-with latest data.
+with latest data. If you would like to guarantee that there is one invocation of
+`OnProgress` for every `Send` call, you should use the `Napi::AsyncProgressQueueWorker` 
+class instead which is documented further down this page.
 
@@ -273,3 +275,4 @@ ```cpp
 
-The code below shows a basic example of the `Napi::AsyncProgressWorker` implementation:
+The code below shows a basic example of the `Napi::AsyncProgressWorker` implementation along with an
+example of how the counterpart in Javascript would appear:
 
@@ -286,24 +289,34 @@ ```cpp
     public:
-        EchoWorker(Function& callback, std::string& echo)
-        : AsyncProgressWorker(callback), echo(echo) {}
+        EchoWorker(Function& okCallback, std::string& echo)
+        : AsyncProgressWorker(okCallback), echo(echo) {}
 
         ~EchoWorker() {}
-    // This code will be executed on the worker thread
-    void Execute(const ExecutionProgress& progress) {
-        // Need to simulate cpu heavy task
-        for (uint32_t i = 0; i < 100; ++i) {
-          progress.Send(&i, 1)
-          std::this_thread::sleep_for(std::chrono::seconds(1));
+        
+        // This code will be executed on the worker thread
+        void Execute(const ExecutionProgress& progress) {
+            // Need to simulate cpu heavy task
+            // Note: This Send() call is not guaranteed to trigger an equal
+            // number of OnProgress calls (read documentation above for more info)
+            for (uint32_t i = 0; i < 100; ++i) {
+              progress.Send(&i, 1)
+            }
         }
-    }
+        
+        void OnError(const Error &e) {
+            HandleScope scope(Env());
+            // Pass error onto JS, no data for other parameters
+            Callback().Call({String::New(Env(), e.Message())});
+        }
 
-    void OnOK() {
-        HandleScope scope(Env());
-        Callback().Call({Env().Null(), String::New(Env(), echo)});
-    }
+        void OnOK() {
+            HandleScope scope(Env());
+            // Pass no error, give back original data
+            Callback().Call({Env().Null(), String::New(Env(), echo)});
+        }
 
-    void OnProgress(const uint32_t* data, size_t /* count */) {
-        HandleScope scope(Env());
-        Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)});
-    }
+        void OnProgress(const uint32_t* data, size_t /* count */) {
+            HandleScope scope(Env());
+            // Pass no error, no echo data, but do pass on the progress data
+            Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)});
+        }
 
@@ -333,4 +346,4 @@ private:
     // We need to validate the arguments here
+    std::string in = info[0].As<String>();
     Function cb = info[1].As<Function>();
-    std::string in = info[0].As<String>();
     EchoWorker* wk = new EchoWorker(cb, in);
@@ -340,2 +353,13 @@ wk->Queue();
 }
+
+// Register the native method for JS to access
+Object Init(Env env, Object exports)
+{
+    exports.Set(String::New(env, "echo"), Function::New(env, Echo));
+
+    return exports;
+}
+
+// Register our native addon
+NODE_API_MODULE(nativeAddon, Init)
 ```
@@ -349,2 +373,16 @@
 
+Lastly, the following Javascript (ES6+) code would be associated the above example:
+
+```js
+const { nativeAddon } = require('binding.node');
+
+const exampleCallback = (errorResponse, okResponse, progressData) => {
+    // Use the data accordingly
+    // ...
+};
+
+// Call our native addon with the paramters of a string and a function
+nativeAddon.echo("example", exampleCallback);
+```
+
 # AsyncProgressQueueWorker
@@ -388,3 +426,5 @@
 
-The code below shows a basic example of the `Napi::AsyncProgressQueueWorker` implementation:
+The code below show an example of the `Napi::AsyncProgressQueueWorker` implementation, but
+also demonsrates how to use multiple `Napi::Function`'s if you wish to provide multiple
+callback functions for more object oriented code:
 
@@ -401,27 +441,51 @@ ```cpp
     public:
-        EchoWorker(Function& callback, std::string& echo)
-        : AsyncProgressQueueWorker(callback), echo(echo) {}
+        EchoWorker(Function& okCallback, Function& errorCallback, Function& progressCallback, std::string& echo)
+        : AsyncProgressQueueWorker(okCallback), echo(echo) {
+            // Set our function references to use them below
+            this->errorCallback.Reset(errorCallback, 1);
+            this->progressCallback.Reset(progressCallback, 1);
+        }
 
         ~EchoWorker() {}
-    // This code will be executed on the worker thread
-    void Execute(const ExecutionProgress& progress) {
-        // Need to simulate cpu heavy task
-        for (uint32_t i = 0; i < 100; ++i) {
-          progress.Send(&i, 1);
-          std::this_thread::sleep_for(std::chrono::seconds(1));
+        
+        // This code will be executed on the worker thread
+        void Execute(const ExecutionProgress& progress) {
+            // Need to simulate cpu heavy task to demonstrate that
+            // every call to Send() will trigger an OnProgress function call
+            for (uint32_t i = 0; i < 100; ++i) {
+              progress.Send(&i, 1);
+            }
         }
-    }
 
-    void OnOK() {
-        HandleScope scope(Env());
-        Callback().Call({Env().Null(), String::New(Env(), echo)});
-    }
+        void OnOK() {
+            HandleScope scope(Env());
+            // Call our onOkCallback in javascript with the data we were given originally
+            Callback().Call({String::New(Env(), echo)});
+        }
+        
+        void OnError(const Error &e) {
+            HandleScope scope(Env());
+            
+            // We call our callback provided in the constructor with 2 parameters
+            if (!this->errorCallback.IsEmpty()) {
+                // Call our onErrorCallback in javascript with the error message
+                this->errorCallback.Call(Receiver().Value(), {String::New(Env(), e.Message())});
+            }
+        }
 
-    void OnProgress(const uint32_t* data, size_t /* count */) {
-        HandleScope scope(Env());
-        Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)});
-    }
+        void OnProgress(const uint32_t* data, size_t /* count */) {
+            HandleScope scope(Env());
+            
+            if (!this->progressCallback.IsEmpty()) {
+                // Call our onProgressCallback in javascript with each integer from 0 to 99 (inclusive)
+                // as this function is triggered from the above Send() calls
+                this->progressCallback.Call(Receiver().Value(), {Number::New(Env(), *data)});
+            }
+        }
 
     private:
         std::string echo;
+        FunctionReference progressCallback;
+        FunctionReference errorCallback;
+        
 };
@@ -450,8 +514,21 @@ ```
     // We need to validate the arguments here.
-    Function cb = info[1].As<Function>();
     std::string in = info[0].As<String>();
-    EchoWorker* wk = new EchoWorker(cb, in);
+    Function errorCb = info[1].As<Function>();
+    Function okCb = info[2].As<Function>();
+    Function progressCb = info[3].As<Function>();
+    EchoWorker* wk = new EchoWorker(okCb, errorCb, progressCb, in);
     wk->Queue();
     return info.Env().Undefined();
 }
+
+// Register the native method for JS to access
+Object Init(Env env, Object exports)
+{
+    exports.Set(String::New(env, "echo"), Function::New(env, Echo));
+
+    return exports;
+}
+
+// Register our native addon
+NODE_API_MODULE(nativeAddon, Init)
 ```
@@ -465,2 +542,26 @@
 
+Lastly, the following Javascript (ES6+) code would be associated the above example:
+
+```js
+const { nativeAddon } = require('binding.node');
+
+const onErrorCallback = (msg) => {
+    // Use the data accordingly
+    // ...
+};
+
+const onOkCallback = (echo) => {
+    // Use the data accordingly
+    // ...
+};
+
+const onProgressCallback = (num) => {
+    // Use the data accordingly
+    // ...
+};
+
+// Call our native addon with the paramters of a string and three callback functions
+nativeAddon.echo("example", onErrorCallback, onOkCallback, onProgressCallback);
+```
+
 [`Napi::AsyncWorker`]: ./async_worker.md

doc/async_worker.md

@@ -398,3 +398,3 @@ # AsyncWorker
 
-The `EchoWorker`'s contructor calls the base class' constructor to pass in the
+The `EchoWorker`'s constructor calls the base class' constructor to pass in the
 callback that the `Napi::AsyncWorker` base class will store persistently. When
@@ -401,0 +401,0 @@ the work on the `Napi::AsyncWorker::Execute` method is done the

doc/boolean.md

@@ -21,3 +21,3 @@ # Boolean
 
-### Contructor
+### Constructor
 
@@ -24,0 +24,0 @@ Creates a new instance of the `Napi::Boolean` object.

doc/checker-tool.md

@@ -29,5 +29,5 @@ # Checker Tool
 The tool accepts the root directory from which to start checking for Node.js
-native addons as a single optional command line parameter. If ommitted it will
+native addons as a single optional command line parameter. If omitted it will
 start checking from the current directory (`.`).
 
 [checker tool]: ../tools/check-napi.js

doc/creating_a_release.md

@@ -39,3 +39,3 @@ # Creating a release
     ```
-* Use the output generated by **changelog maker** to pdate the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/master/CHANGELOG.md)
+* Use the output generated by **changelog maker** to update the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/master/CHANGELOG.md)
 following the style used in publishing the previous release.
@@ -42,0 +42,0 @@

doc/error.md

@@ -120,2 +120,2 @@ # Error
 [`Napi::ObjectReference`]: ./object_reference.md
-[`std::exception`]: http://cplusplus.com/reference/exception/exception/
+[`std::exception`]: https://cplusplus.com/reference/exception/exception/

doc/escapable_handle_scope.md

@@ -62,3 +62,3 @@ # EscapableHandleScope
 in the scope to be collected by the garbage collector. There is no
-guarantee as to when the gargbage collector will do this.
+guarantee as to when the garbage collector will do this.
 
@@ -65,0 +65,0 @@ ### Escape

doc/function_reference.md

@@ -76,3 +76,3 @@ # FunctionReference
 - `[in] args`: Initializer list of JavaScript values as `napi_value` representing
-the arguments of the contructor function.
+the arguments of the constructor function.
 
@@ -79,0 +79,0 @@ Returns a new JavaScript object.

doc/function.md

@@ -221,3 +221,3 @@ # Function
 - `[in] args`: Initializer list of JavaScript values as `napi_value` representing
-the arguments of the contructor function.
+the arguments of the constructor function.
 
@@ -249,3 +249,3 @@ Returns a new JavaScript object.
 
-- `[in] argc`: The number of the arguments passed to the contructor function.
+- `[in] argc`: The number of the arguments passed to the constructor function.
 - `[in] args`: Array of JavaScript values as `napi_value` representing the
@@ -252,0 +252,0 @@ arguments of the constructor function.

doc/handle_scope.md

@@ -57,3 +57,3 @@ # HandleScope
 in the scope to be collected by the garbage collector.  There is no
-guarantee as to when the gargbage collector will do this.
+guarantee as to when the garbage collector will do this.
 
@@ -60,0 +60,0 @@ ### Env

doc/hierarchy.md

@@ -91,2 +91,2 @@ # Full Class Hierarchy
 [`Napi::VersionManagement`]: ./version_management.md
-[`std::exception`]: http://cplusplus.com/reference/exception/exception/
+[`std::exception`]: https://cplusplus.com/reference/exception/exception/

doc/number.md

@@ -19,3 +19,3 @@ # Number
 
-### Contructor
+### Constructor
 
@@ -22,0 +22,0 @@ Creates a new instance of a `Napi::Number` object.

doc/object_lifetime_management.md

@@ -63,3 +63,3 @@ # Object lifetime management
 
-Taking the earlier example, creating a `Napi::HandleScope` in the innner loop
+Taking the earlier example, creating a `Napi::HandleScope` in the inner loop
 would ensure that at most a single new value is held alive throughout the
@@ -66,0 +66,0 @@ execution of the loop:

doc/object_reference.md

@@ -11,3 +11,3 @@ # Object Reference
 
-using namescape Napi;
+using namespace Napi;
 
@@ -14,0 +14,0 @@ void Init(Env env) {

doc/object_wrap.md

@@ -46,3 +46,3 @@ # Object Wrap
 
-    // Create a peristent reference to the class constructor. This will allow
+    // Create a persistent reference to the class constructor. This will allow
     // a function called on a class prototype and a function
@@ -49,0 +49,0 @@ // called on instance of a class to be distinguished from each other.

doc/prebuild_tools.md

@@ -8,4 +8,4 @@ # Prebuild tools
 and in some cases this could create problems. To avoid the compilation process it's
-possible to ditribute the native add-on in pre-built form for different platform
-and architectures. The prebuild tools help to create and distrubute the pre-built
+possible to distribute the native add-on in pre-built form for different platform
+and architectures. The prebuild tools help to create and distribute the pre-built
 form of a native add-on.
@@ -12,0 +12,0 @@

doc/property_descriptor.md

 # Property Descriptor
 
-A [`Napi::Object`](object.md) can be assigned properites via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) functions, which take PropertyDescrptor(s) as their parameters. The `Napi::PropertyDescriptor` can contain either values or functions, which are then assigned to the `Napi::Object`. Note that a single instance of a `Napi::PropertyDescriptor` class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [`Accessor`](#accessor), [`Function`](#function), or [`Value`](#value), each of which return a new static instance of a `Napi::PropertyDescriptor`.
+A [`Napi::Object`](object.md) can be assigned properties via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) functions, which take PropertyDescriptor(s) as their parameters. The `Napi::PropertyDescriptor` can contain either values or functions, which are then assigned to the `Napi::Object`. Note that a single instance of a `Napi::PropertyDescriptor` class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [`Accessor`](#accessor), [`Function`](#function), or [`Value`](#value), each of which return a new static instance of a `Napi::PropertyDescriptor`.
 
@@ -153,3 +153,3 @@ ## Example
 
-* `[in] env`: The environemnt in which to create this accessor.
+* `[in] env`: The environment in which to create this accessor.
 * `[in] object`: The object on which the accessor will be defined.
@@ -203,3 +203,3 @@ * `[in] name`: The name used for the getter function.
 
-* `[in] env`: The environemnt in which to create this accessor.
+* `[in] env`: The environment in which to create this accessor.
 * `[in] object`: The object on which the accessor will be defined.
@@ -206,0 +206,0 @@ * `[in] name`: The name of the getter and setter function.

doc/threadsafe_function.md

 # ThreadSafeFunction
 
-JavaScript functions can normally only be called from a native addon's main
-thread. If an addon creates additional threads, then node-addon-api functions
-that require a `Napi::Env`, `Napi::Value`, or `Napi::Reference` must not be
-called from those threads.
+The `Napi::ThreadSafeFunction` type provides APIs for threads to communicate
+with the addon's main thread to invoke JavaScript functions on their behalf.
+Documentation can be found for an [overview of the API](threadsafe.md), as well
+as [differences between the two thread-safe function
+APIs](threadsafe.md#implementation-differences).
 
-When an addon has additional threads and JavaScript functions need to be invoked
-based on the processing completed by those threads, those threads must
-communicate with the addon's main thread so that the main thread can invoke the
-JavaScript function on their behalf. The thread-safe function APIs provide an
-easy way to do this.
-
-These APIs provide the type `Napi::ThreadSafeFunction` as well as APIs to
-create, destroy, and call objects of this type.
-`Napi::ThreadSafeFunction::New()` creates a persistent reference that holds a
-JavaScript function which can be called from multiple threads. The calls happen
-asynchronously. This means that values with which the JavaScript callback is to
-be called will be placed in a queue, and, for each value in the queue, a call
-will eventually be made to the JavaScript function.
-
-`Napi::ThreadSafeFunction` objects are destroyed when every thread which uses
-the object has called `Release()` or has received a return status of
-`napi_closing` in response to a call to `BlockingCall()` or `NonBlockingCall()`.
-The queue is emptied before the `Napi::ThreadSafeFunction` is destroyed. It is
-important that `Release()` be the last API call made in conjunction with a given
-`Napi::ThreadSafeFunction`, because after the call completes, there is no
-guarantee that the `Napi::ThreadSafeFunction` is still allocated. For the same
-reason it is also important that no more use be made of a thread-safe function
-after receiving a return value of `napi_closing` in response to a call to
-`BlockingCall()` or `NonBlockingCall()`. Data associated with the
-`Napi::ThreadSafeFunction` can be freed in its `Finalizer` callback which was
-passed to `ThreadSafeFunction::New()`.
-
-Once the number of threads making use of a `Napi::ThreadSafeFunction` reaches
-zero, no further threads can start making use of it by calling `Acquire()`. In
-fact, all subsequent API calls associated with it, except `Release()`, will
-return an error value of `napi_closing`.
-
 ## Methods
@@ -95,3 +64,4 @@
   thread, which will be making use of this function.
-- `[optional] context`: Data to attach to the resulting `ThreadSafeFunction`.
+- `[optional] context`: Data to attach to the resulting `ThreadSafeFunction`. It
+  can be retreived by calling `GetContext()`.
 - `[optional] finalizeCallback`: Function to call when the `ThreadSafeFunction`
@@ -105,4 +75,4 @@ is being destroyed.  This callback will be invoked on the main thread when the
   callback completes. Must implement `void operator()(Env env, DataType* data,
-  Context* hint)`, skipping `data` or `hint` if they are not provided.
-  Can be retreived via `GetContext()`.
+  ContextType* hint)`, skipping `data` or `hint` if they are not provided. Can
+  be retrieved via `GetContext()`.
 - `[optional] data`: Data to be passed to `finalizeCallback`.
@@ -115,3 +85,3 @@
 Add a thread to this thread-safe function object, indicating that a new thread
-will start making use of the thread-safe function. 
+will start making use of the thread-safe function.
 
@@ -124,3 +94,3 @@ ```cpp
 - `napi_ok`: The thread has successfully acquired the thread-safe function
-for its use. 
+for its use.
 - `napi_closing`: The thread-safe function has been marked as closing via a
@@ -143,3 +113,3 @@ previous call to `Abort()`.
 - `napi_invalid_arg`: The thread-safe function's thread-count is zero.
-- `napi_generic_failure`: A generic error occurred when attemping to release
+- `napi_generic_failure`: A generic error occurred when attempting to release
 the thread-safe function.
@@ -166,3 +136,3 @@
 - `napi_invalid_arg`: The thread-safe function's thread-count is zero.
-- `napi_generic_failure`: A generic error occurred when attemping to abort
+- `napi_generic_failure`: A generic error occurred when attempting to abort
 the thread-safe function.
@@ -219,3 +189,3 @@
 - `napi_invalid_arg`: The thread-safe function is closed.
-- `napi_generic_failure`: A generic error occurred when attemping to add to the
+- `napi_generic_failure`: A generic error occurred when attempting to add to the
   queue.
@@ -268,6 +238,6 @@
     auto callback = []( Napi::Env env, Function jsCallback, int* value ) {
-      // Transform native data into JS data, passing it to the provided 
+      // Transform native data into JS data, passing it to the provided
       // `jsCallback` -- the TSFN's JavaScript function.
       jsCallback.Call( {Number::New( env, *value )} );
-      
+
       // We're finished with the data.
@@ -274,0 +244,0 @@ delete value;

doc/version_management.md

@@ -23,4 +23,4 @@ # VersionManagement
 
-Retrives information about Node.js version present on the system. All the
-information is stored in the `napi_node_version` structrue that is defined as
+Retrieves information about Node.js version present on the system. All the
+information is stored in the `napi_node_version` structure that is defined as
 shown below:
@@ -27,0 +27,0 @@

package.json

@@ -55,2 +55,6 @@ {
     {
+      "name": "blagoev",
+      "url": "https://github.com/blagoev"
+    },
+    {
       "name": "Bruce A. MacNaughton",
@@ -68,2 +72,6 @@ "url": "https://github.com/bmacnaughton"
     {
+      "name": "Darshan Sen",
+      "url": "https://github.com/RaisinTen"
+    },
+    {
       "name": "David Halls",
@@ -81,2 +89,6 @@ "url": "https://github.com/davedoesdev"
     {
+      "name": "Ferdinand Holzer",
+      "url": "https://github.com/fholzer"
+    },
+    {
       "name": "Eric Bickle",
@@ -98,2 +110,6 @@ "url": "https://github.com/ebickle"
     {
+      "name": "Helio Frota",
+      "url": "https://github.com/helio-frota"
+    },
+    {
       "name": "Hitesh Kanwathirtha",
@@ -147,2 +163,6 @@ "url": "https://github.com/digitalinfinity"
     {
+      "name": "kidneysolo",
+      "url": "https://github.com/kidneysolo"
+    },
+    {
       "name": "Koki Nishihara",
@@ -172,2 +192,6 @@ "url": "https://github.com/Nishikoh"
     {
+      "name": "mastergberry",
+      "url": "https://github.com/mastergberry"
+    },
+    {
       "name": "Mathias Küsel",
@@ -197,2 +221,6 @@ "url": "https://github.com/mathiask88"
     {
+      "name": "nempoBu4",
+      "url": "https://github.com/nempoBu4"
+    },
+    {
       "name": "Nicola Del Gobbo",
@@ -206,2 +234,6 @@ "url": "https://github.com/NickNaso"
     {
+      "name": "Nikolai Vavilov",
+      "url": "https://github.com/seishun"
+    },
+    {
       "name": "Nurbol Alpysbayev",
@@ -269,2 +301,6 @@ "url": "https://github.com/anurbol"
       "url": "https://github.com/fs-eire"
+    },
+    {
+      "name": "Ziqiu Zhao",
+      "url": "https://github.com/ZzqiZQute"
     }
@@ -276,4 +312,6 @@ ],
     "benchmark": "^2.1.4",
+    "bindings": "^1.5.0",
+    "clang-format": "^1.4.0",
     "fs-extra": "^9.0.1",
-    "bindings": "^1.5.0",
+    "pre-commit": "^1.2.2",
     "safe-buffer": "^5.1.1"
@@ -313,5 +351,9 @@ },
     "dev:incremental": "node test",
-    "doc": "doxygen doc/Doxyfile"
+    "doc": "doxygen doc/Doxyfile",
+    "lint": "node tools/clang-format.js",
+    "lint:fix": "git-clang-format '*.h', '*.cc'"
   },
-  "version": "3.0.2"
+  "pre-commit": "lint",
+  "version": "3.1.0",
+  "support": true
 }

README.md

@@ -7,2 +7,10 @@ # **node-addon-api module**
 
+There are three options for implementing addons: N-API, nan, or direct
+use of internal V8, libuv and Node.js libraries. Unless there is a need for
+direct access to functionality which is not exposed by N-API as outlined
+in [C/C++ addons](https://nodejs.org/dist/latest/docs/api/addons.html)
+in Node.js core, use N-API. Refer to
+[C/C++ addons with N-API](https://nodejs.org/dist/latest/docs/api/n-api.html)
+for more information on N-API.
+
 N-API is an ABI stable C interface provided by Node.js for building native
@@ -41,4 +49,4 @@ addons. It is independent from the underlying JavaScript runtime (e.g. V8 or ChakraCore)
 
-The [N-API Resource](http://nodejs.github.io/node-addon-examples/) offers an 
-excellent orientation and tips for developers just getting started with N-API 
+The [N-API Resource](https://nodejs.github.io/node-addon-examples/) offers an
+excellent orientation and tips for developers just getting started with N-API
 and node-addon-api.
@@ -56,3 +64,3 @@
 
-## **Current version: 3.0.2**
+## **Current version: 3.1.0**
 
@@ -127,3 +135,5 @@ (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
     - [AsyncWorker Variants](doc/async_worker_variants.md)
- - [Thread-safe Functions](doc/threadsafe_function.md)
+ - [Thread-safe Functions](doc/threadsafe.md)
+    - [ThreadSafeFunction](doc/threadsafe_function.md)
+    - [TypedThreadSafeFunction](doc/typed_threadsafe_function.md)
  - [Promises](doc/promises.md)
@@ -164,2 +174,11 @@ - [Version management](doc/version_management.md)
 
+To run the tests targetting a specific version of N-API run
+```
+npm install
+export NAPI_VERSION=X
+npm test --NAPI_VERSION=X
+```
+
+where X is the version of N-API you want to target.
+
 ### **Debug**
@@ -166,0 +185,0 @@

tools/README.md

@@ -1,3 +0,9 @@
-# Migration Script
+# Tools
 
+## clang-format
+
+The clang-format checking tools is designed to check changed lines of code compared to given git-refs.
+
+## Migration Script
+
 The migration tool is designed to reduce repetitive work in the migration process. However, the script is not aiming to convert every thing for you. There are usually some small fixes and major reconstruction required.
@@ -45,3 +51,3 @@
   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.
+  3. In your class initialization function, associate native methods in the following way.
 ```
@@ -48,0 +54,0 @@ Napi::FunctionReference constructor;

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Number of package files

88

increased by8.64%

Lines of code

526

increased by13.12%

Number of lines in readme file

274

increased by7.45%

Worsened metrics

Total package byte prevSize

692509

decreased by-5.97%

Dev dependency count

6

increased by50%

Number of low supply chain risk alerts

6

increased by20%

Number of medium supply chain risk alerts

4

increased by33.33%

No dependency changes