Async worker and error handling documentation

README.md

@@ -64,6 +64,8 @@ values. Concepts and operations generally map to ideas specified in the
         - [PropertyDescriptor](doc/property_descriptor.md)
  - [Error Handling](doc/error_handling.md)
     - [Error](doc/error.md)
+    - [TypeError](doc/type_error.md)
+    - [RangeError](doc/range_error.md)
  - [Object Lifettime Management](doc/object_lifetime_management.md)
     - [HandleScope](doc/handle_scope.md)
     - [EscapableHandleScope](doc/escapable_handle_scope.md)

doc/async_operations.md

@@ -1,5 +1,24 @@
 # Asynchronous operations
 
-You are reading a draft of the next documentation and it's in continuos update so
-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+Node.js native add-ons often need to execute long running tasks and to avoid
+blocking the **event loop** they have to run them asynchronously from the
+**event loop**.
+In the Node.js model of execution there are **two threads**, the first is the
+**event loop** thread, that represents the thread where JavaScript code is
+executing. The node.js guidance is to avoid you blocking other work queued on the
+event loop by. Therefore, we need to do this work on another thread.
+
+All this means that native add-ons need to leverage async helpers from libuv as
+part of their implementation. This allows them to schedule work to be executed
+asynchronously so that their methods can return in advance of the work being
+completed.
+
+Node Addon API provides an ABI-stable interface to support functions which covers
+the most common asynchronous use cases. You have two abstract class to implement
+asynchronous operation:
+
+- **[AsyncWorker](async_worker.md)**
+- **[Async Context](async_context.md)**
+
+These two classes help you to manage asynchronous operations through an abstraction
+of the concept of moving data between the **event loop** and **worker threads**.

doc/async_worker.md

@@ -1,5 +1,192 @@
-# Async worker
+# AsyncWorker
 
-You are reading a draft of the next documentation and it's in continuos update so
-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+`AsyncWorker` is an abstract class that you can subclass to remove much of the
+tedious tasks on moving data between the event loop and worker threads. This
+class internally handles all the details of creating and executing asynchronous
+operation.
+
+## Methods
+
+### Env
+
+Requests the environment in which the async worker has been initially created.
+
+```cpp
+Env Env() const;
+```
+
+Returns the environment in which the async worker has been created.
+
+### Queue
+
+Requests that the created work or task will be placed on the queue of the execution.
+
+```cpp
+void Queue();
+```
+
+### Cancel
+
+Cancels queued work if it has not yet been started. If it has already started
+executing, it cannot be cancelled.
+
+```cpp
+void Cancel();
+```
+
+### Receiver
+
+```cpp
+ObjectReference& Receiver();
+```
+
+Returns the persistent object reference of the receiver objet set when the async
+worker is created.
+
+### Callback
+
+```cpp
+FunctionReference& Callback();
+```
+
+Returns the persistent function reference of the callback set when the async
+worker is created. The returned function reference will be called passing it the
+results of the computation happened on the `Execute` method.
+
+### SetError
+
+Sets the error message for the error happened during the execution.
+
+```cpp
+void SetError(const std::string& error);
+```
+
+- `[in] error`: The reference to string that represent the message of the error.
+
+
+### Execute
+
+This method is used to execute some tasks out of the **event loop** on a libuv 
+worker thread. 
+
+```cpp
+virtual void Execute() = 0;
+```
+
+### OnOK
+
+This method represents a callback that is invoked when the computation on the
+`Excecute` method end.
+
+```cpp
+virtual void OnOK();
+```
+
+### OnError
+
+```cpp
+virtual void OnError(const Error& e);
+```
+
+### Constructor
+
+Creates new async worker
+
+```cpp
+explicit AsyncWorker(const Function& callback);
+```
+
+### Constructor
+
+Creates new async worker
+
+```cpp
+explicit AsyncWorker(const Object& receiver, const Function& callback);
+```
+
+### Destructor
+
+Deletes the created work object that is used to execute logic asynchronously
+
+```cpp
+virtual ~AsyncWorker();
+```
+
+## Operator
+
+```cpp
+operator napi_async_work() const;
+```
+
+Returns the N-API napi_async_work wrapped by the AsyncWorker object. This can be
+used to mix usage of the C N-API and node-addon-api.
+
+## Example
+
+The first step to use `AsyncWorker` class is to create a new class that inherit
+from it and implement the `Execute` abstract method. Typically input to your
+worker will be saved within your fields' class generally passed in through its
+constructor.
+
+When the `Execute` method complete without errors the `OnOK` function callback
+will be invoked. In this function the results of the computation will be
+reassembled and returned back to initial JavaScript context.
+
+`AsyncWorker` ensure that all the code inside in the `Execute` function runs in
+background out of the **event loop** thread and at the end `OnOK` or `OnError` 
+function will be called and are executed as part of the event loop.
+
+The code below show a basic example of `AsyncWorker` implementation:
+
+```cpp
+#include<napi.h>
+
+#include <chrono>
+#include <thread>
+
+use namespace Napi;
+
+class EchoWorker : public AsyncWorker {
+    public:
+        EchoWorker(Function& callback, std::string& echo)
+        : AsyncWorker(callback), echo(echo) {}
+
+        ~EchoWorker() {}
+    // This code will be executed on the worker thread
+    void Execute() {
+        // Need to simulate cpu heavy task
+        std::this_thread::sleep_for(std::chrono::seconds(1));
+    }
+
+    void OnOK() {
+        HandleScope scope(Env());
+        Callback().Call({Env().Null(), String::New(Env(), echo)});
+    }
+
+    private:
+        std::string echo;
+};
+```
+
+The `EchoWorker`'s contructor call the base class's constructor to pass in the
+callback that the `AsyncWorker` base class will store persistently. When the work
+on the `Execute` method is done the `OnOk` method is called and the results return
+back to JavaScript invoking the stored callback with its associated environment.
+
+The following code show an example on how to create and and use an `AsyncWorker`
+
+```cpp
+Value Echo(const CallbackInfo& info) {
+    // You need to check the input data 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();
+```
+
+Use the implementation of an `AsyncWorker` is very simple you need only to
+create a new instance and pass to its constructor the callback you want exectute
+when your asynchronous task end and other data you need for your computation. The
+only action you have to do is to call the `Queue` method that will place the
+crearted worker on the queue of the execution.

doc/error.md

@@ -1,5 +1,101 @@
 # Error
 
-You are reading a draft of the next documentation and it's in continuos update so
-if you don't find what you need please refer to:
-[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/)
+The **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.
+
+The **Error** class is a persistent reference to a JavaScript error object and
+inherits its behaviour from ObjectReference class (for more info see: [ObjectReference](object_reference.md)
+section).
+
+If C++ exceptions are enabled (for more info see: [Setup](setup.md) section),
+then the **Error** class extends ```std::exception``` and enables integrated
+error-handling for C++ exceptions and JavaScript exceptions.
+
+For more details about error handling refer to the section titled [Error handling](error_handling.md).
+
+## Methods
+
+### New
+
+Creates a new instance empty of ```Error``` object for the specified environment.
+
+```cpp
+Error::New(Napi:Env env);
+```
+
+- ```[in] Env```: The environment in which to construct the Error object.
+
+Returns an instance of ```Error``` object.
+
+### New
+
+Creates a new instance of ```Error``` object
+
+```cpp
+Error::New(Napi:Env env, const char* message);
+```
+
+- ```[in] Env```: The environment in which to construct the Error object.
+- ```[in] message```: Null-terminated strings to be used as the message for the Error.
+
+Returns an instance of ```Error``` object.
+
+### New
+
+Creates a new instance of ```Error``` object
+
+```cpp
+Error::New(Napi:Env env, const std::string& message);
+```
+
+- `[in] Env`: The environment in which to construct the Error object.
+- `[in] message`: Reference string to be used as the message for the Error.
+
+Returns an instance of ```Error``` object.
+
+### Constructor
+
+Creates a new empty instance of ```Error```
+
+```cpp
+Error();
+```
+
+### Constructor
+
+Initializes a ```Error``` instance from an existing ```Error``` object.
+
+```cpp
+TypeError(napi_env env, napi_value value);
+```
+
+- ```[in] Env```: The environment in which to construct the Error object.
+- ```[in] value```: The ```Error``` reference to wrap.
+
+Returns an instance of ```Error``` object.
+
+### Message
+
+```cpp
+std::string& Message() const NAPI_NOEXCEPT;
+```
+
+Returns the reference to string that represent the message of the error.
+
+### ThrowAsJavaScriptException
+
+```cpp
+void ThrowAsJavaScriptException() const;
+```
+
+Throw the error as JavaScript exception.
+
+### what
+
+```cpp
+const char* 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 eceptions mechanis is enabled.