node-addon-api 2.0.1 → 3.0.2

package/doc/array.md

@@ -0,0 +1,81 @@
+# Array
+
+Class [`Napi::Array`][] inherits from class [`Napi::Object`][].
+
+Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper
+around `napi_value` representing a JavaScript Array.
+
+[`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data
+types such as [`Napi::Int32Array`][] and [`Napi::ArrayBuffer`][], respectively,
+that can be used for transferring large amounts of data from JavaScript to the
+native side. An example illustrating the use of a JavaScript-provided
+`ArrayBuffer` in native code is available [here](https://github.com/nodejs/node-addon-examples/tree/master/array_buffer_to_native/node-addon-api).
+
+## Constructor
+```cpp
+Napi::Array::Array();
+```
+
+Returns an empty array.
+
+If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+```cpp
+Napi::Array::Array(napi_env env, napi_value value);
+```
+- `[in] env` - The environment in which to create the array.
+- `[in] value` - The primitive to wrap.
+
+Returns a `Napi::Array` wrapping a `napi_value`.
+
+If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+## Methods
+
+### New
+```cpp
+static Napi::Array Napi::Array::New(napi_env env);
+```
+- `[in] env` - The environment in which to create the array.
+
+Returns a new `Napi::Array`.
+
+If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+### New
+
+```cpp
+static Napi::Array Napi::Array::New(napi_env env, size_t length);
+```
+- `[in] env` - The environment in which to create the array.
+- `[in] length` - The length of the array.
+
+Returns a new `Napi::Array` with the given length.
+
+If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+### Length
+```cpp
+uint32_t Napi::Array::Length() const;
+```
+
+Returns the length of the array.
+
+Note:
+This can execute JavaScript code implicitly according to JavaScript semantics.
+If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
+being used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+[`Napi::ArrayBuffer`]: ./array_buffer.md
+[`Napi::Int32Array`]: ./typed_array_of.md
+[`Napi::Object`]: ./object.md
+[`Napi::TypedArray`]: ./typed_array.md

package/doc/array_buffer.md

@@ -1,5 +1,7 @@
 # ArrayBuffer
 
+Class `Napi::ArrayBuffer` inherits from class [`Napi::Object`][].
+
 The `Napi::ArrayBuffer` class corresponds to the
 [JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
 class.
@@ -127,3 +129,5 @@ void* Napi::ArrayBuffer::Data() const;
 ```
 
 Returns a pointer the wrapped data.
+
+[`Napi::Object`]: ./object.md

package/doc/async_worker.md

@@ -136,6 +136,35 @@ class was created, passing in the error as the first parameter.
 virtual void Napi::AsyncWorker::OnError(const Napi::Error& e);
 ```
 
+### OnWorkComplete
+
+This method is invoked after the work has completed on JavaScript thread.
+The default implementation of this method checks the status of the work and
+tries to dispatch the result to `Napi::AsyncWorker::OnOk` or `Napi::AsyncWorker::Error`
+if the work has committed an error. If the work was cancelled, neither
+`Napi::AsyncWorker::OnOk` nor `Napi::AsyncWorker::Error` will be invoked.
+After the result is dispatched, the default implementation will call into
+`Napi::AsyncWorker::Destroy` if `SuppressDestruct()` was not called.
+
+```cpp
+virtual void OnWorkComplete(Napi::Env env, napi_status status);
+```
+
+### OnExecute
+
+This method is invoked immediately on the work thread when scheduled.
+The default implementation of this method just calls the `Napi::AsyncWorker::Execute`
+and handles exceptions if cpp exceptions were enabled.
+
+The `OnExecute` method receives an `napi_env` argument. However, the `napi_env`
+must NOT be used within this method, as it does not run on the JavaScript
+thread and must not run any method that would cause JavaScript to run. In
+practice, this means that almost any use of `napi_env` will be incorrect.
+
+```cpp
+virtual void OnExecute(Napi::Env env);
+```
+
 ### Destroy
 
 This method is invoked when the instance must be deallocated. If
@@ -342,7 +371,7 @@ The code below shows a basic example of `Napi::AsyncWorker` the implementation:
 #include <chrono>
 #include <thread>
 
-use namespace Napi;
+using namespace Napi;
 
 class EchoWorker : public AsyncWorker {
     public:
@@ -351,12 +380,12 @@ class EchoWorker : public AsyncWorker {
 
         ~EchoWorker() {}
     // This code will be executed on the worker thread
-    void Execute() {
+    void Execute() override {
         // Need to simulate cpu heavy task
         std::this_thread::sleep_for(std::chrono::seconds(1));
     }
 
-    void OnOK() {
+    void OnOK() override {
         HandleScope scope(Env());
         Callback().Call({Env().Null(), String::New(Env(), echo)});
     }
@@ -380,7 +409,7 @@ The following code shows an example of how to create and use an `Napi::AsyncWork
 // Include EchoWorker class
 // ..
 
-use namespace Napi;
+using namespace Napi;
 
 Value Echo(const CallbackInfo& info) {
     // You need to validate the arguments here.

package/doc/{async_progress_worker.md → async_worker_variants.md}

@@ -272,12 +272,12 @@ called and are executed as part of the event loop.
 The code below shows a basic example of the `Napi::AsyncProgressWorker` implementation:
 
 ```cpp
-#include<napi.h>
+#include <napi.h>
 
 #include <chrono>
 #include <thread>
 
-use namespace Napi;
+using namespace Napi;
 
 class EchoWorker : public AsyncProgressWorker<uint32_t> {
     public:
@@ -323,7 +323,7 @@ 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
@@ -341,4 +341,116 @@ 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.
 
+# 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 shows a basic example of the `Napi::AsyncProgressQueueWorker` implementation:
+
+```cpp
+#include <napi.h>
+
+#include <chrono>
+#include <thread>
+
+using namespace Napi;
+
+class EchoWorker : public AsyncProgressQueueWorker<uint32_t> {
+    public:
+        EchoWorker(Function& callback, std::string& echo)
+        : AsyncProgressQueueWorker(callback), 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));
+        }
+    }
+
+    void OnOK() {
+        HandleScope scope(Env());
+        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)});
+    }
+
+    private:
+        std::string echo;
+};
+```
+
+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.
+    Function cb = info[1].As<Function>();
+    std::string in = info[0].As<String>();
+    EchoWorker* wk = new EchoWorker(cb, in);
+    wk->Queue();
+    return info.Env().Undefined();
+}
+```
+
+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.
+
 [`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)).
@@ -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/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,13 +27,13 @@ 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)
@@ -43,8 +43,8 @@ following the style used in publishing the previous release.
 
 * 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`]: http://cplusplus.com/reference/exception/exception/

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