node-addon-api 2.0.2 → 3.0.0

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
@@ -289,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
@@ -342,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.
@@ -430,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
@@ -482,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/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/value.md

@@ -6,7 +6,7 @@ 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)

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
 };