koffi 2.16.0-beta.2 → 2.16.0

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

@@ -1,266 +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.
-
-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.
-
-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,79 +0,0 @@
-# External (template)
-
-Class `Napi::External<T>` inherits from class [`Napi::TypeTaggable`][].
-
-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. See [Finalization][] for more details.
-
-Note that `Napi::Value::IsExternal()` will return `true` for any external value.
-It does not differentiate between the templated parameter `T` in
-`Napi::External<T>`. It is up to the addon to ensure an `Napi::External<T>`
-object holds the correct `T` when retrieving the data via
-`Napi::External<T>::Data()`. One method to ensure an object is of a specific
-type is through [type tags](./object.md#TypeTag).
-
-## 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`: The function called when the engine destroys the
-  `Napi::External` object, implementing `operator()(Napi::BasicEnv, T*)`. See
-  [Finalization][] for more details.
-
-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`: The function called when the engine destroys the
-  `Napi::External` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`.
-  See [Finalization][] for more details.
-- `[in] finalizeHint`: The 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.
-
-[Finalization]: ./finalization.md
-[`Napi::TypeTaggable`]: ./type_taggable.md

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

@@ -1,18 +0,0 @@
-# External Buffer
-
-**Some runtimes other than Node.js have dropped support for external buffers**.
-On runtimes other than Node.js, node-api methods may return
-`napi_no_external_buffers_allowed` to indicate that external
-buffers are not supported. One such runtime is Electron as
-described in this issue
-[electron/issues/35801](https://github.com/electron/electron/issues/35801).
-
-In order to maintain broadest compatibility with all runtimes,
-you may define `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` in your addon before
-includes for the node-api and node-addon-api headers. Doing so will hide the
-functions that create external buffers. This will ensure a compilation error
-occurs if you accidentally use one of these methods.
-
-In node-addon-api, the `Napi::Buffer::NewOrCopy` provides a convenient way to
-create an external buffer, or allocate a new buffer and copy the data when the
-external buffer is not supported.

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

@@ -1,153 +0,0 @@
-# Finalization
-
-Various node-addon-api methods accept a templated `Finalizer finalizeCallback`
-parameter. This parameter represents a native callback function that runs in
-response to a garbage collection event. A finalizer is considered a _basic_
-finalizer if the callback only utilizes a certain subset of APIs, which may
-provide more efficient memory management, optimizations, improved execution, or
-other benefits.
-
-In general, it is best to use basic finalizers whenever possible (eg. when
-access to JavaScript is _not_ needed). The
-`NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS` preprocessor directive can be defined
-to ensure that all finalizers are basic.
-
-## Finalizers
-
-The callback takes `Napi::Env` as its first argument:
-
-### Example
-
-```cpp
-Napi::External<int>::New(Env(), new int(1), [](Napi::Env env, int* data) {
-  env.RunScript("console.log('Finalizer called')");
-  delete data;
-});
-```
-
-## Basic Finalizers
-
-Use of basic finalizers may allow the engine to perform optimizations when
-scheduling or executing the callback. For example, V8 does not allow access to
-the engine heap during garbage collection. Restricting finalizers from accessing
-the engine heap allows the callback to execute during garbage collection,
-providing a chance to free native memory eagerly.
-
-In general, APIs that access engine heap are not allowed in basic finalizers.
-
-The callback takes `Napi::BasicEnv` as its first argument:
-
-### Example
-
-```cpp
-Napi::ArrayBuffer::New(
-    Env(), data, length, [](Napi::BasicEnv /*env*/, void* finalizeData) {
-      delete[] static_cast<uint8_t*>(finalizeData);
-    });
-```
-
-## Scheduling Finalizers
-
-In addition to passing finalizers to `Napi::External`s and other Node-API
-constructs, `Napi::BasicEnv::PostFinalize(Napi::BasicEnv, Finalizer)` can be
-used to schedule a callback to run outside of the garbage collector
-finalization. Since the associated native memory may already be freed by the
-basic finalizer, any additional data may be passed eg. via the finalizer's
-parameters (`T data*`, `Hint hint*`) or via lambda capture. This allows for
-freeing native data in a basic finalizer, while executing any JavaScript code in
-an additional finalizer.
-
-### Example
-
-```cpp
-// Native Add-on
-
-#include <iostream>
-#include <memory>
-#include "napi.h"
-
-using namespace Napi;
-
-// A structure representing some data that uses a "large" amount of memory.
-class LargeData {
- public:
-  LargeData() : id(instances++) {}
-  size_t id;
-
-  static size_t instances;
-};
-
-size_t LargeData::instances = 0;
-
-// Basic finalizer to free `LargeData`. Takes ownership of the pointer and
-// frees its memory after use.
-void MyBasicFinalizer(Napi::BasicEnv env, LargeData* data) {
-  std::unique_ptr<LargeData> instance(data);
-  std::cout << "Basic finalizer for instance " << instance->id
-            << " called\n";
-
-  // Register a finalizer. Since the instance will be deleted by
-  // the time this callback executes, pass the instance's `id` via lambda copy
-  // capture and _not_ a reference capture that accesses `this`.
-  env.PostFinalizer([instanceId = instance->id](Napi::Env env) {
-    env.RunScript("console.log('Finalizer for instance " +
-                  std::to_string(instanceId) + " called');");
-  });
-
-  // Free the `LargeData` held in `data` once `instance` goes out of scope.
-}
-
-Value CreateExternal(const CallbackInfo& info) {
-  // Create a new instance of LargeData.
-  auto instance = std::make_unique<LargeData>();
-
-  // Wrap the instance in an External object, registering a basic
-  // finalizer that will delete the instance to free the "large" amount of
-  // memory.
-  return External<LargeData>::New(info.Env(), instance.release(), MyBasicFinalizer);
-}
-
-Object Init(Napi::Env env, Object exports) {
-  exports["createExternal"] = Function::New(env, CreateExternal);
-  return exports;
-}
-
-NODE_API_MODULE(addon, Init)
-```
-
-```js
-// JavaScript
-
-const { createExternal } = require('./addon.node');
-
-for (let i = 0; i < 5; i++) {
-  const ext = createExternal();
-  // ... do something with `ext` ..
-}
-
-console.log('Loop complete');
-await new Promise(resolve => setImmediate(resolve));
-console.log('Next event loop cycle');
-```
-
-Possible output:
-
-```
-Basic finalizer for instance 0 called
-Basic finalizer for instance 1 called
-Basic finalizer for instance 2 called
-Basic finalizer for instance 3 called
-Basic finalizer for instance 4 called
-Loop complete
-Finalizer for instance 3 called
-Finalizer for instance 4 called
-Finalizer for instance 1 called
-Finalizer for instance 2 called
-Finalizer for instance 0 called
-Next event loop cycle
-```
-
-If the garbage collector runs during the loop, the basic finalizers execute and
-display their logging message synchronously during the loop execution. The
-additional finalizers execute at some later point after the garbage collection
-cycle.