Skip to content

Latest commit

 

History

History
415 lines (305 loc) · 11.1 KB

basic_types.md

File metadata and controls

415 lines (305 loc) · 11.1 KB
Raw

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

Napi::Value::Value();

Used to create a Node Addon API Napi::Value that represents an empty value.

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

Napi::Value::operator napi_value() const;

Returns the underlying N-API napi_value. If the instance is empty, this returns nullptr.

operator ==

bool Napi::Value::operator ==(const Value& other) const;

Returns true if this value strictly equals another value, or false otherwise.

operator !=

bool Napi::Value::operator !=(const Value& other) const;

Returns false if this value strictly equals another value, or true otherwise.

Methods

From

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

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

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

Napi::Env Napi::Value::Env() const;

Returns the environment that the value is associated with. See Napi::Env for more details about environments.

IsEmpty

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

napi_valuetype Napi::Value::Type() const;

Returns the underlying N-API napi_valuetype of the value.

IsUndefined

bool Napi::Value::IsUndefined() const;

Returns true if the underlying value is a JavaScript undefined or false otherwise.

IsNull

bool Napi::Value::IsNull() const;

Returns true if the underlying value is a JavaScript null or false otherwise.

IsBoolean

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

bool Napi::Value::IsNumber() const;

Returns true if the underlying value is a JavaScript Napi::Number or false otherwise.

IsString

bool Napi::Value::IsString() const;

Returns true if the underlying value is a JavaScript Napi::String or false otherwise.

IsSymbol

bool Napi::Value::IsSymbol() const;

Returns true if the underlying value is a JavaScript Napi::Symbol or false otherwise.

IsArray

bool Napi::Value::IsArray() const;

Returns true if the underlying value is a JavaScript Napi::Array or false otherwise.

IsArrayBuffer

bool Napi::Value::IsArrayBuffer() const;

Returns true if the underlying value is a JavaScript Napi::ArrayBuffer or false otherwise.

IsTypedArray

bool Napi::Value::IsTypedArray() const;

Returns true if the underlying value is a JavaScript Napi::TypedArray or false otherwise.

IsObject

bool Napi::Value::IsObject() const;

Returns true if the underlying value is a JavaScript Napi::Object or false otherwise.

IsFunction

bool Napi::Value::IsFunction() const;

Returns true if the underlying value is a JavaScript Napi::Function or false otherwise.

IsPromise

bool Napi::Value::IsPromise() const;

Returns true if the underlying value is a JavaScript Napi::Promise or false otherwise.

IsDataView

bool Napi::Value::IsDataView() const;

Returns true if the underlying value is a JavaScript Napi::DataView or false otherwise.

IsBuffer

bool Napi::Value::IsBuffer() const;

Returns true if the underlying value is a Node.js Napi::Buffer or false otherwise.

IsExternal

bool Napi::Value::IsExternal() const;

Returns true if the underlying value is a N-API external object or false otherwise.

ToBoolean

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

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

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

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 and Napi::Symbol.

Methods

Constructor

Napi::Name::Name();

Returns an empty Napi::Name.

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.

Constructor

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.

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

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

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

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.