diff --git a/README.md b/README.md index ebf6fec2d..409fd1d16 100644 --- a/README.md +++ b/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) diff --git a/doc/error.md b/doc/error.md index 5ad6befc8..c0c71d637 100644 --- a/doc/error.md +++ b/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/) \ No newline at end of file +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. \ No newline at end of file diff --git a/doc/error_handling.md b/doc/error_handling.md index 14c0c4ac0..093ba6736 100644 --- a/doc/error_handling.md +++ b/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/) \ No newline at end of file +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) + + + +## 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(); +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(); +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. + + + +## 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(); +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(); +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. \ No newline at end of file diff --git a/doc/range_error.md b/doc/range_error.md new file mode 100644 index 000000000..776401399 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/setup.md b/doc/setup.md index be95e747e..176815a96 100644 --- a/doc/setup.md +++ b/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", } ``` diff --git a/doc/type_error.md b/doc/type_error.md new file mode 100644 index 000000000..1fd2532ba --- /dev/null +++ b/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 JavaScript 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. \ No newline at end of file