koffi 2.12.1 → 2.12.2

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

@@ -1,8 +1,15 @@
 # Env
 
-The opaque data structure containing the environment in which the request is being run.
+Class `Napi::Env` inherits from class [`Napi::BasicEnv`][].
 
-The Env object is usually created and passed by the Node.js runtime or node-addon-api infrastructure.
+The data structure containing the environment in which the request is being run.
+
+The `Napi::Env` object is usually created and passed by the Node.js runtime or
+node-addon-api infrastructure.
+
+The `Napi::Env` object represents an environment that has a superset of APIs
+when compared to `Napi::BasicEnv` and therefore _cannot_ be used in basic
+finalizers. See [Finalization][] for more details.
 
 ## Methods
 
@@ -76,132 +83,5 @@ The `script` can be any of the following types:
 - `const char *`
 - `const std::string &`
 
-### GetInstanceData
-```cpp
-template <typename T> T* GetInstanceData() const;
-```
-
-Returns the instance data that was previously associated with the environment,
-or `nullptr` if none was associated.
-
-### SetInstanceData
-
-```cpp
-template <typename T> using Finalizer = void (*)(Env, T*);
-template <typename T, Finalizer<T> fini = Env::DefaultFini<T>>
-void SetInstanceData(T* data) const;
-```
-
-- `[template] fini`: A function to call when the instance data is to be deleted.
-Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
-not given, the default finalizer will be used, which simply uses the `delete`
-operator to destroy `T*` when the addon instance is unloaded.
-- `[in] data`: A pointer to data that will be associated with the instance of
-the addon for the duration of its lifecycle.
-
-Associates a data item stored at `T* data` with the current instance of the
-addon. The item will be passed to the function `fini` which gets called when an
-instance of the addon is unloaded.
-
-### SetInstanceData
-
-```cpp
-template <typename DataType, typename HintType>
-using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
-template <typename DataType,
-          typename HintType,
-          FinalizerWithHint<DataType, HintType> fini =
-            Env::DefaultFiniWithHint<DataType, HintType>>
-void SetInstanceData(DataType* data, HintType* hint) const;
-```
-
-- `[template] fini`: A function to call when the instance data is to be deleted.
-Accepts a function of the form
-`void CleanupData(Napi::Env env, DataType* data, HintType* hint)`. If not given,
-the default finalizer will be used, which simply uses the `delete` operator to
-destroy `T*` when the addon instance is unloaded.
-- `[in] data`: A pointer to data that will be associated with the instance of
-the addon for the duration of its lifecycle.
-- `[in] hint`: A pointer to data that will be associated with the instance of
-the addon for the duration of its lifecycle and will be passed as a hint to
-`fini` when the addon instance is unloaded.
-
-Associates a data item stored at `T* data` with the current instance of the
-addon. The item will be passed to the function `fini` which gets called when an
-instance of the addon is unloaded. This overload accepts an additional hint to
-be passed to `fini`.
-
-### GetModuleFileName
-
-```cpp
-const char* Napi::Env::GetModuleFileName() const;
-```
-
-Returns a A URL containing the absolute path of the location from which the
-add-on was loaded. For a file on the local file system it will start with
-`file://`. The string is null-terminated and owned by env and must thus not be
-modified or freed. It is only valid while the add-on is loaded.
-
-### AddCleanupHook
-
-```cpp
-template <typename Hook>
-CleanupHook<Hook> AddCleanupHook(Hook hook);
-```
-
-- `[in] hook`: A function to call when the environment exits. Accepts a
-  function of the form `void ()`.
-
-Registers `hook` as a function to be run once the current Node.js environment
-exits. Unlike the underlying C-based Node-API, providing the same `hook`
-multiple times **is** allowed. The hooks will be called in reverse order, i.e.
-the most recently added one will be called first.
-
-Returns an `Env::CleanupHook` object, which can be used to remove the hook via
-its `Remove()` method.
-
-### AddCleanupHook
-
-```cpp
-template <typename Hook, typename Arg>
-CleanupHook<Hook, Arg> AddCleanupHook(Hook hook, Arg* arg);
-```
-
-- `[in] hook`: A function to call when the environment exits. Accepts a
-  function of the form `void (Arg* arg)`.
-- `[in] arg`: A pointer to data that will be passed as the argument to `hook`.
-
-Registers `hook` as a function to be run with the `arg` parameter once the
-current Node.js environment exits. Unlike the underlying C-based Node-API,
-providing the same `hook` and `arg` pair multiple times **is** allowed. The
-hooks will be called in reverse order, i.e. the most recently added one will be
-called first.
-
-Returns an `Env::CleanupHook` object, which can be used to remove the hook via
-its `Remove()` method.
-
-# Env::CleanupHook
-
-The `Env::CleanupHook` object allows removal of the hook added via
-`Env::AddCleanupHook()`
-
-## Methods
-
-### IsEmpty
-
-```cpp
-bool IsEmpty();
-```
-
-Returns `true` if the cleanup hook was **not** successfully registered.
-
-### Remove
-
-```cpp
-bool Remove(Env env);
-```
-
-Unregisters the hook from running once the current Node.js environment exits.
-
-Returns `true` if the hook was successfully removed from the Node.js
-environment.
+[`Napi::BasicEnv`]: ./basic_env.md
+[Finalization]: ./finalization.md

package/vendor/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.
 

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

@@ -4,7 +4,11 @@ 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.
+`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
@@ -38,7 +42,9 @@ static Napi::External Napi::External::New(napi_env env,
 
 - `[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.
+- `[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.
 
@@ -54,8 +60,10 @@ static Napi::External Napi::External::New(napi_env env,
 
 - `[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.
+- `[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.
 
@@ -67,4 +75,5 @@ 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/finalization.md

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

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

@@ -17,7 +17,7 @@ more often than it would otherwise in an attempt to garbage collect the JavaScri
 objects that keep the externally allocated memory alive.
 
 ```cpp
-static int64_t Napi::MemoryManagement::AdjustExternalMemory(Napi::Env env, int64_t change_in_bytes);
+static int64_t Napi::MemoryManagement::AdjustExternalMemory(Napi::BasicEnv env, int64_t change_in_bytes);
 ```
 
 - `[in] env`: The environment in which the API is invoked under.

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

@@ -241,9 +241,24 @@ request being made.
 
 ### Finalize
 
-Provides an opportunity to run cleanup code that requires access to the
-`Napi::Env` before the wrapped native object instance is freed.  Override to
-implement.
+Provides an opportunity to run cleanup code that only utilizes basic Node APIs, if any.
+Override to implement. See [Finalization][] for more details.
+
+```cpp
+virtual void Finalize(Napi::BasicEnv env);
+```
+
+- `[in] env`: `Napi::Env`.
+
+### Finalize
+
+Provides an opportunity to run cleanup code that utilizes non-basic Node APIs.
+Override to implement.
+
+*NOTE*: Defining this method causes the deletion of the underlying `T* data` to
+be postponed until _after_ the garbage collection cycle. Since an `Napi::Env`
+has access to non-basic Node APIs, it cannot run in the same current tick as the
+garbage collector.
 
 ```cpp
 virtual void Finalize(Napi::Env env);
@@ -586,3 +601,4 @@ Returns `Napi::PropertyDescriptor` object that represents an static value
 property of a JavaScript class
 
 [`Napi::InstanceWrap<T>`]: ./instance_wrap.md
+[Finalization]: ./finalization.md

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

@@ -75,5 +75,56 @@ Rejects the Promise object held by the `Napi::Promise::Deferred` object.
 
 * `[in] value`: The Node-API primitive value with which to reject the `Napi::Promise`.
 
+## Promise Methods
+
+### Then
+
+```cpp
+Napi::Promise Napi::Promise::Then(napi_value onFulfilled) const;
+Napi::Promise Napi::Promise::Then(const Function& onFulfilled) const;
+```
+
+Attaches a fulfillment handler to the promise and returns a new promise.
+
+**Parameters:**
+* `[in] onFulfilled`: The fulfillment handler for the promise. May be any of:
+  - `napi_value` – a JavaScript function to be called when the promise is fulfilled.
+  - `const Function&` – the [`Napi::Function`](function.md) to be called when the promise is fulfilled.
+
+**Returns:** A new `Napi::Promise` that resolves or rejects based on the handler's result.
+
+### Then
+
+```cpp
+Napi::Promise Napi::Promise::Then(napi_value onFulfilled, napi_value onRejected) const;
+Napi::Promise Napi::Promise::Then(const Function& onFulfilled,
+                                  const Function& onRejected) const;
+```
+
+Attaches a fulfillment and rejection handlers to the promise and returns a new promise.
+
+**Parameters:**
+* `[in] onFulfilled`: The fulfillment handler for the promise. May be any of:
+  - `napi_value` – a JavaScript function to be called when the promise is fulfilled.
+  - `const Function&` – the [`Napi::Function`](function.md) to be called when the promise is fulfilled.
+* `[in] onRejected` (optional): The rejection handler for the promise. May be any of:
+  - `napi_value` – a JavaScript function to be called when the promise is rejected.
+  - `const Function&` – the [`Napi::Function`](function.md) to be called when the promise is rejected.
+
+### Catch
+```cpp
+Napi::Promise Napi::Promise::Catch(napi_value onRejected) const;
+Napi::Promise Napi::Promise::Catch(const Function& onRejected) const;
+```
+
+Attaches a rejection handler to the promise and returns a new promise.
+
+**Parameters:**
+* `[in] onRejected`: The rejection handler for the promise. May be any of:
+  - `napi_value` – a JavaScript function to be called when the promise is rejected.
+  - `const Function&` – the [`Napi::Function`](function.md) to be called when the promise is rejected.
+
+**Returns:** A new `Napi::Promise` that handles rejection cases.
 
 [`Napi::Object`]: ./object.md
+[`Napi::Function`]: ./function.md

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

@@ -38,7 +38,10 @@ 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': [
@@ -46,6 +49,15 @@ To use **Node-API** in a native module:
        ],
      ```
 
+     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:
@@ -81,12 +93,23 @@ To use **Node-API** in a native module:
 At build time, the Node-API back-compat library code will be used only when the
 targeted node version *does not* have Node-API built-in.
 
-The preprocessor directive `NODE_ADDON_API_DISABLE_DEPRECATED` can be defined at
-compile time before including `napi.h` to skip the definition of deprecated APIs.
+The `NODE_ADDON_API_DISABLE_DEPRECATED` preprocessor directive can be defined at
+compile time before including `napi.h` to skip the definition of deprecated
+APIs.
 
 By default, throwing an exception on a terminating environment (eg. worker
 threads) will cause a fatal exception, terminating the Node process. This is to
 provide feedback to the user of the runtime error, as it is impossible to pass
-the error to JavaScript when the environment is terminating. In order to bypass
-this behavior such that the Node process will not terminate, define the
-preprocessor directive `NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS`.
+the error to JavaScript when the environment is terminating.  The
+`NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS` preprocessor directive can be defined
+to bypass this behavior, such that the Node process will not terminate.
+
+Various Node-API constructs provide a mechanism to run a callback in response to
+a garbage collection event of that object. These callbacks are called
+[_finalizers_]. Some finalizers have restrictions on the type of Node-APIs
+available within the callback. node-addon-api provides convenience helpers that
+bypass this limitation, but may cause the add-on to run less efficiently. The
+`NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS` preprocessor directive can be defined
+to disable the convenience helpers.
+
+[_finalizers_]: ./finalization.md

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

@@ -86,6 +86,19 @@ In order to enforce expected type, use `Napi::Value::Is*()` methods to check
 the type before calling `Napi::Value::As()`, or compile with definition
 `NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` to enforce type checks.
 
+### UnsafeAs
+
+```cpp
+template <typename T> T Napi::Value::UnsafeAs() const;
+```
+
+Casts to another type of `Napi::Value`, when the actual type is known or
+assumed.
+
+This conversion does not coerce the type. This does not check the type even if
+`NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` is defined. This indicates intentional
+unsafe type cast. Use `Napi::Value::As()` if possible.
+
 ### Env
 
 ```cpp

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

@@ -11,7 +11,7 @@ important to make decisions based on different versions of the system.
 Retrieves the highest Node-API version supported by Node.js runtime.
 
 ```cpp
-static uint32_t Napi::VersionManagement::GetNapiVersion(Env env);
+static uint32_t Napi::VersionManagement::GetNapiVersion(Napi::BasicEnv env);
 ```
 
 - `[in] env`: The environment in which the API is invoked under.
@@ -34,7 +34,7 @@ typedef struct {
 ````
 
 ```cpp
-static const napi_node_version* Napi::VersionManagement::GetNodeVersion(Env env);
+static const napi_node_version* Napi::VersionManagement::GetNodeVersion(Napi::BasicEnv env);
 ```
 
 - `[in] env`: The environment in which the API is invoked under.

package/vendor/node-addon-api/eslint.config.js

@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = require('neostandard')({
+  semi: true,
+});

package/vendor/node-addon-api/index.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const { version } = require('./package.json');
 
 const includeDir = path.relative('.', __dirname);
 
@@ -7,6 +8,7 @@ module.exports = {
   include_dir: includeDir,
   gyp: path.join(includeDir, 'node_api.gyp:nothing'), // deprecated.
   targets: path.join(includeDir, 'node_addon_api.gyp'),
+  version,
   isNodeApiBuiltin: true,
   needsFlag: false
 };