node-addon-api 3.1.0 → 3.2.0

package/doc/error_handling.md

@@ -1,186 +0,0 @@
-# Error handling
-
-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. **node-addon-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 `Napi::Error` is a persistent reference (for more info see: [`Napi::ObjectReference`](object_reference.md))
-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)), then the
-`Napi::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>
-
-In most cases when an error occurs, the addon should do whatever clean is possible
-and then return to JavaScript so that they error can be propagated.  In less frequent
-cases the addon may be able to recover from the error, clear the error and then
-continue.
-
-## 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 node-addon-api call fails without executing any JavaScript code (for example due to
-an invalid argument), then node-addon-api automatically converts and throws
-the error as a C++ exception of type `Napi::Error`.
-
-If a JavaScript function called by C++ code via node-addon-api throws a JavaScript
-exception, then node-addon-api automatically converts and throws it as a C++
-exception of type `Napi:Error` on return from the JavaScript code to the native
-method.
-
-If a C++ exception of type `Napi::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, node-addon-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 Napi::Error::New(env, "Example exception");
-// other C++ statements
-// ...
-```
-
-The statements following the throw statement will not be executed. The exception
-will bubble up as a C++ exception of type `Napi::Error`, until it is either caught
-while still in C++, or else automatically propagated as a JavaScript exception
-when returning 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
-// ...
-```
-
-The C++ statements following the call to the JavaScript function will not be
-executed. The exception will bubble up as a C++ exception of type `Napi::Error`,
-until it is either caught while still in C++, or else automatically propagated as
-a JavaScript exception when returning 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 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)), then the
-`Napi::Error` class does not extend `std::exception`. This means that any calls to
-node-addon-api function do not throw a C++ exceptions. Instead, it raises
-_pending_ JavaScript exceptions and returns an _empty_ `Napi::Value`.
-The calling code should check `env.IsExceptionPending()` before attempting to use a
-returned value, and may use methods on the `Napi::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 JavaScript exception, the code should generally return
-immediately from the native callback, after performing any necessary cleanup.
-
-### Propagating a N-API JS exception
-
-```cpp
-Napi::Env env = ...
-Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
-Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
-if (env.IsExceptionPending()) {
-    Error e = env.GetAndClearPendingException();
-    return e.Value();
-}
-```
-
-If env.IsExceptionPending() returns true 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::Env env = ...
-Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
-Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
-if (env.IsExceptionPending()) {
-    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.
-
-## Calling N-API directly from a **node-addon-api** addon
-
-**node-addon-api** provides macros for throwing errors in response to non-OK
-`napi_status` results when calling [N-API](https://nodejs.org/docs/latest/api/n-api.html)
-functions from within a native addon. These macros are defined differently
-depending on whether C++ exceptions are enabled or not, but are available for
-use in either case.
-
-### `NAPI_THROW(e, ...)`
-
-This macro accepts a `Napi::Error`, throws it, and returns the value given as
-the last parameter. If C++ exceptions are enabled (by defining
-`NAPI_CPP_EXCEPTIONS` during the build), the return value will be ignored.
-
-### `NAPI_THROW_IF_FAILED(env, status, ...)`
-
-This macro accepts a `Napi::Env` and a `napi_status`. It constructs an error
-from the `napi_status`, throws it, and returns the value given as the last
-parameter. If C++ exceptions are enabled (by defining `NAPI_CPP_EXCEPTIONS`
-during the build), the return value will be ignored.
-
-### `NAPI_THROW_IF_FAILED_VOID(env, status)`
-
-This macro accepts a `Napi::Env` and a `napi_status`. It constructs an error
-from the `napi_status`, throws it, and returns.
-
-### `NAPI_FATAL_IF_FAILED(status, location, message)`
-
-This macro accepts a `napi_status`, a C string indicating the location where the
-error occurred, and a second C string for the message to display.

package/doc/escapable_handle_scope.md

@@ -1,82 +0,0 @@
-# EscapableHandleScope
-
-The `Napi::EscapableHandleScope` class is used to manage the lifetime of object handles
-which are created through the use of node-addon-api. These handles
-keep an object alive in the heap in order to ensure that the objects
-are not collected by the garbage collector while native code is using them.
-A handle may be created when any new node-addon-api Value or one
-of its subclasses is created or returned.
-
-The `Napi::EscapableHandleScope` is a special type of `Napi::HandleScope`
-which allows a single handle to be "promoted" to an outer scope.
-
-For more details refer to the section titled
-[Object lifetime management](object_lifetime_management.md).
-
-## Methods
-
-### Constructor
-
-Creates a new escapable handle scope.
-
-```cpp
-Napi::EscapableHandleScope Napi::EscapableHandleScope::New(Napi:Env env);
-```
-
-- `[in] Env`: The environment in which to construct the `Napi::EscapableHandleScope` object.
-
-Returns a new `Napi::EscapableHandleScope`
-
-### Constructor
-
-Creates a new escapable handle scope.
-
-```cpp
-Napi::EscapableHandleScope Napi::EscapableHandleScope::New(napi_env env, napi_handle_scope scope);
-```
-
-- `[in] env`: napi_env in which the scope passed in was created.
-- `[in] scope`: pre-existing napi_handle_scope.
-
-Returns a new `Napi::EscapableHandleScope` instance which wraps the
-napi_escapable_handle_scope handle passed in. This can be used
-to mix usage of the C N-API and node-addon-api.
-
-operator EscapableHandleScope::napi_escapable_handle_scope
-
-```cpp
-operator Napi::EscapableHandleScope::napi_escapable_handle_scope() const
-```
-
-Returns the N-API napi_escapable_handle_scope wrapped by the `Napi::EscapableHandleScope` object.
-This can be used to mix usage of the C N-API and node-addon-api by allowing
-the class to be used be converted to a napi_escapable_handle_scope.
-
-### Destructor
-```cpp
-Napi::EscapableHandleScope::~EscapableHandleScope();
-```
-
-Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created
-in the scope to be collected by the garbage collector. There is no
-guarantee as to when the garbage collector will do this.
-
-### Escape
-
-```cpp
-napi::Value Napi::EscapableHandleScope::Escape(napi_value escapee);
-```
-
-- `[in] escapee`: Napi::Value or napi_env to promote to the outer scope
-
-Returns `Napi::Value` which can be used in the outer scope. This method can
-be called at most once on a given `Napi::EscapableHandleScope`. If it is called
-more than once an exception will be thrown.
-
-### Env
-
-```cpp
-Napi::Env Napi::EscapableHandleScope::Env() const;
-```
-
-Returns the `Napi::Env` associated with the `Napi::EscapableHandleScope`.

package/doc/external.md

@@ -1,63 +0,0 @@
-# External (template)
-
-Class `Napi::External<T>` inherits from class [`Napi::Value`][].
-
-The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data.
-
-`Napi::External` objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your `Napi::External` object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function.
-
-## Methods
-
-### New
-
-```cpp
-template <typename T>
-static Napi::External Napi::External::New(napi_env env, T* data);
-```
-
-- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
-- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
-
-Returns the created `Napi::External<T>` object.
-
-### New
-
-```cpp
-template <typename T>
-static Napi::External Napi::External::New(napi_env env,
-                    T* data,
-                    Finalizer finalizeCallback);
-```
-
-- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
-- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
-- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting a T* and returning void.
-
-Returns the created `Napi::External<T>` object.
-
-### New
-
-```cpp
-template <typename T>
-static Napi::External Napi::External::New(napi_env env,
-                    T* data,
-                    Finalizer finalizeCallback,
-                    Hint* finalizeHint);
-```
-
-- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
-- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
-- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting T* and Hint* parameters and returning void.
-- `[in] finalizeHint`: A hint value passed to the `finalizeCallback` function.
-
-Returns the created `Napi::External<T>` object.
-
-### Data
-
-```cpp
-T* Napi::External::Data() const;
-```
-
-Returns a pointer to the arbitrary C++ data held by the `Napi::External` object.
-
-[`Napi::Value`]: ./value.md