node-addon-api 3.0.1 → 3.0.2

package/doc/promises.md

@@ -1,5 +1,7 @@
 # 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:
@@ -72,3 +74,6 @@ 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/setup.md

@@ -26,7 +26,7 @@ To use **N-API** in a native module:
   2. Reference this package's include directory and gyp file in `binding.gyp`:
 
 ```gyp
-  'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")"],
+  'include_dirs': ["<!(node -p \"require('node-addon-api').include_dir\")"],
 ```
 
   3. Decide whether the package will enable C++ exceptions in the N-API wrapper.

package/doc/string.md

@@ -1,5 +1,7 @@
 # String
 
+Class `Napi::String` inherits from class [`Napi::Name`][].
+
 ## Constructor
 
 ```cpp
@@ -87,3 +89,5 @@ std::u16string Napi::String::Utf16Value() const;
 ```
 
 Returns a UTF-16 encoded C++ string.
+
+[`Napi::Name`]: ./name.md

package/doc/symbol.md

@@ -1,5 +1,7 @@
 # Symbol
 
+Class `Napi::Symbol` inherits from class [`Napi::Name`][].
+
 ## Methods
 
 ### Constructor
@@ -42,3 +44,5 @@ static Napi::Symbol Napi::Symbol::WellKnown(napi_env env, const std::string& nam
 
 Returns a `Napi::Symbol` representing a well-known `Symbol` from the
 `Symbol` registry.
+
+[`Napi::Name`]: ./name.md

package/doc/typed_array.md

@@ -1,5 +1,7 @@
 # TypedArray
 
+Class `Napi::TypedArray` inherits from class [`Napi::Object`][].
+
 The `Napi::TypedArray` class corresponds to the
 [JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
 class.
@@ -72,3 +74,5 @@ size_t Napi::TypedArray::ByteLength() const;
 ```
 
 Returns the length of the array, in bytes.
+
+[`Napi::Object`]: ./object.md

package/doc/typed_array_of.md

@@ -1,5 +1,7 @@
 # TypedArrayOf
 
+Class `Napi::TypedArrayOf<T>` inherits from class [`Napi::TypedArray`][].
+
 The `Napi::TypedArrayOf` class corresponds to the various
 [JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
 classes.
@@ -131,3 +133,5 @@ const T* Napi::TypedArrayOf::Data() const
 
 Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the
 start of the array.
+
+[`Napi::TypedArray`]: ./typed_array.md

package/doc/value.md

@@ -1,27 +1,13 @@
 # Value
 
-`Napi::Value` is the C++ manifestation of a JavaScript value.
-
-Value is a the base class upon which other JavaScript values such as Number, Boolean, String, and Object are based.
-
-The following classes inherit, either directly or indirectly, from `Napi::Value`:
-
-- [`Napi::Array`](basic_types.md#array)
-- [`Napi::ArrayBuffer`](array_buffer.md)
-- [`Napi::Boolean`](boolean.md)
-- [`Napi::Buffer`](buffer.md)
-- [`Napi::Date`](date.md)
-- [`Napi::External`](external.md)
-- [`Napi::Function`](function.md)
-- [`Napi::Name`](name.md)
-- [`Napi::Number`](number.md)
-- [`Napi::Object`](object.md)
-- [`Napi::String`](string.md)
-- [`Napi::Symbol`](symbol.md)
-- [`Napi::TypedArray`](typed_array.md)
-- [`Napi::TypedArrayOf`](typed_array_of.md)
+`Napi::Value` is the C++ manifestation of a JavaScript value. It is the base
+class upon which other JavaScript values such as `Napi::Number`,
+`Napi::Boolean`, `Napi::String`, and `Napi::Object` are based. 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.
 
-## Methods
+## Constructors
 
 ### Empty Constructor
 
@@ -37,9 +23,10 @@ Creates a new *empty* `Napi::Value` instance.
 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 C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of:
+- `[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:
   - `bool`
   - Any integer type
   - Any floating point type
@@ -50,38 +37,25 @@ Napi::Value::Value(napi_env env, napi_value value);
   - `Napi::Value`
   - `napi_value`
 
-### 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 create the `Napi::Value` object.
-
-- `[in] value`: The N-API primitive value from which to create the `Napi::Value` object.
-
-Returns a `Napi::Value` object from an N-API primitive value.
+## Operators
 
 ### operator napi_value
 
 ```cpp
-operator napi_value() const;
+Napi::Value::operator napi_value() const;
 ```
 
-Returns this Value's N-API value primitive.
-
-Returns `nullptr` if this `Napi::Value` is *empty*.
+Returns the underlying N-API `napi_value`. If the instance is _empty_, this
+returns `nullptr`.
 
 ### operator ==
 
 ```cpp
-
 bool Napi::Value::operator ==(const Napi::Value& other) const;
 ```
 
-- `[in] other`: The `Napi::Value` object to be compared.
-
-Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi::Value`.
+Returns `true` if this value strictly equals another value, or `false`
+otherwise.
 
 ### operator !=
 
@@ -89,18 +63,22 @@ Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi:
 bool Napi::Value::operator !=(const Napi::Value& other) const;
 ```
 
-- `[in] other`: The `Napi::Value` object to be compared.
+Returns `false` if this value strictly equals another value, or `true`
+otherwise.
 
-Returns a `bool` indicating if this `Napi::Value` does not strictly equal another `Napi::Value`.
+## Methods
 
-### StrictEquals
+### As
 
 ```cpp
-bool Napi::Value::StrictEquals(const Napi::Value& other) const;
+template <typename T> T Napi::Value::As() const;
 ```
-- `[in] other`: The `Napi::Value` object to be compared.
 
-Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi::Value`.
+Casts to another type of `Napi::Value`, when the actual type is known or
+assumed.
+
+This conversion does not coerce the type. Calling any methods inappropriate for
+the actual value type will throw `Napi::Error`.
 
 ### Env
 
@@ -108,100 +86,141 @@ Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi:
 Napi::Env Napi::Value::Env() const;
 ```
 
-Returns the `Napi::Env` environment this value is associated with.
+Returns the `Napi::Env` environment this value is associated with. See
+[`Napi::Env`](env.md) for more details about environments.
 
-### IsEmpty
+### From
 
 ```cpp
-bool Napi::Value::IsEmpty() const;
+template <typename T>
+static Napi::Value Napi::Value::From(napi_env env, const T& value);
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is *empty* (uninitialized).
+- `[in] env`: The `napi_env` environment in which to create the `Napi::Value`
+object.
+- `[in] value`: The N-API primitive value from which to create the `Napi::Value`
+object.
 
-An empty `Napi::Value` is invalid, and most attempts to perform an operation on an empty Value will result in an exception.
-Note an empty `Napi::Value` is distinct from JavaScript `null` or `undefined`, which are valid values.
+Returns a `Napi::Value` object from an N-API primitive value.
 
-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. So when not using C++ exceptions, callers should check whether this `Napi::Value` is empty before attempting to use it.
+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`.
 
-### Type
+### IsArray
 
 ```cpp
-napi_valuetype Napi::Value::Type() const;
+bool Napi::Value::IsArray() const;
 ```
 
-Returns the `napi_valuetype` type of the `Napi::Value`.
+Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false`
+otherwise.
 
-### IsUndefined
+### IsArrayBuffer
 
 ```cpp
-bool Napi::Value::IsUndefined() const;
+bool Napi::Value::IsArrayBuffer() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is an undefined JavaScript value.
+Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or
+`false` otherwise.
 
-### IsNull
+### IsBoolean
 
 ```cpp
-bool Napi::Value::IsNull() const;
+bool Napi::Value::IsBoolean() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a null JavaScript value.
+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.
 
-### IsBoolean
+### IsBuffer
 
 ```cpp
-bool Napi::Value::IsBoolean() const;
+bool Napi::Value::IsBuffer() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript boolean.
+Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false`
+otherwise.
 
-### IsNumber
+### IsDataView
+```cpp
+bool Napi::Value::IsDataView() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `Napi::DataView` or
+`false` otherwise.
+
+### IsDate
 
 ```cpp
-bool Napi::Value::IsNumber() const;
+bool Napi::Value::IsDate() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript number.
+Returns `true` if the underlying value is a JavaScript `Date` or `false`
+otherwise.
 
-### IsString
+### IsEmpty
 
 ```cpp
-bool Napi::Value::IsString() const;
+bool Napi::Value::IsEmpty() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript string.
+Returns `true` if the value is uninitialized.
 
-### IsSymbol
+An empty `Napi::Value` is invalid, and most attempts to perform an operation on
+an empty `Napi::Value` will result in an exception. An empty `Napi::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 `Napi::Value` to indicate a pending exception.
+Thus, when C++ exceptions are not being used, callers should check the result of
+`Env::IsExceptionPending` before attempting to use the value.
 
+### IsExternal
 ```cpp
-bool Napi::Value::IsSymbol() const;
+bool Napi::Value::IsExternal() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript symbol.
+Returns `true` if the underlying value is a N-API external object or `false`
+otherwise.
 
-### IsArray
+### IsFunction
 
 ```cpp
-bool Napi::Value::IsArray() const;
+bool Napi::Value::IsFunction() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript array.
+Returns `true` if the underlying value is a JavaScript `Napi::Function` or
+`false` otherwise.
 
-### IsArrayBuffer
+### IsNull
 
 ```cpp
-bool Napi::Value::IsArrayBuffer() const;
+bool Napi::Value::IsNull() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript array buffer.
+Returns `true` if the underlying value is a JavaScript `null` or `false`
+otherwise.
 
-### IsTypedArray
+### IsNumber
 
 ```cpp
-bool Napi::Value::IsTypedArray() const;
+bool Napi::Value::IsNumber() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript typed array.
+Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false`
+otherwise.
 
 ### IsObject
 
@@ -209,41 +228,63 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript typed array.
 bool Napi::Value::IsObject() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is JavaScript object.
+Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false`
+otherwise.
 
-### IsFunction
+### IsPromise
 
 ```cpp
-bool Napi::Value::IsFunction() const;
+bool Napi::Value::IsPromise() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript function.
+Returns `true` if the underlying value is a JavaScript `Napi::Promise` or
+`false` otherwise.
 
-### IsBuffer
+### IsString
 
 ```cpp
-bool Napi::Value::IsBuffer() const;
+bool Napi::Value::IsString() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a Node buffer.
+Returns `true` if the underlying value is a JavaScript `Napi::String` or `false`
+otherwise.
 
-### IsDate
+### IsSymbol
 
 ```cpp
-bool Napi::Value::IsDate() const;
+bool Napi::Value::IsSymbol() const;
 ```
 
-Returns a `bool` indicating if this `Napi::Value` is a JavaScript date.
+Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false`
+otherwise.
 
-### As
+### IsTypedArray
 
 ```cpp
-template <typename T> T Napi::Value::As() const;
+bool Napi::Value::IsTypedArray() const;
 ```
 
-Casts to another type of `Napi::Value`, when the actual type is known or assumed.
+Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or
+`false` otherwise.
 
-This conversion does not coerce the type. Calling any methods inappropriate for the actual value type will throw `Napi::Error`.
+### IsUndefined
+
+```cpp
+bool Napi::Value::IsUndefined() const;
+```
+
+Returns `true` if the underlying value is a JavaScript `undefined` or `false`
+otherwise.
+
+### StrictEquals
+
+```cpp
+bool Napi::Value::StrictEquals(const Napi::Value& other) const;
+```
+- `[in] other`: The `Napi::Value` object to be compared.
+
+Returns a `bool` indicating if this `Napi::Value` strictly equals another
+`Napi::Value`.
 
 ### ToBoolean
 
@@ -251,7 +292,12 @@ This conversion does not coerce the type. Calling any methods inappropriate for
 Napi::Boolean Napi::Value::ToBoolean() const;
 ```
 
-Returns the `Napi::Value` coerced to a JavaScript boolean.
+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
 
@@ -261,6 +307,14 @@ Napi::Number Napi::Value::ToNumber() const;
 
 Returns the `Napi::Value` coerced to a JavaScript number.
 
+### ToObject
+
+```cpp
+Napi::Object Napi::Value::ToObject() const;
+```
+
+Returns the `Napi::Value` coerced to a JavaScript object.
+
 ### ToString
 
 ```cpp
@@ -269,10 +323,18 @@ Napi::String Napi::Value::ToString() const;
 
 Returns the `Napi::Value` coerced to a JavaScript string.
 
-### ToObject
+### Type
 
 ```cpp
-Napi::Object Napi::Value::ToObject() const;
+napi_valuetype Napi::Value::Type() const;
 ```
 
-Returns the `Napi::Value` coerced to a JavaScript object.
+Returns the `napi_valuetype` type of the `Napi::Value`.
+
+[`Napi::Boolean`]: ./boolean.md
+[`Napi::BigInt`]: ./bigint.md
+[`Napi::Date`]: ./date.md
+[`Napi::External`]: ./external.md
+[`Napi::Name`]: ./name.md
+[`Napi::Number`]: ./number.md
+[`Napi::Object`]: ./object.md

package/index.js

@@ -1,10 +1,11 @@
 const path = require('path');
 
-const include = path.relative('.', __dirname);
+const include_dir = path.relative('.', __dirname);
 
 module.exports = {
-  include: include,
-  gyp: path.join(include, 'node_api.gyp:nothing'),
+  include: `"${__dirname}"`, // deprecated, can be removed as part of 4.0.0
+  include_dir,
+  gyp: path.join(include_dir, 'node_api.gyp:nothing'),
   isNodeApiBuiltin: true,
   needsFlag: false
 };