Documentation for error handling

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

doc/error_handling.md

@@ -1,5 +1,138 @@
 # Error handling
 
-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 handling represents one of the most important thing on implementing a
+Node.js native add-on. When an error occurs in your C++ code you have to handle
+and dispatch it correctly. **N-API** uses return values and JavaScript exceptions
+for error handling. You can choice one method or other based on your preferences
+or on the C/C++, library that you are integrating.
+
+The **Error** is a persistent reference (for more info see: [Object reference](object_reference.md)
+section) to a JavaScript error object. Use of this class depends somewhat on
+whether C++ exceptions are enabled at compile time.
+
+The following sections explain the approach for each case:
+
+- [Handling Errors With C++ Exceptions](#exceptions)
+
+- [Handling Errors Without C++ Exceptions](#noexceptions)
+
+<a name="exceptions"></a>
+
+## Handling Errors With C++ Exceptions
+
+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.
+
+If a N-API call fails without executing any JavaScript code (for example due to
+an invalid argument), then the N-API wrapper automatically converts and throws
+the error as a C++ exception of type **Error**.
+
+If a JavaScript function called by C++ code via N-API throws a JavaScript
+exception, then the N-API wrapper automatically converts and throws it as a C++
+exception of type **Error**.
+
+If a C++ exception of type **Error** escapes from a N-API C++ callback, then
+the N-API wrapper automatically converts and throws it as a JavaScript exception.
+
+Therefore, catching a C++ exception of type **Error** prevents a JavaScript
+exception from being thrown.
+
+## Examples with C++ exceptions enabled
+
+### Throwing a C++ exception
+
+```cpp
+Napi::Env env = ...
+throw Napi::Error::New(env, "Example exception");
+// other C++ statements
+// ...
+```
+
+Following C++ statements will not be executed. The exception will bubble up as a
+C++ exception of type **Error**, until it is either caught while still in C++, or
+else automatically propataged as a JavaScript exception when returns to
+JavaScript.
+
+### Propagating a N-API C++ exception
+
+```cpp
+Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
+Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
+// other C++ statements
+// ...
+```
+
+Following C++ statements will not be executed. The exception will bubble up as a
+C++ exception of type **Error**, until it is either caught while still in C++, or
+else automatically propagated as a JavaScript exception when returns to 
+JavaScript.
+
+### Handling a N-API C++ exception
+
+```cpp
+Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
+Napi::Value result;
+try {
+    result = jsFunctionThatThrows({ arg1, arg2 });
+} catch (const Napi::Error& e) {
+    cerr << "Caught JavaScript exception: " + e.what();
+}
+```
+
+Since the exception was caught here, it will not be propagated as a JavaScript
+exception.
+
+<a name="noexceptions"></a>
+
+## Handling Errors Without C++ Exceptions
+
+If C++ exceptions are disabled (for more info see: [Setup](setup.md) section),
+then the **Error**  class does not extend ```std::exception```. This means that
+any call to node-addon-api functions does not throw C++ exception.
+Instead, it raises _pending_ JavaScript exceptions and return _empty_ **Value**.
+The calling code should check ```Value::IsEmpty()``` (for more info see: [Value](value.md))
+before attempting or use a returned value, and may use methods on the **Env** class
+to check for, get, and clear a pending JavaScript exception (for more info see: [Env](env.md)).
+If the pending exception is not cleared, it will be thrown when the native code
+returns to JavaScript.
+
+## Examples with C++ exceptions disabled
+
+### Throwing a JS exception
+
+```cpp
+Napi::Env env = ...
+Napi::Error::New(env, "Example exception").ThrowAsJavaScriptException();
+return;
+```
+
+After throwing a JS exception, the code should generally return immediately from
+the native callback, after performing any necessary cleanup.
+
+### Propagating a N-API JS exception
+
+```cpp
+Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
+Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
+if (result.IsEmpty()) return;
+```
+
+An empty value result from a N-API call indicates that an error occurred, and a
+JavaScript exception is pending. To let the exception propagate, the code should
+generally return immediately from the native callback, after performing any
+necessary cleanup.
+
+### Handling a N-API JS exception
+
+```cpp
+Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
+Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
+if (result.IsEmpty()) {
+    Napi::Error e = env.GetAndClearPendingException();
+    cerr << "Caught JavaScript exception: " + e.Message();
+}
+```
+
+Since the exception was cleared here, it will not be propagated as a JavaScript
+exception after the native callback returns.

doc/range_error.md

@@ -0,0 +1,59 @@
+# RangeError
+
+The **RangeError** class is a representation of the JavaScript RangeError that is
+thrown when trying to pass a value as an argument to a function that does not allow
+a range that includes the value.
+
+The **RangeError** class inherits its behaviours from **Error** class (for more info
+see: [Error](error.md) section).
+
+For more details about error handling refer to the section titled [Error handling](error_handling.md).
+
+## Methods
+
+### New
+
+Creates a new instance of ```RangeError``` object
+
+```cpp
+RangeError::New(Napi:Env env, const char* message);
+```
+
+- ```[in] Env```: The environment in which to construct the RangeError object.
+- ```[in] message```: Null-terminated strings to be used as the message for the RangeError.
+
+Returns an instance of ```RangeError``` object.
+
+### New
+
+Creates a new instance of ```RangeError``` object
+
+```cpp
+RangeError::New(Napi:Env env, const std::string& message);
+```
+
+- `[in] Env`: The environment in which to construct the RangeError object.
+- `[in] message`: Reference string to be used as the message for the RangeError.
+
+Returns an instance of ```RangeError``` object.
+
+### Constructor
+
+Creates a new empty instance of ```RangeError```
+
+```cpp
+RangeError();
+```
+
+### Constructor
+
+Initializes a ```RangeError``` instance from an existing ```Error``` object.
+
+```cpp
+RangeError(napi_env env, napi_value value);
+```
+
+- ```[in] Env```: The environment in which to construct the RangeError object.
+- ```[in] value```: The ```Error``` reference to wrap.
+
+Returns an instance of ```RangeError``` object.

doc/setup.md

@@ -19,7 +19,7 @@ To use **N-API** in a native module:
 
 ```json
   "dependencies": {
-    "node-addon-api": "1.1.0",
+    "node-addon-api": "1.2.0",
   }
 ```
 

doc/type_error.md

@@ -0,0 +1,59 @@
+# TypeError
+
+The **TypeError** class is a representation of the JavaScript TypeError that is
+thrown when an operand or argument passed to a function is incompatible with the
+type expected by the operator or function.
+
+The **TypeError** class inherits its behaviours from **Error** class (for more info
+see: [Error](error.md) section).
+
+For more details about error handling refer to the section titled [Error handling](error_handling.md).
+
+## Methods
+
+### New
+
+Creates a new instance of ```TypeError``` object
+
+```cpp
+TypeError::New(Napi:Env env, const char* message);
+```
+
+- ```[in] Env```: The environment in which to construct the TypeError object.
+- ```[in] message```: Null-terminated strings to be used as the message for the TypeError.
+
+Returns an instance of ```TypeError``` object.
+
+### New
+
+Creates a new instance of ```TypeError``` object
+
+```cpp
+TypeError::New(Napi:Env env, const std::string& message);
+```
+
+- `[in] Env`: The environment in which to construct the TypeError object.
+- `[in] message`: Reference string to be used as the message for the TypeError.
+
+Returns an instance of ```TypeError``` object.
+
+### Constructor
+
+Creates a new empty instance of ```TypeError```
+
+```cpp
+TypeError();
+```
+
+### Constructor
+
+Initializes a ```TypeError``` instance from an existing ```Error``` object.
+
+```cpp
+TypeError(napi_env env, napi_value value);
+```
+
+- ```[in] Env```: The environment in which to construct the TypeError object.
+- ```[in] value```: The ```Error``` reference to wrap.
+
+Returns an instance of ```TypeError``` object.