1# Object
2
3Class `Napi::Object` inherits from class [`Napi::TypeTaggable`][].
4
5The `Napi::Object` class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types:
6
7- [`Napi::Array`](array.md)
8- [`Napi::ArrayBuffer`](array_buffer.md)
9- [`Napi::Buffer<T>`](buffer.md)
10- [`Napi::Function`](function.md)
11- [`Napi::TypedArray`](typed_array.md).
12
13This class provides a number of convenience methods, most of which are used to set or get properties on a JavaScript object. For example, Set() and Get().
14
15## Example
16```cpp
17#include <napi.h>
18
19using namespace Napi;
20
21Void Init(Env env) {
22
23  // Create a new instance
24  Object obj = Object::New(env);
25
26  // Assign values to properties
27  obj.Set("hello", "world");
28  obj.Set(uint32_t(42), "The Answer to Life, the Universe, and Everything");
29  obj.Set("Douglas Adams", true);
30
31  // Get properties
32  Value val1 = obj.Get("hello");
33  Value val2 = obj.Get(uint32_t(42));
34  Value val3 = obj.Get("Douglas Adams");
35
36  // Test if objects have properties.
37  bool obj1 = obj.Has("hello"); // true
38  bool obj2 = obj.Has("world"); // false
39
40}
41```
42
43## Methods
44
45### Empty Constructor
46
47```cpp
48Napi::Object::Object();
49```
50Creates a new empty Object instance.
51
52### Constructor
53
54```cpp
55Napi::Object::Object(napi_env env, napi_value value);
56```
57- `[in] env`: The `napi_env` environment in which to construct the Value object.
58
59- `[in] value`: The `napi_value` which is a handle for a JavaScript object.
60
61Creates a non-empty `Napi::Object` instance.
62
63### New()
64
65```cpp
66Napi::Object Napi::Object::New(napi_env env);
67```
68- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object.
69
70Creates a new `Napi::Object` value.
71
72### Set()
73
74```cpp
75bool Napi::Object::Set (____ key, ____ value) const;
76```
77- `[in] key`: The name for the property being assigned.
78- `[in] value`: The value being assigned to the property.
79
80Add a property with the specified key with the specified value to the object.
81
82The key can be any of the following types:
83- `napi_value`
84- [`Napi::Value`](value.md)
85- `const char*`
86- `const std::string&`
87- `uint32_t`
88
89The `value` can be of any type that is accepted by [`Napi::Value::From`][].
90
91### Delete()
92
93```cpp
94bool Napi::Object::Delete(____ key) const;
95```
96- `[in] key`: The name of the property to delete.
97
98Deletes the property associated with the given key. Returns `true` if the property was deleted.
99
100The `key` can be any of the following types:
101- `napi_value`
102- [`Napi::Value`](value.md)
103- `const char *`
104- `const std::string &`
105- `uint32_t`
106
107### Get()
108
109```cpp
110Napi::Value Napi::Object::Get(____ key);
111```
112- `[in] key`: The name of the property to return the value for.
113
114Returns the [`Napi::Value`](value.md) associated with the key property. Returns the value *undefined* if the key does not exist.
115
116The `key` can be any of the following types:
117- `napi_value`
118- [`Napi::Value`](value.md)
119- `const char *`
120- `const std::string &`
121- `uint32_t`
122
123### Has()
124
125```cpp
126bool Napi::Object::Has (____ key) const;
127```
128- `[in] key`: The name of the property to check.
129
130Returns a `bool` that is *true* if the object has a property named `key` and *false* otherwise.
131
132### InstanceOf()
133
134```cpp
135bool Napi::Object::InstanceOf (const Function& constructor) const
136```
137- `[in] constructor`: The constructor [`Napi::Function`](function.md) of the value that is being compared with the object.
138
139Returns a `bool` that is true if the `Napi::Object` is an instance created by the `constructor` and false otherwise.
140
141Note: This is equivalent to the JavaScript instanceof operator.
142
143### AddFinalizer()
144```cpp
145template <typename Finalizer, typename T>
146inline void AddFinalizer(Finalizer finalizeCallback, T* data) const;
147```
148
149- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
150- `[in] data`: The data to associate with the object.
151
152Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. `finalizeCallback`
153has the signature
154```cpp
155void finalizeCallback(Napi::Env env, T* data);
156```
157where `data` is the pointer that was passed into the call to `AddFinalizer()`.
158
159### AddFinalizer()
160```cpp
161template <typename Finalizer, typename T, typename Hint>
162inline void AddFinalizer(Finalizer finalizeCallback,
163                         T* data,
164                         Hint* finalizeHint) const;
165```
166
167- `[in] data`: The data to associate with the object.
168- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
169
170Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. An additional hint
171may be given. It will also be passed to `finalizeCallback`, which has the signature
172```cpp
173void finalizeCallback(Napi::Env env, T* data, Hint* hint);
174```
175where `data` and `hint` are the pointers that were passed into the call to `AddFinalizer()`.
176
177### GetPropertyNames()
178```cpp
179Napi::Array Napi::Object::GetPropertyNames() const;
180```
181
182Returns the names of the enumerable properties of the object as a [`Napi::Array`](array.md) of strings.
183The properties whose key is a `Symbol` will not be included.
184
185### HasOwnProperty()
186```cpp
187bool Napi::Object::HasOwnProperty(____ key) const;
188```
189- `[in] key` The name of the property to check.
190
191Returns a `bool` that is *true* if the object has an own property named `key` and *false* otherwise.
192
193The key can be any of the following types:
194- `napi_value`
195- [`Napi::Value`](value.md)
196- `const char*`
197- `const std::string&`
198- `uint32_t`
199
200### DefineProperty()
201
202```cpp
203bool Napi::Object::DefineProperty (const Napi::PropertyDescriptor& property) const;
204```
205- `[in] property`: A [`Napi::PropertyDescriptor`](property_descriptor.md).
206
207Define a property on the object.
208
209### DefineProperties()
210
211```cpp
212bool Napi::Object::DefineProperties (____ properties) const;
213```
214- `[in] properties`: A list of [`Napi::PropertyDescriptor`](property_descriptor.md). Can be one of the following types:
215  - const std::initializer_list<Napi::PropertyDescriptor>&
216  - const std::vector<Napi::PropertyDescriptor>&
217
218Defines properties on the object.
219
220### Freeze()
221
222```cpp
223void Napi::Object::Freeze() const;
224```
225
226The `Napi::Object::Freeze()` method freezes an object. A frozen object can no
227longer changed. Freezing an object prevents new properties from being added to
228it, existing properties from being removed, prevents changing the
229enumerability, configurability, or writability of existing properties and
230prevents the value of existing properties from being changed. In addition,
231freezing an object also prevents its prototype from being changed.
232
233### Seal()
234
235```cpp
236void Napi::Object::Seal() const;
237```
238
239The `Napi::Object::Seal()` method seals an object, preventing new properties
240from being added to it and marking all existing properties as non-configurable.
241Values of present properties can still be changed as long as they are
242writable.
243
244### operator\[\]()
245
246```cpp
247Napi::PropertyLValue<std::string> Napi::Object::operator[] (const char* utf8name) const;
248```
249- `[in] utf8name`: UTF-8 encoded null-terminated property name.
250
251Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) as the named
252property or sets the named property.
253
254```cpp
255Napi::PropertyLValue<std::string> Napi::Object::operator[] (const std::string& utf8name) const;
256```
257- `[in] utf8name`: UTF-8 encoded property name.
258
259Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) as the named
260property or sets the named property.
261
262```cpp
263Napi::PropertyLValue<uint32_t> Napi::Object::operator[] (uint32_t index) const;
264```
265- `[in] index`: Element index.
266
267Returns a [`Napi::Object::PropertyLValue`](propertylvalue.md) or sets an
268indexed property or array element.
269
270### begin()
271
272```cpp
273Napi::Object::iterator Napi::Object::begin() const;
274```
275
276Returns a constant iterator to the beginning of the object.
277
278```cpp
279Napi::Object::iterator Napi::Object::begin();
280```
281
282Returns a non constant iterator to the beginning of the object.
283
284### end()
285
286```cpp
287Napi::Object::iterator Napi::Object::end() const;
288```
289
290Returns a constant iterator to the end of the object.
291
292```cpp
293Napi::Object::iterator Napi::Object::end();
294```
295
296Returns a non constant iterator to the end of the object.
297
298## Iterator
299
300Iterators expose an `std::pair<...>`, where the `first` property is a
301[`Napi::Value`](value.md) that holds the currently iterated key and the
302`second` property is a [`Napi::Object::PropertyLValue`](propertylvalue.md) that
303holds the currently iterated value. Iterators are only available if C++
304exceptions are enabled (by defining `NAPI_CPP_EXCEPTIONS` during the build).
305
306### Constant Iterator
307
308In constant iterators, the iterated values are immutable.
309
310#### operator++()
311
312```cpp
313inline Napi::Object::const_iterator& Napi::Object::const_iterator::operator++();
314```
315
316Moves the iterator one step forward.
317
318#### operator==
319
320```cpp
321inline bool Napi::Object::const_iterator::operator==(const Napi::Object::const_iterator& other) const;
322```
323- `[in] other`: Another iterator to compare the current iterator to.
324
325Returns whether both iterators are at the same index.
326
327#### operator!=
328
329```cpp
330inline bool Napi::Object::const_iterator::operator!=(const Napi::Object::const_iterator& other) const;
331```
332- `[in] other`: Another iterator to compare the current iterator to.
333
334Returns whether both iterators are at different indices.
335
336#### operator*()
337
338```cpp
339inline const std::pair<Napi::Value, Napi::Object::PropertyLValue<Napi::Value>> Napi::Object::const_iterator::operator*() const;
340```
341
342Returns the currently iterated key and value.
343
344#### Example
345```cpp
346Value Sum(const CallbackInfo& info) {
347  Object object = info[0].As<Object>();
348  int64_t sum = 0;
349
350  for (const auto& e : object) {
351    sum += static_cast<Value>(e.second).As<Number>().Int64Value();
352  }
353
354  return Number::New(info.Env(), sum);
355}
356```
357
358### Non Constant Iterator
359
360In non constant iterators, the iterated values are mutable.
361
362#### operator++()
363
364```cpp
365inline Napi::Object::iterator& Napi::Object::iterator::operator++();
366```
367
368Moves the iterator one step forward.
369
370#### operator==
371
372```cpp
373inline bool Napi::Object::iterator::operator==(const Napi::Object::iterator& other) const;
374```
375- `[in] other`: Another iterator to compare the current iterator to.
376
377Returns whether both iterators are at the same index.
378
379#### operator!=
380
381```cpp
382inline bool Napi::Object::iterator::operator!=(const Napi::Object::iterator& other) const;
383```
384- `[in] other`: Another iterator to compare the current iterator to.
385
386Returns whether both iterators are at different indices.
387
388#### operator*()
389
390```cpp
391inline std::pair<Napi::Value, Napi::Object::PropertyLValue<Napi::Value>> Napi::Object::iterator::operator*();
392```
393
394Returns the currently iterated key and value.
395
396#### Example
397```cpp
398void Increment(const CallbackInfo& info) {
399  Env env = info.Env();
400  Object object = info[0].As<Object>();
401
402  for (auto e : object) {
403    int64_t value = static_cast<Value>(e.second).As<Number>().Int64Value();
404    ++value;
405    e.second = Napi::Number::New(env, value);
406  }
407}
408```
409
410[`Napi::TypeTaggable`]: ./type_taggable.md
411[`Napi::Value::From`]: ./value.md#from
412