node-addon-api 3.0.1 → 3.0.2

package/doc/basic_types.md

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

@@ -1,14 +0,0 @@
-# Working with JavaScript Values
-
-`node-addon-api` provides a set of classes that allow to create and manage
-JavaScript object:
-
-- [Function](function.md)
-  - [FunctionReference](function_reference.md)
-- [ObjectWrap](object_wrap.md)
-  - [ClassPropertyDescriptor](class_property_descriptor.md)
-- [Buffer](buffer.md)
-- [ArrayBuffer](array_buffer.md)
-- [TypedArray](typed_array.md)
-  - [TypedArrayOf](typed_array_of.md)
-- [DataView](dataview.md)