1# Object Reference
2
3`Napi::ObjectReference` is a subclass of [`Napi::Reference`](reference.md), and is equivalent to an instance of `Napi::Reference<Object>`. This means that a `Napi::ObjectReference` holds a [`Napi::Object`](object.md), and a count of the number of references to that Object. When the count is greater than 0, an ObjectReference is not eligible for garbage collection. This ensures that the Object being held as a value of the ObjectReference will remain accessible, even if the original Object no longer is. However, ObjectReference is unique from a Reference since properties can be set and get to the Object itself that can be accessed through the ObjectReference.
4
5For more general information on references, please consult [`Napi::Reference`](reference.md).
6
7## Example
8```cpp
9#include <napi.h>
10
11using namespace Napi;
12
13void Init(Env env) {
14
15    // Create an empty ObjectReference that has an initial reference count of 2.
16    ObjectReference obj_ref = Reference<Object>::New(Object::New(env), 2);
17
18    // Set a couple of different properties on the reference.
19    obj_ref.Set("hello", String::New(env, "world"));
20    obj_ref.Set(42, "The Answer to Life, the Universe, and Everything");
21
22    // Get the properties using the keys.
23    Value val1 = obj_ref.Get("hello");
24    Value val2 = obj_ref.Get(42);
25}
26```
27
28## Methods
29
30### Initialization
31
32```cpp
33static Napi::ObjectReference Napi::ObjectReference::New(const Napi::Object& value, uint32_t initialRefcount = 0);
34```
35
36* `[in] value`: The `Napi::Object` which is to be referenced.
37
38* `[in] initialRefcount`: The initial reference count.
39
40Returns the newly created reference.
41
42```cpp
43static Napi::ObjectReference Napi::Weak(const Napi::Object& value);
44```
45
46Creates a "weak" reference to the value, in that the initial count of number of references is set to 0.
47
48* `[in] value`: The value which is to be referenced.
49
50Returns the newly created reference.
51
52```cpp
53static Napi::ObjectReference Napi::Persistent(const Napi::Object& value);
54```
55
56Creates a "persistent" reference to the value, in that the initial count of number of references is set to 1.
57
58* `[in] value`: The value which is to be referenced.
59
60Returns the newly created reference.
61
62### Empty Constructor
63
64```cpp
65Napi::ObjectReference::ObjectReference();
66```
67
68Returns a new _empty_ `Napi::ObjectReference` instance.
69
70### Constructor
71
72```cpp
73Napi::ObjectReference::ObjectReference(napi_env env, napi_value value);
74```
75
76* `[in] env`: The `napi_env` environment in which to construct the `Napi::ObjectReference` object.
77
78* `[in] value`: The Node-API primitive value to be held by the `Napi::ObjectReference`.
79
80Returns the newly created reference.
81
82### Set
83```cpp
84bool Napi::ObjectReference::Set(___ key, ___ value);
85```
86
87* `[in] key`: The name for the property being assigned.
88
89* `[in] value`: The value being assigned to the property.
90
91The `key` can be any of the following types:
92- `const char*`
93- `const std::string`
94- `uint32_t`
95
96The `value` can be any of the following types:
97- `napi_value`
98- `Napi::Value`
99- `const char*`
100- `bool`
101- `double`
102
103### Get
104
105```cpp
106Napi::Value Napi::ObjectReference::Get(___ key) const;
107```
108
109* `[in] key`: The name of the property to return the value for.
110
111Returns the [`Napi::Value`](value.md) associated with the key property. Returns NULL if no such key exists.
112
113The `key` can be any of the following types:
114- `const char*`
115- `const std::string`
116- `uint32_t`
117
118