node-addon-api 1.7.2 → 2.0.0

package/doc/async_worker.md

@@ -7,8 +7,8 @@ operation.
 
 Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When
 a thread is available for execution the `Napi::AsyncWorker::Execute` method will
-be invoked.  Once `Napi::AsyncWorker::Execute` completes either
-`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked.  Once
+be invoked. Once `Napi::AsyncWorker::Execute` completes either
+`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once
 the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are
 complete the `Napi::AsyncWorker` instance is destructed.
 
@@ -38,7 +38,7 @@ void Napi::AsyncWorker::Queue();
 ### Cancel
 
 Cancels queued work if it has not yet been started. If it has already started
-executing, it cannot be cancelled.  If cancelled successfully neither
+executing, it cannot be cancelled. If cancelled successfully neither
 `OnOK` nor `OnError` will be called.
 
 ```cpp
@@ -90,14 +90,14 @@ void Napi::AsyncWorker::SetError(const std::string& error);
 
 ### Execute
 
-This method is used to execute some tasks out of the **event loop** on a libuv
+This method is used to execute some tasks outside of the **event loop** on a libuv
 worker thread. Subclasses must implement this method and the method is run on
-a thread other than that running the main event loop.  As the method is not
+a thread other than that running the main event loop. As the method is not
 running on the main event loop, it must avoid calling any methods from node-addon-api
 or running any code that might invoke JavaScript. Instead, once this method is
 complete any interaction through node-addon-api with JavaScript should be implemented
-in the `Napi::AsyncWorker::OnOK` method which runs on the main thread and is
-invoked when the `Napi::AsyncWorker::Execute` method completes.
+in the `Napi::AsyncWorker::OnOK` method and `Napi::AsyncWorker::OnError` which run
+on the main thread and are invoked when the `Napi::AsyncWorker::Execute` method completes.
 
 ```cpp
 virtual void Napi::AsyncWorker::Execute() = 0;
@@ -106,18 +106,19 @@ virtual void Napi::AsyncWorker::Execute() = 0;
 ### OnOK
 
 This method is invoked when the computation in the `Execute` method ends.
-The default implementation runs the Callback optionally provided when the AsyncWorker class
-was created. The callback will by default receive no arguments. To provide arguments,
-override the `GetResult()` method.
+The default implementation runs the `Callback` optionally provided when the
+`AsyncWorker` class was created. The `Callback` will by default receive no
+arguments. The arguments to the `Callback` can be provided by overriding the
+`GetResult()` method.
 
 ```cpp
 virtual void Napi::AsyncWorker::OnOK();
 ```
 ### GetResult
 
-This method returns the arguments passed to the Callback invoked by the default
+This method returns the arguments passed to the `Callback` invoked by the default
 `OnOK()` implementation. The default implementation returns an empty vector,
-providing no arguments to the Callback.
+providing no arguments to the `Callback`.
 
 ```cpp
 virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
@@ -128,7 +129,7 @@ virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
 This method is invoked after `Napi::AsyncWorker::Execute` completes if an error
 occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are
 enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`.
-The default implementation calls the callback provided when the `Napi::AsyncWorker`
+The default implementation calls the `Callback` provided when the `Napi::AsyncWorker`
 class was created, passing in the error as the first parameter.
 
 ```cpp
@@ -172,7 +173,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_
 
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`: Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -189,7 +190,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_
 
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -224,7 +225,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
 - `[in] receiver`: The `this` object passed to the called function.
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -242,7 +243,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
 - `[in] receiver`: The `this` object passed to the called function.
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -274,7 +275,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name);
 ```
 
 - `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
-- `[in] resource_name`: Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 
@@ -290,7 +291,7 @@ explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi:
 ```
 
 - `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
-- `[in] resource_name`:  Null-terminated strings that represents the
+- `[in] resource_name`: Null-terminated string that represents the
 identifier for the kind of resource that is being provided for diagnostic
 information exposed by the async_hooks API.
 - `[in] resource`: Object associated with the asynchronous operation that
@@ -333,7 +334,7 @@ function runs in the background out of the **event loop** thread and at the end
 the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` function will be
 called and are executed as part of the event loop.
 
-The code below show a basic example of `Napi::AsyncWorker` the implementation:
+The code below shows a basic example of `Napi::AsyncWorker` the implementation:
 
 ```cpp
 #include<napi.h>
@@ -371,7 +372,7 @@ the work on the `Napi::AsyncWorker::Execute` method is done the
 `Napi::AsyncWorker::OnOk` method is called and the results return back to
 JavaScript invoking the stored callback with its associated environment.
 
-The following code shows an example on how to create and use an `Napi::AsyncWorker`
+The following code shows an example of how to create and use an `Napi::AsyncWorker`.
 
 ```cpp
 #include<napi.h>
@@ -382,7 +383,7 @@ The following code shows an example on how to create and use an `Napi::AsyncWork
 use namespace Napi;
 
 Value Echo(const CallbackInfo& info) {
-    // You need to check the input data here
+    // You 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);

package/doc/basic_types.md

@@ -257,6 +257,14 @@ bool Napi::Value::IsExternal() const;
 Returns `true` if the underlying value is a N-API external object or `false`
 otherwise.
 
+#### IsDate
+```cpp
+bool Napi::Value::IsDate() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Date` or `false`
+otherwise.
+
 #### ToBoolean
 ```cpp
 Napi::Boolean Napi::Value::ToBoolean() const;

package/doc/class_property_descriptor.md

@@ -20,7 +20,7 @@ class Example : public Napi::ObjectWrap<Example> {
     static Napi::FunctionReference constructor;
     double _value;
     Napi::Value GetValue(const Napi::CallbackInfo &info);
-    Napi::Value SetValue(const Napi::CallbackInfo &info);
+    void SetValue(const Napi::CallbackInfo &info, const Napi::Value &value);
 };
 
 Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
@@ -52,12 +52,11 @@ Napi::Value Example::GetValue(const Napi::CallbackInfo &info) {
     return Napi::Number::New(env, this->_value);
 }
 
-Napi::Value Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) {
+void Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) {
     Napi::Env env = info.Env();
     // ...
     Napi::Number arg = value.As<Napi::Number>();
     this->_value = arg.DoubleValue();
-    return this->GetValue(info);
 }
 
 // Initialize native add-on

package/doc/cmake-js.md

@@ -1,19 +1,68 @@
 # CMake.js
 
-**CMake.js** is a build tool that allow native addon developer to compile their
-C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
-instead of Google's **gyp** format it is base on **CMake** build system.
+[**CMake.js**](https://github.com/cmake-js/cmake-js) is a build tool that allow native addon developers to compile their
+C or C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
+instead of Google's [**gyp**](https://gyp.gsrc.io) tool it is based on the [**CMake**](https://cmake.org) build system.
 
-## **CMake** reference
+## Quick Start
 
-  - [Installation](https://www.npmjs.com/package/cmake-js#installation)
-  - [How to use](https://www.npmjs.com/package/cmake-js#usage)
+### Install CMake
+
+CMake.js requires that CMake be installed. Installers for a variety of platforms can be found on the [CMake website](https://cmake.org).
+
+### Install CMake.js
+
+For developers, CMake.js is typically installed as a global package:
+
+```bash
+npm install -g cmake-js
+cmake-js --help
+```
+
+> For *users* of your native addon, CMake.js should be configured as a dependency in your `package.json` as described in the [CMake.js documentation](https://github.com/cmake-js/cmake-js).
+
+### CMakeLists.txt
+
+Your project will require a `CMakeLists.txt` file. The [CMake.js README file](https://github.com/cmake-js/cmake-js#usage) shows what's necessary.
+
+### NAPI_VERSION
+
+When building N-API addons, it's crucial to specify the N-API version your code is designed to work with. With CMake.js, this information is specified in the `CMakeLists.txt` file:
+
+```
+add_definitions(-DNAPI_VERSION=3)
+```
+
+Since N-API is ABI-stable, your N-API addon will work, without recompilation, with the N-API version you specify in `NAPI_VERSION` and all subsequent N-API versions.
+
+In the absence of a need for features available only in a specific N-API version, version 3 is a good choice as it is the version of N-API that was active when N-API left experimental status.
+
+### NAPI_EXPERIMENTAL
+
+The following line in the `CMakeLists.txt` file will enable N-API experimental features if your code requires them:
+
+```
+add_definitions(-DNAPI_EXPERIMENTAL)
+```
+
+### node-addon-api
+
+If your N-API native add-on uses the optional [**node-addon-api**](https://github.com/nodejs/node-addon-api#node-addon-api-module) C++ wrapper, the `CMakeLists.txt` file requires additional configuration information as described on the [CMake.js README file](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api).
+
+## Example
+
+A working example of an N-API native addon built using CMake.js can be found on the [node-addon-examples repository](https://github.com/nodejs/node-addon-examples/tree/master/build_with_cmake#building-n-api-addons-using-cmakejs).
+
+## **CMake** Reference
+
+  - [Installation](https://github.com/cmake-js/cmake-js#installation)
+  - [How to use](https://github.com/cmake-js/cmake-js#usage)
   - [Using N-API and node-addon-api](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api)
-  - [Tutorials](https://www.npmjs.com/package/cmake-js#tutorials)
-  - [Use case in the works - ArrayFire.js](https://www.npmjs.com/package/cmake-js#use-case-in-the-works---arrayfirejs)
+  - [Tutorials](https://github.com/cmake-js/cmake-js#tutorials)
+  - [Use case in the works - ArrayFire.js](https://github.com/cmake-js/cmake-js#use-case-in-the-works---arrayfirejs)
 
 Sometimes finding the right settings is not easy so to accomplish at most
 complicated task please refer to:
 
 - [CMake documentation](https://cmake.org/)
-- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)
+- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)

package/doc/date.md

@@ -0,0 +1,68 @@
+# 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))
+
+## Methods
+
+### Constructor
+
+Creates a new _empty_ instance of a `Napi::Date` object.
+
+```cpp
+Napi::Date::Date();
+```
+
+Creates a new _non-empty_ instance of a `Napi::Date` object.
+
+```cpp
+Napi::Date::Date(napi_env env, napi_value value);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::Date` object.
+ - `[in] value`: The `napi_value` which is a handle for a JavaScript `Date`.
+
+### New
+
+Creates a new instance of a `Napi::Date` object.
+
+```cpp
+static Napi::Date Napi::Date::New(Napi::Env env, double value);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::Date` object.
+ - `[in] value`: The time value the JavaScript `Date` will contain represented
+  as the number of milliseconds since 1 January 1970 00:00:00 UTC.
+
+Returns a new instance of `Napi::Date` object.
+
+### ValueOf
+
+```cpp
+double Napi::Date::ValueOf() const;
+```
+
+Returns the time value as `double` primitive represented as the number of
+ milliseconds since 1 January 1970 00:00:00 UTC.
+
+## Operators
+
+### operator double
+
+Converts a `Napi::Date` value to a `double` primitive.
+
+```cpp
+Napi::Date::operator double() const;
+```
+
+### Example
+
+The following shows an example of casting a `Napi::Date` value to a `double`
+ primitive.
+
+```cpp
+double operatorVal = Napi::Date::New(Env(), 0); // Napi::Date to double
+// or
+auto instanceVal = info[0].As<Napi::Date>().ValueOf();
+```

package/doc/object.md

@@ -137,6 +137,40 @@ Returns a `bool` that is true if the `Napi::Object` is an instance created by th
 
 Note: This is equivalent to the JavaScript instanceof operator.
 
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T>
+inline void AddFinalizer(Finalizer finalizeCallback, T* data);
+```
+
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+- `[in] data`: The data to associate with the object.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. `finalizeCallback`
+has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data);
+```
+where `data` is the pointer that was passed into the call to `AddFinalizer()`.
+
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T, typename Hint>
+inline void AddFinalizer(Finalizer finalizeCallback,
+                         T* data,
+                         Hint* finalizeHint);
+```
+
+- `[in] data`: The data to associate with the object.
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. An additional hint
+may be given. It will also be passed to `finalizeCallback`, which has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data, Hint* hint);
+```
+where `data` and `hint` are the pointers that were passed into the call to `AddFinalizer()`.
+
 ### DefineProperty()
 
 ```cpp

package/doc/object_wrap.md

@@ -161,7 +161,7 @@ static Napi::Function Napi::ObjectWrap::DefineClass(Napi::Env env,
 JavaScript constructor function.
 * `[in] properties`: Initializer list of class property descriptor describing
 static and instance properties and methods of the class.
-See: [`Class propertry and descriptor`](class_property_descriptor.md).
+See: [`Class property and descriptor`](class_property_descriptor.md).
 * `[in] data`: User-provided data passed to the constructor callback as `data`
 property of the `Napi::CallbackInfo`.
 
@@ -184,12 +184,23 @@ static Napi::Function Napi::ObjectWrap::DefineClass(Napi::Env env,
 JavaScript constructor function.
 * `[in] properties`: Vector of class property descriptor describing static and
 instance properties and methods of the class.
-See: [`Class propertry and descriptor`](class_property_descriptor.md).
+See: [`Class property and descriptor`](class_property_descriptor.md).
 * `[in] data`: User-provided data passed to the constructor callback as `data`
 property of the `Napi::CallbackInfo`.
 
 Returns a `Napi::Function` representing the constructor function for the class.
 
+### Finalize
+
+Provides an opportunity to run cleanup code that requires access to the `Napi::Env`
+before the wrapped native object instance is freed.  Override to implement.
+
+```cpp
+virtual void Finalize(Napi::Env env);
+```
+
+- `[in] env`: `Napi::Env`.
+
 ### StaticMethod
 
 Creates property descriptor that represents a static method of a JavaScript class.

package/doc/prebuild_tools.md

@@ -9,7 +9,7 @@ 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
 form of a native add-on.
 
-The following list report two of the tools that are compatible with **N-API**:
+The following list report known tools that are compatible with **N-API**:
 
 - **[node-pre-gyp](https://www.npmjs.com/package/node-pre-gyp)**
 - **[prebuild](https://www.npmjs.com/package/prebuild)**

package/doc/threadsafe_function.md

@@ -58,7 +58,10 @@ Napi::ThreadSafeFunction::ThreadSafeFunction(napi_threadsafe_function tsfn);
 - `tsfn`: The `napi_threadsafe_function` which is a handle for an existing
   thread-safe function.
 
-Returns a non-empty `Napi::ThreadSafeFunction` instance.
+Returns a non-empty `Napi::ThreadSafeFunction` instance. When using this
+constructor, only use the `Blocking(void*)` / `NonBlocking(void*)` overloads;
+the `Callback` and templated `data*` overloads should _not_ be used. See below
+for additional details.
 
 ### New
 
@@ -171,6 +174,9 @@ There are several overloaded implementations of `BlockingCall()` and
 `NonBlockingCall()` for use with optional parameters: skip the optional
 parameter for that specific overload.
 
+**These specific function overloads should only be used on a `ThreadSafeFunction`
+created via `ThreadSafeFunction::New`.**
+
 ```cpp
 napi_status Napi::ThreadSafeFunction::BlockingCall(DataType* data, Callback callback) const
 
@@ -186,6 +192,17 @@ napi_status Napi::ThreadSafeFunction::NonBlockingCall(DataType* data, Callback c
   necessary to call into JavaScript via `MakeCallback()` because N-API runs
   `callback` in a context appropriate for callbacks.
 
+**These specific function overloads should only be used on a `ThreadSafeFunction`
+created via `ThreadSafeFunction(napi_threadsafe_function)`.**
+
+```cpp
+napi_status Napi::ThreadSafeFunction::BlockingCall(void* data) const
+
+napi_status Napi::ThreadSafeFunction::NonBlockingCall(void* data) const
+```
+- `data`: Data to pass to `call_js_cb` specified when creating the thread-safe
+  function via `napi_create_threadsafe_function`.
+
 Returns one of:
 - `napi_ok`: The call was successfully added to the queue.
 - `napi_queue_full`: The queue was full when trying to call in a non-blocking

package/doc/value.md

@@ -10,6 +10,7 @@ The following classes inherit, either directly or indirectly, from `Napi::Value`
 - [`Napi::ArrayBuffer`](array_buffer.md)
 - [`Napi::Boolean`](boolean.md)
 - [`Napi::Buffer`](buffer.md)
+- [`Napi::Date`](date.md)
 - [`Napi::External`](external.md)
 - [`Napi::Function`](function.md)
 - [`Napi::Name`](name.md)
@@ -226,6 +227,14 @@ bool Napi::Value::IsBuffer() const;
 
 Returns a `bool` indicating if this `Napi::Value` is a Node buffer.
 
+### IsDate
+
+```cpp
+bool Napi::Value::IsDate() const;
+```
+
+Returns a `bool` indicating if this `Napi::Value` is a JavaScript date.
+
 ### As
 
 ```cpp