feat: allow catching all exceptions (#1593)

* feat: allow catching all exceptions

* Address review comments

Author: KevinEady

doc/cmake-js.md

@@ -45,6 +45,25 @@ The following line in the `CMakeLists.txt` file will enable Node-API experimenta
 add_definitions(-DNAPI_EXPERIMENTAL)
 ```
 
+### Exception Handling
+
+To enable C++ exception handling (for more info see: [Setup](setup.md)), define
+the corresponding preprocessor directives depending on which exception handling
+behavior is desired.
+
+To enable C++ exception handling with `Napi::Error` objects only:
+
+```
+add_definitions(-DNAPI_EXPERIMENTAL)
+```
+
+To enable C++ exception handling for all exceptions thrown:
+
+```
+add_definitions(-DNODE_ADDON_API_CPP_EXCEPTIONS)
+add_definitions(-DNODE_ADDON_API_CPP_EXCEPTIONS_ALL)
+```
+
 ### node-addon-api
 
 If your Node-API native add-on uses the optional [**node-addon-api**](https://github.com/nodejs/node-addon-api#node-addon-api-module) C++ wrapper, the `CMakeLists.txt` file requires additional configuration information as described on the [CMake.js README file](https://github.com/cmake-js/cmake-js#node-api-and-node-addon-api).

doc/error_handling.md

@@ -48,6 +48,18 @@ method.
 If a C++ exception of type `Napi::Error` escapes from a Node-API C++ callback, then
 the Node-API wrapper automatically converts and throws it as a JavaScript exception.
 
+If other types of C++ exceptions are thrown, node-addon-api will either abort
+the process or wrap the exception in an `Napi::Error` in order to throw it as a
+JavaScript exception. This behavior is determined by which node-gyp dependency
+used:
+
+- When using the `node_addon_api_except` dependency, only `Napi::Error` objects
+  will be handled.
+- When using the `node_addon_api_except_all` dependency, all exceptions will be
+handled. For exceptions derived from `std::exception`, an `Napi::Error` will be
+created with the message of the exception's `what()` member function. For all
+other exceptions, an `Napi::Error` will be created with a generic error message.
+
 On return from a native method, node-addon-api will automatically convert a pending
 `Napi::Error` C++ exception to a JavaScript exception.
 

doc/setup.md

@@ -38,14 +38,26 @@ To use **Node-API** in a native module:
        ],
      ```
 
-     To enable that capability, add an alternative dependency in `binding.gyp`:
+     To enable that capability, add an alternative dependency in `binding.gyp`
+     depending on if you want to integrate C++ exception handling for exceptions
+     derived from `Napi::Error` or all C++ exceptions. To catch only
+     `Napi::Error` exceptions, use:
 
      ```gyp
        'dependencies': [
          "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except",
        ],
      ```
 
+     Or, to allow catching all native C++ exceptions, use the
+     `node_addon_api_except_all` dependency:
+
+     ```gyp
+       'dependencies': [
+         "<!(node -p \"require('node-addon-api').targets\"):node_addon_api_except_all",
+       ],
+     ```
+
      If you decide to use node-addon-api without C++ exceptions enabled, please
      consider enabling node-addon-api safe API type guards to ensure the proper
      exception handling pattern: