node-addon-api - npm Package Compare versions

Comparing version 1.6.3 to 1.7.0

CHANGELOG.md

 # node-addon-api Changelog
 
+## 2019-07-23 Version 1.7.0, @NickNaso
+
+### Notable changes:
+
+#### API
+
+- Added `Napi::ThreadSafeFunction` api.
+- Added `Napi::AsyncWorker::GetResult()` method to `Napi::AsyncWorker`.
+- Added `Napi::AsyncWorker::Destroy()()` method to `Napi::AsyncWorker`.
+- Use full namespace on macros that create the errors.
+
+#### Documentation
+
+- Added documentation about contribution philosophy.
+- Added documentation for `Napi::ThreadSafeFunction`.
+- Some minor corrections all over the documentation.
+
+#### TEST
+
+- Added test case for bool operator.
+- Fixed test case for `Napi::ObjectWrap`.
+
+### Commmits
+
+* [[`717c9ab163`](https://github.com/nodejs/node-addon-api/commit/717c9ab163)] - **AsyncWorker**: add GetResult() method (Kevin Eady) [#512](https://github.com/nodejs/node-addon-api/pull/512)
+* [[`d9d991bbc9`](https://github.com/nodejs/node-addon-api/commit/d9d991bbc9)] - **doc**: add ThreadSafeFunction to main README (#513) (Kevin Eady) [#513](https://github.com/nodejs/node-addon-api/pull/513)
+* [[`ac6000d0fd`](https://github.com/nodejs/node-addon-api/commit/ac6000d0fd)] - **doc**: fix minor typo (Yohei Kishimoto) [#510](https://github.com/nodejs/node-addon-api/pull/510)
+* [[`e9fa1eaa86`](https://github.com/nodejs/node-addon-api/commit/e9fa1eaa86)] - **doc**: document ThreadSafeFunction (#494) (Kevin Eady) [#494](https://github.com/nodejs/node-addon-api/pull/494)
+* [[`cab3b1e2a2`](https://github.com/nodejs/node-addon-api/commit/cab3b1e2a2)] - **doc**: ClassPropertyDescriptor example (Ross Weir) [#507](https://github.com/nodejs/node-addon-api/pull/507)
+* [[`c32d7dbdcf`](https://github.com/nodejs/node-addon-api/commit/c32d7dbdcf)] - **macros**: create errors fully namespaced (Gabriel Schulhof) [#506](https://github.com/nodejs/node-addon-api/pull/506)
+* [[`0a90df2fcb`](https://github.com/nodejs/node-addon-api/commit/0a90df2fcb)] - Implement ThreadSafeFunction class (Jinho Bang)
+* [[`1fb540eeb5`](https://github.com/nodejs/node-addon-api/commit/1fb540eeb5)] - Use curly brackets to include node\_api.h (NickNaso) [#493](https://github.com/nodejs/node-addon-api/pull/493)
+* [[`b2b08122ea`](https://github.com/nodejs/node-addon-api/commit/b2b08122ea)] - **AsyncWorker**: make callback optional (Kevin Eady) [#489](https://github.com/nodejs/node-addon-api/pull/489)
+* [[`a0cac77c82`](https://github.com/nodejs/node-addon-api/commit/a0cac77c82)] - Added test for bool operator (NickNaso) [#490](https://github.com/nodejs/node-addon-api/pull/490)
+* [[`ab7d8fcc48`](https://github.com/nodejs/node-addon-api/commit/ab7d8fcc48)] - **src**: fix objectwrap test case (Michael Dawson) [#495](https://github.com/nodejs/node-addon-api/pull/495)
+* [[`3b6b9eb88a`](https://github.com/nodejs/node-addon-api/commit/3b6b9eb88a)] - **AsyncWorker**: introduce Destroy() method (Gabriel Schulhof) [#488](https://github.com/nodejs/node-addon-api/pull/488)
+* [[`f633fbd95d`](https://github.com/nodejs/node-addon-api/commit/f633fbd95d)] - string.md: Document existing New(env, value, length) APIs (Tux3) [#486](https://github.com/nodejs/node-addon-api/pull/486)
+* [[`aaea55eda9`](https://github.com/nodejs/node-addon-api/commit/aaea55eda9)] - Little fix on code example (Nicola Del Gobbo) [#470](https://github.com/nodejs/node-addon-api/pull/470)
+* [[`e1cf9a35a1`](https://github.com/nodejs/node-addon-api/commit/e1cf9a35a1)] - Use `Value::IsEmpty` to check for empty value (NickNaso) [#478](https://github.com/nodejs/node-addon-api/pull/478)
+* [[`3ad5dfc7d9`](https://github.com/nodejs/node-addon-api/commit/3ad5dfc7d9)] - Fix link (Alba Mendez) [#481](https://github.com/nodejs/node-addon-api/pull/481)
+* [[`a3b4d99c45`](https://github.com/nodejs/node-addon-api/commit/a3b4d99c45)] - **doc**: Add contribution philosophy doc (Hitesh Kanwathirtha)
+* [[`36863f087b`](https://github.com/nodejs/node-addon-api/commit/36863f087b)] - **doc**: refer to TypedArray and ArrayBuffer from Array (Gabriel "_|Nix|_" Schulhof) [#465](https://github.com/nodejs/node-addon-api/pull/465)
+
 ## 2019-04-03 Version 1.6.3, @NickNaso
@@ -17,3 +60,3 @@
 
-- Some minor corrections all over the documentation
+- Some minor corrections all over the documentation.
 
@@ -20,0 +63,0 @@ ### Commmits

doc/async_worker.md

@@ -82,3 +82,3 @@ # AsyncWorker
 an error message will cause the `Napi::AsyncWorker::OnError` method to be
-invoked instead of `Napi::AsyncWorker::OnOKOnOK` once the
+invoked instead of `Napi::AsyncWorker::OnOK` once the
 `Napi::AsyncWorker::Execute` method completes.
@@ -109,5 +109,6 @@
 
-This method is invoked when the computation in the `Excecute` method ends.
-The default implementation runs the Callback provided when the AsyncWorker class
-was created.
+This method is invoked when the computation in the `Execute` method ends.
+The default implementation runs the Callback optionally provided when the AsyncWorker class
+was created. The callback will by default receive no arguments. To provide arguments,
+override the `GetResult()` method.
 
@@ -117,6 +118,15 @@ ```cpp
 ```
+### GetResult
 
+This method returns the arguments passed to the Callback invoked by the default
+`OnOK()` implementation. The default implementation returns an empty vector,
+providing no arguments to the Callback.
+
+```cpp
+virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env);
+```
+
 ### OnError
 
-This method is invoked afer `Napi::AsyncWorker::Execute` completes if an error
+This method is invoked after `Napi::AsyncWorker::Execute` completes if an error
 occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are
@@ -131,2 +141,15 @@ enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`.
 
+### Destroy
+
+This method is invoked when the instance must be deallocated. If
+`SuppressDestruct()` was not called then this method will be called after either
+`OnError()` or `OnOK()` complete. The default implementation of this method
+causes the instance to delete itself using the `delete` operator. The method is
+provided so as to ensure that instances allocated by means other than the `new`
+operator can be deallocated upon work completion.
+
+```cpp
+virtual void Napi::AsyncWorker::Destroy();
+```
+
 ### Constructor
@@ -143,3 +166,3 @@
 
-Returns a`Napi::AsyncWork` instance which can later be queued for execution by calling
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling
 `Queue`.
@@ -161,3 +184,3 @@
 
-Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
 calling `Napi::AsyncWork::Queue`.
@@ -181,3 +204,3 @@
 
-Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
 calling `Napi::AsyncWork::Queue`.
@@ -197,3 +220,3 @@
 
-Returns a `Napi::AsyncWork` instance which can later be queued for execution by
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
 calling `Napi::AsyncWork::Queue`.
@@ -206,3 +229,3 @@
 ```cpp
-explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback,const char* resource_name);
+explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name);
 ```
@@ -240,2 +263,50 @@
 
+
+### Constructor
+
+Creates a new `Napi::AsyncWorker`.
+
+```cpp
+explicit Napi::AsyncWorker(Napi::Env env);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
+
+Returns an `Napi::AsyncWorker` instance which can later be queued for execution by calling
+`Napi::AsyncWorker::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncWorker`.
+
+```cpp
+explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
+- `[in] resource_name`: Null-terminated strings that represents the
+identifier for the kind of resource that is being provided for diagnostic
+information exposed by the async_hooks API.
+
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWorker::Queue`.
+
+### Constructor
+
+Creates a new `Napi::AsyncWorker`.
+
+```cpp
+explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource);
+```
+
+- `[in] env`: The environment in which to create the `Napi::AsyncWorker`.
+- `[in] resource_name`:  Null-terminated strings that represents the
+identifier for the kind of resource that is being provided for diagnostic
+information exposed by the async_hooks API.
+- `[in] resource`: Object associated with the asynchronous operation that
+will be passed to possible async_hooks.
+
+Returns a `Napi::AsyncWorker` instance which can later be queued for execution by
+calling `Napi::AsyncWorker::Queue`.
+
 ### Destructor
@@ -313,3 +384,3 @@
 
-The following code shows an example on how to create and and use an `Napi::AsyncWorker`
+The following code shows an example on how to create and use an `Napi::AsyncWorker`
 
@@ -316,0 +387,0 @@ ```cpp

doc/basic_types.md

@@ -342,2 +342,8 @@ # Basic Types
 
+[`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data
+types such as [`Int32Array`][] and [`ArrayBuffer`][], respectively, that can be
+used for transferring large amounts of data from JavaScript to the native side.
+An example illustrating the use of a JavaScript-provided `ArrayBuffer` in native
+code is available [here](https://github.com/nodejs/node-addon-examples/tree/master/array_buffer_to_native/node-addon-api).
+
 ### Constructor
@@ -406,1 +412,6 @@ ```cpp
 attempting to use the returned value.
+
+[`Napi::TypedArray`]: ./typed_array.md
+[`Napi::ArrayBuffer`]: ./array_buffer.md
+[`Int32Array`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int32Array
+[`ArrayBuffer`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer

doc/class_property_descriptor.md

@@ -1,2 +0,2 @@
-# Class propertry and descriptor
+# Class property and descriptor
 
@@ -9,2 +9,84 @@ Property descriptor for use with `Napi::ObjectWrap::DefineClass()`.
 
+## Example
+
+```cpp
+#include <napi.h>
+
+class Example : public Napi::ObjectWrap<Example> {
+  public:
+    static Napi::Object Init(Napi::Env env, Napi::Object exports);
+    Example(const Napi::CallbackInfo &info);
+
+  private:
+    static Napi::FunctionReference constructor;
+    double _value;
+    Napi::Value GetValue(const Napi::CallbackInfo &info);
+    Napi::Value SetValue(const Napi::CallbackInfo &info);
+};
+
+Napi::Object Example::Init(Napi::Env env, Napi::Object exports) {
+    Napi::Function func = DefineClass(env, "Example", {
+        // Register a class instance accessor with getter and setter functions.
+        InstanceAccessor("value", &Example::GetValue, &Example::SetValue),
+        // We can also register a readonly accessor by passing nullptr as the setter.
+        InstanceAccessor("readOnlyProp", &Example::GetValue, nullptr)
+    });
+
+    constructor = Napi::Persistent(func);
+    constructor.SuppressDestruct();
+    exports.Set("Example", func);
+
+    return exports;
+}
+
+Example::Example(const Napi::CallbackInfo &info) : Napi::ObjectWrap<Example>(info) {
+    Napi::Env env = info.Env();
+    // ...
+    Napi::Number value = info[0].As<Napi::Number>();
+    this->_value = value.DoubleValue();
+}
+
+Napi::FunctionReference Example::constructor;
+
+Napi::Value Example::GetValue(const Napi::CallbackInfo &info) {
+    Napi::Env env = info.Env();
+    return Napi::Number::New(env, this->_value);
+}
+
+Napi::Value Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) {
+    Napi::Env env = info.Env();
+    // ...
+    Napi::Number arg = value.As<Napi::Number>();
+    this->_value = arg.DoubleValue();
+    return this->GetValue(info);
+}
+
+// Initialize native add-on
+Napi::Object Init (Napi::Env env, Napi::Object exports) {
+    Example::Init(env, exports);
+    return exports;
+}
+
+// Register and initialize native add-on
+NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
+```
+
+The above code can be used from JavaScript as follows:
+
+```js
+'use strict';
+
+const { Example } = require('bindings')('addon');
+
+const example = new Example(11);
+console.log(example.value);
+// It prints 11
+example.value = 19;
+console.log(example.value);
+// It prints 19
+example.readOnlyProp = 500;
+console.log(example.readOnlyProp);
+// Unchanged. It prints 19
+```
+
 ## Methods
@@ -11,0 +93,0 @@

doc/object_wrap.md

@@ -81,3 +81,3 @@ # Object Wrap
 
-// Regisgter and initialize native add-on
+// Register and initialize native add-on
 NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
@@ -84,0 +84,0 @@ ```

doc/object.md

@@ -26,3 +26,3 @@ # Object
   obj.Set("hello", "world");
-  obj.Set(42, "The Answer to Life, the Universe, and Everything");
+  obj.Set(uint32_t(42), "The Answer to Life, the Universe, and Everything");
   obj.Set("Douglas Adams", true);
@@ -32,3 +32,3 @@
   Value val1 = obj.Get("hello");
-  Value val2 = obj.Get(42);
+  Value val2 = obj.Get(uint32_t(42));
   Value val3 = obj.Get("Douglas Adams");
@@ -35,0 +35,0 @@

doc/prebuild_tools.md

@@ -5,3 +5,3 @@ # Prebuild tools
 In order to install a native add-on it's important to have all the necessary
-dependencies installed and well configured (see the [setup](doc/setum.md) section).
+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`
@@ -8,0 +8,0 @@ and in some cases this could create problems. To avoid the compilation process it's

doc/string.md

@@ -59,2 +59,4 @@ # String
 Napi::String::New(napi_env env, const char16_t* value);
+Napi::String::New(napi_env env, const char* value, size_t length);
+Napi::String::New(napi_env env, const char16_t* value, size_t length);
 ```
@@ -68,2 +70,3 @@
   - `const char16_t*` - represents a UTF16-LE string.
+- `[in] length`: The length of the string (not necessarily null-terminated) in code units.
 
@@ -70,0 +73,0 @@ Returns a new `Napi::String` that represents the passed in C++ string.

package.json

@@ -7,2 +7,3 @@ {
     "Abhishek Kumar Singh (https://github.com/abhi11210646)",
+    "Alba Mendez (https://github.com/jmendeth)",
     "Andrew Petersen (https://github.com/kirbysayshi)",
@@ -30,2 +31,3 @@ "Anisha Rohra (https://github.com/anisha-rohra)",
     "joshgarde (https://github.com/joshgarde)",
+    "Kevin Eady (https://github.com/KevinEady)",
     "Konstantin Tarkus (https://github.com/koistya)",
@@ -42,2 +44,3 @@ "Kyle Farnung (https://github.com/kfarnung)",
     "Rolf Timmermans (https://github.com/rolftimmermans)",
+    "Ross Weir (https://github.com/ross-weir)",
     "Ryuichi Okumura (https://github.com/okuryu)",
@@ -47,3 +50,5 @@ "Sampson Gao (https://github.com/sampsongao)",
     "Taylor Woll (https://github.com/boingoing)",
-    "Thomas Gentilhomme (https://github.com/fraxken)"
+    "Thomas Gentilhomme (https://github.com/fraxken)",
+    "Tux3 (https://github.com/tux3)",
+    "Yohei Kishimoto (https://github.com/morokosi)"
   ],
@@ -76,3 +81,3 @@ "dependencies": {},
   },
-  "version": "1.6.3"
+  "version": "1.7.0"
 }

README.md

@@ -49,3 +49,3 @@ # **node-addon-api module**
 
-## **Current version: 1.6.3**
+## **Current version: 1.7.0**
 
@@ -110,2 +110,3 @@ (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
     - [AsyncContext](doc/async_context.md)
+ - [Thread-safe Functions](doc/threadsafe_function.md)
  - [Promises](doc/promises.md)
@@ -164,2 +165,7 @@ - [Version management](doc/version_management.md)
 
+## **Contributing**
+
+We love contributions from the community to **node-addon-api**.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on our philosophy around extending this module.
+
 ### **More resource and info about native Addons**
@@ -166,0 +172,0 @@ - **[C++ Addons](https://nodejs.org/dist/latest/docs/api/addons.html)**

No alert changes

Improved metrics

Total package byte prevSize

753921

increased by7.31%

Number of package files

74

increased by2.78%

Number of lines in readme file

201

increased by3.08%

No dependency changes