node-addon-api 1.7.2 → 3.0.0

package/doc/property_descriptor.md

@@ -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,

package/doc/setup.md

@@ -27,7 +27,6 @@ To use **N-API** in a native module:
 
 ```gyp
   'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")"],
-  'dependencies': ["<!(node -p \"require('node-addon-api').gyp\")"],
 ```
 
   3. Decide whether the package will enable C++ exceptions in the N-API wrapper.

package/doc/string.md

@@ -62,7 +62,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.

package/doc/symbol.md

@@ -23,7 +23,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.

package/doc/threadsafe_function.md

@@ -58,7 +58,10 @@ Napi::ThreadSafeFunction::ThreadSafeFunction(napi_threadsafe_function tsfn);
 - `tsfn`: The `napi_threadsafe_function` which is a handle for an existing
   thread-safe function.
 
-Returns a non-empty `Napi::ThreadSafeFunction` instance.
+Returns a non-empty `Napi::ThreadSafeFunction` instance. When using this
+constructor, only use the `Blocking(void*)` / `NonBlocking(void*)` overloads;
+the `Callback` and templated `data*` overloads should _not_ be used. See below
+for additional details.
 
 ### New
 
@@ -171,6 +174,9 @@ There are several overloaded implementations of `BlockingCall()` and
 `NonBlockingCall()` for use with optional parameters: skip the optional
 parameter for that specific overload.
 
+**These specific function overloads should only be used on a `ThreadSafeFunction`
+created via `ThreadSafeFunction::New`.**
+
 ```cpp
 napi_status Napi::ThreadSafeFunction::BlockingCall(DataType* data, Callback callback) const
 
@@ -186,6 +192,17 @@ napi_status Napi::ThreadSafeFunction::NonBlockingCall(DataType* data, Callback c
   necessary to call into JavaScript via `MakeCallback()` because N-API runs
   `callback` in a context appropriate for callbacks.
 
+**These specific function overloads should only be used on a `ThreadSafeFunction`
+created via `ThreadSafeFunction(napi_threadsafe_function)`.**
+
+```cpp
+napi_status Napi::ThreadSafeFunction::BlockingCall(void* data) const
+
+napi_status Napi::ThreadSafeFunction::NonBlockingCall(void* data) const
+```
+- `data`: Data to pass to `call_js_cb` specified when creating the thread-safe
+  function via `napi_create_threadsafe_function`.
+
 Returns one of:
 - `napi_ok`: The call was successfully added to the queue.
 - `napi_queue_full`: The queue was full when trying to call in a non-blocking

package/doc/value.md

@@ -6,10 +6,11 @@ Value is a the base class upon which other JavaScript values such as Number, Boo
 
 The following classes inherit, either directly or indirectly, from `Napi::Value`:
 
-- [`Napi::Array`](array.md)
+- [`Napi::Array`](basic_types.md#array)
 - [`Napi::ArrayBuffer`](array_buffer.md)
 - [`Napi::Boolean`](boolean.md)
 - [`Napi::Buffer`](buffer.md)
+- [`Napi::Date`](date.md)
 - [`Napi::External`](external.md)
 - [`Napi::Function`](function.md)
 - [`Napi::Name`](name.md)
@@ -226,6 +227,14 @@ bool Napi::Value::IsBuffer() const;
 
 Returns a `bool` indicating if this `Napi::Value` is a Node buffer.
 
+### IsDate
+
+```cpp
+bool Napi::Value::IsDate() const;
+```
+
+Returns a `bool` indicating if this `Napi::Value` is a JavaScript date.
+
 ### As
 
 ```cpp

package/except.gypi

@@ -0,0 +1,16 @@
+{
+  'defines': [ 'NAPI_CPP_EXCEPTIONS' ],
+  'cflags!': [ '-fno-exceptions' ],
+  'cflags_cc!': [ '-fno-exceptions' ],
+  'msvs_settings': {
+    'VCCLCompilerTool': {
+      'ExceptionHandling': 1,
+      'EnablePREfast': 'true',
+    },
+  },
+  'xcode_settings': {
+    'CLANG_CXX_LIBRARY': 'libc++',
+    'MACOSX_DEPLOYMENT_TARGET': '10.7',
+    'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
+  },
+}

package/index.js

@@ -1,45 +1,8 @@
-var path = require('path');
-
-var versionArray = process.version
-  .substr(1)
-  .replace(/-.*$/, '')
-  .split('.')
-  .map(function(item) {
-    return +item;
-  });
-
-// TODO: Check if the main node semantic version is within multiple ranges,
-// or detect presence of built-in N-API by some other mechanism TBD.
-
-// We know which version of Node.js first shipped the incarnation of the API
-// available in *this* package. So, if we find that the Node.js version is below
-// that, we indicate that the API is missing from Node.js.
-var isNodeApiBuiltin = (
-  versionArray[0] > 8 ||
-  (versionArray[0] == 8 && versionArray[1] >= 6) ||
-  (versionArray[0] == 6 && versionArray[1] >= 15) ||
-  (versionArray[0] == 6 && versionArray[1] >= 14 && versionArray[2] >= 2));
-
-// The flag is not needed when the Node version is not 8, nor if the API is
-// built-in, because we removed the flag at the same time as creating the final
-// incarnation of the built-in API.
-var needsFlag = (!isNodeApiBuiltin && versionArray[0] == 8);
-
-var include = [__dirname];
-var gyp = path.join(__dirname, 'src', 'node_api.gyp');
-
-if (isNodeApiBuiltin) {
-  gyp += ':nothing';
-} else {
-  gyp += ':node-api';
-  include.unshift(path.join(__dirname, 'external-napi'));
-}
+const path = require('path');
 
 module.exports = {
-  include: include.map(function(item) {
-    return '"' + item + '"';
-  }).join(' '),
-  gyp: gyp,
-  isNodeApiBuiltin: isNodeApiBuiltin,
-  needsFlag: needsFlag
+  include: `"${__dirname}"`,
+  gyp: path.join(__dirname, 'node_api.gyp:nothing'),
+  isNodeApiBuiltin: true,
+  needsFlag: false
 };