Value

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.

Constructors

Empty Constructor

Napi::Value::Value();

Creates a new empty Napi::Value instance.

Constructor

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:
• bool
• Any integer type
• Any floating point type
• const char* (encoded using UTF-8, null-terminated)
• const char16_t* (encoded using UTF-16-LE, null-terminated)
• std::string (encoded using UTF-8)
• std::u16string
• Napi::Value
• napi_value

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 Napi::Value& other) const;

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

operator !=

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

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

Methods

As

template <typename T> T Napi::Value::As() const;

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

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

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

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 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.

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.

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.

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.

IsBuffer

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

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

IsDataView

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

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

IsDate

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

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

IsEmpty

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

Returns true if the value is uninitialized.

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

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

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

IsFunction

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

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

IsNull

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

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

IsNumber

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

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

IsObject

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

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

IsPromise

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

Returns true if the underlying value is a JavaScript Napi::Promise 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.

IsTypedArray

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

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

IsUndefined

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

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

StrictEquals

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

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 the Napi::Value coerced to a JavaScript number.

ToObject

Napi::Object Napi::Value::ToObject() const;

Returns the Napi::Value coerced to a JavaScript object.

ToString

Napi::String Napi::Value::ToString() const;

Returns the Napi::Value coerced to a JavaScript string.

Type

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

Returns the napi_valuetype type of the Napi::Value.