node-addon-api 3.0.1 → 3.2.1

package/doc/handle_scope.md

@@ -1,65 +0,0 @@
-# HandleScope
-
-The HandleScope class is used to manage the lifetime of object handles
-which are created through the use of node-addon-api. These handles
-keep an object alive in the heap in order to ensure that the objects
-are not collected while native code is using them.
-A handle may be created when any new node-addon-api Value or one
-of its subclasses is created or returned. For more details refer to
-the section titled [Object lifetime management](object_lifetime_management.md).
-
-## Methods
-
-### Constructor
-
-Creates a new handle scope on the stack.
-
-```cpp
-Napi::HandleScope::HandleScope(Napi::Env env);
-```
-
-- `[in] env`: The environment in which to construct the `Napi::HandleScope` object.
-
-Returns a new `Napi::HandleScope`
-
-### Constructor
-
-Creates a new handle scope on the stack.
-
-```cpp
-Napi::HandleScope::HandleScope(Napi::Env env, Napi::HandleScope scope);
-```
-
-- `[in] env`: `Napi::Env` in which the scope passed in was created.
-- `[in] scope`: pre-existing `Napi::HandleScope`.
-
-Returns a new `Napi::HandleScope` instance which wraps the napi_handle_scope
-handle passed in.  This can be used to mix usage of the C N-API
-and node-addon-api.
-
-operator HandleScope::napi_handle_scope
-
-```cpp
-operator Napi::HandleScope::napi_handle_scope() const
-```
-
-Returns the N-API napi_handle_scope wrapped by the `Napi::EscapableHandleScope` object.
-This can be used to mix usage of the C N-API and node-addon-api by allowing
-the class to be used be converted to a napi_handle_scope.
-
-### Destructor
-```cpp
-Napi::HandleScope::~HandleScope();
-```
-
-Deletes the `Napi::HandleScope` instance and allows any objects/handles created
-in the scope to be collected by the garbage collector.  There is no
-guarantee as to when the gargbage collector will do this.
-
-### Env
-
-```cpp
-Napi::Env Napi::HandleScope::Env() const;
-```
-
-Returns the `Napi::Env` associated with the `Napi::HandleScope`.

package/doc/memory_management.md

@@ -1,27 +0,0 @@
-# MemoryManagement
-
-The `Napi::MemoryManagement` class contains functions that give the JavaScript engine
-an indication of the amount of externally allocated memory that is kept alive by
-JavaScript objects.
-
-## Methods
-
-### AdjustExternalMemory
-
-The function `AdjustExternalMemory` adjusts the amount of registered external
-memory used to give the JavaScript engine an indication of the amount of externally
-allocated memory that is kept alive by JavaScript objects.
-The JavaScript engine uses this to decide when to perform global garbage collections.
-Registering externally allocated memory will trigger global garbage collections
-more often than it would otherwise in an attempt to garbage collect the JavaScript
-objects that keep the externally allocated memory alive.
-
-```cpp
-static int64_t Napi::MemoryManagement::AdjustExternalMemory(Napi::Env env, int64_t change_in_bytes);
-```
-
-- `[in] env`: The environment in which the API is invoked under.
-- `[in] change_in_bytes`: The change in externally allocated memory that is kept
-alive by JavaScript objects expressed in bytes.
-
-Returns the adjusted memory value.

package/doc/node-gyp.md

@@ -1,82 +0,0 @@
-# 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/doc/number.md

@@ -1,163 +0,0 @@
-# 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.
-
-### Contructor
-
-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/doc/object.md

@@ -1,275 +0,0 @@
-# Object
-
-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::Value`](value.md) which is extended by [`Napi::Array`](basic_types.md#array)
-- [`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 C++ primitive from which to instantiate the Value. `value` may be any of:
-  - bool
-  - Any integer type
-  - Any floating point type
-  - const char* (encoded using UTF-8, null-terminated)
-  - const char16_t* (encoded using UTF-16-LE, null-terminated)
-  - std::string (encoded using UTF-8)
-  - std::u16string
-  - Napi::Value
-  - napi_value
-
-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
-void Napi::Object::Set (____ key, ____ value);
-```
-- `[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`
-
-While the value must be any of the following types:
-- `napi_value`
-- [`Napi::Value`](value.md)
-- `const char*`
-- `std::string&`
-- `bool`
-- `double`
-
-### Delete()
-
-```cpp
-bool Napi::Object::Delete(____ key);
-```
-- `[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);
-```
-
-- `[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);
-```
-
-- `[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`](basic_types.md#array) 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
-void Napi::Object::DefineProperty (const Napi::PropertyDescriptor& property);
-```
-- `[in] property`: A [`Napi::PropertyDescriptor`](property_descriptor.md).
-
-Define a property on the object.
-
-### DefineProperties()
-
-```cpp
-void Napi::Object::DefineProperties (____ properties)
-```
-- `[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.
-
-### Operator[]()
-
-```cpp
-Napi::PropertyLValue<std::string> Napi::Object::operator[] (const char* utf8name);
-```
-- `[in] utf8name`: UTF-8 encoded null-terminated property name.
-
-Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property.
-
-```cpp
-Napi::PropertyLValue<std::string> Napi::Object::operator[] (const std::string& utf8name);
-```
-- `[in] utf8name`: UTF-8 encoded property name.
-
-Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property.
-
-```cpp
-Napi::PropertyLValue<uint32_t> Napi::Object::operator[] (uint32_t index);
-```
-- `[in] index`: Element index.
-
-Returns a [`Napi::PropertyLValue`](propertylvalue.md) or sets an indexed property or array element.
-
-```cpp
-Napi::Value Napi::Object::operator[] (const char* utf8name) const;
-```
-- `[in] utf8name`: UTF-8 encoded null-terminated property name.
-
-Returns the named property as a [`Napi::Value`](value.md).
-
-```cpp
-Napi::Value Napi::Object::operator[] (const std::string& utf8name) const;
-```
-- `[in] utf8name`: UTF-8 encoded property name.
-
-Returns the named property as a [`Napi::Value`](value.md).
-
-```cpp
-Napi::Value Napi::Object::operator[] (uint32_t index) const;
-```
-- `[in] index`: Element index.
-
-Returns an indexed property or array element as a [`Napi::Value`](value.md).

package/doc/object_lifetime_management.md

@@ -1,83 +0,0 @@
-# Object lifetime management
-
-A handle may be created when any new node-addon-api Value and
-its subclasses is created or returned.
-
-As the methods and classes within the node-addon-api are used,
-handles to objects in the heap for the underlying
-VM may be created. A handle may be created when any new
-node-addon-api Value or one of its subclasses is created or returned.
-These handles must hold the objects 'live' until they are no
-longer required by the native code, otherwise the objects could be
-collected by the garbage collector before the native code was
-finished using them.
-
-As handles are created they are associated with a
-'scope'. The lifespan for the default scope is tied to the lifespan
-of the native method call. The result is that, by default, handles
-remain valid and the objects associated with these handles will be
-held live for the lifespan of the native method call.
-
-In many cases, however, it is necessary that the handles remain valid for
-either a shorter or longer lifespan than that of the native method.
-The sections which follow describe the node-addon-api classes and
-methods that than can be used to change the handle lifespan from
-the default.
-
-## Making handle lifespan shorter than that of the native method
-
-It is often necessary to make the lifespan of handles shorter than
-the lifespan of a native method. For example, consider a native method
-that has a loop which creates a number of values and does something
-with each of the values, one at a time:
-
-```C++
-for (int i = 0; i < LOOP_MAX; i++) {
-  std::string name = std::string("inner-scope") + std::to_string(i);
-  Napi::Value newValue = Napi::String::New(info.Env(), name.c_str());
-  // do something with newValue
-};
-```
-
-This would result in a large number of handles being created, consuming
-substantial resources. In addition, even though the native code could only
-use the most recently created value, all of the previously created
-values would also be kept alive since they all share the same scope.
-
-To handle this case, node-addon-api provides the ability to establish
-a new 'scope' to which newly created handles will be associated. Once those
-handles are no longer required, the scope can be deleted and any handles
-associated with the scope are invalidated. The `Napi::HandleScope`
-and `Napi::EscapableHandleScope` classes are provided by node-addon-api for
-creating additional scopes.
-
-node-addon-api only supports a single nested hierarchy of scopes. There is
-only one active scope at any time, and all new handles will be associated
-with that scope while it is active. Scopes must be deleted in the reverse
-order from which they are opened. In addition, all scopes created within
-a native method must be deleted before returning from that method. Since
-`Napi::HandleScopes` are typically stack allocated the compiler will take care of
-deletion, however, care must be taken to create the scope in the right
-place such that you achieve the desired lifetime.
-
-Taking the earlier example, creating a `Napi::HandleScope` in the innner loop
-would ensure that at most a single new value is held alive throughout the
-execution of the loop:
-
-```C
-for (int i = 0; i < LOOP_MAX; i++) {
-  Napi::HandleScope scope(info.Env());
-  std::string name = std::string("inner-scope") + std::to_string(i);
-  Napi::Value newValue = Napi::String::New(info.Env(), name.c_str());
-  // do something with newValue
-};
-```
-
-When nesting scopes, there are cases where a handle from an
-inner scope needs to live beyond the lifespan of that scope. node-addon-api
-provides the `Napi::EscapableHandleScope` with the `Escape` method
-in order to support this case. An escapable scope
-allows one object to be 'promoted' so that it 'escapes' the
-current scope and the lifespan of the handle changes from the current
-scope to that of the outer scope. The `Escape` method can only be called
-once for a given `Napi::EscapableHandleScope`.