node-addon-api 3.1.0 → 3.2.0

package/doc/boolean.md

@@ -1,68 +0,0 @@
-# Boolean
-
-Class `Napi::Boolean` inherits from class [`Napi::Value`][].
-
-`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.
-
-### Constructor
-
-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.
-
-[`Napi::Value`]: ./value.md

package/doc/buffer.md

@@ -1,144 +0,0 @@
-# Buffer
-
-Class `Napi::Buffer` inherits from class [`Napi::Uint8Array`][].
-
-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.
-
-[`Napi::Uint8Array`]: ./typed_array_of.md

package/doc/callback_scope.md

@@ -1,54 +0,0 @@
-# CallbackScope
-
-There are cases (for example, resolving promises) where it is necessary to have
-the equivalent of the scope associated with a callback in place when making
-certain N-API calls.
-
-## Methods
-
-### Constructor
-
-Creates a new callback scope on the stack.
-
-```cpp
-Napi::CallbackScope::CallbackScope(napi_env env, napi_callback_scope scope);
-```
-
-- `[in] env`: The environment in which to create the `Napi::CallbackScope`.
-- `[in] scope`: The pre-existing `napi_callback_scope` or `Napi::CallbackScope`.
-
-### Constructor
-
-Creates a new callback scope on the stack.
-
-```cpp
-Napi::CallbackScope::CallbackScope(napi_env env, napi_async_context context);
-```
-
-- `[in] env`: The environment in which to create the `Napi::CallbackScope`.
-- `[in] async_context`: The pre-existing `napi_async_context` or `Napi::AsyncContext`.
-
-### Destructor
-
-Deletes the instance of `Napi::CallbackScope` object.
-
-```cpp
-virtual Napi::CallbackScope::~CallbackScope();
-```
-
-### Env
-
-```cpp
-Napi::Env Napi::CallbackScope::Env() const;
-```
-
-Returns the `Napi::Env` associated with the `Napi::CallbackScope`.
-
-## Operator
-
-```cpp
-Napi::CallbackScope::operator napi_callback_scope() const;
-```
-
-Returns the N-API `napi_callback_scope` wrapped by the `Napi::CallbackScope`
-object. This can be used to mix usage of the C N-API and node-addon-api.

package/doc/callbackinfo.md

@@ -1,97 +0,0 @@
-# CallbackInfo
-
-The object representing the components of the JavaScript request being made.
-
-The `Napi::CallbackInfo` object is usually created and passed by the Node.js runtime or node-addon-api infrastructure.
-
-The `Napi::CallbackInfo` object contains the arguments passed by the caller. The number of arguments is returned by the `Length` method. Each individual argument can be accessed using the `operator[]` method.
-
-The `SetData` and `Data` methods are used to set and retrieve the data pointer contained in the `Napi::CallbackInfo` object.
-
-## Methods
-
-### Constructor
-
-```cpp
-Napi::CallbackInfo::CallbackInfo(napi_env env, napi_callback_info info);
-```
-
-- `[in] env`: The `napi_env` environment in which to construct the `Napi::CallbackInfo` object.
-- `[in] info`: The `napi_callback_info` data structure from which to construct the `Napi::CallbackInfo` object.
-
-### Env
-
-```cpp
-Napi::Env Napi::CallbackInfo::Env() const;
-```
-
-Returns the `Env` object in which the request is being made.
-
-### NewTarget
-
-```cpp
-Napi::Value Napi::CallbackInfo::NewTarget() const;
-```
-
-Returns the `new.target` value of the constructor call. If the function that was invoked (and for which the `Napi::NCallbackInfo` was passed) is not a constructor call, a call to `IsEmpty()` on the returned value returns true.
-
-### IsConstructCall
-
-```cpp
-bool Napi::CallbackInfo::IsConstructCall() const;
-```
-
-Returns a `bool` indicating if the function that was invoked (and for which the `Napi::CallbackInfo` was passed) is a constructor call.
-
-### Length
-
-```cpp
-size_t Napi::CallbackInfo::Length() const;
-```
-
-Returns the number of arguments passed in the `Napi::CallbackInfo` object.
-
-### operator []
-
-```cpp
-const Napi::Value operator [](size_t index) const;
-```
-
-- `[in] index`: The zero-based index of the requested argument.
-
-Returns a `Napi::Value` object containing the requested argument.
-
-### This
-
-```cpp
-Napi::Value Napi::CallbackInfo::This() const;
-```
-
-Returns the JavaScript `this` value for the call
-
-### Data
-
-```cpp
-void* Napi::CallbackInfo::Data() const;
-```
-
-Returns the data pointer for the callback.
-
-### SetData
-
-```cpp
-void Napi::CallbackInfo::SetData(void* data);
-```
-
-- `[in] data`: The new data pointer to associate with this `Napi::CallbackInfo` object.
-
-Returns `void`.
-
-### Not documented here
-
-```cpp
-Napi::CallbackInfo::~CallbackInfo();
-// Disallow copying to prevent multiple free of _dynamicArgs
-Napi::CallbackInfo::CallbackInfo(CallbackInfo const &) = delete;
-void Napi::CallbackInfo::operator=(CallbackInfo const &) = delete;
-```

package/doc/checker-tool.md

@@ -1,32 +0,0 @@
-# Checker Tool
-
-**node-addon-api** provides a [checker tool][] that will inspect a given
-directory tree, identifying all Node.js native addons therein, and further
-indicating for each addon whether it is an N-API addon.
-
-## To use the checker tool:
-
-  1. Install the application with `npm install`.
-
-  2. If the application does not depend on **node-addon-api**, copy the
-     checker tool into the application's directory.
-
-  3. If the application does not depend on **node-addon-api**, run the checker
-     tool from the application's directory:
-
-     ```sh
-     node ./check-napi.js
-     ```
-
-     Otherwise, the checker tool can be run from the application's
-     `node_modules/` subdirectory:
-
-     ```sh
-     node ./node_modules/node-addon-api/tools/check-napi.js
-     ```
-
-The tool accepts the root directory from which to start checking for Node.js
-native addons as a single optional command line parameter. If omitted it will
-start checking from the current directory (`.`).
-
-[checker tool]: ../tools/check-napi.js

package/doc/class_property_descriptor.md

@@ -1,117 +0,0 @@
-# Class property and descriptor
-
-Property descriptor for use with `Napi::ObjectWrap::DefineClass()`.
-This is different from the standalone `Napi::PropertyDescriptor` because it is
-specific to each `Napi::ObjectWrap<T>` subclass.
-This prevents using descriptors from a different class when defining a new class
-(preventing the callbacks from having incorrect `this` pointers).
-
-## Example
-
-```cpp
-#include <napi.h>
-
-class Example : public Napi::ObjectWrap<Example> {
-  public:
-    static Napi::Object Init(Napi::Env env, Napi::Object exports);
-    Example(const Napi::CallbackInfo &info);
-
-  private:
-    static Napi::FunctionReference constructor;
-    double _value;
-    Napi::Value GetValue(const Napi::CallbackInfo &info);
-    void SetValue(const Napi::CallbackInfo &info, const Napi::Value &value);
-};
-
-Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
-    Napi::Function func = DefineClass(env, "Example", {
-        // Register a class instance accessor with getter and setter functions.
-        InstanceAccessor<&Example::GetValue, &Example::SetValue>("value"),
-        // We can also register a readonly accessor by omitting the setter.
-        InstanceAccessor<&Example::GetValue>("readOnlyProp")
-    });
-
-    constructor = Napi::Persistent(func);
-    constructor.SuppressDestruct();
-    exports.Set("Example", func);
-
-    return exports;
-}
-
-Example::Example(const Napi::CallbackInfo &info) : Napi::ObjectWrap<Example>(info) {
-    Napi::Env env = info.Env();
-    // ...
-    Napi::Number value = info[0].As<Napi::Number>();
-    this->_value = value.DoubleValue();
-}
-
-Napi::FunctionReference Example::constructor;
-
-Napi::Value Example::GetValue(const Napi::CallbackInfo &info) {
-    Napi::Env env = info.Env();
-    return Napi::Number::New(env, this->_value);
-}
-
-void Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) {
-    Napi::Env env = info.Env();
-    // ...
-    Napi::Number arg = value.As<Napi::Number>();
-    this->_value = arg.DoubleValue();
-}
-
-// Initialize native add-on
-Napi::Object Init (Napi::Env env, Napi::Object exports) {
-    Example::Init(env, exports);
-    return exports;
-}
-
-// Register and initialize native add-on
-NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
-```
-
-The above code can be used from JavaScript as follows:
-
-```js
-'use strict';
-
-const { Example } = require('bindings')('addon');
-
-const example = new Example(11);
-console.log(example.value);
-// It prints 11
-example.value = 19;
-console.log(example.value);
-// It prints 19
-example.readOnlyProp = 500;
-console.log(example.readOnlyProp);
-// Unchanged. It prints 19
-```
-
-## Methods
-
-### Constructor
-
-Creates new instance of `Napi::ClassPropertyDescriptor` descriptor object.
-
-```cpp
-Napi::ClassPropertyDescriptor(napi_property_descriptor desc) : _desc(desc) {}
-```
-
-- `[in] desc`: The `napi_property_descriptor`
-
-Returns new instance of `Napi::ClassPropertyDescriptor` that is used as property descriptor
-inside the `Napi::ObjectWrap<T>` class.
-
-### Operator
-
-```cpp
-operator napi_property_descriptor&() { return _desc; }
-```
-
-Returns the original N-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor`
-
-```cpp
-operator const napi_property_descriptor&() const { return _desc; }
-```
-
-Returns the original N-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor`

package/doc/cmake-js.md

@@ -1,68 +0,0 @@
-# CMake.js
-
-[**CMake.js**](https://github.com/cmake-js/cmake-js) is a build tool that allow native addon developers to compile their
-C or C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but
-instead of Google's [**gyp**](https://gyp.gsrc.io) tool it is based on the [**CMake**](https://cmake.org) build system.
-
-## Quick Start
-
-### Install CMake
-
-CMake.js requires that CMake be installed. Installers for a variety of platforms can be found on the [CMake website](https://cmake.org).
-
-### Install CMake.js
-
-For developers, CMake.js is typically installed as a global package:
-
-```bash
-npm install -g cmake-js
-cmake-js --help
-```
-
-> For *users* of your native addon, CMake.js should be configured as a dependency in your `package.json` as described in the [CMake.js documentation](https://github.com/cmake-js/cmake-js).
-
-### CMakeLists.txt
-
-Your project will require a `CMakeLists.txt` file. The [CMake.js README file](https://github.com/cmake-js/cmake-js#usage) shows what's necessary.
-
-### NAPI_VERSION
-
-When building N-API addons, it's crucial to specify the N-API version your code is designed to work with. With CMake.js, this information is specified in the `CMakeLists.txt` file:
-
-```
-add_definitions(-DNAPI_VERSION=3)
-```
-
-Since N-API is ABI-stable, your N-API addon will work, without recompilation, with the N-API version you specify in `NAPI_VERSION` and all subsequent N-API versions.
-
-In the absence of a need for features available only in a specific N-API version, version 3 is a good choice as it is the version of N-API that was active when N-API left experimental status.
-
-### NAPI_EXPERIMENTAL
-
-The following line in the `CMakeLists.txt` file will enable N-API experimental features if your code requires them:
-
-```
-add_definitions(-DNAPI_EXPERIMENTAL)
-```
-
-### node-addon-api
-
-If your N-API native add-on uses the optional [**node-addon-api**](https://github.com/nodejs/node-addon-api#node-addon-api-module) C++ wrapper, the `CMakeLists.txt` file requires additional configuration information as described on the [CMake.js README file](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api).
-
-## Example
-
-A working example of an N-API native addon built using CMake.js can be found on the [node-addon-examples repository](https://github.com/nodejs/node-addon-examples/tree/master/build_with_cmake#building-n-api-addons-using-cmakejs).
-
-## **CMake** Reference
-
-  - [Installation](https://github.com/cmake-js/cmake-js#installation)
-  - [How to use](https://github.com/cmake-js/cmake-js#usage)
-  - [Using N-API and node-addon-api](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api)
-  - [Tutorials](https://github.com/cmake-js/cmake-js#tutorials)
-  - [Use case in the works - ArrayFire.js](https://github.com/cmake-js/cmake-js#use-case-in-the-works---arrayfirejs)
-
-Sometimes finding the right settings is not easy so to accomplish at most
-complicated task please refer to:
-
-- [CMake documentation](https://cmake.org/)
-- [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki)

package/doc/conversion-tool.md

@@ -1,28 +0,0 @@
-# Conversion Tool
-
-To make the migration to **node-addon-api** easier, we have provided a script to
-help complete some tasks.
-
-## To use the conversion script:
-
-  1. Go to your module directory
-
-```
-cd [module_path]
-```
-
-  2. Install node-addon-api module
-
-```
-npm install node-addon-api
-```
-  3. Run node-addon-api conversion script
-
-```
-node ./node_modules/node-addon-api/tools/conversion.js ./
-```
-
-  4. While this script makes conversion easier, it still cannot fully convert
-the module. The next step is to try to build the module and complete the
-remaining conversions necessary to allow it to compile and pass all of the
-module's tests.

package/doc/creating_a_release.md

@@ -1,62 +0,0 @@
-# Creating a release
-
-Only collaborators in npm for **node-addon-api** can create releases.
-If you want to be able to do releases ask one of the existing
-collaborators to add you. If necessary you can ask the build
-Working Group who manages the Node.js npm user to add you if
-there are no other active collaborators.
-
-## Prerequisites
-
-Before to start creating a new release check if you have installed the following
-tools:
-
-* [Changelog maker](https://www.npmjs.com/package/changelog-maker)
-
-If not please follow the instruction reported in the tool's documentation to
-install it.
-
-## Publish new release
-
-These are the steps to follow to create a new release:
-
-* Open an issue in the **node-addon-api** repo documenting the intent to create a
-new release. Give people some time to comment or suggest PRs that should land first.
-
-* Validate all tests pass by running npm test on master.
-
-* Update the version in **package.json** appropriately.
-
-* Update the [README.md](https://github.com/nodejs/node-addon-api/blob/master/README.md)
-to show the new version as the latest.
-
-* Generate the changelog for the new version using **changelog maker** tool. From
-the route folder of the repo launch the following command:
-
-    ```bash
-    > changelog-maker
-    ```
-* Use the output generated by **changelog maker** to update the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/master/CHANGELOG.md)
-following the style used in publishing the previous release.
-
-* Add any new contributors to the "contributors" section in the package.json
-
-* Validate all tests pass by running npm test on master.
-
-* Use **[CI](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api-new/)**
-to validate tests pass (note there are still some issues on SmartOS and
-Windows in the testing).
-
-* Do a clean checkout of node-addon-api.
-
-* Login and then run `npm publish`.
-
-* Create a release in Github (look at existing releases for an example).
-
-* Validate that you can run `npm install node-addon-api` successfully
-and that the correct version is installed.
-
-* Comment on the issue opened in the first step that the release has been created
-and close the issue.
-
-* Tweet that the release has been created.