ganach-cli 6.12.2

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

@@ -0,0 +1,129 @@
+# ArrayBuffer
+
+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.
+
+```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 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 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.

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

@@ -0,0 +1,86 @@
+# 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 N-API `napi_async_context` wrapped by the `Napi::AsyncContext`
+object. This can be used to mix usage of the C N-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>();
+
+  // Creat 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/node_modules/node-addon-api/doc/async_operations.md

@@ -0,0 +1,31 @@
+# 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)**

package/node_modules/node-addon-api/doc/async_progress_worker.md

@@ -0,0 +1,344 @@
+# AsyncProgressWorker
+
+`Napi::AsyncProgressWorker` is an abstract class which implements `Napi::AsyncWorker`
+while extending `Napi::AsyncWorker` internally with `Napi::ThreadSafeFunction` for
+moving work progress reports from worker thread(s) to event loop threads.
+
+Like `Napi::AsyncWorker`, once created, execution is requested by calling
+`Napi::AsyncProgressWorker::Queue`. When a thread is available for execution
+the `Napi::AsyncProgressWorker::Execute` method will be invoked. During the
+execution, `Napi::AsyncProgressWorker::ExecutionProgress::Send` can be used to
+indicate execution process, which will eventually invoke `Napi::AsyncProgressWorker::OnProgress`
+on the JavaScript thread to safely call into JavaScript. Once `Napi::AsyncProgressWorker::Execute`
+completes either `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError`
+will be invoked. Once the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError`
+methods are complete the `Napi::AsyncProgressWorker` instance is destructed.
+
+For the most basic use, only the `Napi::AsyncProgressWorker::Execute` and
+`Napi::AsyncProgressWorker::OnProgress` method must be implemented in a subclass.
+
+## Methods
+
+[`Napi::AsyncWorker`][] provides detailed descriptions for most methods.
+
+### Execute
+
+This method is used to execute some tasks outside of the **event loop** on a libuv
+worker thread. Subclasses must implement this method and the method is run on
+a thread other than that running the main event loop. As the method is not
+running on the main event loop, it must avoid calling any methods from node-addon-api
+or running any code that might invoke JavaScript. Instead, once this method is
+complete any interaction through node-addon-api with JavaScript should be implemented
+in the `Napi::AsyncProgressWorker::OnOK` method and/or `Napi::AsyncProgressWorker::OnError`
+which run on the main thread and are invoked when the `Napi::AsyncProgressWorker::Execute`
+method completes.
+
+```cpp
+virtual void Napi::AsyncProgressWorker::Execute(const ExecutionProgress& progress) = 0;
+```
+
+### OnOK
+
+This method is invoked when the computation in the `Execute` method ends.
+The default implementation runs the `Callback` optionally provided when the
+`AsyncProgressWorker` class was created. The `Callback` will by default receive no
+arguments. Arguments to the callback can be provided by overriding the `GetResult()`
+method.
+
+```cpp
+virtual void Napi::AsyncProgressWorker::OnOK();
+```
+
+### OnProgress
+
+This method is invoked when the computation in the `Napi::AsyncProgressWorker::ExecutionProcess::Send`
+method was called during worker thread execution.
+
+```cpp
+virtual void Napi::AsyncProgressWorker::OnProgress(const T* data, size_t count)
+```
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Function& callback);
+```
+
+- `[in] callback`: The function which will be called when an asynchronous
+operations ends. The given function is called from the main event loop thread.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name);
+```
+
+- `[in] callback`: The function which will be called when an asynchronous
+operations ends. The given function is called from the main event loop thread.
+- `[in] resource_name`: Null-terminated string that represents the
+identifier for the kind of resource that is being provided for diagnostic
+information exposed by the async_hooks API.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name, const Napi::Object& resource);
+```
+
+- `[in] callback`: The function which will be called when an asynchronous
+operations ends. The given function is called from the main event loop thread.
+- `[in] resource_name`:  Null-terminated string 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.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback);
+```
+
+- `[in] receiver`: The `this` object passed to the called function.
+- `[in] callback`: The function which will be called when an asynchronous
+operations ends. The given function is called from the main event loop thread.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name);
+```
+
+- `[in] receiver`: The `this` object passed to the called function.
+- `[in] callback`: The function which will be called when an asynchronous
+operations ends. The given function is called from the main event loop thread.
+- `[in] resource_name`:  Null-terminated string that represents the
+identifier for the kind of resource that is being provided for diagnostic
+information exposed by the async_hooks API.
+
+Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name, const Napi::Object& resource);
+```
+
+- `[in] receiver`: The `this` object to be passed to the called function.
+- `[in] callback`: The function which will be called when an asynchronous
+operations ends. The given function is called from the main event loop thread.
+- `[in] resource_name`:  Null-terminated string 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.
+
+Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+calling `Napi::AsyncWork::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(Napi::Env env);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
+
+Returns an `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling
+`Napi::AsyncProgressWorker::Queue`.
+
+Available with `NAPI_VERSION` equal to or greater than 5.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
+- `[in] resource_name`: Null-terminated string that represents the
+identifier for the kind of resource that is being provided for diagnostic
+information exposed by the async_hooks API.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncProgressWorker::Queue`.
+
+Available with `NAPI_VERSION` equal to or greater than 5.
+
+### Constructor
+
+Creates a new `Napi::AsyncProgressWorker`.
+
+```cpp
+explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`.
+- `[in] resource_name`:  Null-terminated string 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.
+
+Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by
+calling `Napi::AsyncProgressWorker::Queue`.
+
+Available with `NAPI_VERSION` equal to or greater than 5.
+
+### Destructor
+
+Deletes the created work object that is used to execute logic asynchronously and
+release the internal `Napi::ThreadSafeFunction`, which will be aborted to prevent
+unexpected upcoming thread safe calls.
+
+```cpp
+virtual Napi::AsyncProgressWorker::~AsyncProgressWorker();
+```
+
+# AsyncProgressWorker::ExecutionProcess
+
+A bridge class created before the worker thread execution of `Napi::AsyncProgressWorker::Execute`.
+
+## Methods
+
+### Send
+
+`Napi::AsyncProgressWorker::ExecutionProcess::Send` takes two arguments, a pointer
+to a generic type of data, and a `size_t` to indicate how many items the pointer is
+pointing to.
+
+The data pointed to will be copied to internal slots of `Napi::AsyncProgressWorker` so
+after the call to `Napi::AsyncProgressWorker::ExecutionProcess::Send` the data can
+be safely released.
+
+Note that `Napi::AsyncProgressWorker::ExecutionProcess::Send` merely guarantees
+**eventual** invocation of `Napi::AsyncProgressWorker::OnProgress`, which means
+multiple send might be coalesced into single invocation of `Napi::AsyncProgressWorker::OnProgress`
+with latest data.
+
+```cpp
+void Napi::AsyncProgressWorker::ExecutionProcess::Send(const T* data, size_t count) const;
+```
+
+## Example
+
+The first step to use the `Napi::AsyncProgressWorker` class is to create a new class that
+inherits from it and implement the `Napi::AsyncProgressWorker::Execute` abstract method.
+Typically input to the worker will be saved within the class' fields generally
+passed in through its constructor.
+
+During the worker thread execution, the first argument of `Napi::AsyncProgressWorker::Execute`
+can be used to report the progress of the execution.
+
+When the `Napi::AsyncProgressWorker::Execute` method completes without errors the
+`Napi::AsyncProgressWorker::OnOK` function callback will be invoked. In this function the
+results of the computation will be reassembled and returned back to the initial
+JavaScript context.
+
+`Napi::AsyncProgressWorker` ensures that all the code in the `Napi::AsyncProgressWorker::Execute`
+function runs in the background out of the **event loop** thread and at the end
+the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` function will be
+called and are executed as part of the event loop.
+
+The code below shows a basic example of the `Napi::AsyncProgressWorker` implementation:
+
+```cpp
+#include<napi.h>
+
+#include <chrono>
+#include <thread>
+
+use namespace Napi;
+
+class EchoWorker : public AsyncProgressWorker<uint32_t> {
+    public:
+        EchoWorker(Function& callback, std::string& echo)
+        : AsyncProgressWorker(callback), echo(echo) {}
+
+        ~EchoWorker() {}
+    // This code will be executed on the worker thread
+    void Execute(const ExecutionProgress& progress) {
+        // Need to simulate cpu heavy task
+        for (uint32_t i = 0; i < 100; ++i) {
+          progress.Send(&i, 1)
+          std::this_thread::sleep_for(std::chrono::seconds(1));
+        }
+    }
+
+    void OnOK() {
+        HandleScope scope(Env());
+        Callback().Call({Env().Null(), String::New(Env(), echo)});
+    }
+
+    void OnProgress(const uint32_t* data, size_t /* count */) {
+        HandleScope scope(Env());
+        Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)});
+    }
+
+    private:
+        std::string echo;
+};
+```
+
+The `EchoWorker`'s constructor calls the base class' constructor to pass in the
+callback that the `Napi::AsyncProgressWorker` base class will store persistently. When
+the work on the `Napi::AsyncProgressWorker::Execute` method is done the
+`Napi::AsyncProgressWorker::OnOk` method is called and the results are return back to
+JavaScript when the stored callback is invoked with its associated environment.
+
+The following code shows an example of how to create and use an `Napi::AsyncProgressWorker`
+
+```cpp
+#include <napi.h>
+
+// Include EchoWorker class
+// ..
+
+use namespace Napi;
+
+Value Echo(const CallbackInfo& info) {
+    // We need to validate the arguments here
+    Function cb = info[1].As<Function>();
+    std::string in = info[0].As<String>();
+    EchoWorker* wk = new EchoWorker(cb, in);
+    wk->Queue();
+    return info.Env().Undefined();
+}
+```
+
+The implementation of a `Napi::AsyncProgressWorker` can be used by creating a
+new instance and passing to its constructor the callback to execute when the
+asynchronous task ends and other data needed for the computation. Once created,
+the only other action needed is to call the `Napi::AsyncProgressWorker::Queue`
+method that will queue the created worker for execution.
+
+[`Napi::AsyncWorker`]: ./async_worker.md