koffi 1.1.0-beta.1 → 1.1.0-beta.2

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

@@ -0,0 +1,82 @@
+# node-gyp
+
+C++ code needs to be compiled into executable form whether it be as an object
+file to linked with others, a shared library, or a standalone executable.
+
+The main reason for this is that we need to link to the Node.js dependencies and
+headers correctly, another reason is that we need a cross platform way to build
+C++ source into binary for the target platform.
+
+Until now **node-gyp** is the **de-facto** standard build tool for writing
+Node.js addons. It's based on Google's **gyp** build tool, which abstract away
+many of the tedious issues related to cross platform building.
+
+**node-gyp** uses a file called ```binding.gyp``` that is located on the root of
+your addon project.
+
+```binding.gyp``` file, contains all building configurations organized with a
+JSON like syntax. The most important parameter is the  **target** that must be
+set to the same value used on the initialization code of the addon as in the
+examples reported below:
+
+### **binding.gyp**
+
+```gyp
+{
+  "targets": [
+    {
+      # myModule is the name of your native addon
+      "target_name": "myModule",
+      "sources": ["src/my_module.cc", ...],
+      ...
+  ]
+}
+```
+
+### **my_module.cc**
+
+```cpp
+#include <napi.h>
+
+// ...
+
+/**
+* This code is our entry-point. We receive two arguments here, the first is the
+* environment that represent an independent instance of the JavaScript runtime,
+* the second is exports, the same as module.exports in a .js file.
+* You can either add properties to the exports object passed in or create your
+* own exports object. In either case you must return the object to be used as
+* the exports for the module when you return from the Init function.
+*/
+Napi::Object Init(Napi::Env env, Napi::Object exports) {
+
+  // ...
+
+  return exports;
+}
+
+/**
+* This code defines the entry-point for the Node addon, it tells Node where to go
+* once the library has been loaded into active memory. The first argument must
+* match the "target" in our *binding.gyp*. Using NODE_GYP_MODULE_NAME ensures
+* that the argument will be correct, as long as the module is built with
+* node-gyp (which is the usual way of building modules). The second argument
+* points to the function to invoke. The function must not be namespaced.
+*/
+NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
+```
+
+## **node-gyp** reference
+
+  - [Installation](https://www.npmjs.com/package/node-gyp#installation)
+  - [How to use](https://www.npmjs.com/package/node-gyp#how-to-use)
+  - [The binding.gyp file](https://www.npmjs.com/package/node-gyp#the-bindinggyp-file)
+  - [Commands](https://www.npmjs.com/package/node-gyp#commands)
+  - [Command options](https://www.npmjs.com/package/node-gyp#command-options)
+  - [Configuration](https://www.npmjs.com/package/node-gyp#configuration)
+
+Sometimes finding the right settings for ```binding.gyp``` is not easy so to
+accomplish at most complicated task please refer to:
+
+- [GYP documentation](https://gyp.gsrc.io/index.md)
+- [node-gyp wiki](https://github.com/nodejs/node-gyp/wiki)

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

@@ -0,0 +1,163 @@
+# Number
+
+`Napi::Number` class is a representation of the JavaScript `Number` object. The
+`Napi::Number` class inherits its behavior from `Napi::Value` class
+(for more info see [`Napi::Value`](value.md))
+
+## Methods
+
+### Constructor
+
+Creates a new _empty_ instance of a `Napi::Number` object.
+
+```cpp
+Napi::Number();
+```
+
+Returns a new _empty_ `Napi::Number` object.
+
+### Constructor
+
+Creates a new instance of a `Napi::Number` object.
+
+```cpp
+Napi::Number(napi_env env, napi_value value);
+```
+
+ - `[in] env`: The `napi_env` environment in which to construct the `Napi::Number` object.
+ - `[in] value`: The JavaScript value holding a number.
+
+ Returns a non-empty `Napi::Number` object.
+
+ ### New
+
+ Creates a new instance of a `Napi::Number` object.
+
+```cpp
+Napi::Number Napi::Number::New(napi_env env, double value);
+```
+ - `[in] env`: The `napi_env` environment in which to construct the `Napi::Number` object.
+ - `[in] value`: The C++ primitive from which to instantiate the `Napi::Number`.
+
+Creates a new instance of a `Napi::Number` object.
+
+### Int32Value
+
+Converts a `Napi::Number` value to a `int32_t` primitive type.
+
+```cpp
+Napi::Number::Int32Value() const;
+```
+
+Returns the `int32_t` primitive type of the corresponding `Napi::Number` object.
+
+### Uint32Value
+
+Converts a `Napi::Number` value to a `uint32_t` primitive type.
+
+```cpp
+Napi::Number::Uint32Value() const;
+```
+
+Returns the `uint32_t` primitive type of the corresponding `Napi::Number` object.
+
+### Int64Value
+
+Converts a `Napi::Number` value to a `int64_t` primitive type.
+
+```cpp
+Napi::Number::Int64Value() const;
+```
+
+Returns the `int64_t` primitive type of the corresponding `Napi::Number` object.
+
+### FloatValue
+
+Converts a `Napi::Number` value to a `float` primitive type.
+
+```cpp
+Napi::Number::FloatValue() const;
+```
+
+Returns the `float` primitive type of the corresponding `Napi::Number` object.
+
+### DoubleValue
+
+Converts a `Napi::Number` value to a `double` primitive type.
+
+```cpp
+Napi::Number::DoubleValue() const;
+```
+
+Returns the `double` primitive type of the corresponding `Napi::Number` object.
+
+## Operators
+
+The `Napi::Number` class contains a set of operators to easily cast JavaScript
+`Number` object to one of the following primitive types:
+
+ - `int32_t`
+ - `uint32_t`
+ - `int64_t`
+ - `float`
+ - `double`
+
+### operator int32_t
+
+Converts a `Napi::Number` value to a `int32_t` primitive.
+
+```cpp
+Napi::Number::operator int32_t() const;
+```
+
+Returns the `int32_t` primitive type of the corresponding `Napi::Number` object.
+
+### operator uint32_t
+
+Converts a `Napi::Number` value to a `uint32_t` primitive type.
+
+```cpp
+Napi::Number::operator uint32_t() const;
+```
+
+Returns the `uint32_t` primitive type of the corresponding `Napi::Number` object.
+
+### operator int64_t
+
+Converts a `Napi::Number` value to a `int64_t` primitive type.
+
+```cpp
+Napi::Number::operator int64_t() const;
+```
+
+Returns the `int64_t` primitive type of the corresponding `Napi::Number` object.
+
+### operator float
+
+Converts a `Napi::Number` value to a `float` primitive type.
+
+```cpp
+Napi::Number::operator float() const;
+```
+
+Returns the `float` primitive type of the corresponding `Napi::Number` object.
+
+### operator double
+
+Converts a `Napi::Number` value to a `double` primitive type.
+
+```cpp
+Napi::Number::operator double() const;
+```
+
+Returns the `double` primitive type of the corresponding `Napi::Number` object.
+
+### Example
+
+The following shows an example of casting a number to an `uint32_t` value.
+
+```cpp
+uint32_t operatorVal = Napi::Number::New(Env(), 10.0); // Number to unsigned 32 bit integer
+// or
+auto instanceVal = info[0].As<Napi::Number>().Uint32Value();
+```

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

@@ -0,0 +1,411 @@
+# Object
+
+Class `Napi::Object` inherits from class [`Napi::Value`][].
+
+The `Napi::Object` class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types:
+
+- [`Napi::Array`](array.md)
+- [`Napi::ArrayBuffer`](array_buffer.md)
+- [`Napi::Buffer<T>`](buffer.md)
+- [`Napi::Function`](function.md)
+- [`Napi::TypedArray`](typed_array.md).
+
+This class provides a number of convenience methods, most of which are used to set or get properties on a JavaScript object. For example, Set() and Get().
+
+## Example
+```cpp
+#include <napi.h>
+
+using namespace Napi;
+
+Void Init(Env env) {
+
+  // Create a new instance
+  Object obj = Object::New(env);
+
+  // Assign values to properties
+  obj.Set("hello", "world");
+  obj.Set(uint32_t(42), "The Answer to Life, the Universe, and Everything");
+  obj.Set("Douglas Adams", true);
+
+  // Get properties
+  Value val1 = obj.Get("hello");
+  Value val2 = obj.Get(uint32_t(42));
+  Value val3 = obj.Get("Douglas Adams");
+
+  // Test if objects have properties.
+  bool obj1 = obj.Has("hello"); // true
+  bool obj2 = obj.Has("world"); // false
+
+}
+```
+
+## Methods
+
+### Empty Constructor
+
+```cpp
+Napi::Object::Object();
+```
+Creates a new empty Object instance.
+
+### Constructor
+
+```cpp
+Napi::Object::Object(napi_env env, napi_value value);
+```
+- `[in] env`: The `napi_env` environment in which to construct the Value object.
+
+- `[in] value`: The `napi_value` which is a handle for a JavaScript object.
+
+Creates a non-empty `Napi::Object` instance.
+
+### New()
+
+```cpp
+Napi::Object Napi::Object::New(napi_env env);
+```
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object.
+
+Creates a new `Napi::Object` value.
+
+### Set()
+
+```cpp
+bool Napi::Object::Set (____ key, ____ value) const;
+```
+- `[in] key`: The name for the property being assigned.
+- `[in] value`: The value being assigned to the property.
+
+Add a property with the specified key with the specified value to the object.
+
+The key can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char*`
+- `const std::string&`
+- `uint32_t`
+
+The `value` can be of any type that is accepted by [`Napi::Value::From`][].
+
+### Delete()
+
+```cpp
+bool Napi::Object::Delete(____ key) const;
+```
+- `[in] key`: The name of the property to delete.
+
+Deletes the property associated with the given key. Returns `true` if the property was deleted.
+
+The `key` can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char *`
+- `const std::string &`
+- `uint32_t`
+
+### Get()
+
+```cpp
+Napi::Value Napi::Object::Get(____ key);
+```
+- `[in] key`: The name of the property to return the value for.
+
+Returns the [`Napi::Value`](value.md) associated with the key property. Returns the value *undefined* if the key does not exist.
+
+The `key` can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char *`
+- `const std::string &`
+- `uint32_t`
+
+### Has()
+
+```cpp
+bool Napi::Object::Has (____ key) const;
+```
+- `[in] key`: The name of the property to check.
+
+Returns a `bool` that is *true* if the object has a property named `key` and *false* otherwise.
+
+### InstanceOf()
+
+```cpp
+bool Napi::Object::InstanceOf (const Function& constructor) const
+```
+- `[in] constructor`: The constructor [`Napi::Function`](function.md) of the value that is being compared with the object.
+
+Returns a `bool` that is true if the `Napi::Object` is an instance created by the `constructor` and false otherwise.
+
+Note: This is equivalent to the JavaScript instanceof operator.
+
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T>
+inline void AddFinalizer(Finalizer finalizeCallback, T* data) const;
+```
+
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+- `[in] data`: The data to associate with the object.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. `finalizeCallback`
+has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data);
+```
+where `data` is the pointer that was passed into the call to `AddFinalizer()`.
+
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T, typename Hint>
+inline void AddFinalizer(Finalizer finalizeCallback,
+                         T* data,
+                         Hint* finalizeHint) const;
+```
+
+- `[in] data`: The data to associate with the object.
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. An additional hint
+may be given. It will also be passed to `finalizeCallback`, which has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data, Hint* hint);
+```
+where `data` and `hint` are the pointers that were passed into the call to `AddFinalizer()`.
+
+### GetPropertyNames()
+```cpp
+Napi::Array Napi::Object::GetPropertyNames() const;
+```
+
+Returns the names of the enumerable properties of the object as a [`Napi::Array`](array.md) of strings.
+The properties whose key is a `Symbol` will not be included.
+
+### HasOwnProperty()
+```cpp
+bool Napi::Object::HasOwnProperty(____ key) const;
+```
+- `[in] key` The name of the property to check.
+
+Returns a `bool` that is *true* if the object has an own property named `key` and *false* otherwise.
+
+The key can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char*`
+- `const std::string&`
+- `uint32_t`
+
+### DefineProperty()
+
+```cpp
+bool Napi::Object::DefineProperty (const Napi::PropertyDescriptor& property) const;
+```
+- `[in] property`: A [`Napi::PropertyDescriptor`](property_descriptor.md).
+
+Define a property on the object.
+
+### DefineProperties()
+
+```cpp
+bool Napi::Object::DefineProperties (____ properties) const;
+```
+- `[in] properties`: A list of [`Napi::PropertyDescriptor`](property_descriptor.md). Can be one of the following types:
+  - const std::initializer_list<Napi::PropertyDescriptor>&
+  - const std::vector<Napi::PropertyDescriptor>&
+
+Defines properties on the object.
+
+### Freeze()
+
+```cpp
+void Napi::Object::Freeze() const;
+```
+
+The `Napi::Object::Freeze()` method freezes an object. A frozen object can no
+longer changed. Freezing an object prevents new properties from being added to
+it, existing properties from being removed, prevents changing the
+enumerability, configurability, or writability of existing properties and
+prevents the value of existing properties from being changed. In addition,
+freezing an object also prevents its prototype from being changed.
+
+### Seal()
+
+```cpp
+void Napi::Object::Seal() const;
+```
+
+The `Napi::Object::Seal()` method seals an object, preventing new properties
+from being added to it and marking all existing properties as non-configurable.
+Values of present properties can still be changed as long as they are
+writable.
+
+### operator\[\]()
+
+```cpp
+Napi::PropertyLValue<std::string> Napi::Object::operator[] (const char* utf8name) const;
+```
+- `[in] utf8name`: UTF-8 encoded null-terminated property name.
+
+Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) as the named
+property or sets the named property.
+
+```cpp
+Napi::PropertyLValue<std::string> Napi::Object::operator[] (const std::string& utf8name) const;
+```
+- `[in] utf8name`: UTF-8 encoded property name.
+
+Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) as the named
+property or sets the named property.
+
+```cpp
+Napi::PropertyLValue<uint32_t> Napi::Object::operator[] (uint32_t index) const;
+```
+- `[in] index`: Element index.
+
+Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) or sets an
+indexed property or array element.
+
+### begin()
+
+```cpp
+Napi::Object::iterator Napi::Object::begin() const;
+```
+
+Returns a constant iterator to the beginning of the object.
+
+```cpp
+Napi::Object::iterator Napi::Object::begin();
+```
+
+Returns a non constant iterator to the beginning of the object.
+
+### end()
+
+```cpp
+Napi::Object::iterator Napi::Object::end() const;
+```
+
+Returns a constant iterator to the end of the object.
+
+```cpp
+Napi::Object::iterator Napi::Object::end();
+```
+
+Returns a non constant iterator to the end of the object.
+
+## Iterator
+
+Iterators expose an `std::pair<...>`, where the `first` property is a
+[`Napi::Value`](value.md) that holds the currently iterated key and the
+`second` property is a [`Napi::Object::PropertyLValue`](propertylvalue.md) that
+holds the currently iterated value. Iterators are only available if C++
+exceptions are enabled (by defining `NAPI_CPP_EXCEPTIONS` during the build).
+
+### Constant Iterator
+
+In constant iterators, the iterated values are immutable.
+
+#### operator++()
+
+```cpp
+inline Napi::Object::const_iterator& Napi::Object::const_iterator::operator++();
+```
+
+Moves the iterator one step forward.
+
+#### operator==
+
+```cpp
+inline bool Napi::Object::const_iterator::operator==(const Napi::Object::const_iterator& other) const;
+```
+- `[in] other`: Another iterator to compare the current iterator to.
+
+Returns whether both iterators are at the same index.
+
+#### operator!=
+
+```cpp
+inline bool Napi::Object::const_iterator::operator!=(const Napi::Object::const_iterator& other) const;
+```
+- `[in] other`: Another iterator to compare the current iterator to.
+
+Returns whether both iterators are at different indices.
+
+#### operator*()
+
+```cpp
+inline const std::pair<Napi::Value, Napi::Object::PropertyLValue<Napi::Value>> Napi::Object::const_iterator::operator*() const;
+```
+
+Returns the currently iterated key and value.
+
+#### Example
+```cpp
+Value Sum(const CallbackInfo& info) {
+  Object object = info[0].As<Object>();
+  int64_t sum = 0;
+
+  for (const auto& e : object) {
+    sum += static_cast<Value>(e.second).As<Number>().Int64Value();
+  }
+
+  return Number::New(info.Env(), sum);
+}
+```
+
+### Non Constant Iterator
+
+In non constant iterators, the iterated values are mutable.
+
+#### operator++()
+
+```cpp
+inline Napi::Object::iterator& Napi::Object::iterator::operator++();
+```
+
+Moves the iterator one step forward.
+
+#### operator==
+
+```cpp
+inline bool Napi::Object::iterator::operator==(const Napi::Object::iterator& other) const;
+```
+- `[in] other`: Another iterator to compare the current iterator to.
+
+Returns whether both iterators are at the same index.
+
+#### operator!=
+
+```cpp
+inline bool Napi::Object::iterator::operator!=(const Napi::Object::iterator& other) const;
+```
+- `[in] other`: Another iterator to compare the current iterator to.
+
+Returns whether both iterators are at different indices.
+
+#### operator*()
+
+```cpp
+inline std::pair<Napi::Value, Napi::Object::PropertyLValue<Napi::Value>> Napi::Object::iterator::operator*();
+```
+
+Returns the currently iterated key and value.
+
+#### Example
+```cpp
+void Increment(const CallbackInfo& info) {
+  Env env = info.Env();
+  Object object = info[0].As<Object>();
+
+  for (auto e : object) {
+    int64_t value = static_cast<Value>(e.second).As<Number>().Int64Value();
+    ++value;
+    e.second = Napi::Number::New(env, value);
+  }
+}
+```
+
+[`Napi::Value`]: ./value.md
+[`Napi::Value::From`]: ./value.md#from