node-addon-api 2.0.2 → 3.1.0

package/doc/prebuild_tools.md

@@ -5,8 +5,8 @@ In order to install a native add-on it's important to have all the necessary
 dependencies installed and well configured (see the [setup](setup.md) section).
 The end-user will need to compile the add-on when they will do an `npm install`
 and in some cases this could create problems. To avoid the compilation process it's
-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
+possible to distribute the native add-on in pre-built form for different platform
+and architectures. The prebuild tools help to create and distribute the pre-built
 form of a native add-on.
 
 The following list report known tools that are compatible with **N-API**:

package/doc/promises.md

@@ -1,5 +1,7 @@
 # Promise
 
+Class `Napi::Promise` inherits from class [`Napi::Object`][].
+
 The `Napi::Promise` class, along with its `Napi::Promise::Deferred` class, implement the ability to create, resolve, and reject Promise objects.
 
 The basic approach is to create a `Napi::Promise::Deferred` object and return to your caller the value returned by the `Napi::Promise::Deferred::Promise` method. For example:
@@ -72,3 +74,6 @@ void Napi::Promise::Deferred::Reject(napi_value value) const;
 Rejects the Promise object held by the `Napi::Promise::Deferred` object.
 
 * `[in] value`: The N-API primitive value with which to reject the `Napi::Promise`.
+
+
+[`Napi::Object`]: ./object.md

package/doc/property_descriptor.md

@@ -1,6 +1,6 @@
 # Property Descriptor
 
-A [`Napi::Object`](object.md) can be assigned properites via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) functions, which take PropertyDescrptor(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`.
+A [`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`.
 
 ## Example
 
@@ -26,15 +26,9 @@ Void Init(Env env) {
   Object obj = Object::New(env);
 
   // Accessor
-  PropertyDescriptor pd1 = PropertyDescriptor::Accessor(env,
-                                                        obj,
-                                                        "pd1",
-                                                        TestGetter);
-  PropertyDescriptor pd2 = PropertyDescriptor::Accessor(env,
-                                                        obj,
-                                                        "pd2",
-                                                        TestGetter,
-                                                        TestSetter);
+  PropertyDescriptor pd1 = PropertyDescriptor::Accessor<TestGetter>("pd1");
+  PropertyDescriptor pd2 =
+      PropertyDescriptor::Accessor<TestGetter, TestSetter>("pd2");
   // Function
   PropertyDescriptor pd3 = PropertyDescriptor::Function(env,
                                                         "function",
@@ -51,6 +45,26 @@ Void Init(Env env) {
 }
 ```
 
+## Types
+
+### PropertyDescriptor::GetterCallback
+
+```cpp
+typedef Napi::Value (*GetterCallback)(const Napi::CallbackInfo& info);
+```
+
+This is the signature of a getter function to be passed as a template parameter
+to `PropertyDescriptor::Accessor`.
+
+### PropertyDescriptor::SetterCallback
+
+```cpp
+typedef void (*SetterCallback)(const Napi::CallbackInfo& info);
+```
+
+This is the signature of a setter function to be passed as a template parameter
+to `PropertyDescriptor::Accessor`.
+
 ## Methods
 
 ### Constructor
@@ -63,6 +77,47 @@ Napi::PropertyDescriptor::PropertyDescriptor (napi_property_descriptor desc);
 
 ### Accessor
 
+```cpp
+template <Napi::PropertyDescriptor::GetterCallback Getter>
+static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
+                             napi_property_attributes attributes = napi_default,
+                             void* data = nullptr);
+```
+
+* `[template] Getter`: A getter function.
+* `[in] attributes`: Potential attributes for the getter function.
+* `[in] data`: A pointer to data of any type, default is a null pointer.
+
+Returns a PropertyDescriptor that contains a read-only property.
+
+The name of the property can be any of the following types:
+- `const char*`
+- `const std::string &`
+- `napi_value value`
+- `Napi::Name`
+
+```cpp
+template <
+Napi::PropertyDescriptor::GetterCallback Getter,
+Napi::PropertyDescriptor::SetterCallback Setter>
+static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
+                             napi_property_attributes attributes = napi_default,
+                             void* data = nullptr);
+```
+
+* `[template] Getter`: A getter function.
+* `[template] Setter`: A setter function.
+* `[in] attributes`: Potential attributes for the getter function.
+* `[in] data`: A pointer to data of any type, default is a null pointer.
+
+Returns a PropertyDescriptor that contains a read-write property.
+
+The name of the property can be any of the following types:
+- `const char*`
+- `const std::string &`
+- `napi_value value`
+- `Napi::Name`
+
 ```cpp
 static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name,
                 Getter getter,
@@ -95,7 +150,7 @@ static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (
                 void *data = nullptr);
 ```
 
-* `[in] env`: The environemnt in which to create this accessor.
+* `[in] env`: The environment in which to create this accessor.
 * `[in] object`: The object on which the accessor will be defined.
 * `[in] name`: The name used for the getter function.
 * `[in] getter`: A getter function.
@@ -144,7 +199,7 @@ static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (
                 void *data = nullptr);
 ```
 
-* `[in] env`: The environemnt in which to create this accessor.
+* `[in] env`: The environment in which to create this accessor.
 * `[in] object`: The object on which the accessor will be defined.
 * `[in] name`: The name of the getter and setter function.
 * `[in] getter`: The getter function.

package/doc/setup.md

@@ -26,8 +26,7 @@ To use **N-API** in a native module:
   2. Reference this package's include directory and gyp file in `binding.gyp`:
 
 ```gyp
-  'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")"],
-  'dependencies': ["<!(node -p \"require('node-addon-api').gyp\")"],
+  'include_dirs': ["<!(node -p \"require('node-addon-api').include_dir\")"],
 ```
 
   3. Decide whether the package will enable C++ exceptions in the N-API wrapper.

package/doc/string.md

@@ -1,5 +1,7 @@
 # String
 
+Class `Napi::String` inherits from class [`Napi::Name`][].
+
 ## Constructor
 
 ```cpp
@@ -62,7 +64,7 @@ Napi::String::New(napi_env env, const char16_t* value, size_t length);
 
 - `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object.
 - `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of:
-  - `std::string&` - represents an ANSI string.
+  - `std::string&` - represents a UTF8 string.
   - `std::u16string&` - represents a UTF16-LE string.
   - `const char*` - represents a UTF8 string.
   - `const char16_t*` - represents a UTF16-LE string.
@@ -87,3 +89,5 @@ std::u16string Napi::String::Utf16Value() const;
 ```
 
 Returns a UTF-16 encoded C++ string.
+
+[`Napi::Name`]: ./name.md

package/doc/symbol.md

@@ -1,5 +1,7 @@
 # Symbol
 
+Class `Napi::Symbol` inherits from class [`Napi::Name`][].
+
 ## Methods
 
 ### Constructor
@@ -23,7 +25,7 @@ Napi::Symbol::New(napi_env env, napi_value description);
 - `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object.
 - `[in] value`: The C++ primitive which represents the description hint for the `Napi::Symbol`.
   `description` may be any of:
-  - `std::string&` - ANSI string description.
+  - `std::string&` - UTF8 string description.
   - `const char*` - represents a UTF8 string description.
   - `String` - Node addon API String description.
   - `napi_value` - N-API `napi_value` description.
@@ -42,3 +44,5 @@ static Napi::Symbol Napi::Symbol::WellKnown(napi_env env, const std::string& nam
 
 Returns a `Napi::Symbol` representing a well-known `Symbol` from the
 `Symbol` registry.
+
+[`Napi::Name`]: ./name.md

package/doc/threadsafe.md

@@ -0,0 +1,121 @@
+# Thread-safe Functions
+
+JavaScript functions can normally only be called from a native addon's main
+thread. If an addon creates additional threads, then node-addon-api functions
+that require a `Napi::Env`, `Napi::Value`, or `Napi::Reference` must not be
+called from those threads.
+
+When an addon has additional threads and JavaScript functions need to be invoked
+based on the processing completed by those threads, those threads must
+communicate with the addon's main thread so that the main thread can invoke the
+JavaScript function on their behalf. The thread-safe function APIs provide an
+easy way to do this. These APIs provide two types --
+[`Napi::ThreadSafeFunction`](threadsafe_function.md) and
+[`Napi::TypedThreadSafeFunction`](typed_threadsafe_function.md) -- as well as
+APIs to create, destroy, and call objects of this type. The differences between
+the two are subtle and are [highlighted below](#implementation-differences).
+Regardless of which type you choose, the APIs between the two are similar.
+
+`Napi::[Typed]ThreadSafeFunction::New()` creates a persistent reference that
+holds a JavaScript function which can be called from multiple threads. The calls
+happen asynchronously. This means that values with which the JavaScript callback
+is to be called will be placed in a queue, and, for each value in the queue, a
+call will eventually be made to the JavaScript function.
+
+`Napi::[Typed]ThreadSafeFunction` objects are destroyed when every thread which
+uses the object has called `Release()` or has received a return status of
+`napi_closing` in response to a call to `BlockingCall()` or `NonBlockingCall()`.
+The queue is emptied before the `Napi::[Typed]ThreadSafeFunction` is destroyed.
+It is important that `Release()` be the last API call made in conjunction with a
+given `Napi::[Typed]ThreadSafeFunction`, because after the call completes, there
+is no guarantee that the `Napi::[Typed]ThreadSafeFunction` is still allocated.
+For the same reason it is also important that no more use be made of a
+thread-safe function after receiving a return value of `napi_closing` in
+response to a call to `BlockingCall()` or `NonBlockingCall()`. Data associated
+with the `Napi::[Typed]ThreadSafeFunction` can be freed in its `Finalizer`
+callback which was passed to `[Typed]ThreadSafeFunction::New()`.
+
+Once the number of threads making use of a `Napi::[Typed]ThreadSafeFunction`
+reaches zero, no further threads can start making use of it by calling
+`Acquire()`. In fact, all subsequent API calls associated with it, except
+`Release()`, will return an error value of `napi_closing`.
+
+## Implementation Differences
+
+The choice between `Napi::ThreadSafeFunction` and
+`Napi::TypedThreadSafeFunction` depends largely on how you plan to execute your
+native C++ code (the "callback") on the Node.js thread.
+
+### [`Napi::ThreadSafeFunction`](threadsafe_function.md)
+
+This API is designed without N-API 5 native support for [the optional JavaScript
+  function callback feature](https://github.com/nodejs/node/commit/53297e66cb).
+
+This API has some dynamic functionality, in that:
+- The `[Non]BlockingCall()` methods provide a `Napi::Function` parameter as the
+  callback to run when processing the data item on the main thread -- the
+  `CallJs` callback. Since the callback is a parameter, it can be changed for
+  every call.
+- Different C++ data types may be passed with each call of `[Non]BlockingCall()`
+  to match the specific data type as specified in the `CallJs` callback.
+
+Note that this functionality comes with some **additional overhead** and
+situational **memory leaks**:
+- The API acts as a "broker" between the underlying `napi_threadsafe_function`,
+  and dynamically constructs a wrapper for your callback on the heap for every
+  call to `[Non]BlockingCall()`.
+- In acting in this "broker" fashion, the API will call the underlying "make
+  call" N-API method on this packaged item. If the API has determined the
+  thread-safe function is no longer accessible (eg. all threads have released
+  yet there are still items on the queue), **the callback passed to
+  [Non]BlockingCall will not execute**. This means it is impossible to perform
+  clean-up for calls that never execute their `CallJs` callback. **This may lead
+  to memory leaks** if you are dynamically allocating memory.
+- The `CallJs` does not receive the thread-safe function's context as a
+  parameter. In order for the callback to access the context, it must have a
+  reference to either (1) the context directly, or (2) the thread-safe function
+  to call `GetContext()`. Furthermore, the `GetContext()` method is not
+  _type-safe_, as the method returns an object that can be "any-casted", instead
+  of having a static type.
+
+### [`Napi::TypedThreadSafeFunction`](typed_threadsafe_function.md)
+
+The `TypedThreadSafeFunction` class is a new implementation to address the
+drawbacks listed above. The API is designed with N-API 5's support of an
+optional function callback. The API will correctly allow developers to pass
+`std::nullptr` instead of a `const Function&` for the callback function
+specified in `::New`. It also provides helper APIs to _target_ N-API 4 and
+construct a no-op `Function` **or** to target N-API 5 and "construct" a
+`std::nullptr` callback. This allows a single codebase to use the same APIs,
+with just a switch of the `NAPI_VERSION` compile-time constant.
+
+The removal of the dynamic call functionality has the following implications:
+- The API does _not_ act as a "broker" compared to the
+  `Napi::ThreadSafeFunction`. Once Node.js finalizes the thread-safe function,
+  the `CallJs` callback will execute with an empty `Napi::Env` for any remaining
+  items on the queue. This provides the ability to handle any necessary cleanup
+  of the item's data.
+- The callback _does_ receive the context as a parameter, so a call to
+  `GetContext()` is _not_ necessary. This context type is specified as the
+  **first template argument** specified to `::New`, ensuring type safety.
+- The `New()` constructor accepts the `CallJs` callback as the **second type
+  argument**. The callback must be statically defined for the API to access it.
+  This affords the ability to statically pass the context as the correct type
+  across all methods.
+- Only one C++ data type may be specified to every call to `[Non]BlockingCall()`
+  -- the **third template argument** specified to `::New`. Any "dynamic call
+  data" must be implemented by the user.
+
+
+### Usage Suggestions
+
+In summary, it may be best to use `Napi::TypedThreadSafeFunction` if:
+
+- static, compile-time support for targeting N-API 4 or 5+ with an optional
+  JavaScript callback feature is desired;
+- the callback can have `static` storage class and will not change across calls
+  to `[Non]BlockingCall()`;
+- cleanup of items' data is required (eg. deleting dynamically-allocated data
+  that is created at the caller level).
+
+Otherwise, `Napi::ThreadSafeFunction` may be a better choice.

package/doc/threadsafe_function.md

@@ -1,41 +1,10 @@
 # ThreadSafeFunction
 
-JavaScript functions can normally only be called from a native addon's main
-thread. If an addon creates additional threads, then node-addon-api functions
-that require a `Napi::Env`, `Napi::Value`, or `Napi::Reference` must not be
-called from those threads.
-
-When an addon has additional threads and JavaScript functions need to be invoked
-based on the processing completed by those threads, those threads must
-communicate with the addon's main thread so that the main thread can invoke the
-JavaScript function on their behalf. The thread-safe function APIs provide an
-easy way to do this.
-
-These APIs provide the type `Napi::ThreadSafeFunction` as well as APIs to
-create, destroy, and call objects of this type.
-`Napi::ThreadSafeFunction::New()` creates a persistent reference that holds a
-JavaScript function which can be called from multiple threads. The calls happen
-asynchronously. This means that values with which the JavaScript callback is to
-be called will be placed in a queue, and, for each value in the queue, a call
-will eventually be made to the JavaScript function.
-
-`Napi::ThreadSafeFunction` objects are destroyed when every thread which uses
-the object has called `Release()` or has received a return status of
-`napi_closing` in response to a call to `BlockingCall()` or `NonBlockingCall()`.
-The queue is emptied before the `Napi::ThreadSafeFunction` is destroyed. It is
-important that `Release()` be the last API call made in conjunction with a given
-`Napi::ThreadSafeFunction`, because after the call completes, there is no
-guarantee that the `Napi::ThreadSafeFunction` is still allocated. For the same
-reason it is also important that no more use be made of a thread-safe function
-after receiving a return value of `napi_closing` in response to a call to
-`BlockingCall()` or `NonBlockingCall()`. Data associated with the
-`Napi::ThreadSafeFunction` can be freed in its `Finalizer` callback which was
-passed to `ThreadSafeFunction::New()`.
-
-Once the number of threads making use of a `Napi::ThreadSafeFunction` reaches
-zero, no further threads can start making use of it by calling `Acquire()`. In
-fact, all subsequent API calls associated with it, except `Release()`, will
-return an error value of `napi_closing`.
+The `Napi::ThreadSafeFunction` type provides APIs for threads to communicate
+with the addon's main thread to invoke JavaScript functions on their behalf.
+Documentation can be found for an [overview of the API](threadsafe.md), as well
+as [differences between the two thread-safe function
+APIs](threadsafe.md#implementation-differences).
 
 ## Methods
 
@@ -92,7 +61,8 @@ New(napi_env env,
 - `maxQueueSize`: Maximum size of the queue. `0` for no limit.
 - `initialThreadCount`: The initial number of threads, including the main
   thread, which will be making use of this function.
-- `[optional] context`: Data to attach to the resulting `ThreadSafeFunction`.
+- `[optional] context`: Data to attach to the resulting `ThreadSafeFunction`. It
+  can be retreived by calling `GetContext()`.
 - `[optional] finalizeCallback`: Function to call when the `ThreadSafeFunction`
   is being destroyed.  This callback will be invoked on the main thread when the
   thread-safe function is about to be destroyed. It receives the context and the
@@ -101,8 +71,8 @@ New(napi_env env,
   `uv_thread_join()`. It is important that, aside from the main loop thread,
   there be no threads left using the thread-safe function after the finalize
   callback completes. Must implement `void operator()(Env env, DataType* data,
-  Context* hint)`, skipping `data` or `hint` if they are not provided.
-  Can be retreived via `GetContext()`.
+  ContextType* hint)`, skipping `data` or `hint` if they are not provided. Can
+  be retrieved via `GetContext()`.
 - `[optional] data`: Data to be passed to `finalizeCallback`.
 
 Returns a non-empty `Napi::ThreadSafeFunction` instance.
@@ -110,7 +80,7 @@ Returns a non-empty `Napi::ThreadSafeFunction` instance.
 ### Acquire
 
 Add a thread to this thread-safe function object, indicating that a new thread
-will start making use of the thread-safe function. 
+will start making use of the thread-safe function.
 
 ```cpp
 napi_status Napi::ThreadSafeFunction::Acquire()
@@ -118,7 +88,7 @@ napi_status Napi::ThreadSafeFunction::Acquire()
 
 Returns one of:
 - `napi_ok`: The thread has successfully acquired the thread-safe function
-for its use. 
+for its use.
 - `napi_closing`: The thread-safe function has been marked as closing via a
 previous call to `Abort()`.
 
@@ -136,7 +106,7 @@ napi_status Napi::ThreadSafeFunction::Release()
 Returns one of:
 - `napi_ok`: The thread-safe function has been successfully released.
 - `napi_invalid_arg`: The thread-safe function's thread-count is zero.
-- `napi_generic_failure`: A generic error occurred when attemping to release
+- `napi_generic_failure`: A generic error occurred when attempting to release
 the thread-safe function.
 
 ### Abort
@@ -158,7 +128,7 @@ napi_status Napi::ThreadSafeFunction::Abort()
 Returns one of:
 - `napi_ok`: The thread-safe function has been successfully aborted.
 - `napi_invalid_arg`: The thread-safe function's thread-count is zero.
-- `napi_generic_failure`: A generic error occurred when attemping to abort
+- `napi_generic_failure`: A generic error occurred when attempting to abort
 the thread-safe function.
 
 ### BlockingCall / NonBlockingCall
@@ -210,7 +180,7 @@ Returns one of:
 - `napi_closing`: The thread-safe function is aborted and cannot accept more
   calls.
 - `napi_invalid_arg`: The thread-safe function is closed.
-- `napi_generic_failure`: A generic error occurred when attemping to add to the
+- `napi_generic_failure`: A generic error occurred when attempting to add to the
   queue.
 
 ## Example
@@ -258,10 +228,10 @@ Value Start( const CallbackInfo& info )
   // Create a native thread
   nativeThread = std::thread( [count] {
     auto callback = []( Napi::Env env, Function jsCallback, int* value ) {
-      // Transform native data into JS data, passing it to the provided 
+      // Transform native data into JS data, passing it to the provided
       // `jsCallback` -- the TSFN's JavaScript function.
       jsCallback.Call( {Number::New( env, *value )} );
-      
+
       // We're finished with the data.
       delete value;
     };

package/doc/typed_array.md

@@ -1,5 +1,7 @@
 # TypedArray
 
+Class `Napi::TypedArray` inherits from class [`Napi::Object`][].
+
 The `Napi::TypedArray` class corresponds to the
 [JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
 class.
@@ -72,3 +74,5 @@ size_t Napi::TypedArray::ByteLength() const;
 ```
 
 Returns the length of the array, in bytes.
+
+[`Napi::Object`]: ./object.md

package/doc/typed_array_of.md

@@ -1,5 +1,7 @@
 # TypedArrayOf
 
+Class `Napi::TypedArrayOf<T>` inherits from class [`Napi::TypedArray`][].
+
 The `Napi::TypedArrayOf` class corresponds to the various
 [JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)
 classes.
@@ -131,3 +133,5 @@ const T* Napi::TypedArrayOf::Data() const
 
 Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the
 start of the array.
+
+[`Napi::TypedArray`]: ./typed_array.md