node-addon-api 1.7.2 → 3.0.0

package/doc/date.md

@@ -0,0 +1,68 @@
+# Date
+
+`Napi::Date` class is a representation of the JavaScript `Date` object. The
+`Napi::Date` class inherits its behavior from `Napi::Value` class
+(for more info see [`Napi::Value`](value.md))
+
+## Methods
+
+### Constructor
+
+Creates a new _empty_ instance of a `Napi::Date` object.
+
+```cpp
+Napi::Date::Date();
+```
+
+Creates a new _non-empty_ instance of a `Napi::Date` object.
+
+```cpp
+Napi::Date::Date(napi_env env, napi_value value);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::Date` object.
+ - `[in] value`: The `napi_value` which is a handle for a JavaScript `Date`.
+
+### New
+
+Creates a new instance of a `Napi::Date` object.
+
+```cpp
+static Napi::Date Napi::Date::New(Napi::Env env, double value);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::Date` object.
+ - `[in] value`: The time value the JavaScript `Date` will contain represented
+  as the number of milliseconds since 1 January 1970 00:00:00 UTC.
+
+Returns a new instance of `Napi::Date` object.
+
+### ValueOf
+
+```cpp
+double Napi::Date::ValueOf() const;
+```
+
+Returns the time value as `double` primitive represented as the number of
+ milliseconds since 1 January 1970 00:00:00 UTC.
+
+## Operators
+
+### operator double
+
+Converts a `Napi::Date` value to a `double` primitive.
+
+```cpp
+Napi::Date::operator double() const;
+```
+
+### Example
+
+The following shows an example of casting a `Napi::Date` value to a `double`
+ primitive.
+
+```cpp
+double operatorVal = Napi::Date::New(Env(), 0); // Napi::Date to double
+// or
+auto instanceVal = info[0].As<Napi::Date>().ValueOf();
+```

package/doc/env.md

@@ -61,3 +61,17 @@ Napi::Error Napi::Env::GetAndClearPendingException();
 ```
 
 Returns an `Napi::Error` object representing the environment's pending exception, if any.
+
+### RunScript
+
+```cpp
+Napi::Value Napi::Env::RunScript(____ script);
+```
+- `[in] script`: A string containing JavaScript code to execute.
+
+Runs JavaScript code contained in a string and returns its result.
+
+The `script` can be any of the following types:
+- [`Napi::String`](string.md)
+- `const char *`
+- `const std::string &`

package/doc/function.md

@@ -11,6 +11,10 @@ functions that were created in JavaScript and passed to the native add-on.
 The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info
 see: [`Napi::Object`](object.md)).
 
+> For callbacks that will be called with asynchronous events from a
+> non-JavaScript thread, please refer to [`Napi::ThreadSafeFunction`][] for more
+> examples.
+
 ## Example
 
 ```cpp
@@ -25,7 +29,7 @@ Value Fn(const CallbackInfo& info) {
 }
 
 Object Init(Env env, Object exports) {
-  exports.Set(String::New(env, "fn"), Function::New(env, Fn));
+  exports.Set(String::New(env, "fn"), Function::New<Fn>(env));
 }
 
 NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
@@ -47,6 +51,27 @@ and in general in situations which don't have an existing JavaScript function on
 the stack. The `Call` method is used when there is already a JavaScript function
 on the stack (for example when running a native method called from JavaScript).
 
+## Type definitions
+
+### Napi::Function::VoidCallback
+
+This is the type describing a callback returning `void` that will be invoked
+from JavaScript.
+
+```cpp
+typedef void (*VoidCallback)(const Napi::CallbackInfo& info);
+```
+
+### Napi::Function::Callback
+
+This is the type describing a callback returning a value that will be invoked
+from JavaScript.
+
+
+```cpp
+typedef Value (*Callback)(const Napi::CallbackInfo& info);
+```
+
 ## Methods
 
 ### Constructor
@@ -74,6 +99,86 @@ Returns a non-empty `Napi::Function` instance.
 
 Creates an instance of a `Napi::Function` object.
 
+```cpp
+template <Napi::VoidCallback cb>
+static Napi::Function New(napi_env env,
+                          const char* utf8name = nullptr,
+                          void* data = nullptr);
+```
+
+- `[template] cb`: The native function to invoke when the JavaScript function is
+invoked.
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
+- `[in] utf8name`: Null-terminated string to be used as the name of the function.
+- `[in] data`: User-provided data context. This will be passed back into the
+function when invoked later.
+
+Returns an instance of a `Napi::Function` object.
+
+### New
+
+Creates an instance of a `Napi::Function` object.
+
+```cpp
+template <Napi::Callback cb>
+static Napi::Function New(napi_env env,
+                          const char* utf8name = nullptr,
+                          void* data = nullptr);
+```
+
+- `[template] cb`: The native function to invoke when the JavaScript function is
+invoked.
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
+- `[in] utf8name`: Null-terminated string to be used as the name of the function.
+- `[in] data`: User-provided data context. This will be passed back into the
+function when invoked later.
+
+Returns an instance of a `Napi::Function` object.
+
+### New
+
+Creates an instance of a `Napi::Function` object.
+
+```cpp
+template <Napi::VoidCallback cb>
+static Napi::Function New(napi_env env,
+                          const std::string& utf8name,
+                          void* data = nullptr);
+```
+
+- `[template] cb`: The native function to invoke when the JavaScript function is
+invoked.
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
+- `[in] utf8name`: String to be used as the name of the function.
+- `[in] data`: User-provided data context. This will be passed back into the
+function when invoked later.
+
+Returns an instance of a `Napi::Function` object.
+
+### New
+
+Creates an instance of a `Napi::Function` object.
+
+```cpp
+template <Napi::Callback cb>
+static Napi::Function New(napi_env env,
+                          const std::string& utf8name,
+                          void* data = nullptr);
+```
+
+- `[template] cb`: The native function to invoke when the JavaScript function is
+invoked.
+- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
+- `[in] utf8name`: String to be used as the name of the function.
+- `[in] data`: User-provided data context. This will be passed back into the
+function when invoked later.
+
+Returns an instance of a `Napi::Function` object.
+
+### New
+
+Creates an instance of a `Napi::Function` object.
+
 ```cpp
 template <typename Callable>
 static Napi::Function Napi::Function::New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr);
@@ -292,3 +397,5 @@ Napi::Value Napi::Function::operator ()(const std::initializer_list<napi_value>&
 - `[in] args`: Initializer list of JavaScript values as `napi_value`.
 
 Returns a `Napi::Value` representing the JavaScript value returned by the function.
+
+[`Napi::ThreadSafeFunction`]: ./threadsafe_function.md

package/doc/object.md

@@ -2,7 +2,7 @@
 
 The `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:
 
-- [`Napi::Value`](value.md) and extends [`Napi::Array`](array.md)
+- [`Napi::Value`](value.md) which is extended by [`Napi::Array`](basic_types.md#array)
 - [`Napi::ArrayBuffer`](array_buffer.md)
 - [`Napi::Buffer<T>`](buffer.md)
 - [`Napi::Function`](function.md)
@@ -101,6 +101,22 @@ While the value must be any of the following types:
 - `bool`
 - `double`
 
+### Delete()
+
+```cpp
+bool Napi::Object::Delete(____ key);
+```
+- `[in] key`: The name of the property to delete.
+
+Deletes the property associated with the given key. Returns `true` if the property was deleted.
+
+The `key` can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char *`
+- `const std::string &`
+- `uint32_t`
+
 ### Get()
 
 ```cpp
@@ -137,6 +153,63 @@ Returns a `bool` that is true if the `Napi::Object` is an instance created by th
 
 Note: This is equivalent to the JavaScript instanceof operator.
 
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T>
+inline void AddFinalizer(Finalizer finalizeCallback, T* data);
+```
+
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+- `[in] data`: The data to associate with the object.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. `finalizeCallback`
+has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data);
+```
+where `data` is the pointer that was passed into the call to `AddFinalizer()`.
+
+### AddFinalizer()
+```cpp
+template <typename Finalizer, typename T, typename Hint>
+inline void AddFinalizer(Finalizer finalizeCallback,
+                         T* data,
+                         Hint* finalizeHint);
+```
+
+- `[in] data`: The data to associate with the object.
+- `[in] finalizeCallback`: The function to call when the object is garbage-collected.
+
+Associates `data` with the object, calling `finalizeCallback` when the object is garbage-collected. An additional hint
+may be given. It will also be passed to `finalizeCallback`, which has the signature
+```cpp
+void finalizeCallback(Napi::Env env, T* data, Hint* hint);
+```
+where `data` and `hint` are the pointers that were passed into the call to `AddFinalizer()`.
+
+### GetPropertyNames()
+```cpp
+Napi::Array Napi::Object::GetPropertyNames() const;
+```
+
+Returns the names of the enumerable properties of the object as a [`Napi::Array`](basic_types.md#array) of strings.
+The properties whose key is a `Symbol` will not be included.
+
+### HasOwnProperty()
+```cpp
+bool Napi::Object::HasOwnProperty(____ key); const
+```
+- `[in] key` The name of the property to check.
+
+Returns a `bool` that is *true* if the object has an own property named `key` and *false* otherwise.
+
+The key can be any of the following types:
+- `napi_value`
+- [`Napi::Value`](value.md)
+- `const char*`
+- `const std::string&`
+- `uint32_t`
+
 ### DefineProperty()
 
 ```cpp

package/doc/object_lifetime_management.md

@@ -69,7 +69,7 @@ for (int i = 0; i < LOOP_MAX; i++) {
   Napi::HandleScope scope(info.Env());
   std::string name = std::string("inner-scope") + std::to_string(i);
   Napi::Value newValue = Napi::String::New(info.Env(), name.c_str());
-  // do something with neValue
+  // do something with newValue
 };
 ```
 

package/doc/object_wrap.md

@@ -34,8 +34,8 @@ class Example : public Napi::ObjectWrap<Example> {
 Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
     // This method is used to hook the accessor and method callbacks
     Napi::Function func = DefineClass(env, "Example", {
-        InstanceMethod("GetValue", &Example::GetValue),
-        InstanceMethod("SetValue", &Example::SetValue)
+        InstanceMethod<&Example::GetValue>("GetValue"),
+        InstanceMethod<&Example::SetValue>("SetValue")
     });
 
     // Create a peristent reference to the class constructor. This will allow
@@ -161,7 +161,7 @@ static Napi::Function Napi::ObjectWrap::DefineClass(Napi::Env env,
 JavaScript constructor function.
 * `[in] properties`: Initializer list of class property descriptor describing
 static and instance properties and methods of the class.
-See: [`Class propertry and descriptor`](class_property_descriptor.md).
+See: [`Class property and descriptor`](class_property_descriptor.md).
 * `[in] data`: User-provided data passed to the constructor callback as `data`
 property of the `Napi::CallbackInfo`.
 
@@ -184,12 +184,23 @@ static Napi::Function Napi::ObjectWrap::DefineClass(Napi::Env env,
 JavaScript constructor function.
 * `[in] properties`: Vector of class property descriptor describing static and
 instance properties and methods of the class.
-See: [`Class propertry and descriptor`](class_property_descriptor.md).
+See: [`Class property and descriptor`](class_property_descriptor.md).
 * `[in] data`: User-provided data passed to the constructor callback as `data`
 property of the `Napi::CallbackInfo`.
 
 Returns a `Napi::Function` representing the constructor function for the class.
 
+### Finalize
+
+Provides an opportunity to run cleanup code that requires access to the `Napi::Env`
+before the wrapped native object instance is freed.  Override to implement.
+
+```cpp
+virtual void Finalize(Napi::Env env);
+```
+
+- `[in] env`: `Napi::Env`.
+
 ### StaticMethod
 
 Creates property descriptor that represents a static method of a JavaScript class.
@@ -278,6 +289,93 @@ One or more of `napi_property_attributes`.
 Returns `Napi::PropertyDescriptor` object that represents a static method of a
 JavaScript class.
 
+### StaticMethod
+
+Creates property descriptor that represents a static method of a JavaScript class.
+
+```cpp
+template <StaticVoidMethodCallback method>
+static Napi::PropertyDescriptor Napi::ObjectWrap::StaticMethod(const char* utf8name,
+                                       napi_property_attributes attributes = napi_default,
+                                       void* data = nullptr);
+```
+
+- `[in] method`: The native function that represents a static method of a
+JavaScript class. This function returns nothing.
+- `[in] utf8name`: Null-terminated string that represents the name of a static
+method for the class.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into method when it is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents the static method of a
+JavaScript class.
+
+### StaticMethod
+
+Creates property descriptor that represents a static method of a JavaScript class.
+
+```cpp
+template <StaticMethodCallback method>
+static Napi::PropertyDescriptor Napi::ObjectWrap::StaticMethod(const char* utf8name,
+                                       napi_property_attributes attributes = napi_default,
+                                       void* data = nullptr);
+```
+
+- `[in] method`: The native function that represents a static method of a
+JavaScript class.
+- `[in] utf8name`: Null-terminated string that represents the name of a static
+method for the class.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into method when it is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents a static method of a
+JavaScript class.
+
+### StaticMethod
+
+Creates property descriptor that represents a static method of a JavaScript class.
+
+```cpp
+template <StaticVoidMethodCallback method>
+static Napi::PropertyDescriptor Napi::ObjectWrap::StaticMethod(Symbol name,
+                                       napi_property_attributes attributes = napi_default,
+                                       void* data = nullptr);
+```
+
+- `[in] method`: The native function that represents a static method of a
+JavaScript class.
+- `[in] name`: Napi:Symbol that represents the name of a static
+method for the class.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into method when it is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents the static method of a
+JavaScript class.
+
+### StaticMethod
+
+Creates property descriptor that represents a static method of a JavaScript class.
+
+```cpp
+template <StaticMethodCallback method>
+static Napi::PropertyDescriptor Napi::ObjectWrap::StaticMethod(Symbol name,
+                                       napi_property_attributes attributes = napi_default,
+                                       void* data = nullptr);
+```
+
+- `[in] method`: The native function that represents a static method of a
+JavaScript class.
+- `[in] name`: Napi:Symbol that represents the name of a static.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into method when it is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents a static method of a
+JavaScript class.
+
 ### StaticAccessor
 
 Creates property descriptor that represents a static accessor property of a
@@ -331,6 +429,57 @@ is invoked.
 Returns `Napi::PropertyDescriptor` object that represents a static accessor
 property of a JavaScript class.
 
+### StaticAccessor
+
+Creates property descriptor that represents a static accessor property of a
+JavaScript class.
+
+```cpp
+template <StaticGetterCallback getter, StaticSetterCallback setter=nullptr>
+static Napi::PropertyDescriptor Napi::ObjectWrap::StaticAccessor(const char* utf8name,
+                                         napi_property_attributes attributes = napi_default,
+                                         void* data = nullptr);
+```
+
+- `[in] getter`: The native function to call when a get access to the property of
+a JavaScript class is performed.
+- `[in] setter`: The native function to call when a set access to the property of
+a JavaScript class is performed.
+- `[in] utf8name`: Null-terminated string that represents the name of a static
+accessor property for the class.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into getter or setter when
+is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents a static accessor
+property of a JavaScript class.
+
+### StaticAccessor
+
+Creates property descriptor that represents a static accessor property of a
+JavaScript class.
+
+```cpp
+template <StaticGetterCallback getter, StaticSetterCallback setter=nullptr>
+static Napi::PropertyDescriptor Napi::ObjectWrap::StaticAccessor(Symbol name,
+                                         napi_property_attributes attributes = napi_default,
+                                         void* data = nullptr);
+```
+
+- `[in] getter`: The native function to call when a get access to the property of
+a JavaScript class is performed.
+- `[in] setter`: The native function to call when a set access to the property of
+a JavaScript class is performed.
+- `[in] name`: Napi:Symbol that represents the name of a static accessor.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into getter or setter when
+is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents a static accessor
+property of a JavaScript class.
+
 ### InstanceMethod
 
 Creates property descriptor that represents an instance method of a JavaScript class.
@@ -419,6 +568,94 @@ One or more of `napi_property_attributes`.
 Returns `Napi::PropertyDescriptor` object that represents an instance method of a
 JavaScript class.
 
+### InstanceMethod
+
+Creates property descriptor that represents an instance method of a JavaScript class.
+
+```cpp
+template <InstanceVoidMethodCallback method>
+static Napi::PropertyDescriptor Napi::ObjectWrap::InstanceMethod(const char* utf8name,
+                                         napi_property_attributes attributes = napi_default,
+                                         void* data = nullptr);
+```
+
+- `[in] method`: The native function that represents an instance method of a
+JavaScript class.
+- `[in] utf8name`: Null-terminated string that represents the name of an instance
+method for the class.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into method when it is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents an instance method of a
+JavaScript class.
+
+### InstanceMethod
+
+Creates property descriptor that represents an instance method of a JavaScript class.
+
+```cpp
+template <InstanceMethodCallback method>
+static Napi::PropertyDescriptor Napi::ObjectWrap::InstanceMethod(const char* utf8name,
+                                         napi_property_attributes attributes = napi_default,
+                                         void* data = nullptr);
+```
+
+- `[in] method`: The native function that represents an instance method of a
+JavaScript class.
+- `[in] utf8name`: Null-terminated string that represents the name of an instance
+method for the class.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into method when it is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents an instance method of a
+JavaScript class.
+
+### InstanceMethod
+
+Creates property descriptor that represents an instance method of a JavaScript class.
+
+```cpp
+template <InstanceVoidMethodCallback method>
+static Napi::PropertyDescriptor Napi::ObjectWrap::InstanceMethod(Napi::Symbol name,
+                                         napi_property_attributes attributes = napi_default,
+                                         void* data = nullptr);
+```
+
+- `[in] method`: The native function that represents an instance method of a
+JavaScript class.
+- `[in] name`: The `Napi::Symbol` object whose value is used to identify the
+instance method for the class.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into method when it is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents an instance method of a
+JavaScript class.
+
+### InstanceMethod
+
+Creates property descriptor that represents an instance method of a JavaScript class.
+
+```cpp
+template <InstanceMethodCallback method>
+static Napi::PropertyDescriptor Napi::ObjectWrap::InstanceMethod(Napi::Symbol name,
+                                         napi_property_attributes attributes = napi_default,
+                                         void* data = nullptr);
+```
+
+- `[in] method`: The native function that represents an instance method of a
+JavaScript class.
+- `[in] name`: The `Napi::Symbol` object whose value is used to identify the
+instance method for the class.
+- `[in] attributes`: The attributes associated with a particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into method when it is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents an instance method of a
+JavaScript class.
+
 ### InstanceAccessor
 
 Creates property descriptor that represents an instance accessor property of a
@@ -471,6 +708,56 @@ One or more of `napi_property_attributes`.
 Returns `Napi::PropertyDescriptor` object that represents an instance accessor
 property of a JavaScript class.
 
+### InstanceAccessor
+
+Creates property descriptor that represents an instance accessor property of a
+JavaScript class.
+
+```cpp
+template <InstanceGetterCallback getter, InstanceSetterCallback setter=nullptr>
+static Napi::PropertyDescriptor Napi::ObjectWrap::InstanceAccessor(const char* utf8name,
+                                           napi_property_attributes attributes = napi_default,
+                                           void* data = nullptr);
+```
+
+- `[in] getter`: The native function to call when a get access to the property of
+a JavaScript class is performed.
+- `[in] setter`: The native function to call when a set access to the property of
+a JavaScript class is performed.
+- `[in] utf8name`: Null-terminated string that represents the name of an instance
+accessor property for the class.
+- `[in] attributes`: The attributes associated with the particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into getter or setter when this is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents an instance accessor
+property of a JavaScript class.
+
+### InstanceAccessor
+
+Creates property descriptor that represents an instance accessor property of a
+JavaScript class.
+
+```cpp
+template <InstanceGetterCallback getter, InstanceSetterCallback setter=nullptr>
+static Napi::PropertyDescriptor Napi::ObjectWrap::InstanceAccessor(Symbol name,
+                                           napi_property_attributes attributes = napi_default,
+                                           void* data = nullptr);
+```
+
+- `[in] getter`: The native function to call when a get access to the property of
+a JavaScript class is performed.
+- `[in] setter`: The native function to call when a set access to the property of
+a JavaScript class is performed.
+- `[in] name`: The `Napi::Symbol` object whose value is used to identify the
+instance accessor.
+- `[in] attributes`: The attributes associated with the particular property.
+One or more of `napi_property_attributes`.
+- `[in] data`: User-provided data passed into getter or setter when this is invoked.
+
+Returns `Napi::PropertyDescriptor` object that represents an instance accessor
+property of a JavaScript class.
+
 ### StaticValue
 
 Creates property descriptor that represents an static value property of a

package/doc/prebuild_tools.md

@@ -9,7 +9,7 @@ possible to ditribute the native add-on in pre-built form for different platform
 and architectures. The prebuild tools help to create and distrubute the pre-built
 form of a native add-on.
 
-The following list report two of the tools that are compatible with **N-API**:
+The following list report known tools that are compatible with **N-API**:
 
 - **[node-pre-gyp](https://www.npmjs.com/package/node-pre-gyp)**
 - **[prebuild](https://www.npmjs.com/package/prebuild)**