node-addon-api 3.1.0 → 3.2.0

package/doc/promises.md

@@ -1,79 +0,0 @@
-# Promise
-
-Class `Napi::Promise` inherits from class [`Napi::Object`][].
-
-The `Napi::Promise` class, along with its `Napi::Promise::Deferred` class, implement the ability to create, resolve, and reject Promise objects.
-
-The basic approach is to create a `Napi::Promise::Deferred` object and return to your caller the value returned by the `Napi::Promise::Deferred::Promise` method. For example:
-
-```cpp
-Napi::Value YourFunction(const Napi::CallbackInfo& info) {
-  // your code goes here...
-  Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(info.Env());
-  // deferred needs to survive this call...
-  return deferred.Promise();
-}
-```
-
-Later, when the asynchronous process completes, call either the `Resolve` or `Reject` method on the `Napi::Promise::Deferred` object created earlier:
-
-```cpp
-  deferred.Resolve(String::New(info.Env(), "OK"));
-```
-
-## Promise::Deferred Methods
-
-### Factory Method
-
-```cpp
-static Napi::Promise::Deferred Napi::Promise::Deferred::New(napi_env env);
-```
-
-* `[in] env`: The `napi_env` environment in which to create the `Napi::Promise::Deferred` object.
-
-### Constructor
-
-```cpp
-Napi::Promise::Deferred(napi_env env);
-```
-
-* `[in] env`: The `napi_env` environment in which to construct the `Napi::Promise::Deferred` object.
-
-### Env
-
-```cpp
-Napi::Env Napi::Promise::Deferred::Env() const;
-```
-
-Returns the Env environment this `Napi::Promise::Deferred` object is associated with.
-
-### Promise
-
-```cpp
-Napi::Promise Napi::Promise::Deferred::Promise() const;
-```
-
-Returns the `Napi::Promise` object held by the `Napi::Promise::Deferred` object.
-
-### Resolve
-
-```cpp
-void Napi::Promise::Deferred::Resolve(napi_value value) const;
-```
-
-Resolves the `Napi::Promise` object held by the `Napi::Promise::Deferred` object.
-
-* `[in] value`: The N-API primitive value with which to resolve the `Napi::Promise`.
-
-### Reject
-
-```cpp
-void Napi::Promise::Deferred::Reject(napi_value value) const;
-```
-
-Rejects the Promise object held by the `Napi::Promise::Deferred` object.
-
-* `[in] value`: The N-API primitive value with which to reject the `Napi::Promise`.
-
-
-[`Napi::Object`]: ./object.md

package/doc/property_descriptor.md

@@ -1,286 +0,0 @@
-# Property Descriptor
-
-A [`Napi::Object`](object.md) can be assigned properties via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) functions, which take PropertyDescriptor(s) as their parameters. The `Napi::PropertyDescriptor` can contain either values or functions, which are then assigned to the `Napi::Object`. Note that a single instance of a `Napi::PropertyDescriptor` class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [`Accessor`](#accessor), [`Function`](#function), or [`Value`](#value), each of which return a new static instance of a `Napi::PropertyDescriptor`.
-
-## Example
-
-```cpp
-#include <napi.h>
-
-using namespace Napi;
-
-Value TestGetter(const CallbackInfo& info) {
-   return Boolean::New(info.Env(), testValue);
-}
-
-void TestSetter(const CallbackInfo& info) {
-   testValue = info[0].As<Boolean>();
-}
-
-Value TestFunction(const CallbackInfo& info) {
-   return Boolean::New(info.Env(), true);
-}
-
-Void Init(Env env) {
-  // Create an object.
-  Object obj = Object::New(env);
-
-  // Accessor
-  PropertyDescriptor pd1 = PropertyDescriptor::Accessor<TestGetter>("pd1");
-  PropertyDescriptor pd2 =
-      PropertyDescriptor::Accessor<TestGetter, TestSetter>("pd2");
-  // Function
-  PropertyDescriptor pd3 = PropertyDescriptor::Function(env,
-                                                        "function",
-                                                        TestFunction);
-  // Value
-  Boolean true_bool = Boolean::New(env, true);
-  PropertyDescriptor pd4 =
-      PropertyDescriptor::Value("boolean value",
-                                Napi::Boolean::New(env, true),
-                                napi_writable);
-
-  // Assign properties to the object.
-  obj.DefineProperties({pd1, pd2, pd3, pd4});
-}
-```
-
-## Types
-
-### PropertyDescriptor::GetterCallback
-
-```cpp
-typedef Napi::Value (*GetterCallback)(const Napi::CallbackInfo& info);
-```
-
-This is the signature of a getter function to be passed as a template parameter
-to `PropertyDescriptor::Accessor`.
-
-### PropertyDescriptor::SetterCallback
-
-```cpp
-typedef void (*SetterCallback)(const Napi::CallbackInfo& info);
-```
-
-This is the signature of a setter function to be passed as a template parameter
-to `PropertyDescriptor::Accessor`.
-
-## Methods
-
-### Constructor
-
-```cpp
-Napi::PropertyDescriptor::PropertyDescriptor (napi_property_descriptor desc);
-```
-
-* `[in] desc`: A PropertyDescriptor that is needed in order to create another PropertyDescriptor.
-
-### Accessor
-
-```cpp
-template <Napi::PropertyDescriptor::GetterCallback Getter>
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
-                             napi_property_attributes attributes = napi_default,
-                             void* data = nullptr);
-```
-
-* `[template] Getter`: A getter function.
-* `[in] attributes`: Potential attributes for the getter function.
-* `[in] data`: A pointer to data of any type, default is a null pointer.
-
-Returns a PropertyDescriptor that contains a read-only property.
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `napi_value value`
-- `Napi::Name`
-
-```cpp
-template <
-Napi::PropertyDescriptor::GetterCallback Getter,
-Napi::PropertyDescriptor::SetterCallback Setter>
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
-                             napi_property_attributes attributes = napi_default,
-                             void* data = nullptr);
-```
-
-* `[template] Getter`: A getter function.
-* `[template] Setter`: A setter function.
-* `[in] attributes`: Potential attributes for the getter function.
-* `[in] data`: A pointer to data of any type, default is a null pointer.
-
-Returns a PropertyDescriptor that contains a read-write property.
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `napi_value value`
-- `Napi::Name`
-
-```cpp
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
-                Getter getter,
-                napi_property_attributes attributes = napi_default,
-                void *data = nullptr);
-```
-
-* `[in] name`: The name used for the getter function.
-* `[in] getter`: A getter function.
-* `[in] attributes`: Potential attributes for the getter function.
-* `[in] data`: A pointer to data of any type, default is a null pointer.
-
-Returns a PropertyDescriptor that contains a function.
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `napi_value value`
-- `Napi::Name`
-
-**This signature is deprecated. It will result in a memory leak if used.**
-
-```cpp
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (
-                Napi::Env env,
-                Napi::Object object,
-                ___ name,
-                Getter getter,
-                napi_property_attributes attributes = napi_default,
-                void *data = nullptr);
-```
-
-* `[in] env`: The environment in which to create this accessor.
-* `[in] object`: The object on which the accessor will be defined.
-* `[in] name`: The name used for the getter function.
-* `[in] getter`: A getter function.
-* `[in] attributes`: Potential attributes for the getter function.
-* `[in] data`: A pointer to data of any type, default is a null pointer.
-
-Returns a `Napi::PropertyDescriptor` that contains a `Getter` accessor.
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `Napi::Name`
-
-```cpp
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
-                Getter getter,
-                Setter setter,
-                napi_property_attributes attributes = napi_default,
-                void *data = nullptr);
-```
-
-* `[in] name`: The name of the getter and setter function.
-* `[in] getter`: The getter function.
-* `[in] setter`: The setter function.
-* `[in] attributes`: Potential attributes for the getter function.
-* `[in] data`: A pointer to data of any type, default is a null pointer.
-
-Returns a `Napi::PropertyDescriptor` that contains a `Getter` and `Setter` function.
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `napi_value value`
-- `Napi::Name`
-
-**This signature is deprecated. It will result in a memory leak if used.**
-
-```cpp
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (
-                Napi::Env env,
-                Napi::Object object,
-                ___ name,
-                Getter getter,
-                Setter setter,
-                napi_property_attributes attributes = napi_default,
-                void *data = nullptr);
-```
-
-* `[in] env`: The environment in which to create this accessor.
-* `[in] object`: The object on which the accessor will be defined.
-* `[in] name`: The name of the getter and setter function.
-* `[in] getter`: The getter function.
-* `[in] setter`: The setter function.
-* `[in] attributes`: Potential attributes for the getter function.
-* `[in] data`: A pointer to data of any type, default is a null pointer.
-
-Returns a `Napi::PropertyDescriptor` that contains a `Getter` and `Setter` function.
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `Napi::Name`
-
-### Function
-
-```cpp
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Function (___ name,
-                Callable cb,
-                napi_property_attributes attributes = napi_default,
-		            void *data = nullptr);
-```
-
-* `[in] name`: The name of the Callable function.
-* `[in] cb`: The function
-* `[in] attributes`: Potential attributes for the getter function.
-* `[in] data`: A pointer to data of any type, default is a null pointer.
-
-Returns a `Napi::PropertyDescriptor` that contains a callable `Napi::Function`.
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `napi_value value`
-- `Napi::Name`
-
-**This signature is deprecated. It will result in a memory leak if used.**
-
-```cpp
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Function (
-                Napi::Env env,
-                ___ name,
-                Callable cb,
-                napi_property_attributes attributes = napi_default,
-		            void *data = nullptr);
-```
-
-* `[in] env`: The environment in which to create this accessor.
-* `[in] name`: The name of the Callable function.
-* `[in] cb`: The function
-* `[in] attributes`: Potential attributes for the getter function.
-* `[in] data`: A pointer to data of any type, default is a null pointer.
-
-Returns a `Napi::PropertyDescriptor` that contains a callable `Napi::Function`.
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `Napi::Name`
-
-### Value
-
-```cpp
-static Napi::PropertyDescriptor Napi::PropertyDescriptor::Value (___ name,
-                napi_value value,
-                napi_property_attributes attributes = napi_default);
-```
-
-The name of the property can be any of the following types:
-- `const char*`
-- `const std::string &`
-- `napi_value value`
-- `Napi::Name`
-
-## Related Information
-
-### napi\_property\_attributes
-`napi_property_attributes` are flags used to indicate to JavaScript certain permissions that the property is meant to have. The following are the flag options:
-- napi\_default,
-- napi\_writable,
-- napi\_enumerable,
-- napi\_configurable
-For more information on the flags and on napi\_property\_attributes, please read the documentation [here](https://github.com/nodejs/node/blob/master/doc/api/n-api.md#napi_property_attributes).
-

package/doc/range_error.md

@@ -1,59 +0,0 @@
-# RangeError
-
-The `Napi::RangeError` class is a representation of the JavaScript `RangeError` that is
-thrown when trying to pass a value as an argument to a function that does not allow
-a range that includes the value.
-
-The `Napi::RangeError` class inherits its behaviors from the `Napi::Error` class (for
-more info see: [`Napi::Error`](error.md)).
-
-For more details about error handling refer to the section titled [Error handling](error_handling.md).
-
-## Methods
-
-### New
-
-Creates a new instance of a `Napi::RangeError` object.
-
-```cpp
-Napi::RangeError::New(Napi::Env env, const char* message);
-```
-
-- `[in] Env`: The environment in which to construct the `Napi::RangeError` object.
-- `[in] message`: Null-terminated string to be used as the message for the `Napi::RangeError`.
-
-Returns an instance of a `Napi::RangeError` object.
-
-### New
-
-Creates a new instance of a `Napi::RangeError` object.
-
-```cpp
-Napi::RangeError::New(Napi::Env env, const std::string& message);
-```
-
-- `[in] Env`: The environment in which to construct the `Napi::RangeError` object.
-- `[in] message`: Reference string to be used as the message for the `Napi::RangeError`.
-
-Returns an instance of a `Napi::RangeError` object.
-
-### Constructor
-
-Creates a new empty instance of a `Napi::RangeError`.
-
-```cpp
-Napi::RangeError::RangeError();
-```
-
-### Constructor
-
-Initializes a `Napi::RangeError` instance from an existing Javascript error object.
-
-```cpp
-Napi::RangeError::RangeError(napi_env env, napi_value value);
-```
-
-- `[in] Env`: The environment in which to construct the `Napi::RangeError` object.
-- `[in] value`: The `Napi::Error` reference to wrap.
-
-Returns an instance of a `Napi::RangeError` object.

package/doc/reference.md

@@ -1,111 +0,0 @@
-# Reference (template)
-
-Holds a counted reference to a [`Napi::Value`](value.md) object; initially a weak reference unless otherwise specified, may be changed to/from a strong reference by adjusting the refcount.
-
-The referenced `Napi::Value` is not immediately destroyed when the reference count is zero; it is merely then eligible for garbage-collection if there are no other references to the `Napi::Value`.
-
-`Napi::Reference` objects allocated in static space, such as a global static instance, must call the `SuppressDestruct` method to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid.
-
-The following classes inherit, either directly or indirectly, from `Napi::Reference`:
-
-* [`Napi::ObjectWrap`](object_wrap.md)
-* [`Napi::ObjectReference`](object_reference.md)
-* [`Napi::FunctionReference`](function_reference.md)
-
-## Methods
-
-### Factory Method
-
-```cpp
-static Napi::Reference<T> Napi::Reference::New(const T& value, uint32_t initialRefcount = 0);
-```
-
-* `[in] value`: The value which is to be referenced.
-
-* `[in] initialRefcount`: The initial reference count.
-
-### Empty Constructor
-
-```cpp
-Napi::Reference::Reference();
-```
-
-Creates a new _empty_ `Napi::Reference` instance.
-
-### Constructor
-
-```cpp
-Napi::Reference::Reference(napi_env env, napi_value value);
-```
-
-* `[in] env`: The `napi_env` environment in which to construct the `Napi::Reference` object.
-
-* `[in] value`: The N-API primitive value to be held by the `Napi::Reference`.
-
-### Env
-
-```cpp
-Napi::Env Napi::Reference::Env() const;
-```
-
-Returns the `Napi::Env` value in which the `Napi::Reference` was instantiated.
-
-### IsEmpty
-
-```cpp
-bool Napi::Reference::IsEmpty() const;
-```
-
-Determines whether the value held by the `Napi::Reference` is empty.
-
-### Value
-
-```cpp
-T Napi::Reference::Value() const;
-```
-
-Returns the value held by the `Napi::Reference`.
-
-### Ref
-
-```cpp
-uint32_t Napi::Reference::Ref();
-```
-
-Increments the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the increment fails.
-
-### Unref
-
-```cpp
-uint32_t Napi::Reference::Unref();
-```
-
-Decrements the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the decrement fails.
-
-### Reset (Empty)
-
-```cpp
-void Napi::Reference::Reset();
-```
-
-Sets the value held by the `Napi::Reference` to be empty.
-
-### Reset
-
-```cpp
-void Napi::Reference::Reset(const T& value, uint32_t refcount = 0);
-```
-
-* `[in] value`: The value which is to be referenced.
-
-* `[in] initialRefcount`: The initial reference count.
-
-Sets the value held by the `Napi::Reference`.
-
-### SuppressDestruct
-
-```cpp
-void Napi::Reference::SuppressDestruct();
-```
-
-Call this method on a `Napi::Reference` that is declared as static data to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid.

package/doc/setup.md

@@ -1,81 +0,0 @@
-# Setup
-
-## Prerequisites
-
-Before starting to use **N-API** you need to assure you have the following
-prerequisites:
-
-* **Node.JS** see: [Installing Node.js](https://nodejs.org/)
-
-* **Node.js native addon build tool**
-
-  - **[node-gyp](node-gyp.md)**
-
-## Installation and usage
-
-To use **N-API** in a native module:
-
-  1. Add a dependency on this package to `package.json`:
-
-```json
-  "dependencies": {
-    "node-addon-api": "*",
-  }
-```
-
-  2. Reference this package's include directory and gyp file in `binding.gyp`:
-
-```gyp
-  'include_dirs': ["<!(node -p \"require('node-addon-api').include_dir\")"],
-```
-
-  3. Decide whether the package will enable C++ exceptions in the N-API wrapper.
-     The base ABI-stable C APIs do not throw or handle C++ exceptions, but the
-     N-API C++ wrapper classes may _optionally_
-     [integrate C++ and JavaScript exception-handling
-     ](https://nodejs.github.io/node-addon-api/class_napi_1_1_error.html).
-     To enable that capability, C++ exceptions must be enabled in `binding.gyp`:
-
-```gyp
-  'cflags!': [ '-fno-exceptions' ],
-  'cflags_cc!': [ '-fno-exceptions' ],
-  'xcode_settings': {
-    'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
-    'CLANG_CXX_LIBRARY': 'libc++',
-    'MACOSX_DEPLOYMENT_TARGET': '10.7',
-  },
-  'msvs_settings': {
-    'VCCLCompilerTool': { 'ExceptionHandling': 1 },
-  },
-```
-
-  Alternatively, disable use of C++ exceptions in N-API:
-
-```gyp
-  'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ],
-```
-  4. If you would like your native addon to support OSX, please also add the
-  following settings in the `binding.gyp` file:
-
-  ```gyp
-  ['OS=="mac"', {
-      'cflags+': ['-fvisibility=hidden'],
-      'xcode_settings': {
-        'GCC_SYMBOLS_PRIVATE_EXTERN': 'YES', # -fvisibility=hidden
-      }
-  }]
-  ```
-
-  5. Include `napi.h` in the native module code.
-     To ensure only ABI-stable APIs are used, DO NOT include
-     `node.h`, `nan.h`, or `v8.h`.
-
-```C++
-#include "napi.h"
-```
-
-At build time, the N-API back-compat library code will be used only when the
-targeted node version *does not* have N-API built-in.
-
-The preprocessor directive `NODE_ADDON_API_DISABLE_DEPRECATED` can be defined at
-compile time before including `napi.h` to skip the definition of deprecated APIs.

package/doc/string.md

@@ -1,93 +0,0 @@
-# String
-
-Class `Napi::String` inherits from class [`Napi::Name`][].
-
-## Constructor
-
-```cpp
-Napi::String::String();
-```
-
-Returns a new **empty** `Napi::String` instance.
-
-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.
-
-```cpp
-Napi::String::String(napi_env env, napi_value value); ///< Wraps a N-API value primitive.
-```
-- `[in] env` - The environment in which to create the string.
-- `[in] value` - The primitive to wrap.
-
-Returns a `Napi::String` 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.
-
-## Operators
-
-### operator std::string
-
-```cpp
-Napi::String::operator std::string() const;
-```
-
-Returns a UTF-8 encoded C++ string.
-
-### operator std::u16string
-```cpp
-Napi::String::operator std::u16string() const;
-```
-
-Returns a UTF-16 encoded C++ string.
-
-## Methods
-
-### New
-```cpp
-Napi::String::New();
-```
-
-Returns a new empty `Napi::String`.
-
-### New
-```cpp
-Napi::String::New(napi_env env, const std::string& value);
-Napi::String::New(napi_env env, const std::u16::string& value);
-Napi::String::New(napi_env env, const char* value);
-Napi::String::New(napi_env env, const char16_t* value);
-Napi::String::New(napi_env env, const char* value, size_t length);
-Napi::String::New(napi_env env, const char16_t* value, size_t length);
-```
-
-- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object.
-- `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of:
-  - `std::string&` - represents a UTF8 string.
-  - `std::u16string&` - represents a UTF16-LE string.
-  - `const char*` - represents a UTF8 string.
-  - `const char16_t*` - represents a UTF16-LE string.
-- `[in] length`: The length of the string (not necessarily null-terminated) in code units.
-
-Returns a new `Napi::String` that represents the passed in C++ string.
-
-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.
-
-### Utf8Value
-```cpp
-std::string Napi::String::Utf8Value() const;
-```
-
-Returns a UTF-8 encoded C++ string.
-
-### Utf16Value
-```cpp
-std::u16string Napi::String::Utf16Value() const;
-```
-
-Returns a UTF-16 encoded C++ string.
-
-[`Napi::Name`]: ./name.md