node-addon-api 3.0.2 → 3.1.0

package/.clang-format

@@ -0,0 +1,111 @@
+---
+Language:        Cpp
+# BasedOnStyle:  Google
+AccessModifierOffset: -1
+AlignAfterOpenBracket: Align
+AlignConsecutiveAssignments: false
+AlignConsecutiveDeclarations: false
+AlignEscapedNewlines: Right
+AlignOperands:   true
+AlignTrailingComments: true
+AllowAllParametersOfDeclarationOnNextLine: true
+AllowShortBlocksOnASingleLine: false
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: true
+AllowShortLoopsOnASingleLine: true
+AlwaysBreakAfterDefinitionReturnType: None
+AlwaysBreakAfterReturnType: None
+AlwaysBreakBeforeMultilineStrings: false
+AlwaysBreakTemplateDeclarations: true
+BinPackArguments: false
+BinPackParameters: false
+BraceWrapping:
+  AfterClass:      false
+  AfterControlStatement: false
+  AfterEnum:       false
+  AfterFunction:   false
+  AfterNamespace:  false
+  AfterObjCDeclaration: false
+  AfterStruct:     false
+  AfterUnion:      false
+  AfterExternBlock: false
+  BeforeCatch:     false
+  BeforeElse:      false
+  IndentBraces:    false
+  SplitEmptyFunction: true
+  SplitEmptyRecord: true
+  SplitEmptyNamespace: true
+BreakBeforeBinaryOperators: None
+BreakBeforeBraces: Attach
+BreakBeforeInheritanceComma: false
+BreakBeforeTernaryOperators: true
+BreakConstructorInitializersBeforeComma: false
+BreakConstructorInitializers: BeforeColon
+BreakAfterJavaFieldAnnotations: false
+BreakStringLiterals: true
+ColumnLimit:      80
+CommentPragmas:  '^ IWYU pragma:'
+CompactNamespaces: false
+ConstructorInitializerAllOnOneLineOrOnePerLine: true
+ConstructorInitializerIndentWidth: 4
+ContinuationIndentWidth: 4
+Cpp11BracedListStyle: true
+DerivePointerAlignment: false
+DisableFormat:   false
+ExperimentalAutoDetectBinPacking: false
+FixNamespaceComments: true
+ForEachMacros:
+  - foreach
+  - Q_FOREACH
+  - BOOST_FOREACH
+IncludeBlocks:   Preserve
+IncludeCategories:
+  - Regex:           '^<ext/.*\.h>'
+    Priority:        2
+  - Regex:           '^<.*\.h>'
+    Priority:        1
+  - Regex:           '^<.*'
+    Priority:        2
+  - Regex:           '.*'
+    Priority:        3
+IncludeIsMainRegex: '([-_](test|unittest))?$'
+IndentCaseLabels: true
+IndentPPDirectives: None
+IndentWidth:     2
+IndentWrappedFunctionNames: false
+JavaScriptQuotes: Leave
+JavaScriptWrapImports: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+MacroBlockBegin: ''
+MacroBlockEnd:   ''
+MaxEmptyLinesToKeep: 1
+NamespaceIndentation: None
+ObjCBlockIndentWidth: 2
+ObjCSpaceAfterProperty: false
+ObjCSpaceBeforeProtocolList: false
+PenaltyBreakAssignment: 2
+PenaltyBreakBeforeFirstCallParameter: 1
+PenaltyBreakComment: 300
+PenaltyBreakFirstLessLess: 120
+PenaltyBreakString: 1000
+PenaltyExcessCharacter: 1000000
+PenaltyReturnTypeOnItsOwnLine: 200
+PointerAlignment: Left
+ReflowComments:  true
+SortIncludes:    true
+SortUsingDeclarations: true
+SpaceAfterCStyleCast: false
+SpaceAfterTemplateKeyword: true
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeParens: ControlStatements
+SpaceInEmptyParentheses: false
+SpacesBeforeTrailingComments: 2
+SpacesInAngles:  false
+SpacesInContainerLiterals: true
+SpacesInCStyleCastParentheses: false
+SpacesInParentheses: false
+SpacesInSquareBrackets: false
+Standard:        Auto
+TabWidth:        8
+UseTab:          Never

package/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: Node.js CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        node-version:
+          - node/10
+          - node/12
+          - node/14
+          - node/15
+        compiler:
+          - gcc
+          - clang
+        os:
+          - ubuntu-16.04 # ubuntu-18.04/ubuntu-latest missing package g++-4.9
+          - macos-latest
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+    - name: Install system dependencies
+      run: |
+        if [ "${{ matrix.compiler }}" = "gcc" -a "${{ matrix.os }}" = ubuntu-* ]; then
+          sudo add-apt-repository ppa:ubuntu-toolchain-r/test
+          sudo apt-get update
+          sudo apt-get install g++-4.9
+        fi
+    - name: Use Node.js ${{ matrix.node-version }}
+      run: |
+        git clone --branch v1.4.2 --depth 1 https://github.com/jasongin/nvs ~/.nvs
+        . ~/.nvs/nvs.sh
+        nvs --version
+        nvs add ${{ matrix.node-version }}
+        nvs use ${{ matrix.node-version }}
+        node --version
+        npm --version
+        npm install
+    - name: npm test
+      run: |
+        if [ "${{ matrix.compiler }}" = "gcc" ]; then
+          export CC="gcc" CXX="g++"
+        fi
+        if [ "${{ matrix.compiler }}" = "gcc" -a "${{ matrix.os }}" = ubuntu-* ]; then
+          export CC="gcc-4.9" CXX="g++-4.9" AR="gcc-ar-4.9" RANLIB="gcc-ranlib-4.9" NM="gcc-nm-4.9"
+        fi
+        if [ "${{ matrix.compiler }}" = "clang" ]; then
+          export CC="clang" CXX="clang++"
+        fi
+        export CFLAGS="$CFLAGS -O3 --coverage" LDFLAGS="$LDFLAGS --coverage"
+        echo "CFLAGS=\"$CFLAGS\" LDFLAGS=\"$LDFLAGS\""
+        npm run pretest -- --verbose
+        node test

package/.github/workflows/linter.yml

@@ -0,0 +1,24 @@
+name: Style Checks
+
+on: [push, pull_request]
+
+jobs:
+  lint:
+    if: github.repository == 'nodejs/node-addon-api'
+    strategy:
+      matrix:
+        node-version: [14.x]
+        os: [ubuntu-latest]
+
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+    - run: git branch -a
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - run: npm install
+    - run: CLANG_FORMAT_START=refs/remotes/origin/master npm run lint

package/.github/workflows/stale.yml

@@ -0,0 +1,18 @@
+name: "Close stale issues"
+on:
+  schedule:
+  - cron: "0 0 * * *"
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/stale@v1
+      with:
+        repo-token: ${{ secrets.GITHUB_TOKEN }}
+        stale-issue-message: 'This issue is stale because it has been open many days with no activity. It will be closed soon unless the stale label is removed or a comment is made.'
+        stale-issue-label: 'stale'
+        exempt-issue-label: 'never stale'
+        days-before-stale: 90
+        days-before-close: 30
+

package/.travis.yml

@@ -20,7 +20,6 @@ matrix:
   fast_finish: true
   allow_failures:
     - env: NODEJS_VERSION=nightly
-sudo: false
 cache:
   directories:
     - node_modules

package/CHANGELOG.md

@@ -1,5 +1,81 @@
 # node-addon-api Changelog
 
+## 2020-12-17 Version 3.1.0, @NickNaso
+
+### Notable changes:
+
+#### API
+
+- Added `Napi::TypedThreadSafeFunction` class that is a new implementation for
+thread-safe functions. 
+- Fixed leak on `Napi::AsyncProgressWorkerBase`.
+- Fixed empty data on `Napi::AsyncProgressWorker::OnProgress` caused by race 
+conditions of `Napi::AsyncProgressWorker`.
+- Added `Napi::ArrayBuffer::Detach()` and `Napi::ArrayBuffer::IsDetached()`.
+- Fixed problem on `Napi::FinalizeCallback` it needs to create a 
+`Napi::HandleScope` when it calls `Napi::ObjectWrap::~ObjectWrap()`.
+
+#### Documentation
+
+- Added documentation for `Napi::TypedThreadSafeFunction`.
+- Removed unsued Doxygen file.
+- Clarified when to use N-API.
+- Added support information.
+- Some minor corrections all over the documentation.
+
+#### TEST
+
+- Added test for `Napi::TypedThreadSafeFunction`.
+- Fixed testing for specific N-API version.
+- Some minor corrections all over the test suite.
+
+### TOOL
+
+- Setup github actions for tests.
+- Added stale action.
+- Removed `sudo` tag from Travis CI.
+- Added clang-format.
+- Added pre-commit package for linting.
+
+### Commits
+
+* [[`ff642c5b85`](https://github.com/nodejs/node-addon-api/commit/ff642c5b85)] - **doc**: fix tsfn docs to reflect true implementation (#860) (Kevin Eady)
+* [[`86feeebf54`](https://github.com/nodejs/node-addon-api/commit/86feeebf54)] - **src**: empty data OnProgress in AsyncProgressWorker (legendecas) [#853](https://github.com/nodejs/node-addon-api/pull/853)
+* [[`a7fb5fb31c`](https://github.com/nodejs/node-addon-api/commit/a7fb5fb31c)] - **action**: add stale action (#856) (Michael Dawson)
+* [[`fd44609885`](https://github.com/nodejs/node-addon-api/commit/fd44609885)] - **chore**: setup github actions for tests (#854) (legendecas) [#854](https://github.com/nodejs/node-addon-api/pull/854)
+* [[`c52ace4813`](https://github.com/nodejs/node-addon-api/commit/c52ace4813)] - **script**: fix complains that js files are not supported on npm run lint:fix (#852) (legendecas)
+* [[`b4a3364ad5`](https://github.com/nodejs/node-addon-api/commit/b4a3364ad5)] - **doc**: remove unused Doxygen file (#851) (Michael Dawson)
+* [[`b810466ae2`](https://github.com/nodejs/node-addon-api/commit/b810466ae2)] - **doc**: clarify when to use N-API (#849) (Michael Dawson)
+* [[`528b9f6832`](https://github.com/nodejs/node-addon-api/commit/528b9f6832)] - **test**: remove sudo from travis (#850) (Michael Dawson)
+* [[`4bb680de4e`](https://github.com/nodejs/node-addon-api/commit/4bb680de4e)] - Remove misleading sentence (#847) (Nikolai Vavilov) [#847](https://github.com/nodejs/node-addon-api/pull/847)
+* [[`48e6b584a3`](https://github.com/nodejs/node-addon-api/commit/48e6b584a3)] - Merge pull request #742 from KevinEady/contexted-tsfn-api-gcc-4 (Gabriel Schulhof)
+* [[`d5e37210cc`](https://github.com/nodejs/node-addon-api/commit/d5e37210cc)] - **tools**: print more instructions on clang-format check failed (#846) (legendecas) [#846](https://github.com/nodejs/node-addon-api/pull/846)
+* [[`d9e11ff2c9`](https://github.com/nodejs/node-addon-api/commit/d9e11ff2c9)] - **doc**: add support info (#843) (Michael Dawson) [#843](https://github.com/nodejs/node-addon-api/pull/843)
+* [[`356e93d69a`](https://github.com/nodejs/node-addon-api/commit/356e93d69a)] - **test**: fixup testing for specific N-API version (#840) (Michael Dawson) [#840](https://github.com/nodejs/node-addon-api/pull/840)
+* [[`5e5b9ce1b7`](https://github.com/nodejs/node-addon-api/commit/5e5b9ce1b7)] - Apply formatting changes (Kevin Eady)
+* [[`559ad8c0c0`](https://github.com/nodejs/node-addon-api/commit/559ad8c0c0)] - Merge remote-tracking branch 'upstream/master' into contexted-tsfn-api-gcc-4 (Kevin Eady)
+* [[`c24c455ced`](https://github.com/nodejs/node-addon-api/commit/c24c455ced)] - Rename to TypedThreadSafeFunction (Kevin Eady)
+* [[`63b43f4125`](https://github.com/nodejs/node-addon-api/commit/63b43f4125)] - **test**: fix buildType bug objectwrap\_worker\_thread (raisinten) [#837](https://github.com/nodejs/node-addon-api/pull/837)
+* [[`6321f2ba1a`](https://github.com/nodejs/node-addon-api/commit/6321f2ba1a)] - **test**: fix typos in addon\_build/index.js (raisinten) [#838](https://github.com/nodejs/node-addon-api/pull/838)
+* [[`59c6a6aeb0`](https://github.com/nodejs/node-addon-api/commit/59c6a6aeb0)] - **fix**: git-clang-format doesn't recognize no changes requested on given files (#835) (legendecas)
+* [[`1427b3ef78`](https://github.com/nodejs/node-addon-api/commit/1427b3ef78)] - **src**: create a HandleScope in FinalizeCallback (blagoev) [#832](https://github.com/nodejs/node-addon-api/pull/832)
+* [[`8fb5820557`](https://github.com/nodejs/node-addon-api/commit/8fb5820557)] - **build**: add incremental clang-format checks (legendecas) [#819](https://github.com/nodejs/node-addon-api/pull/819)
+* [[`2c02d317e5`](https://github.com/nodejs/node-addon-api/commit/2c02d317e5)] - **build**: add pre-commit package for linting (#823) (Kevin Eady)
+* [[`1b52c28eb8`](https://github.com/nodejs/node-addon-api/commit/1b52c28eb8)] - Clean up AsyncProgressWorker documentation (#831) (mastergberry)
+* [[`4abe7cfe30`](https://github.com/nodejs/node-addon-api/commit/4abe7cfe30)] - **test**: rename tsfnex test files (Kevin Eady)
+* [[`c9563caa25`](https://github.com/nodejs/node-addon-api/commit/c9563caa25)] - **src**: add ArrayBuffer::Detach() and ::IsDetached() (Tobias Nießen) [#659](https://github.com/nodejs/node-addon-api/pull/659)
+* [[`c79cabaed2`](https://github.com/nodejs/node-addon-api/commit/c79cabaed2)] - **doc**: avoid directing users to HTTP (#828) (Tobias Nießen)
+* [[`7a13f861ab`](https://github.com/nodejs/node-addon-api/commit/7a13f861ab)] - **doc**: fix additional typo (Kevin Eady)
+* [[`7ec9741dd2`](https://github.com/nodejs/node-addon-api/commit/7ec9741dd2)] - Merge remote-tracking branch 'upstream/master' into contexted-tsfn-api-gcc-4 (Kevin Eady)
+* [[`f5fad239fa`](https://github.com/nodejs/node-addon-api/commit/f5fad239fa)] - Update object\_reference.md (#827) (kidneysolo)
+* [[`35b65712c2`](https://github.com/nodejs/node-addon-api/commit/35b65712c2)] - **Fix**: some typos in documentation (#826) (Helio Frota)
+* [[`8983383000`](https://github.com/nodejs/node-addon-api/commit/8983383000)] - **Fix**: some typos in the document (#825) (Ziqiu Zhao)
+* [[`826e466ef6`](https://github.com/nodejs/node-addon-api/commit/826e466ef6)] - Fixed example in addon.md. (#820) (nempoBu4) [#820](https://github.com/nodejs/node-addon-api/pull/820)
+* [[`b54f5eb788`](https://github.com/nodejs/node-addon-api/commit/b54f5eb788)] - Additional changes from review (Kevin Eady)
+* [[`59f27dac9a`](https://github.com/nodejs/node-addon-api/commit/59f27dac9a)] - Fix common.gypi (Kevin Eady)
+* [[`151a914c99`](https://github.com/nodejs/node-addon-api/commit/151a914c99)] - Apply documentation suggestions from code review (Kevin Eady)
+* [[`ceb27d4949`](https://github.com/nodejs/node-addon-api/commit/ceb27d4949)] - **src**: fix leak in AsyncProgressWorkerBase\<DataType\> (Ferdinand Holzer) [#795](https://github.com/nodejs/node-addon-api/pull/795)
+
 ## 2020-09-18 Version 3.0.2, @NickNaso
 
 ### Notable changes:

package/README.md

@@ -4,6 +4,14 @@ the use of the C based [N-API](https://nodejs.org/dist/latest/docs/api/n-api.htm
 provided by Node.js when using C++. It provides a C++ object model
 and exception handling semantics with low overhead.
 
+There are three options for implementing addons: N-API, nan, or direct
+use of internal V8, libuv and Node.js libraries. Unless there is a need for
+direct access to functionality which is not exposed by N-API as outlined
+in [C/C++ addons](https://nodejs.org/dist/latest/docs/api/addons.html)
+in Node.js core, use N-API. Refer to
+[C/C++ addons with N-API](https://nodejs.org/dist/latest/docs/api/n-api.html)
+for more information on N-API.
+
 N-API is an ABI stable C interface provided by Node.js for building native
 addons. It is independent from the underlying JavaScript runtime (e.g. V8 or ChakraCore)
 and is maintained as part of Node.js itself. It is intended to insulate
@@ -37,8 +45,8 @@ APIs exposed by node-addon-api are generally used to create and
 manipulate JavaScript values. Concepts and operations generally map
 to ideas specified in the **ECMA262 Language Specification**.
 
-The [N-API Resource](http://nodejs.github.io/node-addon-examples/) offers an 
-excellent orientation and tips for developers just getting started with N-API 
+The [N-API Resource](https://nodejs.github.io/node-addon-examples/) offers an
+excellent orientation and tips for developers just getting started with N-API
 and node-addon-api.
 
 - **[Setup](#setup)**
@@ -51,7 +59,7 @@ and node-addon-api.
 - **[Contributors](#contributors)**
 - **[License](#license)**
 
-## **Current version: 3.0.2**
+## **Current version: 3.1.0**
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
 
@@ -121,7 +129,9 @@ The following is the documentation for node-addon-api.
     - [AsyncWorker](doc/async_worker.md)
     - [AsyncContext](doc/async_context.md)
     - [AsyncWorker Variants](doc/async_worker_variants.md)
- - [Thread-safe Functions](doc/threadsafe_function.md)
+ - [Thread-safe Functions](doc/threadsafe.md)
+    - [ThreadSafeFunction](doc/threadsafe_function.md)
+    - [TypedThreadSafeFunction](doc/typed_threadsafe_function.md)
  - [Promises](doc/promises.md)
  - [Version management](doc/version_management.md)
 
@@ -157,6 +167,15 @@ npm install
 npm test --disable-deprecated
 ```
 
+To run the tests targetting a specific version of N-API run
+```
+npm install
+export NAPI_VERSION=X
+npm test --NAPI_VERSION=X
+```
+
+where X is the version of N-API you want to target.
+
 ### **Debug**
 
 To run the **node-addon-api** tests with `--debug` option:

package/doc/addon.md

@@ -34,16 +34,16 @@ The `Napi::Addon<T>` class can be used together with the `NODE_API_ADDON()` and
 class ExampleAddon : public Napi::Addon<ExampleAddon> {
  public:
   ExampleAddon(Napi::Env env, Napi::Object exports) {
-    // In the constructor we declare the functions the add-on makes avaialable
+    // In the constructor we declare the functions the add-on makes available
     // to JavaScript.
     DefineAddon(exports, {
       InstanceMethod("increment", &ExampleAddon::Increment),
 
       // We can also attach plain objects to `exports`, and instance methods as
       // properties of those sub-objects.
-      InstanceValue("subObject", DefineProperties(Napi::Object::New(), {
-        InstanceMethod("decrement", &ExampleAddon::Decrement
-      })), napi_enumerable)
+      InstanceValue("subObject", DefineProperties(Napi::Object::New(env), {
+        InstanceMethod("decrement", &ExampleAddon::Decrement)
+      }), napi_enumerable)
     });
   }
  private:
@@ -80,7 +80,7 @@ The above code can be used from JavaScript as follows:
 const exampleAddon = require('bindings')('example_addon');
 console.log(exampleAddon.increment()); // prints 43
 console.log(exampleAddon.increment()); // prints 44
-consnole.log(exampleAddon.subObject.decrement()); // prints 43
+console.log(exampleAddon.subObject.decrement()); // prints 43
 ```
 
 When Node.js loads an instance of the add-on, a new instance of the class is

package/doc/array_buffer.md

@@ -130,4 +130,20 @@ void* Napi::ArrayBuffer::Data() const;
 
 Returns a pointer the wrapped data.
 
+### Detach
+
+```cpp
+void Napi::ArrayBuffer::Detach();
+```
+
+Invokes the `ArrayBuffer` detach operation on a detachable `ArrayBuffer`.
+
+### IsDetached
+
+```cpp
+bool Napi::ArrayBuffer::IsDetached() const;
+```
+
+Returns `true` if this `ArrayBuffer` has been detached.
+
 [`Napi::Object`]: ./object.md

package/doc/async_context.md

@@ -73,7 +73,7 @@ void MakeCallbackWithAsyncContext(const Napi::CallbackInfo& info) {
   Napi::Function callback = info[0].As<Napi::Function>();
   Napi::Object resource = info[1].As<Napi::Object>();
 
-  // Creat a new async context instance.
+  // Create a new async context instance.
   Napi::AsyncContext context(info.Env(), "async_context_test", resource);
 
   // Invoke the callback with the async context instance.

package/doc/async_worker.md

@@ -395,7 +395,7 @@ class EchoWorker : public AsyncWorker {
 };
 ```
 
-The `EchoWorker`'s contructor calls the base class' constructor to pass in the
+The `EchoWorker`'s constructor calls the base class' constructor to pass in the
 callback that the `Napi::AsyncWorker` base class will store persistently. When
 the work on the `Napi::AsyncWorker::Execute` method is done the
 `Napi::AsyncWorker::OnOk` method is called and the results return back to