ganach-cli 6.12.2

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

@@ -0,0 +1,423 @@
+# Basic Types
+
+Node Addon API consists of a few fundamental data types. These allow a user of
+the API to create, convert and introspect fundamental JavaScript types, and
+interoperate with their C++ counterparts.
+
+## Value
+
+`Napi::Value` is the base class of Node Addon API's fundamental object type hierarchy.
+It represents a JavaScript value of an unknown type. It is a thin wrapper around
+the N-API datatype `napi_value`. Methods on this class can be used to check
+the JavaScript type of the underlying N-API `napi_value` and also to convert to
+C++ types.
+
+### Constructor
+
+```cpp
+Napi::Value::Value();
+```
+
+Used to create a Node Addon API `Napi::Value` that represents an **empty** value.
+
+```cpp
+Napi::Value::Value(napi_env env, napi_value value);
+```
+
+- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value`
+object.
+- `[in] value` - The underlying JavaScript value that the `Napi::Value` instance
+represents.
+
+Returns a Node.js Addon API `Napi::Value` that represents the `napi_value` passed
+in.
+
+### Operators
+
+#### operator napi_value
+
+```cpp
+Napi::Value::operator napi_value() const;
+```
+
+Returns the underlying N-API `napi_value`. If the instance is _empty_, this
+returns `nullptr`.
+
+#### operator ==
+
+```cpp
+bool Napi::Value::operator ==(const Value& other) const;
+```
+
+Returns `true` if this value strictly equals another value, or `false` otherwise.
+
+#### operator !=
+
+```cpp
+bool Napi::Value::operator !=(const Value& other) const;
+```
+
+Returns `false` if this value strictly equals another value, or `true` otherwise.
+
+### Methods
+
+#### From
+```cpp
+template <typename T>
+static Napi::Value Napi::Value::From(napi_env env, const T& value);
+```
+
+- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` object.
+- `[in] value` - The C++ type to represent in JavaScript.
+
+Returns a `Napi::Value` representing the input C++ type in JavaScript.
+
+This method is used to convert from a C++ type to a JavaScript value.
+Here, `value` may be any of:
+- `bool` - returns a `Napi::Boolean`.
+- Any integer type - returns a `Napi::Number`.
+- Any floating point type - returns a `Napi::Number`.
+- `const char*` (encoded using UTF-8, null-terminated) - returns a `Napi::String`.
+- `const char16_t*` (encoded using UTF-16-LE, null-terminated) - returns a `Napi::String`.
+- `std::string` (encoded using UTF-8) - returns a `Napi::String`.
+- `std::u16string` - returns a `Napi::String`.
+- `napi::Value` - returns a `Napi::Value`.
+- `napi_value` - returns a `Napi::Value`.
+
+#### As
+```cpp
+template <typename T> T Napi::Value::As() const;
+```
+
+Returns the `Napi::Value` cast to a desired C++ type.
+
+Use this when the actual type is known or assumed.
+
+Note:
+This conversion does NOT coerce the type. Calling any methods inappropriate for
+the actual value type will throw `Napi::Error`.
+
+#### StrictEquals
+```cpp
+bool Napi::Value::StrictEquals(const Value& other) const;
+```
+
+- `[in] other` - The value to compare against.
+
+Returns true if the other `Napi::Value` is strictly equal to this one.
+
+#### Env
+```cpp
+Napi::Env Napi::Value::Env() const;
+```
+
+Returns the environment that the value is associated with. See
+[`Napi::Env`](env.md) for more details about environments.
+
+#### IsEmpty
+```cpp
+bool Napi::Value::IsEmpty() const;
+```
+
+Returns `true` if the value is uninitialized.
+
+An empty value is invalid, and most attempts to perform an operation on an
+empty value will result in an exception. An empty value is distinct from
+JavaScript `null` or `undefined`, which are valid values.
+
+When C++ exceptions are disabled at compile time, a method with a `Napi::Value`
+return type may return an empty value to indicate a pending exception. If C++
+exceptions are not being used, callers should check the result of
+`Env::IsExceptionPending` before attempting to use the value.
+
+#### Type
+```cpp
+napi_valuetype Napi::Value::Type() const;
+```
+
+Returns the underlying N-API `napi_valuetype` of the value.
+
+#### IsUndefined
+```cpp
+bool Napi::Value::IsUndefined() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `undefined` or `false`
+otherwise.
+
+#### IsNull
+```cpp
+bool Napi::Value::IsNull() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `null` or `false`
+otherwise.
+
+#### IsBoolean
+```cpp
+bool Napi::Value::IsBoolean() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `true` or JavaScript
+`false`, or `false` if the value is not a `Napi::Boolean` value in JavaScript.
+
+#### IsNumber
+```cpp
+bool Napi::Value::IsNumber() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false`
+otherwise.
+
+#### IsString
+```cpp
+bool Napi::Value::IsString() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::String` or `false`
+otherwise.
+
+#### IsSymbol
+```cpp
+bool Napi::Value::IsSymbol() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false`
+otherwise.
+
+#### IsArray
+```cpp
+bool Napi::Value::IsArray() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false`
+otherwise.
+
+#### IsArrayBuffer
+```cpp
+bool Napi::Value::IsArrayBuffer() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or `false`
+otherwise.
+
+#### IsTypedArray
+```cpp
+bool Napi::Value::IsTypedArray() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or `false`
+otherwise.
+
+#### IsObject
+```cpp
+bool Napi::Value::IsObject() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false`
+otherwise.
+
+#### IsFunction
+```cpp
+bool Napi::Value::IsFunction() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::Function` or `false`
+otherwise.
+
+#### IsPromise
+```cpp
+bool Napi::Value::IsPromise() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::Promise` or `false`
+otherwise.
+
+#### IsDataView
+```cpp
+bool Napi::Value::IsDataView() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::DataView` or `false`
+otherwise.
+
+#### IsBuffer
+```cpp
+bool Napi::Value::IsBuffer() const;
+```
+
+Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false`
+otherwise.
+
+#### IsExternal
+```cpp
+bool Napi::Value::IsExternal() const;
+```
+
+Returns `true` if the underlying value is a N-API external object or `false`
+otherwise.
+
+#### IsDate
+```cpp
+bool Napi::Value::IsDate() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Date` or `false`
+otherwise.
+
+#### ToBoolean
+```cpp
+Napi::Boolean Napi::Value::ToBoolean() const;
+```
+
+Returns a `Napi::Boolean` representing the `Napi::Value`.
+
+This is a wrapper around `napi_coerce_to_boolean`. This will throw a JavaScript
+exception if the coercion fails. If C++ exceptions are not being used, callers
+should check the result of `Env::IsExceptionPending` before attempting to use
+the returned value.
+
+#### ToNumber
+```cpp
+Napi::Number Napi::Value::ToNumber() const;
+```
+
+Returns a `Napi::Number` representing the `Napi::Value`.
+
+Note:
+This can cause script code to be executed according to JavaScript semantics.
+This is a wrapper around `napi_coerce_to_number`. This will throw a JavaScript
+exception if the coercion fails. If C++ exceptions are not being used, callers
+should check the result of `Env::IsExceptionPending` before attempting to use
+the returned value.
+
+#### ToString
+```cpp
+Napi::String Napi::Value::ToString() const;
+```
+
+Returns a `Napi::String` representing the `Napi::Value`.
+
+Note that this can cause script code to be executed according to JavaScript
+semantics. This is a wrapper around `napi_coerce_to_string`. This will throw a
+JavaScript exception if the coercion fails. If C++ exceptions are not being
+used, callers should check the result of `Env::IsExceptionPending` before
+attempting to use the returned value.
+
+#### ToObject
+```cpp
+Napi::Object Napi::Value::ToObject() const;
+```
+
+Returns a `Napi::Object` representing the `Napi::Value`.
+
+This is a wrapper around `napi_coerce_to_object`. This will throw a JavaScript
+exception if the coercion fails. If C++ exceptions are not being used, callers
+should check the result of `Env::IsExceptionPending` before attempting to use
+the returned value.
+
+## Name
+
+Names are JavaScript values that can be used as a property name. There are two
+specialized types of names supported in Node.js Addon API [`Napi::String`](string.md)
+and [`Napi::Symbol`](symbol.md).
+
+### Methods
+
+#### Constructor
+```cpp
+Napi::Name::Name();
+```
+
+Returns an empty `Napi::Name`.
+
+```cpp
+Napi::Name::Name(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::Name` created from the JavaScript primitive.
+
+Note:
+The value is not coerced to a string.
+
+## Array
+
+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 [`Int32Array`][] and [`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/master/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::TypedArray`]: ./typed_array.md
+[`Napi::ArrayBuffer`]: ./array_buffer.md
+[`Int32Array`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int32Array
+[`ArrayBuffer`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer

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

@@ -0,0 +1,92 @@
+# BigInt
+
+A JavaScript BigInt value.
+
+## Methods
+
+### New
+
+```cpp
+static Napi::BigInt Napi::BigInt::New(Napi::Env env, int64_t value);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::BigInt` object.
+ - `[in] value`: The value the JavaScript `BigInt` will contain
+
+These APIs convert the C `int64_t` and `uint64_t` types to the JavaScript
+`BigInt` type.
+
+```cpp
+static Napi::BigInt Napi::BigInt::New(Napi::Env env,
+                  int sign_bit,
+                  size_t word_count,
+                  const uint64_t* words);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::BigInt` object.
+ - `[in] sign_bit`: Determines if the resulting `BigInt` will be positive or negative.
+ - `[in] word_count`: The length of the words array.
+ - `[in] words`: An array of `uint64_t` little-endian 64-bit words.
+
+This API converts an array of unsigned 64-bit words into a single `BigInt`
+value.
+
+The resulting `BigInt` is calculated as: (–1)<sup>`sign_bit`</sup> (`words[0]`
+× (2<sup>64</sup>)<sup>0</sup> + `words[1]` × (2<sup>64</sup>)<sup>1</sup> + …)
+
+Returns a new JavaScript `BigInt`.
+
+### Constructor
+
+```cpp
+Napi::BigInt();
+```
+
+Returns a new empty JavaScript `Napi::BigInt`.
+
+### Int64Value
+
+```cpp
+int64_t Napi::BitInt::Int64Value(bool* lossless) const;
+```
+
+ - `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly.
+
+Returns the C `int64_t` primitive equivalent of the given JavaScript
+`BigInt`. If needed it will truncate the value, setting lossless to false.
+
+### Uint64Value
+
+```cpp
+uint64_t Napi::BigInt::Uint64Value(bool* lossless) const;
+```
+
+ - `[out] lossless`: Indicates whether the `BigInt` value was converted
+   losslessly.
+
+Returns the C `uint64_t` primitive equivalent of the given JavaScript
+`BigInt`. If needed it will truncate the value, setting lossless to false.
+
+### WordCount
+
+```cpp
+size_t Napi::BigInt::WordCount() const;
+```
+
+Returns the number of words needed to store this `BigInt` value.
+
+### ToWords
+
+```cpp
+void Napi::BigInt::ToWords(size_t* word_count, int* sign_bit, uint64_t* words);
+```
+
+ - `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive
+   or negative.
+ - `[in/out] word_count`: Must be initialized to the length of the words array.
+   Upon return, it will be set to the actual number of words that would be
+   needed to store this `BigInt`.
+ - `[out] words`: Pointer to a pre-allocated 64-bit word array.
+
+Returns a single `BigInt` value into a sign bit, 64-bit little-endian array,
+and the number of elements in the array.

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

@@ -0,0 +1,64 @@
+# Boolean
+
+`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.
+
+### Contructor
+
+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.

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

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