node-addon-api 3.0.2 → 3.1.0

package/doc/async_worker_variants.md

@@ -243,7 +243,9 @@ be safely released.
 Note that `Napi::AsyncProgressWorker::ExecutionProcess::Send` merely guarantees
 **eventual** invocation of `Napi::AsyncProgressWorker::OnProgress`, which means
 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.
 
 ```cpp
 void Napi::AsyncProgressWorker::ExecutionProcess::Send(const T* data, size_t count) const;
@@ -269,7 +271,8 @@ function runs in the background out of the **event loop** thread and at the end
 the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` function will be
 called and are executed as part of the event loop.
 
-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:
 
 ```cpp
 #include <napi.h>
@@ -281,28 +284,38 @@ using namespace Napi;
 
 class EchoWorker : public AsyncProgressWorker<uint32_t> {
     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)});
+        }
 
     private:
         std::string echo;
@@ -327,12 +340,23 @@ using namespace Napi;
 
 Value Echo(const CallbackInfo& info) {
     // We need to validate the arguments here
-    Function cb = info[1].As<Function>();
     std::string in = info[0].As<String>();
+    Function cb = info[1].As<Function>();
     EchoWorker* wk = new EchoWorker(cb, 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)
 ```
 
 The implementation of a `Napi::AsyncProgressWorker` can be used by creating a
@@ -341,6 +365,20 @@ asynchronous task ends and other data needed for the computation. Once created,
 the only other action needed is to call the `Napi::AsyncProgressWorker::Queue`
 method that will queue the created worker for execution.
 
+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
 
 `Napi::AsyncProgressQueueWorker` acts exactly like `Napi::AsyncProgressWorker`
@@ -379,7 +417,9 @@ void Napi::AsyncProgressQueueWorker::ExecutionProcess::Send(const T* data, size_
 
 ## Example
 
-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:
 
 ```cpp
 #include <napi.h>
@@ -391,31 +431,55 @@ using namespace Napi;
 
 class EchoWorker : public AsyncProgressQueueWorker<uint32_t> {
     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;
+        
 };
 ```
 
@@ -439,12 +503,25 @@ using namespace Napi;
 
 Value Echo(const CallbackInfo& info) {
     // 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)
 ```
 
 The implementation of a `Napi::AsyncProgressQueueWorker` can be used by creating a
@@ -453,4 +530,28 @@ asynchronous task ends and other data needed for the computation. Once created,
 the only other action needed is to call the `Napi::AsyncProgressQueueWorker::Queue`
 method that will queue the created worker for execution.
 
+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

package/doc/boolean.md

@@ -18,7 +18,7 @@ Napi::Boolean::Boolean();
 
 Returns a new _empty_  `Napi::Boolean` object.
 
-### Contructor
+### Constructor
 
 Creates a new instance of the `Napi::Boolean` object.
 

package/doc/checker-tool.md

@@ -26,7 +26,7 @@ indicating for each addon whether it is an N-API addon.
      ```
 
 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

package/doc/creating_a_release.md

@@ -36,7 +36,7 @@ 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)
+* 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.
 
 * Add any new contributors to the "contributors" section in the package.json

package/doc/error.md

@@ -117,4 +117,4 @@ Returns a pointer to a null-terminated string that is used to identify the
 exception. This method can be used only if the exception mechanism is enabled.
 
 [`Napi::ObjectReference`]: ./object_reference.md
-[`std::exception`]: http://cplusplus.com/reference/exception/exception/
+[`std::exception`]: https://cplusplus.com/reference/exception/exception/

package/doc/escapable_handle_scope.md

@@ -59,7 +59,7 @@ Napi::EscapableHandleScope::~EscapableHandleScope();
 
 Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created
 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.
 
 ### Escape
 

package/doc/function.md

@@ -218,7 +218,7 @@ Napi::Object Napi::Function::New(const std::initializer_list<napi_value>& args)
 ```
 
 - `[in] args`: Initializer list of JavaScript values as `napi_value` representing
-the arguments of the contructor function.
+the arguments of the constructor function.
 
 Returns a new JavaScript object.
 
@@ -245,7 +245,7 @@ object.
 Napi::Object Napi::Function::New(size_t argc, const napi_value* args) const;
 ```
 
-- `[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
 arguments of the constructor function.
 

package/doc/function_reference.md

@@ -73,7 +73,7 @@ Napi::Object Napi::FunctionReference::New(const std::initializer_list<napi_value
 ```
 
 - `[in] args`: Initializer list of JavaScript values as `napi_value` representing
-the arguments of the contructor function.
+the arguments of the constructor function.
 
 Returns a new JavaScript object.
 

package/doc/handle_scope.md

@@ -54,7 +54,7 @@ Napi::HandleScope::~HandleScope();
 
 Deletes the `Napi::HandleScope` instance and allows any objects/handles created
 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.
 
 ### Env
 

package/doc/hierarchy.md

@@ -88,4 +88,4 @@
 [`Napi::Uint8Array`]: ./typed_array_of.md
 [`Napi::Value`]: ./value.md
 [`Napi::VersionManagement`]: ./version_management.md
-[`std::exception`]: http://cplusplus.com/reference/exception/exception/
+[`std::exception`]: https://cplusplus.com/reference/exception/exception/

package/doc/number.md

@@ -16,7 +16,7 @@ Napi::Number();
 
 Returns a new _empty_ `Napi::Number` object.
 
-### Contructor
+### Constructor
 
 Creates a new instance of a `Napi::Number` object.
 

package/doc/object_lifetime_management.md

@@ -60,7 +60,7 @@ a native method must be deleted before returning from that method. Since
 deletion, however, care must be taken to create the scope in the right
 place such that you achieve the desired lifetime.
 
-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
 execution of the loop:
 

package/doc/object_reference.md

@@ -8,7 +8,7 @@ For more general information on references, please consult [`Napi::Reference`](r
 ```cpp
 #include <napi.h>
 
-using namescape Napi;
+using namespace Napi;
 
 void Init(Env env) {
 

package/doc/object_wrap.md

@@ -43,7 +43,7 @@ Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
 
     Napi::FunctionReference* constructor = new Napi::FunctionReference();
 
-    // 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
     // called on instance of a class to be distinguished from each other.
     *constructor = Napi::Persistent(func);

package/doc/prebuild_tools.md

@@ -5,8 +5,8 @@ In order to install a native add-on it's important to have all the necessary
 dependencies installed and well configured (see the [setup](setup.md) section).
 The end-user will need to compile the add-on when they will do an `npm install`
 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.
 
 The following list report known tools that are compatible with **N-API**:

package/doc/property_descriptor.md

@@ -1,6 +1,6 @@
 # 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`.
 
 ## Example
 
@@ -150,7 +150,7 @@ static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (
                 void *data = nullptr);
 ```
 
-* `[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.
 * `[in] name`: The name used for the getter function.
 * `[in] getter`: A getter function.
@@ -199,7 +199,7 @@ static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (
                 void *data = nullptr);
 ```
 
-* `[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.
 * `[in] name`: The name of the getter and setter function.
 * `[in] getter`: The getter function.

package/doc/threadsafe.md

@@ -0,0 +1,121 @@
+# Thread-safe Functions
+
+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.
+
+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 two types --
+[`Napi::ThreadSafeFunction`](threadsafe_function.md) and
+[`Napi::TypedThreadSafeFunction`](typed_threadsafe_function.md) -- as well as
+APIs to create, destroy, and call objects of this type. The differences between
+the two are subtle and are [highlighted below](#implementation-differences).
+Regardless of which type you choose, the APIs between the two are similar.
+
+`Napi::[Typed]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::[Typed]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::[Typed]ThreadSafeFunction` is destroyed.
+It is important that `Release()` be the last API call made in conjunction with a
+given `Napi::[Typed]ThreadSafeFunction`, because after the call completes, there
+is no guarantee that the `Napi::[Typed]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::[Typed]ThreadSafeFunction` can be freed in its `Finalizer`
+callback which was passed to `[Typed]ThreadSafeFunction::New()`.
+
+Once the number of threads making use of a `Napi::[Typed]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`.
+
+## Implementation Differences
+
+The choice between `Napi::ThreadSafeFunction` and
+`Napi::TypedThreadSafeFunction` depends largely on how you plan to execute your
+native C++ code (the "callback") on the Node.js thread.
+
+### [`Napi::ThreadSafeFunction`](threadsafe_function.md)
+
+This API is designed without N-API 5 native support for [the optional JavaScript
+  function callback feature](https://github.com/nodejs/node/commit/53297e66cb).
+
+This API has some dynamic functionality, in that:
+- The `[Non]BlockingCall()` methods provide a `Napi::Function` parameter as the
+  callback to run when processing the data item on the main thread -- the
+  `CallJs` callback. Since the callback is a parameter, it can be changed for
+  every call.
+- Different C++ data types may be passed with each call of `[Non]BlockingCall()`
+  to match the specific data type as specified in the `CallJs` callback.
+
+Note that this functionality comes with some **additional overhead** and
+situational **memory leaks**:
+- The API acts as a "broker" between the underlying `napi_threadsafe_function`,
+  and dynamically constructs a wrapper for your callback on the heap for every
+  call to `[Non]BlockingCall()`.
+- In acting in this "broker" fashion, the API will call the underlying "make
+  call" N-API method on this packaged item. If the API has determined the
+  thread-safe function is no longer accessible (eg. all threads have released
+  yet there are still items on the queue), **the callback passed to
+  [Non]BlockingCall will not execute**. This means it is impossible to perform
+  clean-up for calls that never execute their `CallJs` callback. **This may lead
+  to memory leaks** if you are dynamically allocating memory.
+- The `CallJs` does not receive the thread-safe function's context as a
+  parameter. In order for the callback to access the context, it must have a
+  reference to either (1) the context directly, or (2) the thread-safe function
+  to call `GetContext()`. Furthermore, the `GetContext()` method is not
+  _type-safe_, as the method returns an object that can be "any-casted", instead
+  of having a static type.
+
+### [`Napi::TypedThreadSafeFunction`](typed_threadsafe_function.md)
+
+The `TypedThreadSafeFunction` class is a new implementation to address the
+drawbacks listed above. The API is designed with N-API 5's support of an
+optional function callback. The API will correctly allow developers to pass
+`std::nullptr` instead of a `const Function&` for the callback function
+specified in `::New`. It also provides helper APIs to _target_ N-API 4 and
+construct a no-op `Function` **or** to target N-API 5 and "construct" a
+`std::nullptr` callback. This allows a single codebase to use the same APIs,
+with just a switch of the `NAPI_VERSION` compile-time constant.
+
+The removal of the dynamic call functionality has the following implications:
+- The API does _not_ act as a "broker" compared to the
+  `Napi::ThreadSafeFunction`. Once Node.js finalizes the thread-safe function,
+  the `CallJs` callback will execute with an empty `Napi::Env` for any remaining
+  items on the queue. This provides the ability to handle any necessary cleanup
+  of the item's data.
+- The callback _does_ receive the context as a parameter, so a call to
+  `GetContext()` is _not_ necessary. This context type is specified as the
+  **first template argument** specified to `::New`, ensuring type safety.
+- The `New()` constructor accepts the `CallJs` callback as the **second type
+  argument**. The callback must be statically defined for the API to access it.
+  This affords the ability to statically pass the context as the correct type
+  across all methods.
+- Only one C++ data type may be specified to every call to `[Non]BlockingCall()`
+  -- the **third template argument** specified to `::New`. Any "dynamic call
+  data" must be implemented by the user.
+
+
+### Usage Suggestions
+
+In summary, it may be best to use `Napi::TypedThreadSafeFunction` if:
+
+- static, compile-time support for targeting N-API 4 or 5+ with an optional
+  JavaScript callback feature is desired;
+- the callback can have `static` storage class and will not change across calls
+  to `[Non]BlockingCall()`;
+- cleanup of items' data is required (eg. deleting dynamically-allocated data
+  that is created at the caller level).
+
+Otherwise, `Napi::ThreadSafeFunction` may be a better choice.