koffi 1.1.0-beta.1 → 1.1.0-beta.4

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

@@ -0,0 +1,254 @@
+# 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

@@ -0,0 +1,80 @@
+# 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

@@ -0,0 +1,63 @@
+# 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