koffi 1.0.3 → 1.1.0-beta.0

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

@@ -1,163 +0,0 @@
-# Add-on Structure
-
-Class `Napi::Addon<T>` inherits from class [`Napi::InstanceWrap<T>`][].
-
-Creating add-ons that work correctly when loaded multiple times from the same
-source package into multiple Node.js threads and/or multiple times into the same
-Node.js thread requires that all global data they hold be associated with the
-environment in which they run. It is not safe to store global data in static
-variables because doing so does not take into account the fact that an add-on
-may be loaded into multiple threads nor that an add-on may be loaded multiple
-times into a single thread.
-
-The `Napi::Addon<T>` class can be used to define an entire add-on. Instances of
-`Napi::Addon<T>` subclasses become instances of the add-on, stored safely by
-Node.js on its various threads and into its various contexts. Thus, any data
-stored in the instance variables of a `Napi::Addon<T>` subclass instance are
-stored safely by Node.js. Functions exposed to JavaScript using
-`Napi::Addon<T>::InstanceMethod` and/or `Napi::Addon<T>::DefineAddon` are
-instance methods of the `Napi::Addon` subclass and thus have access to data
-stored inside the instance.
-
-`Napi::Addon<T>::DefineProperties` may be used to attach `Napi::Addon<T>`
-subclass instance methods to objects other than the one that will be returned to
-Node.js as the add-on instance.
-
-The `Napi::Addon<T>` class can be used together with the `NODE_API_ADDON()` and
-`NODE_API_NAMED_ADDON()` macros to define add-ons.
-
-## Example
-
-```cpp
-#include <napi.h>
-
-class ExampleAddon : public Napi::Addon<ExampleAddon> {
- public:
-  ExampleAddon(Napi::Env env, Napi::Object exports) {
-    // In the constructor we declare the functions the add-on makes available
-    // to JavaScript.
-    DefineAddon(exports, {
-      InstanceMethod("increment", &ExampleAddon::Increment),
-
-      // We can also attach plain objects to `exports`, and instance methods as
-      // properties of those sub-objects.
-      InstanceValue("subObject", DefineProperties(Napi::Object::New(env), {
-        InstanceMethod("decrement", &ExampleAddon::Decrement)
-      }), napi_enumerable)
-    });
-  }
- private:
-
-  // This method has access to the data stored in the environment because it is
-  // an instance method of `ExampleAddon` and because it was listed among the
-  // property descriptors passed to `DefineAddon()` in the constructor.
-  Napi::Value Increment(const Napi::CallbackInfo& info) {
-    return Napi::Number::New(info.Env(), ++value);
-  }
-
-  // This method has access to the data stored in the environment because it is
-  // an instance method of `ExampleAddon` and because it was exposed to
-  // JavaScript by calling `DefineProperties()` with the object onto which it is
-  // attached.
-  Napi::Value Decrement(const Napi::CallbackInfo& info) {
-    return Napi::Number::New(info.Env(), --value);
-  }
-
-  // Data stored in these variables is unique to each instance of the add-on.
-  uint32_t value = 42;
-};
-
-// The macro announces that instances of the class `ExampleAddon` will be
-// created for each instance of the add-on that must be loaded into Node.js.
-NODE_API_ADDON(ExampleAddon)
-```
-
-The above code can be used from JavaScript as follows:
-
-```js
-'use strict'
-
-const exampleAddon = require('bindings')('example_addon');
-console.log(exampleAddon.increment()); // prints 43
-console.log(exampleAddon.increment()); // prints 44
-console.log(exampleAddon.subObject.decrement()); // prints 43
-```
-
-When Node.js loads an instance of the add-on, a new instance of the class is
-created. Its constructor receives the environment `Napi::Env env` and the
-exports object `Napi::Object exports`. It can then use the method `DefineAddon`
-to either attach methods, accessors, and/or values to the `exports` object or to
-create its own `exports` object and attach methods, accessors, and/or values to
-it.
-
-**Note:** `Napi::Addon<T>` uses `Napi::Env::SetInstanceData()` internally. This
-means that the add-on should only use `Napi::Env::GetInstanceData` explicitly to
-retrieve the instance of the `Napi::Addon<T>` class. Variables whose scope would
-otherwise be global should be stored as instance variables in the
-`Napi::Addon<T>` class.
-
-Functions created with `Napi::Function::New()`, accessors created with
-`PropertyDescriptor::Accessor()`, and values can also be attached. If their
-implementation requires the `ExampleAddon` instance, it can be retrieved from
-the `Napi::Env env` with `GetInstanceData()`:
-
-```cpp
-void ExampleBinding(const Napi::CallbackInfo& info) {
-  ExampleAddon* addon = info.Env().GetInstanceData<ExampleAddon>();
-}
-```
-
-## Methods
-
-### Constructor
-
-Creates a new instance of the add-on.
-
-```cpp
-Napi::Addon(Napi::Env env, Napi::Object exports);
-```
-
-- `[in] env`: The environment into which the add-on is being loaded.
-- `[in] exports`: The exports object received from JavaScript.
-
-Typically, the constructor calls `DefineAddon()` to attach methods, accessors,
-and/or values to `exports`. The constructor may also create a new object and
-pass it to `DefineAddon()` as its first parameter if it wishes to replace the
-`exports` object as provided by Node.js.
-
-### DefineAddon
-
-Defines an add-on instance with functions, accessors, and/or values.
-
-```cpp
-template <typename T>
-void Napi::Addon<T>::DefineAddon(Napi::Object exports,
-                   const std::initializer_list<PropertyDescriptor>& properties);
-```
-
-* `[in] exports`: The object to return to Node.js as an instance of the add-on.
-* `[in] properties`: Initializer list of add-on property descriptors of the
-methods, property accessors, and values that define the add-on. They will be
-set on `exports`.
-See: [`Class property and descriptor`](class_property_descriptor.md).
-
-### DefineProperties
-
-Defines function, accessor, and/or value properties on an object using add-on
-instance methods.
-
-```cpp
-template <typename T>
-Napi::Object
-Napi::Addon<T>::DefineProperties(Napi::Object object,
-                   const std::initializer_list<PropertyDescriptor>& properties);
-```
-
-* `[in] object`: The object that will receive the new properties.
-* `[in] properties`: Initializer list of property descriptors of the methods,
-property accessors, and values to attach to `object`.
-See: [`Class property and descriptor`](class_property_descriptor.md).
-
-Returns `object`.
-
-[`Napi::InstanceWrap<T>`]: ./instance_wrap.md

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

@@ -1,81 +0,0 @@
-# Array
-
-Class [`Napi::Array`][] inherits from class [`Napi::Object`][].
-
-Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper
-around `napi_value` representing a JavaScript Array.
-
-[`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data
-types such as [`Napi::Int32Array`][] and [`Napi::ArrayBuffer`][], respectively,
-that can be used for transferring large amounts of data from JavaScript to the
-native side. An example illustrating the use of a JavaScript-provided
-`ArrayBuffer` in native code is available [here](https://github.com/nodejs/node-addon-examples/tree/HEAD/array_buffer_to_native/node-addon-api).
-
-## Constructor
-```cpp
-Napi::Array::Array();
-```
-
-Returns an empty array.
-
-If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not
-being used, callers should check the result of `Env::IsExceptionPending` before
-attempting to use the returned value.
-
-```cpp
-Napi::Array::Array(napi_env env, napi_value value);
-```
-- `[in] env` - The environment in which to create the array.
-- `[in] value` - The primitive to wrap.
-
-Returns a `Napi::Array` wrapping a `napi_value`.
-
-If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
-being used, callers should check the result of `Env::IsExceptionPending` before
-attempting to use the returned value.
-
-## Methods
-
-### New
-```cpp
-static Napi::Array Napi::Array::New(napi_env env);
-```
-- `[in] env` - The environment in which to create the array.
-
-Returns a new `Napi::Array`.
-
-If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
-being used, callers should check the result of `Env::IsExceptionPending` before
-attempting to use the returned value.
-
-### New
-
-```cpp
-static Napi::Array Napi::Array::New(napi_env env, size_t length);
-```
-- `[in] env` - The environment in which to create the array.
-- `[in] length` - The length of the array.
-
-Returns a new `Napi::Array` with the given length.
-
-If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
-being used, callers should check the result of `Env::IsExceptionPending` before
-attempting to use the returned value.
-
-### Length
-```cpp
-uint32_t Napi::Array::Length() const;
-```
-
-Returns the length of the array.
-
-Note:
-This can execute JavaScript code implicitly according to JavaScript semantics.
-If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not
-being used, callers should check the result of `Env::IsExceptionPending` before
-attempting to use the returned value.
-
-[`Napi::ArrayBuffer`]: ./array_buffer.md
-[`Napi::Int32Array`]: ./typed_array_of.md
-[`Napi::Object`]: ./object.md
-[`Napi::TypedArray`]: ./typed_array.md

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

@@ -1,155 +0,0 @@
-# ArrayBuffer
-
-Class `Napi::ArrayBuffer` inherits from class [`Napi::Object`][].
-
-The `Napi::ArrayBuffer` class corresponds to the
-[JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)
-class.
-
-## Methods
-
-### New
-
-Allocates a new `Napi::ArrayBuffer` instance with a given length.
-
-```cpp
-static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, size_t byteLength);
-```
-
-- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
-- `[in] byteLength`: The length to be allocated, in bytes.
-
-Returns a new `Napi::ArrayBuffer` instance.
-
-### New
-
-Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
-
-The `Napi::ArrayBuffer` instance does not assume ownership for the data and
-expects it to be valid for the lifetime of the instance. Since the
-`Napi::ArrayBuffer` 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::ArrayBuffer` gets garbage-collected. If you need to free
-the data retained by the `Napi::ArrayBuffer` object please use other
-variants of the `Napi::ArrayBuffer::New` factory method that accept
-`Napi::Finalizer`, which is a function that will be invoked when the
-`Napi::ArrayBuffer` object has been destroyed.
-
-```cpp
-static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength);
-```
-
-- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
-- `[in] externalData`: The pointer to the external data to wrap.
-- `[in] byteLength`: The length of the `externalData`, in bytes.
-
-Returns a new `Napi::ArrayBuffer` instance.
-
-### New
-
-Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
-
-The `Napi::ArrayBuffer` instance does not assume ownership for the data and
-expects it to be valid for the lifetime of the instance. The data can only be
-freed once the `finalizeCallback` is invoked to indicate that the
-`Napi::ArrayBuffer` has been released.
-
-```cpp
-template <typename Finalizer>
-static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
-                       void* externalData,
-                       size_t byteLength,
-                       Finalizer finalizeCallback);
-```
-
-- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
-- `[in] externalData`: The pointer to the external data to wrap.
-- `[in] byteLength`: The length of the `externalData`, in bytes.
-- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
-  destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the
-  `externalData` pointer), and return `void`.
-
-Returns a new `Napi::ArrayBuffer` instance.
-
-### New
-
-Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
-
-The `Napi::ArrayBuffer` instance does not assume ownership for the data and expects it
-to be valid for the lifetime of the instance. The data can only be freed once
-the `finalizeCallback` is invoked to indicate that the `Napi::ArrayBuffer` has been
-released.
-
-```cpp
-template <typename Finalizer, typename Hint>
-static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
-                       void* externalData,
-                       size_t byteLength,
-                       Finalizer finalizeCallback,
-                       Hint* finalizeHint);
-```
-
-- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
-- `[in] externalData`: The pointer to the external data to wrap.
-- `[in] byteLength`: The length of the `externalData`, in bytes.
-- `[in] finalizeCallback`: The function to be called when the `Napi::ArrayBuffer` is
-  destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the
-  `externalData` 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::ArrayBuffer` instance.
-
-### Constructor
-
-Initializes an empty instance of the `Napi::ArrayBuffer` class.
-
-```cpp
-Napi::ArrayBuffer::ArrayBuffer();
-```
-
-### Constructor
-
-Initializes a wrapper instance of an existing `Napi::ArrayBuffer` object.
-
-```cpp
-Napi::ArrayBuffer::ArrayBuffer(napi_env env, napi_value value);
-```
-
-- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
-- `[in] value`: The `Napi::ArrayBuffer` reference to wrap.
-
-### ByteLength
-
-```cpp
-size_t Napi::ArrayBuffer::ByteLength() const;
-```
-
-Returns the length of the wrapped data, in bytes.
-
-### Data
-
-```cpp
-void* Napi::ArrayBuffer::Data() const;
-```
-
-Returns a pointer the wrapped data.
-
-### Detach
-
-```cpp
-void Napi::ArrayBuffer::Detach();
-```
-
-Invokes the `ArrayBuffer` detach operation on a detachable `ArrayBuffer`.
-
-### IsDetached
-
-```cpp
-bool Napi::ArrayBuffer::IsDetached() const;
-```
-
-Returns `true` if this `ArrayBuffer` has been detached.
-
-[`Napi::Object`]: ./object.md

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

@@ -1,86 +0,0 @@
-# AsyncContext
-
-The [Napi::AsyncWorker](async_worker.md) class may not be appropriate for every
-scenario. When using any other async mechanism, introducing a new class
-`Napi::AsyncContext` is necessary to ensure an async operation is properly
-tracked by the runtime. The `Napi::AsyncContext` class can be passed to
-[Napi::Function::MakeCallback()](function.md) method to properly restore the
-correct async execution context.
-
-## Methods
-
-### Constructor
-
-Creates a new `Napi::AsyncContext`.
-
-```cpp
-explicit Napi::AsyncContext::AsyncContext(napi_env env, const char* resource_name);
-```
-
-- `[in] env`: The environment in which to create the `Napi::AsyncContext`.
-- `[in] resource_name`: Null-terminated strings that represents the
-identifier for the kind of resource that is being provided for diagnostic
-information exposed by the `async_hooks` API.
-
-### Constructor
-
-Creates a new `Napi::AsyncContext`.
-
-```cpp
-explicit Napi::AsyncContext::AsyncContext(napi_env env, const char* resource_name, const Napi::Object& resource);
-```
-
-- `[in] env`: The environment in which to create the `Napi::AsyncContext`.
-- `[in] resource_name`: Null-terminated strings that represents the
-identifier for the kind of resource that is being provided for diagnostic
-information exposed by the `async_hooks` API.
-- `[in] resource`: Object associated with the asynchronous operation that
-will be passed to possible `async_hooks`.
-
-### Destructor
-
-The `Napi::AsyncContext` to be destroyed.
-
-```cpp
-virtual Napi::AsyncContext::~AsyncContext();
-```
-
-### Env
-
-Requests the environment in which the async context has been initially created.
-
-```cpp
-Napi::Env Env() const;
-```
-
-Returns the `Napi::Env` environment in which the async context has been created.
-
-## Operator
-
-```cpp
-Napi::AsyncContext::operator napi_async_context() const;
-```
-
-Returns the Node-API `napi_async_context` wrapped by the `Napi::AsyncContext`
-object. This can be used to mix usage of the C Node-API and node-addon-api.
-
-## Example
-
-```cpp
-#include "napi.h"
-
-void MakeCallbackWithAsyncContext(const Napi::CallbackInfo& info) {
-  Napi::Function callback = info[0].As<Napi::Function>();
-  Napi::Object resource = info[1].As<Napi::Object>();
-
-  // Create a new async context instance.
-  Napi::AsyncContext context(info.Env(), "async_context_test", resource);
-
-  // Invoke the callback with the async context instance.
-  callback.MakeCallback(Napi::Object::New(info.Env()),
-      std::initializer_list<napi_value>{}, context);
-
-  // The async context instance is automatically destroyed here because it's
-  // block-scope like `Napi::HandleScope`.
-}
-```

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

@@ -1,31 +0,0 @@
-# Asynchronous operations
-
-Node.js native add-ons often need to execute long running tasks and to avoid
-blocking the **event loop** they have to run them asynchronously from the
-**event loop**.
-In the Node.js model of execution the event loop thread represents the thread
-where JavaScript code is executing. The Node.js guidance is to avoid blocking
-other work queued on the event loop thread. Therefore, we need to do this work on
-another thread.
-
-All this means that native add-ons need to leverage async helpers from libuv as
-part of their implementation. This allows them to schedule work to be executed
-asynchronously so that their methods can return in advance of the work being
-completed.
-
-Node Addon API provides an interface to support functions that cover
-the most common asynchronous use cases. There is an abstract classes to implement
-asynchronous operations:
-
-- **[`Napi::AsyncWorker`](async_worker.md)**
-
-These class helps manage asynchronous operations through an abstraction
-of the concept of moving data between the **event loop** and **worker threads**.
-
-Also, the above class may not be appropriate for every scenario. When using any
-other asynchronous mechanism, the following API is necessary to ensure an
-asynchronous operation is properly tracked by the runtime:
-
-- **[AsyncContext](async_context.md)**
-
-- **[CallbackScope](callback_scope.md)**