1# Value
2
3`Napi::Value` is the C++ manifestation of a JavaScript value. It is the base
4class upon which other JavaScript values such as `Napi::Number`,
5`Napi::Boolean`, `Napi::String`, and `Napi::Object` are based. It represents a
6JavaScript value of an unknown type. It is a thin wrapper around the Node-API
7datatype `napi_value`. Methods on this class can be used to check the JavaScript
8type of the underlying Node-API `napi_value` and also to convert to C++ types.
9
10## Constructors
11
12### Empty Constructor
13
14```cpp
15Napi::Value::Value();
16```
17
18Creates a new *empty* `Napi::Value` instance.
19
20### Constructor
21
22```cpp
23Napi::Value::Value(napi_env env, napi_value value);
24```
25
26- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value`
27object.
28- `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`.
29value` may be any of:
30  - `bool`
31  - Any integer type
32  - Any floating point type
33  - `const char*` (encoded using UTF-8, null-terminated)
34  - `const char16_t*` (encoded using UTF-16-LE, null-terminated)
35  - `std::string` (encoded using UTF-8)
36  - `std::u16string`
37  - `Napi::Value`
38  - `napi_value`
39
40## Operators
41
42### operator napi_value
43
44```cpp
45Napi::Value::operator napi_value() const;
46```
47
48Returns the underlying Node-API `napi_value`. If the instance is _empty_, this
49returns `nullptr`.
50
51### operator ==
52
53```cpp
54bool Napi::Value::operator ==(const Napi::Value& other) const;
55```
56
57Returns `true` if this value strictly equals another value, or `false`
58otherwise.
59
60### operator !=
61
62```cpp
63bool Napi::Value::operator !=(const Napi::Value& other) const;
64```
65
66Returns `false` if this value strictly equals another value, or `true`
67otherwise.
68
69## Methods
70
71### As
72
73```cpp
74template <typename T> T Napi::Value::As() const;
75```
76
77Casts to another type of `Napi::Value`, when the actual type is known or
78assumed.
79
80This conversion does not coerce the type. Calling any methods inappropriate for
81the actual value type will throw `Napi::Error`. When C++ exceptions are
82disabled, the thrown error will not be reflected before control returns to
83JavaScript.
84
85In order to enforce expected type, use `Napi::Value::Is*()` methods to check
86the type before calling `Napi::Value::As()`, or compile with definition
87`NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` to enforce type checks.
88
89### Env
90
91```cpp
92Napi::Env Napi::Value::Env() const;
93```
94
95Returns the `Napi::Env` environment this value is associated with. See
96[`Napi::Env`](env.md) for more details about environments.
97
98### From
99
100```cpp
101template <typename T>
102static Napi::Value Napi::Value::From(napi_env env, const T& value);
103```
104
105- `[in] env`: The `napi_env` environment in which to create the `Napi::Value`
106object.
107- `[in] value`: The Node-API primitive value from which to create the `Napi::Value`
108object.
109
110Returns a `Napi::Value` object from an Node-API primitive value.
111
112This method is used to convert from a C++ type to a JavaScript value.
113Here, `value` may be any of:
114- `bool` - returns a `Napi::Boolean`.
115- Any integer type - returns a `Napi::Number`.
116- Any floating point type - returns a `Napi::Number`.
117- `const char*` (encoded using UTF-8, null-terminated) - returns a
118`Napi::String`.
119- `const char16_t*` (encoded using UTF-16-LE, null-terminated) - returns a
120`Napi::String`.
121- `std::string` (encoded using UTF-8) - returns a `Napi::String`.
122- `std::u16string` - returns a `Napi::String`.
123- `Napi::Value` - returns a `Napi::Value`.
124- `Napi_value` - returns a `Napi::Value`.
125
126### IsArray
127
128```cpp
129bool Napi::Value::IsArray() const;
130```
131
132Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false`
133otherwise.
134
135### IsArrayBuffer
136
137```cpp
138bool Napi::Value::IsArrayBuffer() const;
139```
140
141Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or
142`false` otherwise.
143
144### IsBigInt
145
146```cpp
147bool Napi::Value::IsBigInt() const;
148```
149
150Returns `true` if the underlying value is a JavaScript `Napi::BigInt` or `false`
151otherwise.
152
153### IsBoolean
154
155```cpp
156bool Napi::Value::IsBoolean() const;
157```
158
159Returns `true` if the underlying value is a JavaScript `true` or JavaScript
160`false`, or `false` if the value is not a `Napi::Boolean` value in JavaScript.
161
162### IsBuffer
163
164```cpp
165bool Napi::Value::IsBuffer() const;
166```
167
168Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false`
169otherwise.
170
171### IsDataView
172```cpp
173bool Napi::Value::IsDataView() const;
174```
175
176Returns `true` if the underlying value is a JavaScript `Napi::DataView` or
177`false` otherwise.
178
179### IsDate
180
181```cpp
182bool Napi::Value::IsDate() const;
183```
184
185Returns `true` if the underlying value is a JavaScript `Date` or `false`
186otherwise.
187
188### IsEmpty
189
190```cpp
191bool Napi::Value::IsEmpty() const;
192```
193
194Returns `true` if the value is uninitialized.
195
196An empty `Napi::Value` is invalid, and most attempts to perform an operation on
197an empty `Napi::Value` will result in an exception. An empty `Napi::Value` is
198distinct from JavaScript `null` or `undefined`, which are valid values.
199
200When C++ exceptions are disabled at compile time, a method with a `Napi::Value`
201return type may return an empty `Napi::Value` to indicate a pending exception.
202Thus, when C++ exceptions are not being used, callers should check the result of
203`Env::IsExceptionPending` before attempting to use the value.
204
205### IsExternal
206```cpp
207bool Napi::Value::IsExternal() const;
208```
209
210Returns `true` if the underlying value is a Node-API external object or `false`
211otherwise.
212
213### IsFunction
214
215```cpp
216bool Napi::Value::IsFunction() const;
217```
218
219Returns `true` if the underlying value is a JavaScript `Napi::Function` or
220`false` otherwise.
221
222### IsNull
223
224```cpp
225bool Napi::Value::IsNull() const;
226```
227
228Returns `true` if the underlying value is a JavaScript `null` or `false`
229otherwise.
230
231### IsNumber
232
233```cpp
234bool Napi::Value::IsNumber() const;
235```
236
237Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false`
238otherwise.
239
240### IsObject
241
242```cpp
243bool Napi::Value::IsObject() const;
244```
245
246Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false`
247otherwise.
248
249### IsPromise
250
251```cpp
252bool Napi::Value::IsPromise() const;
253```
254
255Returns `true` if the underlying value is a JavaScript `Napi::Promise` or
256`false` otherwise.
257
258### IsString
259
260```cpp
261bool Napi::Value::IsString() const;
262```
263
264Returns `true` if the underlying value is a JavaScript `Napi::String` or `false`
265otherwise.
266
267### IsSymbol
268
269```cpp
270bool Napi::Value::IsSymbol() const;
271```
272
273Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false`
274otherwise.
275
276### IsTypedArray
277
278```cpp
279bool Napi::Value::IsTypedArray() const;
280```
281
282Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or
283`false` otherwise.
284
285### IsUndefined
286
287```cpp
288bool Napi::Value::IsUndefined() const;
289```
290
291Returns `true` if the underlying value is a JavaScript `undefined` or `false`
292otherwise.
293
294### StrictEquals
295
296```cpp
297bool Napi::Value::StrictEquals(const Napi::Value& other) const;
298```
299- `[in] other`: The `Napi::Value` object to be compared.
300
301Returns a `bool` indicating if this `Napi::Value` strictly equals another
302`Napi::Value`.
303
304### ToBoolean
305
306```cpp
307Napi::Boolean Napi::Value::ToBoolean() const;
308```
309
310Returns a `Napi::Boolean` representing the `Napi::Value`.
311
312This is a wrapper around `napi_coerce_to_boolean`. This will throw a JavaScript
313exception if the coercion fails. If C++ exceptions are not being used, callers
314should check the result of `Env::IsExceptionPending` before attempting to use
315the returned value.
316
317### ToNumber
318
319```cpp
320Napi::Number Napi::Value::ToNumber() const;
321```
322
323Returns the `Napi::Value` coerced to a JavaScript number.
324
325### ToObject
326
327```cpp
328Napi::Object Napi::Value::ToObject() const;
329```
330
331Returns the `Napi::Value` coerced to a JavaScript object.
332
333### ToString
334
335```cpp
336Napi::String Napi::Value::ToString() const;
337```
338
339Returns the `Napi::Value` coerced to a JavaScript string.
340
341### Type
342
343```cpp
344napi_valuetype Napi::Value::Type() const;
345```
346
347Returns the `napi_valuetype` type of the `Napi::Value`.
348
349[`Napi::Boolean`]: ./boolean.md
350[`Napi::BigInt`]: ./bigint.md
351[`Napi::Date`]: ./date.md
352[`Napi::External`]: ./external.md
353[`Napi::Name`]: ./name.md
354[`Napi::Number`]: ./number.md
355[`Napi::Object`]: ./object.md
356