node-addon-api 2.0.2 → 3.1.0

package/doc/{async_progress_worker.md → 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,40 +271,51 @@ 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>
+#include <napi.h>
 
 #include <chrono>
 #include <thread>
 
-use namespace Napi;
+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;
@@ -323,16 +336,27 @@ The following code shows an example of how to create and use an `Napi::AsyncProg
 // Include EchoWorker class
 // ..
 
-use namespace Napi;
+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,4 +365,193 @@ 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`
+except that each progress committed by `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send`
+during `Napi::AsyncProgressQueueWorker::Execute` is guaranteed to be
+processed by `Napi::AsyncProgressQueueWorker::OnProgress` on the JavaScript
+thread in the order it was committed.
+
+For the most basic use, only the `Napi::AsyncProgressQueueWorker::Execute` and
+`Napi::AsyncProgressQueueWorker::OnProgress` method must be implemented in a subclass.
+
+# AsyncProgressQueueWorker::ExecutionProcess
+
+A bridge class created before the worker thread execution of `Napi::AsyncProgressQueueWorker::Execute`.
+
+## Methods
+
+### Send
+
+`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` takes two arguments, a pointer
+to a generic type of data, and a `size_t` to indicate how many items the pointer is
+pointing to.
+
+The data pointed to will be copied to internal slots of `Napi::AsyncProgressQueueWorker` so
+after the call to `Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` the data can
+be safely released.
+
+`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` guarantees invocation
+of `Napi::AsyncProgressQueueWorker::OnProgress`, which means multiple `Send`
+call will result in the in-order invocation of `Napi::AsyncProgressQueueWorker::OnProgress`
+with each data item.
+
+```cpp
+void Napi::AsyncProgressQueueWorker::ExecutionProcess::Send(const T* data, size_t count) const;
+```
+
+## Example
+
+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>
+
+#include <chrono>
+#include <thread>
+
+using namespace Napi;
+
+class EchoWorker : public AsyncProgressQueueWorker<uint32_t> {
+    public:
+        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 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());
+            // 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());
+            
+            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;
+        
+};
+```
+
+The `EchoWorker`'s constructor calls the base class' constructor to pass in the
+callback that the `Napi::AsyncProgressQueueWorker` base class will store
+persistently. When the work on the `Napi::AsyncProgressQueueWorker::Execute`
+method is done the `Napi::AsyncProgressQueueWorker::OnOk` method is called and
+the results are returned back to JavaScript when the stored callback is invoked
+with its associated environment.
+
+The following code shows an example of how to create and use an
+`Napi::AsyncProgressQueueWorker`.
+
+```cpp
+#include <napi.h>
+
+// Include EchoWorker class
+// ..
+
+using namespace Napi;
+
+Value Echo(const CallbackInfo& info) {
+    // We need to validate the arguments here.
+    std::string in = info[0].As<String>();
+    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
+new instance and passing to its constructor the callback to execute when the
+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/bigint.md

@@ -1,5 +1,7 @@
 # BigInt
 
+Class `Napi::Bigint` inherits from class [`Napi::Value`][].
+
 A JavaScript BigInt value.
 
 ## Methods
@@ -8,6 +10,7 @@ A JavaScript BigInt value.
 
 ```cpp
 static Napi::BigInt Napi::BigInt::New(Napi::Env env, int64_t value);
+static Napi::BigInt Napi::BigInt::New(Napi::Env env, uint64_t value);
 ```
 
  - `[in] env`: The environment in which to construct the `Napi::BigInt` object.
@@ -47,7 +50,7 @@ Returns a new empty JavaScript `Napi::BigInt`.
 ### Int64Value
 
 ```cpp
-int64_t Napi::BitInt::Int64Value(bool* lossless) const;
+int64_t Napi::BigInt::Int64Value(bool* lossless) const;
 ```
 
  - `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly.
@@ -78,7 +81,7 @@ Returns the number of words needed to store this `BigInt` value.
 ### ToWords
 
 ```cpp
-void Napi::BigInt::ToWords(size_t* word_count, int* sign_bit, uint64_t* words);
+void Napi::BigInt::ToWords(int* sign_bit, size_t* word_count, uint64_t* words);
 ```
 
  - `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive
@@ -90,3 +93,5 @@ void Napi::BigInt::ToWords(size_t* word_count, int* sign_bit, uint64_t* words);
 
 Returns a single `BigInt` value into a sign bit, 64-bit little-endian array,
 and the number of elements in the array.
+
+[`Napi::Value`]: ./value.md

package/doc/boolean.md

@@ -1,5 +1,7 @@
 # Boolean
 
+Class `Napi::Boolean` inherits from class [`Napi::Value`][].
+
 `Napi::Boolean` class is a representation of the JavaScript `Boolean` object. The
 `Napi::Boolean` class inherits its behavior from the `Napi::Value` class
 (for more info see: [`Napi::Value`](value.md)).
@@ -16,7 +18,7 @@ Napi::Boolean::Boolean();
 
 Returns a new _empty_  `Napi::Boolean` object.
 
-### Contructor
+### Constructor
 
 Creates a new instance of the `Napi::Boolean` object.
 
@@ -62,3 +64,5 @@ Napi::Boolean::operator bool() const;
 ```
 
 Returns the boolean primitive type of the corresponding `Napi::Boolean` object.
+
+[`Napi::Value`]: ./value.md

package/doc/buffer.md

@@ -1,5 +1,7 @@
 # Buffer
 
+Class `Napi::Buffer` inherits from class [`Napi::Uint8Array`][].
+
 The `Napi::Buffer` class creates a projection of raw data that can be consumed by
 script.
 
@@ -138,3 +140,5 @@ size_t Napi::Buffer::Length() const;
 ```
 
 Returns the number of `T` elements in the external data.
+
+[`Napi::Uint8Array`]: ./typed_array_of.md

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/class_property_descriptor.md

@@ -26,9 +26,9 @@ class Example : public Napi::ObjectWrap<Example> {
 Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
     Napi::Function func = DefineClass(env, "Example", {
         // Register a class instance accessor with getter and setter functions.
-        InstanceAccessor("value", &Example::GetValue, &Example::SetValue),
-        // We can also register a readonly accessor by passing nullptr as the setter.
-        InstanceAccessor("readOnlyProp", &Example::GetValue, nullptr)
+        InstanceAccessor<&Example::GetValue, &Example::SetValue>("value"),
+        // We can also register a readonly accessor by omitting the setter.
+        InstanceAccessor<&Example::GetValue>("readOnlyProp")
     });
 
     constructor = Napi::Persistent(func);

package/doc/creating_a_release.md

@@ -13,7 +13,7 @@ tools:
 
 * [Changelog maker](https://www.npmjs.com/package/changelog-maker)
 
-If not please follow the instruction reported in the tool's documentation to 
+If not please follow the instruction reported in the tool's documentation to
 install it.
 
 ## Publish new release
@@ -27,24 +27,24 @@ new release. Give people some time to comment or suggest PRs that should land fi
 
 * Update the version in **package.json** appropriately.
 
-* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/master/README.md) 
+* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/master/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 
+    ```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
 
 * Validate all tests pass by running npm test on master.
 
-* 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
+* Use **[CI](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api-new/)**
+to validate tests pass (note there are still some issues on SmartOS and
 Windows in the testing).
 
 * Do a clean checkout of node-addon-api.

package/doc/dataview.md

@@ -1,5 +1,7 @@
 # DataView
 
+Class `Napi::DataView` inherits from class [`Napi::Object`][].
+
 The `Napi::DataView` class corresponds to the
 [JavaScript `DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)
 class.
@@ -242,3 +244,5 @@ void Napi::DataView::SetUint32(size_t byteOffset, uint32_t value) const;
 
 - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data.
 - `[in] value`: The value to set.
+
+[`Napi::Object`]: ./object.md

package/doc/date.md

@@ -1,8 +1,8 @@
 # Date
 
 `Napi::Date` class is a representation of the JavaScript `Date` object. The
-`Napi::Date` class inherits its behavior from `Napi::Value` class
-(for more info see [`Napi::Value`](value.md))
+`Napi::Date` class inherits its behavior from the `Napi::Value` class
+(for more info see [`Napi::Value`](value.md)).
 
 ## Methods
 

package/doc/env.md

@@ -61,3 +61,72 @@ Napi::Error Napi::Env::GetAndClearPendingException();
 ```
 
 Returns an `Napi::Error` object representing the environment's pending exception, if any.
+
+### RunScript
+
+```cpp
+Napi::Value Napi::Env::RunScript(____ script);
+```
+- `[in] script`: A string containing JavaScript code to execute.
+
+Runs JavaScript code contained in a string and returns its result.
+
+The `script` can be any of the following types:
+- [`Napi::String`](string.md)
+- `const char *`
+- `const std::string &`
+
+### GetInstanceData
+```cpp
+template <typename T> T* GetInstanceData();
+```
+
+Returns the instance data that was previously associated with the environment,
+or `nullptr` if none was associated.
+
+### SetInstanceData
+
+```cpp
+template <typename T> using Finalizer = void (*)(Env, T*);
+template <typename T, Finalizer<T> fini = Env::DefaultFini<T>>
+void SetInstanceData(T* data);
+```
+
+- `[template] fini`: A function to call when the instance data is to be deleted.
+Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
+not given, the default finalizer will be used, which simply uses the `delete`
+operator to destroy `T*` when the addon instance is unloaded.
+- `[in] data`: A pointer to data that will be associated with the instance of
+the addon for the duration of its lifecycle.
+
+Associates a data item stored at `T* data` with the current instance of the
+addon. The item will be passed to the function `fini` which gets called when an
+instance of the addon is unloaded.
+
+### SetInstanceData
+
+```cpp
+template <typename DataType, typename HintType>
+using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
+template <typename DataType,
+          typename HintType,
+          FinalizerWithHint<DataType, HintType> fini =
+            Env::DefaultFiniWithHint<DataType, HintType>>
+void SetInstanceData(DataType* data, HintType* hint);
+```
+
+- `[template] fini`: A function to call when the instance data is to be deleted.
+Accepts a function of the form
+`void CleanupData(Napi::Env env, DataType* data, HintType* hint)`. If not given,
+the default finalizer will be used, which simply uses the `delete` operator to
+destroy `T*` when the addon instance is unloaded.
+- `[in] data`: A pointer to data that will be associated with the instance of
+the addon for the duration of its lifecycle.
+- `[in] hint`: A pointer to data that will be associated with the instance of
+the addon for the duration of its lifecycle and will be passed as a hint to
+`fini` when the addon instance is unloaded.
+
+Associates a data item stored at `T* data` with the current instance of the
+addon. The item will be passed to the function `fini` which gets called when an
+instance of the addon is unloaded. This overload accepts an additional hint to
+be passed to `fini`.

package/doc/error.md

@@ -1,5 +1,7 @@
 # Error
 
+Class `Napi::Error` inherits from class [`Napi::ObjectReference`][] and class [`std::exception`][].
+
 The `Napi::Error` class is a representation of the JavaScript `Error` object that is thrown
 when runtime errors occur. The Error object can also be used as a base object for
 user-defined exceptions.
@@ -113,3 +115,6 @@ const char* Napi::Error::what() const NAPI_NOEXCEPT override;
 
 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`]: 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/external.md

@@ -1,5 +1,7 @@
 # External (template)
 
+Class `Napi::External<T>` inherits from class [`Napi::Value`][].
+
 The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data.
 
 `Napi::External` objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your `Napi::External` object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function.
@@ -57,3 +59,5 @@ T* Napi::External::Data() const;
 ```
 
 Returns a pointer to the arbitrary C++ data held by the `Napi::External` object.
+
+[`Napi::Value`]: ./value.md