node-addon-api 3.0.0 → 3.2.0

package/package-support.json

@@ -0,0 +1,21 @@
+{
+  "versions": [
+    {
+      "version": "*",
+      "target": {
+        "node": "active"
+      },
+      "response": {
+        "type": "time-permitting",
+        "paid": false,
+        "contact": {
+          "name": "node-addon-api team",
+          "url": "https://github.com/nodejs/node-addon-api/issues"
+        }
+      },
+      "backing": [ { "project": "https://github.com/nodejs" },
+                   { "foundation": "https://openjsf.org/" }
+      ]
+    }
+  ]
+}

package/package.json

@@ -51,6 +51,10 @@
       "name": "Bill Gallafent",
       "url": "https://github.com/gallafent"
     },
+    {
+      "name": "blagoev",
+      "url": "https://github.com/blagoev"
+    },
     {
       "name": "Bruce A. MacNaughton",
       "url": "https://github.com/bmacnaughton"
@@ -59,6 +63,14 @@
       "name": "Cory Mickelson",
       "url": "https://github.com/corymickelson"
     },
+    {
+      "name": "Daniel Bevenius",
+      "url": "https://github.com/danbev"
+    },
+    {
+      "name": "Darshan Sen",
+      "url": "https://github.com/RaisinTen"
+    },
     {
       "name": "David Halls",
       "url": "https://github.com/davedoesdev"
@@ -71,6 +83,10 @@
       "name": "Dongjin Na",
       "url": "https://github.com/nadongguri"
     },
+    {
+      "name": "Ferdinand Holzer",
+      "url": "https://github.com/fholzer"
+    },
     {
       "name": "Eric Bickle",
       "url": "https://github.com/ebickle"
@@ -87,6 +103,10 @@
       "name": "Gus Caplan",
       "url": "https://github.com/devsnek"
     },
+    {
+      "name": "Helio Frota",
+      "url": "https://github.com/helio-frota"
+    },
     {
       "name": "Hitesh Kanwathirtha",
       "url": "https://github.com/digitalinfinity"
@@ -95,6 +115,10 @@
       "name": "ikokostya",
       "url": "https://github.com/ikokostya"
     },
+    {
+      "name": "Jack Xia",
+      "url": "https://github.com/JckXia"
+    },
     {
       "name": "Jake Barnes",
       "url": "https://github.com/DuBistKomisch"
@@ -107,6 +131,10 @@
       "name": "Jason Ginchereau",
       "url": "https://github.com/jasongin"
     },
+    {
+      "name": "Jeroen Janssen",
+      "url": "https://github.com/japj"
+    },
     {
       "name": "Jim Schlight",
       "url": "https://github.com/jschlight"
@@ -115,10 +143,18 @@
       "name": "Jinho Bang",
       "url": "https://github.com/romandev"
     },
+    {
+      "name": "José Expósito",
+      "url": "https://github.com/JoseExposito"
+    },
     {
       "name": "joshgarde",
       "url": "https://github.com/joshgarde"
     },
+    {
+      "name": "Kasumi Hanazuki",
+      "url": "https://github.com/hanazuki"
+    },
     {
       "name": "Kelvin",
       "url": "https://github.com/kelvinhammond"
@@ -127,6 +163,18 @@
       "name": "Kevin Eady",
       "url": "https://github.com/KevinEady"
     },
+    {
+      "name": "Kévin VOYER",
+      "url": "https://github.com/kecsou"
+    },
+    {
+      "name": "kidneysolo",
+      "url": "https://github.com/kidneysolo"
+    },
+    {
+      "name": "Koki Nishihara",
+      "url": "https://github.com/Nishikoh"
+    },
     {
       "name": "Konstantin Tarkus",
       "url": "https://github.com/koistya"
@@ -139,10 +187,22 @@
       "name": "legendecas",
       "url": "https://github.com/legendecas"
     },
+    {
+      "name": "LongYinan",
+      "url": "https://github.com/Brooooooklyn"
+    },
+    {
+      "name": "Lovell Fuller",
+      "url": "https://github.com/lovell"
+    },
     {
       "name": "Luciano Martorella",
       "url": "https://github.com/lmartorella"
     },
+    {
+      "name": "mastergberry",
+      "url": "https://github.com/mastergberry"
+    },
     {
       "name": "Mathias Küsel",
       "url": "https://github.com/mathiask88"
@@ -167,6 +227,10 @@
       "name": "Mikhail Cheshkov",
       "url": "https://github.com/mcheshkov"
     },
+    {
+      "name": "nempoBu4",
+      "url": "https://github.com/nempoBu4"
+    },
     {
       "name": "Nicola Del Gobbo",
       "url": "https://github.com/NickNaso"
@@ -175,10 +239,18 @@
       "name": "Nick Soggin",
       "url": "https://github.com/iSkore"
     },
+    {
+      "name": "Nikolai Vavilov",
+      "url": "https://github.com/seishun"
+    },
     {
       "name": "Nurbol Alpysbayev",
       "url": "https://github.com/anurbol"
     },
+    {
+      "name": "pacop",
+      "url": "https://github.com/pacop"
+    },
     {
       "name": "Philipp Renoth",
       "url": "https://github.com/DaAitch"
@@ -223,6 +295,10 @@
       "name": "Tux3",
       "url": "https://github.com/tux3"
     },
+    {
+      "name": "Vlad Velmisov",
+      "url": "https://github.com/Velmisov"
+    },
     {
       "name": "Yohei Kishimoto",
       "url": "https://github.com/morokosi"
@@ -230,12 +306,19 @@
     {
       "name": "Yulong Wang",
       "url": "https://github.com/fs-eire"
+    },
+    {
+      "name": "Ziqiu Zhao",
+      "url": "https://github.com/ZzqiZQute"
     }
   ],
-  "dependencies": {},
-  "description": "Node.js API (N-API)",
+  "description": "Node.js API (Node-API)",
   "devDependencies": {
     "benchmark": "^2.1.4",
+    "bindings": "^1.5.0",
+    "clang-format": "^1.4.0",
+    "fs-extra": "^9.0.1",
+    "pre-commit": "^1.2.2",
     "safe-buffer": "^5.1.1"
   },
   "directories": {},
@@ -261,6 +344,11 @@
     "type": "git",
     "url": "git://github.com/nodejs/node-addon-api.git"
   },
+  "files": [
+    "*.{c,h,gyp,gypi}",
+    "package-support.json",
+    "tools/"
+  ],
   "scripts": {
     "prebenchmark": "node-gyp rebuild -C benchmark",
     "benchmark": "node benchmark",
@@ -270,7 +358,11 @@
     "dev": "node test",
     "predev:incremental": "node-gyp configure build -C test --debug",
     "dev:incremental": "node test",
-    "doc": "doxygen doc/Doxyfile"
+    "doc": "doxygen doc/Doxyfile",
+    "lint": "node tools/clang-format",
+    "lint:fix": "node tools/clang-format --fix"
   },
-  "version": "3.0.0"
+  "pre-commit": "lint",
+  "version": "3.2.0",
+  "support": true
 }

package/tools/README.md

@@ -1,4 +1,10 @@
-# Migration Script
+# Tools
+
+## clang-format
+
+The clang-format checking tools is designed to check changed lines of code compared to given git-refs.
+
+## Migration Script
 
 The migration tool is designed to reduce repetitive work in the migration process. However, the script is not aiming to convert every thing for you. There are usually some small fixes and major reconstruction required.
 
@@ -42,7 +48,7 @@ and define it as
 This way, the `Napi::ObjectWrap` constructor will be invoked after the object has been instantiated and `Napi::ObjectWrap` can use the `this` pointer to create a reference to the wrapped object.
 
   2. Move your original constructor code into the new constructor. Delete your original constructor.
-  3. In your class initialization function, associate native methods in the following way. The `&` character before methods is required because they are not static methods but instance methods.
+  3. In your class initialization function, associate native methods in the following way.
 ```
 Napi::FunctionReference constructor;
 

package/tools/clang-format.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+
+const spawn = require('child_process').spawnSync;
+const path = require('path');
+
+const filesToCheck = ['*.h', '*.cc'];
+const CLANG_FORMAT_START = process.env.CLANG_FORMAT_START || 'main';
+
+function main(args) {
+  let fix = false;
+  while (args.length > 0) {
+    switch (args[0]) {
+      case '-f':
+      case '--fix':
+        fix = true;
+      default:
+    }
+    args.shift();
+  }
+
+  let clangFormatPath = path.dirname(require.resolve('clang-format'));
+  const options = ['--binary=node_modules/.bin/clang-format', '--style=file'];
+  if (fix) {
+    options.push(CLANG_FORMAT_START);
+  } else {
+    options.push('--diff', CLANG_FORMAT_START);
+  }
+
+  const gitClangFormatPath = path.join(clangFormatPath,
+    'bin/git-clang-format');
+  const result = spawn('python', [
+    gitClangFormatPath,
+    ...options,
+    '--',
+    ...filesToCheck
+  ], { encoding: 'utf-8' });
+
+  if (result.stderr) {
+    console.error('Error running git-clang-format:', result.stderr);
+    return 2;
+  }
+
+  const clangFormatOutput = result.stdout.trim();
+  // Bail fast if in fix mode.
+  if (fix) {
+    console.log(clangFormatOutput);
+    return 0;
+  }
+  // Detect if there is any complains from clang-format
+  if (clangFormatOutput !== '' &&
+      clangFormatOutput !== ('no modified files to format') &&
+      clangFormatOutput !== ('clang-format did not modify any files')) {
+    console.error(clangFormatOutput);
+    const fixCmd = 'npm run lint:fix';
+    console.error(`
+      ERROR: please run "${fixCmd}" to format changes in your commit
+        Note that when running the command locally, please keep your local
+        main branch and working branch up to date with nodejs/node-addon-api
+        to exclude un-related complains.
+        Or you can run "env CLANG_FORMAT_START=upstream/main ${fixCmd}".`);
+    return 1;
+  }
+}
+
+if (require.main === module) {
+  process.exitCode = main(process.argv.slice(2));
+}

package/tools/conversion.js

@@ -22,8 +22,8 @@ if (disable != "--disable" && dir != "--disable") {
        [ /[ ]*"nan": *"[^"]+"(,|)[\n\r]/g, '' ]
     ],
     'binding.gyp': [
-       [ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1  \'<!@(node -p "require(\\\'node-addon-api\\\').include")\',' ],
-       [ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1  "<!@(node -p \\"require(\'node-addon-api\').include\\")",' ],
+       [ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1  \'<!(node -p "require(\\\'node-addon-api\\\').include_dir")\',' ],
+       [ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1  "<!(node -p \\"require(\'node-addon-api\').include_dir\\")",' ],
        [ /[ ]*("|')<!\(node -e ("|'|\\"|\\')require\(("|'|\\"|\\')nan("|'|\\"|\\')\)("|'|\\"|\\')\)("|')(,|)[\r\n]/g, '' ],
        [ /([ ]*)("|')target_name("|'): ("|')(.+?)("|'),/g, '$1$2target_name$2: $4$5$6,\n      $2cflags!$2: [ $2-fno-exceptions$2 ],\n      $2cflags_cc!$2: [ $2-fno-exceptions$2 ],\n      $2xcode_settings$2: { $2GCC_ENABLE_CPP_EXCEPTIONS$2: $2YES$2,\n        $2CLANG_CXX_LIBRARY$2: $2libc++$2,\n        $2MACOSX_DEPLOYMENT_TARGET$2: $210.7$2,\n      },\n      $2msvs_settings$2: {\n        $2VCCLCompilerTool$2: { $2ExceptionHandling$2: 1 },\n      },' ],
     ]
@@ -35,8 +35,8 @@ if (disable != "--disable" && dir != "--disable") {
       [ /[ ]*"nan": *"[^"]+"(,|)[\n\r]/g, '' ]
     ],
     'binding.gyp': [
-      [ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1  \'<!@(node -p "require(\\\'node-addon-api\\\').include")\',' ],
-      [ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1  "<!@(node -p \'require(\\\"node-addon-api\\\").include\')",' ],
+      [ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1  \'<!(node -p "require(\\\'node-addon-api\\\').include_dir")\',' ],
+      [ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1  "<!(node -p \'require(\\\"node-addon-api\\\").include_dir\')",' ],
       [ /[ ]*("|')<!\(node -e ("|'|\\"|\\')require\(("|'|\\"|\\')nan("|'|\\"|\\')\)("|'|\\"|\\')\)("|')(,|)[\r\n]/g, '' ],
       [ /([ ]*)("|')target_name("|'): ("|')(.+?)("|'),/g, '$1$2target_name$2: $4$5$6,\n      $2cflags!$2: [ $2-fno-exceptions$2 ],\n      $2cflags_cc!$2: [ $2-fno-exceptions$2 ],\n      $2defines$2: [ $2NAPI_DISABLE_CPP_EXCEPTIONS$2 ],\n      $2conditions$2: [\n        [\'OS==\"win\"\', { $2defines$2: [ $2_HAS_EXCEPTIONS=1$2 ] }]\n      ]' ],
     ]

package/.editorconfig

@@ -1,8 +0,0 @@
-root = true
-
-[*]
-charset = utf-8
-trim_trailing_whitespace = true
-insert_final_newline = true
-indent_style = space
-indent_size = 2

package/.travis.yml

@@ -1,59 +0,0 @@
-language: c++
-compiler:
-  - clang
-  - gcc
-# For Linux, use an Ubuntu 14 image
-dist: trusty
-os:
-  - linux
-  - osx
-env:
-  global:
-    # https://github.com/jasongin/nvs/blob/master/doc/CI.md
-    - NVS_VERSION=1.4.2
-  matrix:
-    - NODEJS_VERSION=node/10
-    - NODEJS_VERSION=node/12
-    - NODEJS_VERSION=node/14
-    - NODEJS_VERSION=nightly
-matrix:
-  fast_finish: true
-  allow_failures:
-    - env: NODEJS_VERSION=nightly
-sudo: false
-cache:
-  directories:
-    - node_modules
-    - $HOME/.npm
-addons:
-  apt:
-    sources:
-      - ubuntu-toolchain-r-test
-    packages:
-      - g++-4.9
-before_install:
-  # coveralls
-  - pip2 install --user cpp-coveralls
-  # compilers
-  - if [ "$CXX" = "g++" -a "$TRAVIS_OS_NAME" = "linux" ]; then export CXX="g++-4.9" CC="gcc-4.9" AR="gcc-ar-4.9" RANLIB="gcc-ranlib-4.9" NM="gcc-nm-4.9" ; fi
-  - if [ "$CXX" = "clang++" ]; then export NPMOPT=--clang=1 ; fi
-  - export CFLAGS="$CFLAGS -O3 --coverage" LDFLAGS="$LDFLAGS --coverage"
-  - echo "CFLAGS=\"$CFLAGS\" LDFLAGS=\"$LDFLAGS\""
-  # nvs
-  - git clone --branch v$NVS_VERSION --depth 1 https://github.com/jasongin/nvs ~/.nvs
-  - . ~/.nvs/nvs.sh
-  - nvs --version
-  # node.js
-  - nvs add $NODEJS_VERSION
-  - nvs use $NODEJS_VERSION
-  - node --version
-  - npm --version
-install:
-  - npm install $NPMOPT
-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
-after_success:
-  - cpp-coveralls --gcov-options '\-lp' --build-root test/build --exclude test

package/CODE_OF_CONDUCT.md

@@ -1,4 +0,0 @@
-# Code of Conduct
-
-The Node.js Code of Conduct, which applies to this project, can be found at
-https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md.

package/CONTRIBUTING.md

@@ -1,66 +0,0 @@
-# **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/appveyor.yml

@@ -1,48 +0,0 @@
-environment:
-  # https://github.com/jasongin/nvs/blob/master/doc/CI.md
-  NVS_VERSION: 1.4.2
-  fast_finish: true
-  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: nightly
-    - NODEJS_VERSION: chakracore-nightly
-
-matrix:
-  fast_finish: true
-  allow_failures:
-    - NODEJS_VERSION: nightly
-    - NODEJS_VERSION: chakracore-nightly
-
-platform:
-  - x86
-  - x64
-
-install:
-  # nvs
-  - git clone --branch v%NVS_VERSION% --depth 1 https://github.com/jasongin/nvs %LOCALAPPDATA%\nvs
-  - set PATH=%LOCALAPPDATA%\nvs;%PATH%
-  - nvs --version
-  # node.js
-  - nvs add %NODEJS_VERSION%/%PLATFORM%
-  - nvs use %NODEJS_VERSION%/%PLATFORM%
-  - node --version
-  - node -p process.arch
-  - npm --version
-  # app
-  - npm install
-
-test_script:
-  - npm test
-
-build: off
-
-version: "{build}"
-
-cache:
-  - node_modules

package/benchmark/README.md

@@ -1,47 +0,0 @@
-# Benchmarks
-
-## Running the benchmarks
-
-From the parent directory, run
-
-```bash
-npm run-script benchmark
-```
-
-The above script supports the following arguments:
-
-* `--benchmarks=...`: A semicolon-separated list of benchmark names. These names
-    will be mapped to file names in this directory by appending `.js`.
-
-## Adding benchmarks
-
-The steps below should be followed when adding new benchmarks.
-
-0. Decide on a name for the benchmark. This name will be used in several places.
-   This example will use the name `new_benchmark`.
-
-0. Create files `new_benchmark.cc` and `new_benchmark.js` in this directory.
-
-0. Copy an existing benchmark in `binding.gyp` and change the target name prefix
-    and the source file name to `new_benchmark`. This should result in two new
-    targets which look like this:
-
-    ```gyp
-      {
-        'target_name': 'new_benchmark',
-        'sources': [ 'new_benchmark.cc' ],
-        'includes': [ '../except.gypi' ],
-      },
-      {
-        'target_name': 'new_benchmark_noexcept',
-        'sources': [ 'new_benchmark.cc' ],
-        'includes': [ '../noexcept.gypi' ],
-      },
-    ```
-
-    There should always be a pair of targets: one bearing the name of the
-    benchmark and configured with C++ exceptions enabled, and one bearing the
-    same name followed by the suffix `_noexcept` and configured with C++
-    exceptions disabled. This will ensure that the benchmark can be written to
-    cover both the case where C++ exceptions are enabled and the case where they
-    are disabled.

package/benchmark/binding.gyp

@@ -1,25 +0,0 @@
-{
-  'target_defaults': { 'includes': ['../common.gypi'] },
-  'targets': [
-    {
-      'target_name': 'function_args',
-      'sources': [ 'function_args.cc' ],
-      'includes': [ '../except.gypi' ],
-    },
-    {
-      'target_name': 'function_args_noexcept',
-      'sources': [ 'function_args.cc' ],
-      'includes': [ '../noexcept.gypi' ],
-    },
-    {
-      'target_name': 'property_descriptor',
-      'sources': [ 'property_descriptor.cc' ],
-      'includes': [ '../except.gypi' ],
-    },
-    {
-      'target_name': 'property_descriptor_noexcept',
-      'sources': [ 'property_descriptor.cc' ],
-      'includes': [ '../noexcept.gypi' ],
-    },
-  ]
-}