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 Node-API datatype napi_value. Methods on this class can be used to check the JavaScript type of the underlying Node-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 Node-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. When C++ exceptions are disabled, the thrown error will not be reflected before control returns to JavaScript.

In order to enforce expected type, use Napi::Value::Is*() methods to check the type before calling Napi::Value::As(), or compile with definition NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS to enforce type checks.

UnsafeAs

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

Casts to another type of Napi::Value, when the actual type is known or assumed.

This conversion does not coerce the type. This does not check the type even if NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS is defined. This indicates intentional unsafe type cast. Use Napi::Value::As() if possible.

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 Node-API primitive value from which to create the Napi::Value object.

Returns a Napi::Value object from an Node-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.

IsBigInt

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

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