koffi 0.9.33 → 0.9.34

package/vendor/node-addon-api/doc/error_handling.md

@@ -1,254 +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.
-
-Note, that due to limitations of the Node-API, if one attempts to cast the error object wrapping a primitive inside a C++ addon, the wrapped object
-will be received instead. (With property `4bda9e7e-4913-4dbc-95de-891cbf66598e-errorVal` containing the primitive value thrown)
-
-The following sections explain the approach for each case:
-
-- [Handling Errors With C++ Exceptions](#exceptions)
-- [Handling Errors With Maybe Type and C++ Exceptions Disabled](#noexceptions-maybe)
-- [Handling Errors Without C++ Exceptions](#noexceptions)
-
-<a name="exceptions"></a>
-
-In most cases when an error occurs, the addon should do whatever cleanup is possible
-and then return to JavaScript so that the 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 Node-API C++ callback, then
-the Node-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 Node-API C++ exception
-
-```cpp
-Napi::Function jsFunctionThatThrows = someValue.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 Node-API C++ exception
-
-```cpp
-Napi::Function jsFunctionThatThrows = someValue.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-maybe"></a>
-
-## Handling Errors With Maybe Type and C++ Exceptions Disabled
-
-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 functions do not throw a C++ exceptions. Instead, these node-api
-functions that call into JavaScript are returning with `Maybe` boxed values.
-In that case, the calling side should convert the `Maybe` boxed values with
-checks to ensure that the call did succeed and therefore no exception is pending.
-If the check fails, that is to say, the returning value is _empty_, the calling
-side should determine what to do with `env.GetAndClearPendingException()` before
-attempting to call another node-api (for more info see: [Env](env.md)).
-
-The conversion from the `Maybe` boxed value to the actual return value is
-enforced by compilers so that the exceptions must be properly handled before
-continuing.
-
-## Examples with Maybe Type and 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 Node-API JS exception
-
-```cpp
-Napi::Env env = ...
-Napi::Function jsFunctionThatThrows = someValue.As<Napi::Function>();
-Maybe<Napi::Value> maybeResult = jsFunctionThatThrows({ arg1, arg2 });
-Napi::Value result;
-if (!maybeResult.To(&result)) {
-    // The Maybe is empty, calling into js failed, cleaning up...
-    // It is recommended to return an empty Maybe if the procedure failed.
-    return result;
-}
-```
-
-If `maybeResult.To(&result)` returns false 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 Node-API JS exception
-
-```cpp
-Napi::Env env = ...
-Napi::Function jsFunctionThatThrows = someValue.As<Napi::Function>();
-Maybe<Napi::Value> maybeResult = jsFunctionThatThrows({ arg1, arg2 });
-if (maybeResult.IsNothing()) {
-    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.
-
-<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 Node-API JS exception
-
-```cpp
-Napi::Env env = ...
-Napi::Function jsFunctionThatThrows = someValue.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 Node-API JS exception
-
-```cpp
-Napi::Env env = ...
-Napi::Function jsFunctionThatThrows = someValue.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 Node-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 [Node-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/vendor/node-addon-api/doc/escapable_handle_scope.md

@@ -1,80 +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 Node-API and node-addon-api.
-
-```cpp
-operator Napi::EscapableHandleScope::napi_escapable_handle_scope() const
-```
-
-Returns the Node-API `napi_escapable_handle_scope` wrapped by the `Napi::EscapableHandleScope` object.
-This can be used to mix usage of the C Node-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/vendor/node-addon-api/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