External memory management

README.md

@@ -76,6 +76,7 @@ values. Concepts and operations generally map to ideas specified in the
     - [ArrayBuffer](doc/array_buffer.md)
     - [TypedArray](doc/typed_array.md)
       - [TypedArrayOf](doc/typed_array_of.md)
+ - [Memory Management](doc/memory_management.md)     
  - [Async Operations](doc/async_operations.md)
     - [AsyncWorker](async_worker.md)
  - [Promises](doc/promises.md)

doc/error.md

@@ -1,5 +1,114 @@
 # 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.
+
+### Fatal
+
+In case of an unrecoverable error in a native module, a fatal error can be thrown
+to immediately terminate the process.
+
+```cpp
+static NAPI_NO_RETURN void Fatal(const char* location, const char* message);
+```
+
+The function call does not return, the process will be terminated.
+
+### Constructor
+
+Creates a new empty instance of `Error`
+
+```cpp
+Error();
+```
+
+### Constructor
+
+Initializes a `Error` instance from an existing JavaScript error object.
+
+```cpp
+Error(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
+
+Throw the error as JavaScript exception.
+
+```cpp
+void ThrowAsJavaScriptException() const;
+```
+
+Throws 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 exception mechanism is enabled.

doc/error_handling.md

@@ -1,5 +1,151 @@
 # 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/)
+Error handling represents one of the most important considerations when
+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 choose return values or
+exception handling based on the mechanism that works best for your add-on.
+
+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 on whether C++
+exceptions are enabled at compile time.
+
+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.
+
+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
+
+When C++ exceptions are enabled try/catch can be used to catch exceptions thrown
+from calls to JavaScript and then they can either be handled or rethrown before
+returning from a native method.
+
+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** on return from the JavaScript code to the native 
+method.
+
+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.
+
+On return from a native method, N-API will automatically convert a pending C++
+exception to a JavaScript exception.
+
+When C++ exceptions are enabled try/catch can be used to catch exceptions thrown
+from calls to JavaScript and then they can either be handled or rethrown before
+returning from a native method.
+
+## Examples with C++ exceptions enabled
+
+### Throwing a C++ exception
+
+```cpp
+Env env = ...
+throw 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 propagated as a JavaScript exception when returns to
+JavaScript.
+
+### Propagating a N-API C++ exception
+
+```cpp
+Function jsFunctionThatThrows = someObj.As<Function>();
+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
+Function jsFunctionThatThrows = someObj.As<Function>();
+Value result;
+try {
+    result = jsFunctionThatThrows({ arg1, arg2 });
+} catch (const 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
+calls to node-addon-api function do not throw C++ exceptions. 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
+Env env = ...
+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
+Env env = ...
+Function jsFunctionThatThrows = someObj.As<Function>();
+Value result = jsFunctionThatThrows({ arg1, arg2 });
+if (env.IsExceptionPending()) {
+    Error e = env.GetAndClearPendingException();
+    return e.Value();
+}
+```
+
+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
+Env env = ...
+Function jsFunctionThatThrows = someObj.As<Function>();
+Value result = jsFunctionThatThrows({ arg1, arg2 });
+if (env.IsExceptionPending()) {
+    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/memory_management.md

@@ -0,0 +1,24 @@
+# Memory Management
+
+The function `AdjustExternalMemory` adjusts the amount of registered external
+memory. Used to give the JavaScript engine an indication of the amount of externally
+allocated memory that is kept alive by JavaScript objects.
+The JavaScript engine uses this to decide when to perform global garbage collections.
+Registering externally allocated memory will trigger global garbage collections
+more often than it would otherwise in an attempt to garbage collect the JavaScript
+objects that keep the externally allocated memory alive.
+
+## AdjustExternalMemory
+
+This function gives the JavaScript engine an indication of the amount of externally
+allocated memory that is kept alive by JavaScript objects.
+
+```cpp
+int64_t AdjustExternalMemory(napi_env env, int64_t change_in_bytes);
+```
+
+- `[in] env`: The environment in which the API is inoked under.
+- `[in] change_in_bytes`: The change in externally allocated memory that is kept 
+alive by JavaScript objects expressed in bytes.
+
+Returns the adjusted memory value.

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 Javascript 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",
   }
 ```