koffi 1.1.0-beta.0 → 1.1.0-beta.3

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

@@ -0,0 +1,68 @@
+# Boolean
+
+Class `Napi::Boolean` inherits from class [`Napi::Value`][].
+
+`Napi::Boolean` class is a representation of the JavaScript `Boolean` object. The
+`Napi::Boolean` class inherits its behavior from the `Napi::Value` class
+(for more info see: [`Napi::Value`](value.md)).
+
+## Methods
+
+### Constructor
+
+Creates a new empty instance of an `Napi::Boolean` object.
+
+```cpp
+Napi::Boolean::Boolean();
+```
+
+Returns a new _empty_  `Napi::Boolean` object.
+
+### Constructor
+
+Creates a new instance of the `Napi::Boolean` object.
+
+```cpp
+Napi::Boolean(napi_env env, napi_value value);
+```
+
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Boolean` object.
+- `[in] value`: The `napi_value` which is a handle for a JavaScript `Boolean`.
+
+Returns a non-empty `Napi::Boolean` object.
+
+### New
+
+Initializes a new instance of the `Napi::Boolean` object.
+
+```cpp
+Napi::Boolean Napi::Boolean::New(napi_env env, bool value);
+```
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Boolean` object.
+- `[in] value`: The primitive boolean value (`true` or `false`).
+
+Returns a new instance of the `Napi::Boolean` object.
+
+### Value
+
+Converts a `Napi::Boolean` value to a boolean primitive.
+
+```cpp
+bool Napi::Boolean::Value() const;
+```
+
+Returns the boolean primitive type of the corresponding `Napi::Boolean` object.
+
+## Operators
+
+### operator bool
+
+Converts a `Napi::Boolean` value to a boolean primitive.
+
+```cpp
+Napi::Boolean::operator bool() const;
+```
+
+Returns the boolean primitive type of the corresponding `Napi::Boolean` object.
+
+[`Napi::Value`]: ./value.md

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

@@ -0,0 +1,150 @@
+# Buffer
+
+Class `Napi::Buffer` inherits from class [`Napi::Uint8Array`][].
+
+The `Napi::Buffer` class creates a projection of raw data that can be consumed by
+script.
+
+## Methods
+
+### New
+
+Allocates a new `Napi::Buffer` object with a given length.
+
+```cpp
+static Napi::Buffer<T> Napi::Buffer::New(napi_env env, size_t length);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] length`: The number of `T` elements to allocate.
+
+Returns a new `Napi::Buffer` object.
+
+### New
+
+Wraps the provided external data into a new `Napi::Buffer` object.
+
+The `Napi::Buffer` object does not assume ownership for the data and expects it to be
+valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage
+collection this overload is only suitable for data which is static and never
+needs to be freed.
+This factory method will not provide the caller with an opportunity to free the
+data when the `Napi::Buffer` gets garbage-collected. If you need to free the
+data retained by the `Napi::Buffer` object please use other variants of the
+`Napi::Buffer::New` factory method that accept `Napi::Finalizer`, which is a
+function that will be invoked when the `Napi::Buffer` object has been
+destroyed.
+
+```cpp
+static Napi::Buffer<T> Napi::Buffer::New(napi_env env, T* data, size_t length);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+
+Returns a new `Napi::Buffer` object.
+
+### New
+
+Wraps the provided external data into a new `Napi::Buffer` object.
+
+The `Napi::Buffer` object does not assume ownership for the data and expects it
+to be valid for the lifetime of the object. The data can only be freed once the
+`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
+
+```cpp
+template <typename Finalizer>
+static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
+                     T* data,
+                     size_t length,
+                     Finalizer finalizeCallback);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
+  destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
+  external data pointer), and return `void`.
+
+Returns a new `Napi::Buffer` object.
+
+### New
+
+Wraps the provided external data into a new `Napi::Buffer` object.
+
+The `Napi::Buffer` object does not assume ownership for the data and expects it to be
+valid for the lifetime of the object. The data can only be freed once the
+`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
+
+```cpp
+template <typename Finalizer, typename Hint>
+static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
+                     T* data,
+                     size_t length,
+                     Finalizer finalizeCallback,
+                     Hint* finalizeHint);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] data`: The pointer to the external data to expose.
+- `[in] length`: The number of `T` elements in the external data.
+- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
+  destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
+  external data pointer) and `Hint*`, and return `void`.
+- `[in] finalizeHint`: The hint to be passed as the second parameter of the
+  finalize callback.
+
+Returns a new `Napi::Buffer` object.
+
+### Copy
+
+Allocates a new `Napi::Buffer` object and copies the provided external data into it.
+
+```cpp
+static Napi::Buffer<T> Napi::Buffer::Copy(napi_env env, const T* data, size_t length);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] data`: The pointer to the external data to copy.
+- `[in] length`: The number of `T` elements in the external data.
+
+Returns a new `Napi::Buffer` object containing a copy of the data.
+
+### Constructor
+
+Initializes an empty instance of the `Napi::Buffer` class.
+
+```cpp
+Napi::Buffer::Buffer();
+```
+
+### Constructor
+
+Initializes the `Napi::Buffer` object using an existing Uint8Array.
+
+```cpp
+Napi::Buffer::Buffer(napi_env env, napi_value value);
+```
+
+- `[in] env`: The environment in which to create the `Napi::Buffer` object.
+- `[in] value`: The Uint8Array reference to wrap.
+
+### Data
+
+```cpp
+T* Napi::Buffer::Data() const;
+```
+
+Returns a pointer the external data.
+
+### Length
+
+```cpp
+size_t Napi::Buffer::Length() const;
+```
+
+Returns the number of `T` elements in the external data.
+
+[`Napi::Uint8Array`]: ./typed_array_of.md

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

@@ -0,0 +1,54 @@
+# CallbackScope
+
+There are cases (for example, resolving promises) where it is necessary to have
+the equivalent of the scope associated with a callback in place when making
+certain Node-API calls.
+
+## Methods
+
+### Constructor
+
+Creates a new callback scope on the stack.
+
+```cpp
+Napi::CallbackScope::CallbackScope(napi_env env, napi_callback_scope scope);
+```
+
+- `[in] env`: The environment in which to create the `Napi::CallbackScope`.
+- `[in] scope`: The pre-existing `napi_callback_scope` or `Napi::CallbackScope`.
+
+### Constructor
+
+Creates a new callback scope on the stack.
+
+```cpp
+Napi::CallbackScope::CallbackScope(napi_env env, napi_async_context context);
+```
+
+- `[in] env`: The environment in which to create the `Napi::CallbackScope`.
+- `[in] async_context`: The pre-existing `napi_async_context` or `Napi::AsyncContext`.
+
+### Destructor
+
+Deletes the instance of `Napi::CallbackScope` object.
+
+```cpp
+virtual Napi::CallbackScope::~CallbackScope();
+```
+
+### Env
+
+```cpp
+Napi::Env Napi::CallbackScope::Env() const;
+```
+
+Returns the `Napi::Env` associated with the `Napi::CallbackScope`.
+
+## Operator
+
+```cpp
+Napi::CallbackScope::operator napi_callback_scope() const;
+```
+
+Returns the Node-API `napi_callback_scope` wrapped by the `Napi::CallbackScope`
+object. This can be used to mix usage of the C Node-API and node-addon-api.

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

@@ -0,0 +1,97 @@
+# CallbackInfo
+
+The object representing the components of the JavaScript request being made.
+
+The `Napi::CallbackInfo` object is usually created and passed by the Node.js runtime or node-addon-api infrastructure.
+
+The `Napi::CallbackInfo` object contains the arguments passed by the caller. The number of arguments is returned by the `Length` method. Each individual argument can be accessed using the `operator[]` method.
+
+The `SetData` and `Data` methods are used to set and retrieve the data pointer contained in the `Napi::CallbackInfo` object.
+
+## Methods
+
+### Constructor
+
+```cpp
+Napi::CallbackInfo::CallbackInfo(napi_env env, napi_callback_info info);
+```
+
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::CallbackInfo` object.
+- `[in] info`: The `napi_callback_info` data structure from which to construct the `Napi::CallbackInfo` object.
+
+### Env
+
+```cpp
+Napi::Env Napi::CallbackInfo::Env() const;
+```
+
+Returns the `Env` object in which the request is being made.
+
+### NewTarget
+
+```cpp
+Napi::Value Napi::CallbackInfo::NewTarget() const;
+```
+
+Returns the `new.target` value of the constructor call. If the function that was invoked (and for which the `Napi::NCallbackInfo` was passed) is not a constructor call, a call to `IsEmpty()` on the returned value returns true.
+
+### IsConstructCall
+
+```cpp
+bool Napi::CallbackInfo::IsConstructCall() const;
+```
+
+Returns a `bool` indicating if the function that was invoked (and for which the `Napi::CallbackInfo` was passed) is a constructor call.
+
+### Length
+
+```cpp
+size_t Napi::CallbackInfo::Length() const;
+```
+
+Returns the number of arguments passed in the `Napi::CallbackInfo` object.
+
+### operator []
+
+```cpp
+const Napi::Value operator [](size_t index) const;
+```
+
+- `[in] index`: The zero-based index of the requested argument.
+
+Returns a `Napi::Value` object containing the requested argument.
+
+### This
+
+```cpp
+Napi::Value Napi::CallbackInfo::This() const;
+```
+
+Returns the JavaScript `this` value for the call
+
+### Data
+
+```cpp
+void* Napi::CallbackInfo::Data() const;
+```
+
+Returns the data pointer for the callback.
+
+### SetData
+
+```cpp
+void Napi::CallbackInfo::SetData(void* data);
+```
+
+- `[in] data`: The new data pointer to associate with this `Napi::CallbackInfo` object.
+
+Returns `void`.
+
+### Not documented here
+
+```cpp
+Napi::CallbackInfo::~CallbackInfo();
+// Disallow copying to prevent multiple free of _dynamicArgs
+Napi::CallbackInfo::CallbackInfo(CallbackInfo const &) = delete;
+void Napi::CallbackInfo::operator=(CallbackInfo const &) = delete;
+```

package/vendor/node-addon-api/doc/checker-tool.md

@@ -0,0 +1,32 @@
+# Checker Tool
+
+**node-addon-api** provides a [checker tool][] that will inspect a given
+directory tree, identifying all Node.js native addons therein, and further
+indicating for each addon whether it is an Node-API addon.
+
+## To use the checker tool:
+
+  1. Install the application with `npm install`.
+
+  2. If the application does not depend on **node-addon-api**, copy the
+     checker tool into the application's directory.
+
+  3. If the application does not depend on **node-addon-api**, run the checker
+     tool from the application's directory:
+
+     ```sh
+     node ./check-napi.js
+     ```
+
+     Otherwise, the checker tool can be run from the application's
+     `node_modules/` subdirectory:
+
+     ```sh
+     node ./node_modules/node-addon-api/tools/check-napi.js
+     ```
+
+The tool accepts the root directory from which to start checking for Node.js
+native addons as a single optional command line parameter. If omitted it will
+start checking from the current directory (`.`).
+
+[checker tool]: ../tools/check-napi.js

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

@@ -0,0 +1,123 @@
+# Class property and descriptor
+
+Property descriptor for use with `Napi::ObjectWrap<T>` and 
+`Napi::InstanceWrap<T>`. This is different from the standalone
+`Napi::PropertyDescriptor` because it is specific to each 
+`Napi::ObjectWrap<T>` and `Napi::InstanceWrap<T>` subclasses.
+This prevents using descriptors from a different class when defining a new
+class (preventing the callbacks from having incorrect `this` pointers).
+
+`Napi::ClassPropertyDescriptor` is a helper class created with
+`Napi::ObjectWrap<T>` and `Napi::InstanceWrap<T>`. For more reference about it
+see:
+
+- [InstanceWrap](./instance_wrap.md)
+- [ObjectWrap](./object_wrap.md)
+
+## Example
+
+```cpp
+#include <napi.h>
+
+class Example : public Napi::ObjectWrap<Example> {
+  public:
+    static Napi::Object Init(Napi::Env env, Napi::Object exports);
+    Example(const Napi::CallbackInfo &info);
+
+  private:
+    double _value;
+    Napi::Value GetValue(const Napi::CallbackInfo &info);
+    void SetValue(const Napi::CallbackInfo &info, const Napi::Value &value);
+};
+
+Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
+    Napi::Function func = DefineClass(env, "Example", {
+        // Register a class instance accessor with getter and setter functions.
+        InstanceAccessor<&Example::GetValue, &Example::SetValue>("value"),
+        // We can also register a readonly accessor by omitting the setter.
+        InstanceAccessor<&Example::GetValue>("readOnlyProp")
+    });
+
+    Napi::FunctionReference *constructor = new Napi::FunctionReference();
+    *constructor = Napi::Persistent(func);
+    env.SetInstanceData(constructor);
+    exports.Set("Example", func);
+
+    return exports;
+}
+
+Example::Example(const Napi::CallbackInfo &info) : Napi::ObjectWrap<Example>(info) {
+    Napi::Env env = info.Env();
+    // ...
+    Napi::Number value = info[0].As<Napi::Number>();
+    this->_value = value.DoubleValue();
+}
+
+Napi::Value Example::GetValue(const Napi::CallbackInfo &info) {
+    Napi::Env env = info.Env();
+    return Napi::Number::New(env, this->_value);
+}
+
+void Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) {
+    Napi::Env env = info.Env();
+    // ...
+    Napi::Number arg = value.As<Napi::Number>();
+    this->_value = arg.DoubleValue();
+}
+
+// Initialize native add-on
+Napi::Object Init (Napi::Env env, Napi::Object exports) {
+    Example::Init(env, exports);
+    return exports;
+}
+
+// Register and initialize native add-on
+NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
+```
+
+The above code can be used from JavaScript as follows:
+
+```js
+'use strict';
+
+const { Example } = require('bindings')('addon');
+
+const example = new Example(11);
+console.log(example.value);
+// It prints 11
+example.value = 19;
+console.log(example.value);
+// It prints 19
+example.readOnlyProp = 500;
+console.log(example.readOnlyProp);
+// Unchanged. It prints 19
+```
+
+## Methods
+
+### Constructor
+
+Creates new instance of `Napi::ClassPropertyDescriptor` descriptor object.
+
+```cpp
+Napi::ClassPropertyDescriptor(napi_property_descriptor desc) : _desc(desc) {}
+```
+
+- `[in] desc`: The `napi_property_descriptor`
+
+Returns new instance of `Napi::ClassPropertyDescriptor` that is used as property descriptor
+inside the `Napi::ObjectWrap<T>` class.
+
+### Operator
+
+```cpp
+operator napi_property_descriptor&() { return _desc; }
+```
+
+Returns the original Node-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor`
+
+```cpp
+operator const napi_property_descriptor&() const { return _desc; }
+```
+
+Returns the original Node-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor`

package/vendor/node-addon-api/doc/cmake-js.md

@@ -0,0 +1,68 @@
+# CMake.js
+
+[**CMake.js**](https://github.com/cmake-js/cmake-js) is a build tool that allow native addon developers to compile their
+C or C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
+instead of Google's [**gyp**](https://gyp.gsrc.io) tool it is based on the [**CMake**](https://cmake.org) build system.
+
+## Quick Start
+
+### Install CMake
+
+CMake.js requires that CMake be installed. Installers for a variety of platforms can be found on the [CMake website](https://cmake.org).
+
+### Install CMake.js
+
+For developers, CMake.js is typically installed as a global package:
+
+```bash
+npm install -g cmake-js
+cmake-js --help
+```
+
+> For *users* of your native addon, CMake.js should be configured as a dependency in your `package.json` as described in the [CMake.js documentation](https://github.com/cmake-js/cmake-js).
+
+### CMakeLists.txt
+
+Your project will require a `CMakeLists.txt` file. The [CMake.js README file](https://github.com/cmake-js/cmake-js#usage) shows what's necessary.
+
+### NAPI_VERSION
+
+When building Node-API addons, it's crucial to specify the Node-API version your code is designed to work with. With CMake.js, this information is specified in the `CMakeLists.txt` file:
+
+```
+add_definitions(-DNAPI_VERSION=3)
+```
+
+Since Node-API is ABI-stable, your Node-API addon will work, without recompilation, with the Node-API version you specify in `NAPI_VERSION` and all subsequent Node-API versions.
+
+In the absence of a need for features available only in a specific Node-API version, version 3 is a good choice as it is the version of Node-API that was active when Node-API left experimental status.
+
+### NAPI_EXPERIMENTAL
+
+The following line in the `CMakeLists.txt` file will enable Node-API experimental features if your code requires them:
+
+```
+add_definitions(-DNAPI_EXPERIMENTAL)
+```
+
+### node-addon-api
+
+If your Node-API native add-on uses the optional [**node-addon-api**](https://github.com/nodejs/node-addon-api#node-addon-api-module) C++ wrapper, the `CMakeLists.txt` file requires additional configuration information as described on the [CMake.js README file](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api).
+
+## Example
+
+A working example of an Node-API native addon built using CMake.js can be found on the [node-addon-examples repository](https://github.com/nodejs/node-addon-examples/tree/HEAD/build_with_cmake#building-n-api-addons-using-cmakejs).
+
+## **CMake** Reference
+
+  - [Installation](https://github.com/cmake-js/cmake-js#installation)
+  - [How to use](https://github.com/cmake-js/cmake-js#usage)
+  - [Using Node-API and node-addon-api](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api)
+  - [Tutorials](https://github.com/cmake-js/cmake-js#tutorials)
+  - [Use case in the works - ArrayFire.js](https://github.com/cmake-js/cmake-js#use-case-in-the-works---arrayfirejs)
+
+Sometimes finding the right settings is not easy so to accomplish at most
+complicated task please refer to:
+
+- [CMake documentation](https://cmake.org/)
+- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)

package/vendor/node-addon-api/doc/conversion-tool.md

@@ -0,0 +1,28 @@
+# Conversion Tool
+
+To make the migration to **node-addon-api** easier, we have provided a script to
+help complete some tasks.
+
+## To use the conversion script:
+
+  1. Go to your module directory
+
+```
+cd [module_path]
+```
+
+  2. Install node-addon-api module
+
+```
+npm install node-addon-api
+```
+  3. Run node-addon-api conversion script
+
+```
+node ./node_modules/node-addon-api/tools/conversion.js ./
+```
+
+  4. While this script makes conversion easier, it still cannot fully convert
+the module. The next step is to try to build the module and complete the
+remaining conversions necessary to allow it to compile and pass all of the
+module's tests.

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

@@ -0,0 +1,62 @@
+# Creating a release
+
+Only collaborators in npm for **node-addon-api** can create releases.
+If you want to be able to do releases ask one of the existing
+collaborators to add you. If necessary you can ask the build
+Working Group who manages the Node.js npm user to add you if
+there are no other active collaborators.
+
+## Prerequisites
+
+Before to start creating a new release check if you have installed the following
+tools:
+
+* [Changelog maker](https://www.npmjs.com/package/changelog-maker)
+
+If not please follow the instruction reported in the tool's documentation to
+install it.
+
+## Publish new release
+
+These are the steps to follow to create a new release:
+
+* Open an issue in the **node-addon-api** repo documenting the intent to create a
+new release. Give people some time to comment or suggest PRs that should land first.
+
+* Validate all tests pass by running `npm test` on the `main` branch.
+
+* Update the version in **package.json** appropriately.
+
+* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/main/README.md)
+to show the new version as the latest.
+
+* Generate the changelog for the new version using **changelog maker** tool. From
+the route folder of the repo launch the following command:
+
+    ```bash
+    > changelog-maker
+    ```
+* Use the output generated by **changelog maker** to update the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/main/CHANGELOG.md)
+following the style used in publishing the previous release.
+
+* Add any new contributors to the "contributors" section in the package.json
+
+* Validate all tests pass by running `npm test` on the `main` branch.
+
+* Use **[CI](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api-new/)**
+to validate tests pass (note there are still some issues on SmartOS and
+Windows in the testing).
+
+* Do a clean checkout of node-addon-api.
+
+* Login and then run `npm publish`.
+
+* Create a release in Github (look at existing releases for an example).
+
+* Validate that you can run `npm install node-addon-api` successfully
+and that the correct version is installed.
+
+* Comment on the issue opened in the first step that the release has been created
+and close the issue.
+
+* Tweet that the release has been created.