1# Property Descriptor
2
3A [`Napi::Object`](object.md) can be assigned properties via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) functions, which take PropertyDescriptor(s) as their parameters. The `Napi::PropertyDescriptor` can contain either values or functions, which are then assigned to the `Napi::Object`. Note that a single instance of a `Napi::PropertyDescriptor` class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [`Accessor`](#accessor), [`Function`](#function), or [`Value`](#value), each of which return a new static instance of a `Napi::PropertyDescriptor`.
4
5## Example
6
7```cpp
8#include <napi.h>
9
10using namespace Napi;
11
12Value TestGetter(const CallbackInfo& info) {
13   return Boolean::New(info.Env(), testValue);
14}
15
16void TestSetter(const CallbackInfo& info) {
17   testValue = info[0].As<Boolean>();
18}
19
20Value TestFunction(const CallbackInfo& info) {
21   return Boolean::New(info.Env(), true);
22}
23
24Void Init(Env env) {
25  // Create an object.
26  Object obj = Object::New(env);
27
28  // Accessor
29  PropertyDescriptor pd1 = PropertyDescriptor::Accessor<TestGetter>("pd1");
30  PropertyDescriptor pd2 =
31      PropertyDescriptor::Accessor<TestGetter, TestSetter>("pd2");
32  // Function
33  PropertyDescriptor pd3 = PropertyDescriptor::Function(env,
34                                                        "function",
35                                                        TestFunction);
36  // Value
37  Boolean true_bool = Boolean::New(env, true);
38  PropertyDescriptor pd4 =
39      PropertyDescriptor::Value("boolean value",
40                                Napi::Boolean::New(env, true),
41                                napi_writable);
42
43  // Assign properties to the object.
44  obj.DefineProperties({pd1, pd2, pd3, pd4});
45}
46```
47
48## Types
49
50### PropertyDescriptor::GetterCallback
51
52```cpp
53using GetterCallback = Napi::Value (*)(const Napi::CallbackInfo& info);
54```
55
56This is the signature of a getter function to be passed as a template parameter
57to `PropertyDescriptor::Accessor`.
58
59### PropertyDescriptor::SetterCallback
60
61```cpp
62using SetterCallback = void (*)(const Napi::CallbackInfo& info);
63```
64
65This is the signature of a setter function to be passed as a template parameter
66to `PropertyDescriptor::Accessor`.
67
68## Methods
69
70### Constructor
71
72```cpp
73Napi::PropertyDescriptor::PropertyDescriptor (napi_property_descriptor desc);
74```
75
76* `[in] desc`: A PropertyDescriptor that is needed in order to create another PropertyDescriptor.
77
78### Accessor
79
80```cpp
81template <Napi::PropertyDescriptor::GetterCallback Getter>
82static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
83                             napi_property_attributes attributes = napi_default,
84                             void* data = nullptr);
85```
86
87* `[template] Getter`: A getter function.
88* `[in] attributes`: Potential attributes for the getter function.
89* `[in] data`: A pointer to data of any type, default is a null pointer.
90
91Returns a PropertyDescriptor that contains a read-only property.
92
93The name of the property can be any of the following types:
94- `const char*`
95- `const std::string &`
96- `napi_value value`
97- `Napi::Name`
98
99```cpp
100template <
101Napi::PropertyDescriptor::GetterCallback Getter,
102Napi::PropertyDescriptor::SetterCallback Setter>
103static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
104                             napi_property_attributes attributes = napi_default,
105                             void* data = nullptr);
106```
107
108* `[template] Getter`: A getter function.
109* `[template] Setter`: A setter function.
110* `[in] attributes`: Potential attributes for the getter function.
111* `[in] data`: A pointer to data of any type, default is a null pointer.
112
113Returns a PropertyDescriptor that contains a read-write property.
114
115The name of the property can be any of the following types:
116- `const char*`
117- `const std::string &`
118- `napi_value value`
119- `Napi::Name`
120
121```cpp
122static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
123                Getter getter,
124                napi_property_attributes attributes = napi_default,
125                void *data = nullptr);
126```
127
128* `[in] name`: The name used for the getter function.
129* `[in] getter`: A getter function.
130* `[in] attributes`: Potential attributes for the getter function.
131* `[in] data`: A pointer to data of any type, default is a null pointer.
132
133Returns a PropertyDescriptor that contains a function.
134
135The name of the property can be any of the following types:
136- `const char*`
137- `const std::string &`
138- `napi_value value`
139- `Napi::Name`
140
141**The above signature is deprecated. It will result in a memory leak if used.**
142
143```cpp
144static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (
145                Napi::Env env,
146                Napi::Object object,
147                ___ name,
148                Getter getter,
149                napi_property_attributes attributes = napi_default,
150                void *data = nullptr);
151```
152
153* `[in] env`: The environment in which to create this accessor.
154* `[in] object`: The object on which the accessor will be defined.
155* `[in] name`: The name used for the getter function.
156* `[in] getter`: A getter function.
157* `[in] attributes`: Potential attributes for the getter function.
158* `[in] data`: A pointer to data of any type, default is a null pointer.
159
160Returns a `Napi::PropertyDescriptor` that contains a `Getter` accessor.
161
162The name of the property can be any of the following types:
163- `const char*`
164- `const std::string &`
165- `Napi::Name`
166
167```cpp
168static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
169                Getter getter,
170                Setter setter,
171                napi_property_attributes attributes = napi_default,
172                void *data = nullptr);
173```
174
175* `[in] name`: The name of the getter and setter function.
176* `[in] getter`: The getter function.
177* `[in] setter`: The setter function.
178* `[in] attributes`: Potential attributes for the getter function.
179* `[in] data`: A pointer to data of any type, default is a null pointer.
180
181Returns a `Napi::PropertyDescriptor` that contains a `Getter` and `Setter` function.
182
183The name of the property can be any of the following types:
184- `const char*`
185- `const std::string &`
186- `napi_value value`
187- `Napi::Name`
188
189**The above signature is deprecated. It will result in a memory leak if used.**
190
191```cpp
192static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (
193                Napi::Env env,
194                Napi::Object object,
195                ___ name,
196                Getter getter,
197                Setter setter,
198                napi_property_attributes attributes = napi_default,
199                void *data = nullptr);
200```
201
202* `[in] env`: The environment in which to create this accessor.
203* `[in] object`: The object on which the accessor will be defined.
204* `[in] name`: The name of the getter and setter function.
205* `[in] getter`: The getter function.
206* `[in] setter`: The setter function.
207* `[in] attributes`: Potential attributes for the getter function.
208* `[in] data`: A pointer to data of any type, default is a null pointer.
209
210Returns a `Napi::PropertyDescriptor` that contains a `Getter` and `Setter` function.
211
212The name of the property can be any of the following types:
213- `const char*`
214- `const std::string &`
215- `Napi::Name`
216
217### Function
218
219```cpp
220static Napi::PropertyDescriptor Napi::PropertyDescriptor::Function (___ name,
221                Callable cb,
222                napi_property_attributes attributes = napi_default,
223                void *data = nullptr);
224```
225
226* `[in] name`: The name of the Callable function.
227* `[in] cb`: The function
228* `[in] attributes`: Potential attributes for the getter function.
229* `[in] data`: A pointer to data of any type, default is a null pointer.
230
231Returns a `Napi::PropertyDescriptor` that contains a callable `Napi::Function`.
232
233The name of the property can be any of the following types:
234- `const char*`
235- `const std::string &`
236- `napi_value value`
237- `Napi::Name`
238
239**The above signature is deprecated. It will result in a memory leak if used.**
240
241```cpp
242static Napi::PropertyDescriptor Napi::PropertyDescriptor::Function (
243                Napi::Env env,
244                ___ name,
245                Callable cb,
246                napi_property_attributes attributes = napi_default,
247                void *data = nullptr);
248```
249
250* `[in] env`: The environment in which to create this accessor.
251* `[in] name`: The name of the Callable function.
252* `[in] cb`: The function
253* `[in] attributes`: Potential attributes for the getter function.
254* `[in] data`: A pointer to data of any type, default is a null pointer.
255
256Returns a `Napi::PropertyDescriptor` that contains a callable `Napi::Function`.
257
258The name of the property can be any of the following types:
259- `const char*`
260- `const std::string &`
261- `Napi::Name`
262
263### Value
264
265```cpp
266static Napi::PropertyDescriptor Napi::PropertyDescriptor::Value (___ name,
267                napi_value value,
268                napi_property_attributes attributes = napi_default);
269```
270
271The name of the property can be any of the following types:
272- `const char*`
273- `const std::string &`
274- `napi_value value`
275- `Napi::Name`
276
277## Related Information
278
279### napi\_property\_attributes
280`napi_property_attributes` are flags used to indicate to JavaScript certain permissions that the property is meant to have. The following are the flag options:
281- napi\_default,
282- napi\_writable,
283- napi\_enumerable,
284- napi\_configurable
285For more information on the flags and on napi\_property\_attributes, please read the documentation [here](/node/blob/HEAD/doc/api/n-api.md#napi_property_attributes).
286
287