node-addon-api 1.6.3 → 2.0.0

package/.travis.yml

@@ -12,20 +12,17 @@ env:
     # https://github.com/jasongin/nvs/blob/master/doc/CI.md
     - NVS_VERSION=1.4.2
   matrix:
-    - NODEJS_VERSION=node/4
     - NODEJS_VERSION=node/6
     - NODEJS_VERSION=node/8
-    - NODEJS_VERSION=node/9
     - NODEJS_VERSION=node/10
-    - NODEJS_VERSION=chakracore/8
-    - NODEJS_VERSION=chakracore/10
+    - NODEJS_VERSION=node/12
+    - NODEJS_VERSION=node/13
     - NODEJS_VERSION=nightly
-    - NODEJS_VERSION=chakracore-nightly
 matrix:
   fast_finish: true
   allow_failures:
     - env: NODEJS_VERSION=nightly
-    - env: NODEJS_VERSION=chakracore-nightly
+    - env: NODEJS_VERSION=node/6
 sudo: false
 cache:
   directories:
@@ -60,6 +57,6 @@ script:
   # Travis CI sets NVM_NODEJS_ORG_MIRROR, but it makes node-gyp fail to download headers for nightly builds.
   - unset NVM_NODEJS_ORG_MIRROR
 
-  - npm test $NPMOPT
+  - npm test
 after_success:
   - cpp-coveralls --gcov-options '\-lp' --build-root test/build --exclude test

package/CHANGELOG.md

@@ -1,5 +1,125 @@
 # node-addon-api Changelog
 
+## 2019-11-21 Version 2.0.0, @NickNaso
+
+### Notable changes:
+
+#### API
+
+- Added `Napi::AsyncProgressWorker` api.
+- Added error checking on `Napi::ThreadSafeFunction::GetContext`.
+- Added copy constructor to `Napi::ThreadSafeFunction`.
+- Added `Napi::ThreadSafeFunction::Ref` and `Napi::ThreadSafeFunction::Unref` to `Napi::ThreadSafeFunction`.
+- Added `Napi::Object::AddFinalizer` method.
+- Use `napi_add_finalizer()` to attach data when building against N-API 5.
+- Added `Napi::Date` api.
+- Added `Napi::ObjectWrap::Finalize` method.
+
+#### Documentation
+
+- Added documentation for `Napi::AsyncProgressWorker`.
+- Improve `Napi::AsyncWorker` documentation.
+- Added documentation for `Napi::Object::AddFinalizer` method.
+- Improved documentation for `Napi::ThreadSafeFunction`.
+- Improved documentation about the usage of CMake as build tool.
+- Some minor corrections all over the documentation.
+
+#### TEST
+
+- Added test cases for `Napi::AsyncProgressWorker` api.
+- Added test cases for `Napi::Date` api.
+- Added test cases for new features added to `Napi::ThreadSafeFunction`.
+
+### Commmits
+
+* [[`c881168d49`](https://github.com/nodejs/node-addon-api/commit/c881168d49)] - **tsfn**: add error checking on GetContext (#583) (Kevin Eady) [#583](https://github.com/nodejs/node-addon-api/pull/583)
+* [[`24d75dd82f`](https://github.com/nodejs/node-addon-api/commit/24d75dd82f)] - Merge pull request #588 from NickNaso/add-asyncprogress-worker-readme (Nicola Del Gobbo)
+* [[`aa79e37b62`](https://github.com/nodejs/node-addon-api/commit/aa79e37b62)] - Merge pull request #587 from timrach/patch-1 (Nicola Del Gobbo)
+* [[`df75e08c2b`](https://github.com/nodejs/node-addon-api/commit/df75e08c2b)] - **tsfn**: support direct calls to underlying napi\_tsfn (Kevin Eady) [#58](https://github.com/nodejs/node-addon-api/pull/58)
+* [[`2298dfae58`](https://github.com/nodejs/node-addon-api/commit/2298dfae58)] - **doc**: Added AsyncProgressWorker to readme (NickNaso)
+* [[`b3609d33b6`](https://github.com/nodejs/node-addon-api/commit/b3609d33b6)] - Fix return type and declaration of setter callback (Tim Rach)
+* [[`295e560f55`](https://github.com/nodejs/node-addon-api/commit/295e560f55)] - **test**: improve guards for experimental features (legendecas)
+* [[`2e71842f63`](https://github.com/nodejs/node-addon-api/commit/2e71842f63)] - **tsfn**: Implement copy constructor (Kevin Eady) [#546](https://github.com/nodejs/node-addon-api/pull/546)
+* [[`650562cab9`](https://github.com/nodejs/node-addon-api/commit/650562cab9)] - **src**: implement AsyncProgressWorker (legendecas) [#529](https://github.com/nodejs/node-addon-api/pull/529)
+* [[`bdfd14101f`](https://github.com/nodejs/node-addon-api/commit/bdfd14101f)] - **src**: attach data with napi\_add\_finalizer (Gabriel Schulhof) [#577](https://github.com/nodejs/node-addon-api/pull/577)
+* [[`9e955a802b`](https://github.com/nodejs/node-addon-api/commit/9e955a802b)] - **doc**: change node.js to Node.js per guideline (#579) (Tobias Nießen) [#579](https://github.com/nodejs/node-addon-api/pull/579)
+* [[`b42e21e3a9`](https://github.com/nodejs/node-addon-api/commit/b42e21e3a9)] - **build**: move node/6 to travis allowed failures and add node/13 (#573) (Gabriel Schulhof)
+* [[`8d6132f609`](https://github.com/nodejs/node-addon-api/commit/8d6132f609)] - **doc**: improve AsyncWorker docs (#571) (legendecas) [#571](https://github.com/nodejs/node-addon-api/pull/571)
+* [[`bc8fc23627`](https://github.com/nodejs/node-addon-api/commit/bc8fc23627)] - **test**: do not run TSFN tests on NAPI\_VERSION \< 4 (legendecas) [#576](https://github.com/nodejs/node-addon-api/pull/576)
+* [[`bcc1d58fc4`](https://github.com/nodejs/node-addon-api/commit/bcc1d58fc4)] - implement Object::AddFinalizer (Gabriel Schulhof)
+* [[`e9a4bcd52a`](https://github.com/nodejs/node-addon-api/commit/e9a4bcd52a)] - **doc**: updates Make.js doc to current best practices (Jim Schlight) [#558](https://github.com/nodejs/node-addon-api/pull/558)
+* [[`b513d1aa7a`](https://github.com/nodejs/node-addon-api/commit/b513d1aa7a)] - **doc**: fix return type of ArrayBuffer::Data (Tobias Nießen) [#552](https://github.com/nodejs/node-addon-api/pull/552)
+* [[`34c11cf0a4`](https://github.com/nodejs/node-addon-api/commit/34c11cf0a4)] - **src**: disallow copying, double close of scopes (legendecas) [#566](https://github.com/nodejs/node-addon-api/pull/566)
+* [[`ce139a05e8`](https://github.com/nodejs/node-addon-api/commit/ce139a05e8)] - **src**: make failure of closing scopes fatal (legendecas) [#566](https://github.com/nodejs/node-addon-api/pull/566)
+* [[`740c79823e`](https://github.com/nodejs/node-addon-api/commit/740c79823e)] - **src**: add Env() to AsyncContext (Rolf Timmermans) [#568](https://github.com/nodejs/node-addon-api/pull/568)
+* [[`ea9ce1c801`](https://github.com/nodejs/node-addon-api/commit/ea9ce1c801)] - **tsfn**: add wrappers for Ref and Unref (Kevin Eady) [#561](https://github.com/nodejs/node-addon-api/pull/561)
+* [[`2e1769e1a3`](https://github.com/nodejs/node-addon-api/commit/2e1769e1a3)] - **error**: remove unnecessary if condition (legendecas) [#562](https://github.com/nodejs/node-addon-api/pull/562)
+* [[`828f223a87`](https://github.com/nodejs/node-addon-api/commit/828f223a87)] - **doc**: fix spelling in ObjectWrap doc (#563) (Tobias Nießen) [#563](https://github.com/nodejs/node-addon-api/pull/563)
+* [[`dd9fa8a4a8`](https://github.com/nodejs/node-addon-api/commit/dd9fa8a4a8)] - **doc**: move Arunesh and Taylor to Emeritus (#540) (Michael Dawson) [#540](https://github.com/nodejs/node-addon-api/pull/540)
+* [[`cf8b8415df`](https://github.com/nodejs/node-addon-api/commit/cf8b8415df)] - **doc**: add Kevin to the list of collaborators (#539) (Michael Dawson) [#539](https://github.com/nodejs/node-addon-api/pull/539)
+* [[`5d6aeae7b5`](https://github.com/nodejs/node-addon-api/commit/5d6aeae7b5)] - **build**: enable travis for fast PR check (legendecas)
+* [[`6192e705cd`](https://github.com/nodejs/node-addon-api/commit/6192e705cd)] - **src**: add napi\_date (Mathias Küsel) [#497](https://github.com/nodejs/node-addon-api/pull/497)
+* [[`7b1ee96d52`](https://github.com/nodejs/node-addon-api/commit/7b1ee96d52)] - **doc**: update prebuild\_tools.md (Nurbol Alpysbayev) [#527](https://github.com/nodejs/node-addon-api/pull/527)
+* [[`0b4f3a5b8c`](https://github.com/nodejs/node-addon-api/commit/0b4f3a5b8c)] - **tsfn**: fix crash on releasing tsfn (legendecas) [#532](https://github.com/nodejs/node-addon-api/pull/532)
+* [[`c3c8814d2f`](https://github.com/nodejs/node-addon-api/commit/c3c8814d2f)] - implement virutal ObjectWrap::Finalize (Michael Price) [#515](https://github.com/nodejs/node-addon-api/pull/515)
+
+## 2019-07-23 Version 1.7.1, @NickNaso
+
+### Notable changes:
+
+#### API
+
+- Fixed compilation problems that happen on Node.js with N-API version less than 4.
+
+### Commmits
+
+* [[`c20bcbd069`](https://github.com/nodejs/node-addon-api/commit/c20bcbd069)] - Merge pull request #518 from NickNaso/master (Nicola Del Gobbo)
+* [[`6720d57253`](https://github.com/nodejs/node-addon-api/commit/6720d57253)] - Create the native threadsafe\_function for test only for N-API greater than 3. (NickNaso)
+* [[`37b6c185ad`](https://github.com/nodejs/node-addon-api/commit/37b6c185ad)] - Fix compilation breakage on 1.7.0 (NickNaso)
+
+## 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
 
 ### Notable changes:
@@ -14,7 +134,7 @@
 
 #### Documentation
 
-- Some minor corrections all over the documentation
+- Some minor corrections all over the documentation.
 
 ### Commmits
 

package/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# **node-addon-api** Contribution Philosophy
+
+The **node-addon-api** team loves contributions. There are many ways in which you can
+contribute to **node-addon-api**:
+- Source code fixes
+- Additional tests
+- Documentation improvements
+- Joining the N-API working group and participating in meetings
+
+## Source changes
+
+**node-addon-api** is meant to be a thin convenience wrapper around N-API. With this
+in mind, contributions of any new APIs that wrap around a core N-API API will
+be considered for merge. However, changes that wrap existing **node-addon-api**
+APIs are encouraged to instead be provided as an ecosystem module. The
+**node-addon-api** team is happy to link to a curated set of modules that build on
+top of **node-addon-api** if they have broad usefulness to the community and promote
+a recommended idiom or pattern.
+
+### Rationale
+
+The N-API team considered a couple different approaches with regards to changes
+extending **node-addon-api**
+- Larger core module - Incorporate these helpers and patterns into **node-addon-api**
+- Extras package - Create a new package (strawman name '**node-addon-api**-extras')
+that contain utility classes and methods that help promote good patterns and
+idioms while writing native addons with **node-addon-api**.
+- Ecosystem - Encourage creation of a module ecosystem around **node-addon-api**
+where folks can build on top of it.
+
+#### Larger Core
+This is probably our simplest option in terms of immediate action needed. It
+would involve landing any open PRs against **node-addon-api**, and continuing to
+encourage folks to make PRs for utility helpers against the same repository.
+
+The downside of the approach is the following:
+- Less coherency for our API set
+- More maintenance burden on the N-API WG core team.
+
+#### Extras Package
+This involves us spinning up a new package which contains the utility classes
+and methods. This has the benefit of having a separate module where helpers
+which make it easier to implement certain patterns and idioms for native addons
+easier.
+
+The downside of this approach is the following:
+- Potential for confusion - we'll need to provide clear documentation to help the
+community understand where a particular contribution should be directed to (what
+belongs in **node-addon-api** vs **node-addon-api-extras**)
+- Need to define the level of support/API guarantees
+- Unclear if the maintenance burden on the N-API WG is reduced or not
+
+#### Ecosystem
+This doesn't require a ton of up-front work from the N-API WG. Instead of
+accepting utility PRs into **node-addon-api** or creating and maintaining a new
+module, the WG will encourage the creation of an ecosystem of modules that
+build on top of **node-addon-api**, and provide some level of advertising for these
+modules (listing them out on the repository/wiki, using them in workshops/tutorials
+etc).
+
+The downside of this approach is the following:
+- Potential for lack of visibility - evangelism and education is hard, and module
+authors might not find right patterns and instead implement things themselves
+- There might be greater friction for the N-API WG in evolving APIs since the
+ecosystem would have taken dependencies on the API shape of **node-addon-api**
+

package/README.md

@@ -46,7 +46,7 @@ to ideas specified in the **ECMA262 Language Specification**.
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 1.6.3**
+## **Current version: 2.0.0**
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
 
@@ -75,6 +75,7 @@ The following is the documentation for node-addon-api.
     - [String](doc/string.md)
     - [Name](doc/basic_types.md#name)
     - [Number](doc/number.md)
+    - [Date](doc/date.md)
     - [BigInt](doc/bigint.md)
     - [Boolean](doc/boolean.md)
     - [Env](doc/env.md)
@@ -106,6 +107,8 @@ The following is the documentation for node-addon-api.
  - [Async Operations](doc/async_operations.md)
     - [AsyncWorker](doc/async_worker.md)
     - [AsyncContext](doc/async_context.md)
+    - [AsyncProgressWorker](doc/async_progress_worker.md)
+ - [Thread-safe Functions](doc/threadsafe_function.md)
  - [Promises](doc/promises.md)
  - [Version management](doc/version_management.md)
 
@@ -159,6 +162,11 @@ Take a look and get inspired by our **[test suite](https://github.com/nodejs/nod
 
 <a name="resources"></a>
 
+## **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**
 - **[C++ Addons](https://nodejs.org/dist/latest/docs/api/addons.html)**
 - **[N-API](https://nodejs.org/dist/latest/docs/api/n-api.html)**
@@ -172,20 +180,21 @@ Take a look and get inspired by our **[test suite](https://github.com/nodejs/nod
 | Name                | GitHub Link                                           |
 | ------------------- | ----------------------------------------------------- |
 | Anna Henningsen     | [addaleax](https://github.com/addaleax)               |
-| Arunesh Chandra     | [aruneshchandra](https://github.com/aruneshchandra)   |
 | Gabriel Schulhof    | [gabrielschulhof](https://github.com/gabrielschulhof) |
 | Hitesh Kanwathirtha | [digitalinfinity](https://github.com/digitalinfinity) |
 | Jim Schlight        | [jschlight](https://github.com/jschlight)             |
 | Michael Dawson      | [mhdawson](https://github.com/mhdawson)               |
+| Kevin Eady          | [KevinEady](https://github.com/KevinEady)
 | Nicola Del Gobbo    | [NickNaso](https://github.com/NickNaso)               |
-| Taylor Woll         | [boingoing](https://github.com/boingoing)             |
 
 ### Emeritus
 | Name                | GitHub Link                                           |
 | ------------------- | ----------------------------------------------------- |
+| Arunesh Chandra     | [aruneshchandra](https://github.com/aruneshchandra)   |
 | Benjamin Byholm     | [kkoopa](https://github.com/kkoopa)                   |
 | Jason Ginchereau    | [jasongin](https://github.com/jasongin)               |
 | Sampson Gao         | [sampsongao](https://github.com/sampsongao)           |
+| Taylor Woll         | [boingoing](https://github.com/boingoing)             |
 
 <a name="license"></a>
 

package/doc/array_buffer.md

@@ -123,7 +123,7 @@ Returns the length of the wrapped data, in bytes.
 ### Data
 
 ```cpp
-T* Napi::ArrayBuffer::Data() const;
+void* Napi::ArrayBuffer::Data() const;
 ```
 
 Returns a pointer the wrapped data.

package/doc/async_context.md

@@ -45,6 +45,16 @@ The `Napi::AsyncContext` to be destroyed.
 virtual Napi::AsyncContext::~AsyncContext();
 ```
 
+### Env
+
+Requests the environment in which the async context has been initially created.
+
+```cpp
+Napi::Env Env() const;
+```
+
+Returns the `Napi::Env` environment in which the async context has been created.
+
 ## Operator
 
 ```cpp

package/doc/async_operations.md

@@ -4,7 +4,7 @@ Node.js native add-ons often need to execute long running tasks and to avoid
 blocking the **event loop** they have to run them asynchronously from the
 **event loop**.
 In the Node.js model of execution the event loop thread represents the thread
-where JavaScript code is executing. The node.js guidance is to avoid blocking
+where JavaScript code is executing. The Node.js guidance is to avoid blocking
 other work queued on the event loop thread. Therefore, we need to do this work on
 another thread.