node-addon-api 1.6.3 → 2.0.0

package/doc/async_progress_worker.md

@@ -0,0 +1,344 @@
+# AsyncProgressWorker
+
+`Napi::AsyncProgressWorker` is an abstract class which implements `Napi::AsyncWorker`
+while extending `Napi::AsyncWorker` internally with `Napi::ThreadSafeFunction` for
+moving work progress reports from worker thread(s) to event loop threads.
+
+Like `Napi::AsyncWorker`, once created, execution is requested by calling
+`Napi::AsyncProgressWorker::Queue`. When a thread is available for execution
+the `Napi::AsyncProgressWorker::Execute` method will be invoked. During the
+execution, `Napi::AsyncProgressWorker::ExecutionProgress::Send` can be used to
+indicate execution process, which will eventually invoke `Napi::AsyncProgressWorker::OnProgress`
+on the JavaScript thread to safely call into JavaScript. Once `Napi::AsyncProgressWorker::Execute`
+completes either `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError`
+will be invoked. Once the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError`
+methods are complete the `Napi::AsyncProgressWorker` instance is destructed.
+
+For the most basic use, only the `Napi::AsyncProgressWorker::Execute` and
+`Napi::AsyncProgressWorker::OnProgress` method must be implemented in a subclass.
+
+## Methods
+
+[`Napi::AsyncWorker`][] provides detailed descriptions for most methods.
+
+### Execute
+
+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
+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::AsyncProgressWorker::OnOK` method and/or `Napi::AsyncProgressWorker::OnError`
+which run on the main thread and are invoked when the `Napi::AsyncProgressWorker::Execute`
+method completes.
+
+```cpp
+virtual void Napi::AsyncProgressWorker::Execute(const ExecutionProgress& progress) = 0;
+```
+
+### OnOK
+
+This method is invoked when the computation in the `Execute` method ends.
+The default implementation runs the `Callback` optionally provided when the
+`AsyncProgressWorker` class was created. The `Callback` will by default receive no
+arguments. Arguments to the callback can be provided by overriding the `GetResult()`
+method.
+
+```cpp
+virtual void Napi::AsyncProgressWorker::OnOK();
+```
+
+### OnProgress
+
+This method is invoked when the computation in the `Napi::AsyncProgressWorker::ExecutionProcess::Send`
+method was called during worker thread execution.
+
+```cpp
+virtual void Napi::AsyncProgressWorker::OnProgress(const T* data, size_t count)
+```
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Function& callback);
+```
+
+- `[in] callback`: The function which will be called when an asynchronous
+operations ends. The given function is called from the main event loop thread.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name);
+```
+
+- `[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 string that represents the
+identifier for the kind of resource that is being provided for diagnostic
+information exposed by the async_hooks API.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name, const Napi::Object& 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 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
+will be passed to possible async_hooks.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback);
+```
+
+- `[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.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name);
+```
+
+- `[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 string that represents the
+identifier for the kind of resource that is being provided for diagnostic
+information exposed by the async_hooks API.
+
+Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name, const Napi::Object& resource);
+```
+
+- `[in] receiver`: The `this` object to be 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 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
+will be passed to possible async_hooks.
+
+Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(Napi::Env env);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
+
+Returns an `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling
+`Napi::AsyncProgressWorker::Queue`.
+
+Available with `NAPI_VERSION` equal to or greater than 5.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
+- `[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.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncProgressWorker::Queue`.
+
+Available with `NAPI_VERSION` equal to or greater than 5.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
+- `[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
+will be passed to possible async_hooks.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncProgressWorker::Queue`.
+
+Available with `NAPI_VERSION` equal to or greater than 5.
+
+### Destructor
+
+Deletes the created work object that is used to execute logic asynchronously and
+release the internal `Napi::ThreadSafeFunction`, which will be aborted to prevent
+unexpected upcoming thread safe calls.
+
+```cpp
+virtual Napi::AsyncProgressWorker::~AsyncProgressWorker();
+```
+
+# AsyncProgressWorker::ExecutionProcess
+
+A bridge class created before the worker thread execution of `Napi::AsyncProgressWorker::Execute`.
+
+## Methods
+
+### Send
+
+`Napi::AsyncProgressWorker::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::AsyncProgressWorker` so
+after the call to `Napi::AsyncProgressWorker::ExecutionProcess::Send` the data can
+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.
+
+```cpp
+void Napi::AsyncProgressWorker::ExecutionProcess::Send(const T* data, size_t count) const;
+```
+
+## Example
+
+The first step to use the `Napi::AsyncProgressWorker` class is to create a new class that
+inherits from it and implement the `Napi::AsyncProgressWorker::Execute` abstract method.
+Typically input to the worker will be saved within the class' fields generally
+passed in through its constructor.
+
+During the worker thread execution, the first argument of `Napi::AsyncProgressWorker::Execute`
+can be used to report the progress of the execution.
+
+When the `Napi::AsyncProgressWorker::Execute` method completes without errors the
+`Napi::AsyncProgressWorker::OnOK` function callback will be invoked. In this function the
+results of the computation will be reassembled and returned back to the initial
+JavaScript context.
+
+`Napi::AsyncProgressWorker` ensures that all the code in the `Napi::AsyncProgressWorker::Execute`
+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:
+
+```cpp
+#include<napi.h>
+
+#include <chrono>
+#include <thread>
+
+use namespace Napi;
+
+class EchoWorker : public AsyncProgressWorker<uint32_t> {
+    public:
+        EchoWorker(Function& callback, std::string& echo)
+        : AsyncProgressWorker(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::AsyncProgressWorker` base class will store persistently. When
+the work on the `Napi::AsyncProgressWorker::Execute` method is done the
+`Napi::AsyncProgressWorker::OnOk` method is called and the results are return 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::AsyncProgressWorker`
+
+```cpp
+#include <napi.h>
+
+// Include EchoWorker class
+// ..
+
+use 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::AsyncProgressWorker` 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::AsyncProgressWorker::Queue`
+method that will queue the created worker for execution.
+
+[`Napi::AsyncWorker`]: ./async_worker.md

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
@@ -79,7 +79,7 @@ the `Napi::AsyncWorker::OnOK` callback.
 
 Sets the error message for the error that happened during the execution. Setting
 an error message will cause the `Napi::AsyncWorker::OnError` method to be
-invoked instead of `Napi::AsyncWorker::OnOKOnOK` once the
+invoked instead of `Napi::AsyncWorker::OnOK` once the
 `Napi::AsyncWorker::Execute` method completes.
 
 ```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;
@@ -105,26 +105,50 @@ virtual void Napi::AsyncWorker::Execute() = 0;
 
 ### OnOK
 
-This method is invoked when the computation in the `Excecute` method ends.
-The default implementation runs the Callback provided when the AsyncWorker class
-was created.
+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. 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
+`OnOK()` implementation. The default implementation returns an empty vector,
+providing no arguments to the `Callback`.
+
+```cpp
+virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
+```
 
 ### OnError
 
-This method is invoked afer `Napi::AsyncWorker::Execute` completes if an error
+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
 virtual void Napi::AsyncWorker::OnError(const Napi::Error& e);
 ```
 
+### Destroy
+
+This method is invoked when the instance must be deallocated. If
+`SuppressDestruct()` was not called then this method will be called after either
+`OnError()` or `OnOK()` complete. The default implementation of this method
+causes the instance to delete itself using the `delete` operator. The method is
+provided so as to ensure that instances allocated by means other than the `new`
+operator can be deallocated upon work completion.
+
+```cpp
+virtual void Napi::AsyncWorker::Destroy();
+```
+
 ### Constructor
 
 Creates a new `Napi::AsyncWorker`.
@@ -136,7 +160,7 @@ explicit Napi::AsyncWorker(const Napi::Function& callback);
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
 
-Returns a`Napi::AsyncWork` instance which can later be queued for execution by calling
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling
 `Queue`.
 
 ### Constructor
@@ -149,11 +173,11 @@ 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.
 
-Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
 calling `Napi::AsyncWork::Queue`.
 
 ### Constructor
@@ -166,13 +190,13 @@ 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
 will be passed to possible async_hooks.
 
-Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
 calling `Napi::AsyncWork::Queue`.
 
 ### Constructor
@@ -187,7 +211,7 @@ explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& c
 - `[in] callback`: The function which will be called when an asynchronous
 operations ends. The given function is called from the main event loop thread.
 
-Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
 calling `Napi::AsyncWork::Queue`.
 
 ### Constructor
@@ -195,13 +219,13 @@ calling `Napi::AsyncWork::Queue`.
 Creates a new `Napi::AsyncWorker`.
 
 ```cpp
-explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback,const char* resource_name);
+explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name);
 ```
 
 - `[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.
 
@@ -219,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
@@ -228,6 +252,54 @@ will be passed to possible async_hooks.
 Returns a `Napi::AsyncWork` instance which can later be queued for execution by
 calling `Napi::AsyncWork::Queue`.
 
+
+### Constructor
+
+Creates a new `Napi::AsyncWorker`.
+
+```cpp
+explicit Napi::AsyncWorker(Napi::Env env);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
+
+Returns an `Napi::AsyncWorker` instance which can later be queued for execution by calling
+`Napi::AsyncWorker::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncWorker`.
+
+```cpp
+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 string that represents the
+identifier for the kind of resource that is being provided for diagnostic
+information exposed by the async_hooks API.
+
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWorker::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncWorker`.
+
+```cpp
+explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
+- `[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
+will be passed to possible async_hooks.
+
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWorker::Queue`.
+
 ### Destructor
 
 Deletes the created work object that is used to execute logic asynchronously.
@@ -262,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>
@@ -300,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 and use an `Napi::AsyncWorker`
+The following code shows an example of how to create and use an `Napi::AsyncWorker`.
 
 ```cpp
 #include<napi.h>
@@ -311,7 +383,7 @@ The following code shows an example on how to create and and use an `Napi::Async
 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;
@@ -339,6 +347,12 @@ The value is not coerced to a string.
 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 [`Int32Array`][] and [`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();
@@ -402,3 +416,8 @@ 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::TypedArray`]: ./typed_array.md
+[`Napi::ArrayBuffer`]: ./array_buffer.md
+[`Int32Array`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int32Array
+[`ArrayBuffer`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer