diff --git a/.eslintrc.js b/.eslintrc.js
deleted file mode 100644
index edc9cc529..000000000
--- a/.eslintrc.js
+++ /dev/null
@@ -1,6 +0,0 @@
-module.exports = {
- parserOptions: {
- sourceType: 'script'
- },
- extends: ['semistandard']
-};
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 331778bf3..a420a61ab 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -3,14 +3,26 @@ updates:
- package-ecosystem: github-actions
directory: /
schedule:
- interval: daily
+ interval: weekly
+ groups:
+ all:
+ patterns:
+ - '*'
- package-ecosystem: npm
directory: /
schedule:
- interval: daily
+ interval: weekly
+ groups:
+ all:
+ patterns:
+ - '*'
- package-ecosystem: npm
directory: /test/addon_build/tpl
schedule:
- interval: daily
+ interval: weekly
+ groups:
+ all:
+ patterns:
+ - '*'
diff --git a/.github/workflows/ci-win.yml b/.github/workflows/ci-win.yml
index 738d0354a..4b0ebfb23 100644
--- a/.github/workflows/ci-win.yml
+++ b/.github/workflows/ci-win.yml
@@ -2,6 +2,9 @@ name: Node.js CI Windows Platform
on: [push, pull_request]
+env:
+ PYTHON_VERSION: '3.11'
+
permissions:
contents: read
@@ -9,17 +12,44 @@ jobs:
test:
timeout-minutes: 30
strategy:
+ fail-fast: false
matrix:
- node-version: [ 16.x, 18.x, 20.x ]
+ api_version:
+ - standard
+ - experimental
+ node-version:
+ - 20.x
+ - 22.x
+ - 24.x
+ - 25.x
+ - 26.x
architecture: [x64, x86]
os:
- - windows-2019
- windows-2022
+ - windows-2025
+ exclude:
+ # Skip when node 24.x or 25.x AND architecture is x86 since there is
+ # no published Node.js x86 build for those versions.
+ - node-version: 24.x
+ architecture: x86
+ - node-version: 25.x
+ architecture: x86
+ - node-version: 26.x
+ architecture: x86
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+ - name: Harden Runner
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ - name: Set up Python ${{ env.PYTHON_VERSION }}
+ uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
- name: Use Node.js ${{ matrix.node-version }}
- uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+ uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
with:
node-version: ${{ matrix.node-version }}
architecture: ${{ matrix.architecture }}
@@ -31,6 +61,10 @@ jobs:
run: |
npm install
- name: npm test
+ shell: bash
run: |
+ if [ "${{ matrix.api_version }}" = "experimental" ]; then
+ export NAPI_VERSION=2147483647
+ fi
npm run pretest -- --verbose
node test
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f7b932522..3813c3d62 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2,6 +2,9 @@ name: Node.js CI Unix Platform
on: [push, pull_request]
+env:
+ PYTHON_VERSION: '3.11'
+
permissions:
contents: read
@@ -9,8 +12,17 @@ jobs:
test:
timeout-minutes: 30
strategy:
+ fail-fast: false
matrix:
- node-version: [ 16.x, 18.x, 20.x ]
+ api_version:
+ - standard
+ - experimental
+ node-version:
+ - 20.x
+ - 22.x
+ - 24.x
+ - 25.x
+ - 26.x
os:
- macos-latest
- ubuntu-latest
@@ -22,9 +34,18 @@ jobs:
compiler: gcc # GCC is an alias for clang on the MacOS image.
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+ - name: Harden Runner
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ - name: Set up Python ${{ env.PYTHON_VERSION }}
+ uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
- name: Use Node.js ${{ matrix.node-version }}
- uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+ uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
with:
node-version: ${{ matrix.node-version }}
- name: Check Node.js installation
@@ -36,6 +57,9 @@ jobs:
npm install
- name: npm test
run: |
+ if [ "${{ matrix.api_version }}" = "experimental" ]; then
+ export NAPI_VERSION=2147483647
+ fi
if [ "${{ matrix.compiler }}" = "gcc" ]; then
export CC="gcc" CXX="g++"
fi
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
index bd001f504..8758fdcef 100644
--- a/.github/workflows/codeql.yml
+++ b/.github/workflows/codeql.yml
@@ -41,16 +41,16 @@ jobs:
steps:
- name: Harden Runner
- uses: step-security/harden-runner@03bee3930647ebbf994244c21ddbc0d4933aab4f # v2.3.0
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
with:
egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
- name: Checkout repository
- uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
- uses: github/codeql-action/init@7df0ce34898d659f95c0c4a09eaa8d4e32ee64db # v2.2.12
+ uses: github/codeql-action/init@0d579ffd059c29b07949a3cce3983f0780820c98 # v4.32.6
with:
languages: ${{ matrix.language }}
# If you wish to specify custom queries, you can do so here or in a config file.
@@ -70,7 +70,7 @@ jobs:
- name: Use Node.js v18.x
if: matrix.language == 'cpp'
- uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+ uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
with:
node-version: 18.x
@@ -80,6 +80,6 @@ jobs:
npx node-gyp rebuild -C test
- name: Perform CodeQL Analysis
- uses: github/codeql-action/analyze@7df0ce34898d659f95c0c4a09eaa8d4e32ee64db # v2.2.12
+ uses: github/codeql-action/analyze@0d579ffd059c29b07949a3cce3983f0780820c98 # v4.32.6
with:
category: "/language:${{matrix.language}}"
diff --git a/.github/workflows/coverage-linux.yml b/.github/workflows/coverage-linux.yml
new file mode 100644
index 000000000..3d116e405
--- /dev/null
+++ b/.github/workflows/coverage-linux.yml
@@ -0,0 +1,68 @@
+name: Coverage Linux
+
+on:
+ pull_request:
+ types: [opened, synchronize, reopened]
+ paths-ignore:
+ - '**.md'
+ - benchmark/**
+ - doc/**
+ - tools/**
+ - unit-test/**
+ - .github/**
+ - '!.github/workflows/coverage-linux.yml'
+ push:
+ branches:
+ - main
+ paths-ignore:
+ - '**.md'
+ - benchmark/**
+ - doc/**
+ - tools/**
+ - unit-test/**
+ - .github/**
+ - '!.github/workflows/coverage-linux.yml'
+
+env:
+ PYTHON_VERSION: '3.11'
+ NODE_VERSION: '22.x'
+
+permissions:
+ contents: read
+
+jobs:
+ coverage-linux:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Harden Runner
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ with:
+ persist-credentials: false
+ - name: Set up Python ${{ env.PYTHON_VERSION }}
+ uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
+ - name: Use Node.js ${{ env.NODE_VERSION }}
+ uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+ with:
+ node-version: ${{ env.NODE_VERSION }}
+ - name: Environment Information
+ run: npx envinfo
+ - name: Install gcovr
+ run: pip install gcovr==6.0
+ - name: Install dependencies
+ run: npm install
+ - name: Test with coverage
+ run: |
+ npm run create-coverage
+ - name: Generate coverage report (XML)
+ run: |
+ npm run report-coverage-xml
+ - name: Upload
+ uses: codecov/codecov-action@671740ac38dd9b0130fbe1cec585b89eea48d3de # v5.5.2
+ with:
+ directory: ./coverage-xml
diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml
index b12f53867..8d6513bed 100644
--- a/.github/workflows/dependency-review.yml
+++ b/.github/workflows/dependency-review.yml
@@ -17,11 +17,11 @@ jobs:
runs-on: ubuntu-latest
steps:
- name: Harden Runner
- uses: step-security/harden-runner@03bee3930647ebbf994244c21ddbc0d4933aab4f # v2.3.0
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
with:
egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
- name: 'Checkout Repository'
- uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- name: 'Dependency Review'
- uses: actions/dependency-review-action@0efb1d1d84fc9633afcdaad14c485cbbc90ef46c # v2.5.1
+ uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml
index c96494017..4cd921796 100644
--- a/.github/workflows/linter.yml
+++ b/.github/workflows/linter.yml
@@ -10,17 +10,22 @@ jobs:
if: github.repository == 'nodejs/node-addon-api'
strategy:
matrix:
- node-version: [16.x]
+ node-version: [22.x]
os: [ubuntu-latest]
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+ - name: Harden Runner
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 0
- run: git branch -a
- name: Use Node.js ${{ matrix.node-version }}
- uses: actions/setup-node@64ed1c7eab4cce3362f8c340dee64e5eaeef8f7c # v3.6.0
+ uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
with:
node-version: ${{ matrix.node-version }}
- run: npm install
diff --git a/.github/workflows/node-api-headers.yml b/.github/workflows/node-api-headers.yml
new file mode 100644
index 000000000..59c686348
--- /dev/null
+++ b/.github/workflows/node-api-headers.yml
@@ -0,0 +1,71 @@
+name: Node.js CI with node-api-headers
+
+on: [push, pull_request]
+
+env:
+ PYTHON_VERSION: '3.11'
+
+permissions:
+ contents: read
+
+jobs:
+ test:
+ timeout-minutes: 30
+ strategy:
+ fail-fast: false
+ matrix:
+ api_version:
+ - '9'
+ node-version:
+ - 22.x
+ node-api-headers-version:
+ - '1.1.0'
+ - '1.2.0'
+ - '1.3.0'
+ os:
+ - ubuntu-latest
+ compiler:
+ - gcc
+ - clang
+ runs-on: ${{ matrix.os }}
+ steps:
+ - name: Harden Runner
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ - name: Set up Python ${{ env.PYTHON_VERSION }}
+ uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+ with:
+ python-version: ${{ env.PYTHON_VERSION }}
+ - name: Use Node.js ${{ matrix.node-version }}
+ uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+ with:
+ node-version: ${{ matrix.node-version }}
+ - name: Check Node.js installation
+ run: |
+ node --version
+ npm --version
+ - name: Install dependencies
+ run: |
+ npm install
+ npm install "node-api-headers@${{ matrix.node-api-headers-version }}"
+ - name: npm test
+ run: |
+ export NAPI_VERSION=${{ matrix.api_version }}
+ if [ "${{ matrix.compiler }}" = "gcc" ]; then
+ export CC="gcc" CXX="g++"
+ fi
+ if [ "${{ matrix.compiler }}" = "clang" ]; then
+ export CC="clang" CXX="clang++"
+ fi
+ echo "CC=\"$CC\" CXX=\"$CXX\""
+ echo "$CC --version"
+ $CC --version
+ echo "$CXX --version"
+ $CXX --version
+ export CFLAGS="$CFLAGS -O3 --coverage" LDFLAGS="$LDFLAGS --coverage"
+ export use_node_api_headers=true
+ echo "CFLAGS=\"$CFLAGS\" LDFLAGS=\"$LDFLAGS\""
+ npm run pretest -- --verbose
diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml
new file mode 100644
index 000000000..a6f09719a
--- /dev/null
+++ b/.github/workflows/release-please.yml
@@ -0,0 +1,51 @@
+name: release-please
+
+on:
+ push:
+ branches:
+ - main
+ workflow_dispatch:
+
+permissions:
+ id-token: write # Required for OIDC
+ contents: read
+
+jobs:
+ release-please:
+ runs-on: ubuntu-latest
+ outputs:
+ release_created: ${{ steps.release.outputs.release_created }}
+ permissions:
+ contents: write
+ pull-requests: write
+ steps:
+ - name: Harden Runner
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+ with:
+ egress-policy: audit
+
+ - uses: googleapis/release-please-action@16a9c90856f42705d54a6fda1823352bdc62cf38 # v4.4.0
+ id: release
+ with:
+ config-file: release-please-config.json
+ manifest-file: .release-please-manifest.json
+
+ npm-publish:
+ needs: release-please
+ if: ${{ needs.release-please.outputs.release_created }}
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ id-token: write
+ steps:
+ - name: Harden Runner
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+ with:
+ egress-policy: audit
+
+ - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+ - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+ with:
+ node-version: 24 # npm >= 11.5.1
+ registry-url: 'https://registry.npmjs.org'
+ - run: npm publish --provenance --access public
diff --git a/.github/workflows/scorecards.yml b/.github/workflows/scorecards.yml
index 1bcc9a57c..d902982dc 100644
--- a/.github/workflows/scorecards.yml
+++ b/.github/workflows/scorecards.yml
@@ -31,17 +31,17 @@ jobs:
steps:
- name: Harden Runner
- uses: step-security/harden-runner@03bee3930647ebbf994244c21ddbc0d4933aab4f # v2.3.0
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
with:
egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
- name: "Checkout code"
- uses: actions/checkout@c85c95e3d7251135ab7dc9ce3241c5835cc595a9 # v3.5.3
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- name: "Run analysis"
- uses: ossf/scorecard-action@99c53751e09b9529366343771cc321ec74e9bd3d # v2.0.6
+ uses: ossf/scorecard-action@4eaacf0543bb3f2c246792bd56e8cdeffafb205a # v2.4.3
with:
results_file: results.sarif
results_format: sarif
@@ -63,7 +63,7 @@ jobs:
# Upload the results as artifacts (optional). Commenting out will disable uploads of run results in SARIF
# format to the repository Actions tab.
- name: "Upload artifact"
- uses: actions/upload-artifact@0b7f8abb1508181956e8e162db84b466c27e18ce # v3.1.2
+ uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
with:
name: SARIF file
path: results.sarif
@@ -71,6 +71,6 @@ jobs:
# Upload the results to GitHub's code scanning dashboard.
- name: "Upload to code-scanning"
- uses: github/codeql-action/upload-sarif@7df0ce34898d659f95c0c4a09eaa8d4e32ee64db # v2.2.12
+ uses: github/codeql-action/upload-sarif@0d579ffd059c29b07949a3cce3983f0780820c98 # v4.32.6
with:
sarif_file: results.sarif
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
index 183792d49..7554cf154 100644
--- a/.github/workflows/stale.yml
+++ b/.github/workflows/stale.yml
@@ -13,7 +13,12 @@ jobs:
pull-requests: write # for actions/stale to close stale PRs
runs-on: ubuntu-latest
steps:
- - uses: actions/stale@f7176fd3007623b69d27091f9b9d4ab7995f0a06 # v5.2.1
+ - name: Harden Runner
+ uses: step-security/harden-runner@58077d3c7e43986b6b15fba718e8ea69e387dfcc # v2.15.1
+ with:
+ egress-policy: audit
+
+ - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
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.'
diff --git a/.gitignore b/.gitignore
index b1233109f..a154db646 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,4 +3,20 @@
/benchmark/build
/benchmark/src
/test/addon_build/addons
+/test/require_basic_finalizers/addons
/.vscode
+
+# ignore node-gyp generated files outside its build directory
+/test/*.Makefile
+/test/*.mk
+
+# ignore node-gyp generated Visual Studio files
+*.vcxproj
+*.vcxproj.filters
+*.vcxproj.user
+*.vsidx
+*.sln
+*.suo
+/test/.vs/
+/test/Release/
+/test/Debug/
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
new file mode 100644
index 000000000..6139450aa
--- /dev/null
+++ b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+ ".": "8.8.0"
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e0477814e..7917ee681 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,209 @@
# node-addon-api Changelog
+## [8.8.0](https://github.com/nodejs/node-addon-api/compare/v8.7.0...v8.8.0) (2026-05-13)
+
+
+### Features
+
+* add std::string_view overload for Symbol::For ([#1722](https://github.com/nodejs/node-addon-api/issues/1722)) ([f65113b](https://github.com/nodejs/node-addon-api/commit/f65113b6ce54271b0a26f97fc624b5574b64a048))
+* add String::New overload for string_view ([#1706](https://github.com/nodejs/node-addon-api/issues/1706)) ([0add130](https://github.com/nodejs/node-addon-api/commit/0add1306f60b81432da94d13683aa0b06aa52925))
+
+## [8.7.0](https://github.com/nodejs/node-addon-api/compare/v8.6.0...v8.7.0) (2026-03-23)
+
+
+### Features
+
+* add Date::New overload for a std::chrono::system_clock::time_point ([#1705](https://github.com/nodejs/node-addon-api/issues/1705)) ([7fb063d](https://github.com/nodejs/node-addon-api/commit/7fb063d95ff5ef816d1616f9acf4afac854cfd4c))
+* add Object::GetPrototype and Object::SetPrototype ([#1715](https://github.com/nodejs/node-addon-api/issues/1715)) ([967bbd5](https://github.com/nodejs/node-addon-api/commit/967bbd5911c7e90b428d4769b9ab1b1a0cee4451)), closes [#1691](https://github.com/nodejs/node-addon-api/issues/1691)
+* add support for SharedArrayBuffer in DataViews ([#1714](https://github.com/nodejs/node-addon-api/issues/1714)) ([7b8d69e](https://github.com/nodejs/node-addon-api/commit/7b8d69e0ba912291aea0b337f7f1814b1032f7f0))
+
+
+### Bug Fixes
+
+* add missing const to ObjectReference::Set string parameter ([#1713](https://github.com/nodejs/node-addon-api/issues/1713)) ([845ba8e](https://github.com/nodejs/node-addon-api/commit/845ba8e4b0888ca20ed3f7c95f9d461cbce338c5))
+* fix -Wextra-semi ([#1718](https://github.com/nodejs/node-addon-api/issues/1718)) ([7fef973](https://github.com/nodejs/node-addon-api/commit/7fef9739166ebb89263459e9f4c3363678cd6367))
+
+## [8.6.0](https://github.com/nodejs/node-addon-api/compare/v8.5.0...v8.6.0) (2026-01-30)
+
+
+### Features
+
+* add SharedArrayBuffer ([#1688](https://github.com/nodejs/node-addon-api/issues/1688)) ([220bee2](https://github.com/nodejs/node-addon-api/commit/220bee244fae2e36405bf2bda33cb3985a846912))
+* silence a legitimate vfptr sanitizer warning that is on by default in Android NDK 29 ([#1692](https://github.com/nodejs/node-addon-api/issues/1692)) ([46673f4](https://github.com/nodejs/node-addon-api/commit/46673f403adf799cc73419427dd3cf166badff22))
+
+## [8.5.0](https://github.com/nodejs/node-addon-api/compare/v8.4.0...v8.5.0) (2025-07-04)
+
+
+### Features
+
+* add Then and Catch methods to Promise ([#1668](https://github.com/nodejs/node-addon-api/issues/1668)) ([ab3e5fe](https://github.com/nodejs/node-addon-api/commit/ab3e5fe59570cbb5ed7cc9891b3f25fe373f028f))
+
+## [8.4.0](https://github.com/nodejs/node-addon-api/compare/v8.3.1...v8.4.0) (2025-06-11)
+
+
+### Features
+
+* add sugar method for PropertyLValue ([#1651](https://github.com/nodejs/node-addon-api/issues/1651)) ([#1655](https://github.com/nodejs/node-addon-api/issues/1655)) ([1e57a0a](https://github.com/nodejs/node-addon-api/commit/1e57a0ae82786c320c784ec6b67f357c85733132))
+
+## [8.3.1](https://github.com/nodejs/node-addon-api/compare/v8.3.0...v8.3.1) (2025-02-18)
+
+
+### Bug Fixes
+
+* add missing `stdexcept` include to test ([#1634](https://github.com/nodejs/node-addon-api/issues/1634)) ([14c1a4f](https://github.com/nodejs/node-addon-api/commit/14c1a4f28278c5b02d0ea910061aad4312bb701e))
+* node-api version 10 support ([#1641](https://github.com/nodejs/node-addon-api/issues/1641)) ([932ad15](https://github.com/nodejs/node-addon-api/commit/932ad1503f7a3402716178a91879b5ab850a61b0))
+
+## [8.3.0](https://github.com/nodejs/node-addon-api/compare/v8.2.2...v8.3.0) (2024-11-29)
+
+
+### Features
+
+* allow catching all exceptions ([#1593](https://github.com/nodejs/node-addon-api/issues/1593)) ([c679f6f](https://github.com/nodejs/node-addon-api/commit/c679f6f4c9dc6bf9fc0d99cbe5982bd24a5e2c7b))
+
+## [8.2.2](https://github.com/nodejs/node-addon-api/compare/v8.2.1...v8.2.2) (2024-11-07)
+
+
+### Bug Fixes
+
+* mark external memory and version APIs as basic ([#1597](https://github.com/nodejs/node-addon-api/issues/1597)) ([78da4fa](https://github.com/nodejs/node-addon-api/commit/78da4fa2251af1e4de16efac94d92388f117ae6e))
+* missing napi_delete_reference on ObjectWrap ref ([#1607](https://github.com/nodejs/node-addon-api/issues/1607)) ([98aae33](https://github.com/nodejs/node-addon-api/commit/98aae3343c3af36b4befd6b67c4cb19ba49b8d20))
+
+## [8.2.1](https://github.com/nodejs/node-addon-api/compare/v8.2.0...v8.2.1) (2024-10-09)
+
+
+### Bug Fixes
+
+* failed type cast checks in Symbol::WellKnown ([#1581](https://github.com/nodejs/node-addon-api/issues/1581)) ([d8523a7](https://github.com/nodejs/node-addon-api/commit/d8523a708030a0a3abb9d7832051c70e2dafac3d))
+* missing node_api_nogc_env definition ([#1585](https://github.com/nodejs/node-addon-api/issues/1585)) ([6ba3891](https://github.com/nodejs/node-addon-api/commit/6ba3891954d8b56215d133e54a86cb621e476b9e))
+
+## [8.2.0](https://github.com/nodejs/node-addon-api/compare/v8.1.0...v8.2.0) (2024-09-19)
+
+
+### Features
+
+* add support for nogc types via `BasicEnv` ([#1514](https://github.com/nodejs/node-addon-api/issues/1514)) ([b4aeecb](https://github.com/nodejs/node-addon-api/commit/b4aeecb046480eeaaf1c578a140f71ac0e77094f))
+* add support for requiring basic finalizers ([#1568](https://github.com/nodejs/node-addon-api/issues/1568)) ([7bcb826](https://github.com/nodejs/node-addon-api/commit/7bcb826aa4323f450b3c58f9c7fb34243ff13f77))
+
+
+### Bug Fixes
+
+* call base basic finalizer if none defined ([#1574](https://github.com/nodejs/node-addon-api/issues/1574)) ([294a43f](https://github.com/nodejs/node-addon-api/commit/294a43f8c6a4c79b3295a8f1b83d4782d44cfe74))
+
+## [8.1.0](https://github.com/nodejs/node-addon-api/compare/node-addon-api-v8.0.0...node-addon-api-v8.1.0) (2024-07-05)
+
+
+### Features
+
+* Expose version property in public API ([#1479](https://github.com/nodejs/node-addon-api/issues/1479)) ([23bb42b](https://github.com/nodejs/node-addon-api/commit/23bb42b5e47630c9082dddbabea555626571926e))
+* improve messages on CheckCast ([#1507](https://github.com/nodejs/node-addon-api/issues/1507)) ([bf49519](https://github.com/nodejs/node-addon-api/commit/bf49519a4ce08ee5320327c9a0199cd89d5b87b3))
+
+
+### Bug Fixes
+
+* fix compilation for Visual Studio 2022 ([#1492](https://github.com/nodejs/node-addon-api/issues/1492)) ([e011720](https://github.com/nodejs/node-addon-api/commit/e011720010af26ed66638ceac822e5f1c5e43cde))
+* restore ability to run under NAPI_EXPERIMENTAL ([#1409](https://github.com/nodejs/node-addon-api/issues/1409)) ([40bcb09](https://github.com/nodejs/node-addon-api/commit/40bcb09e6b82e7a1164cb3de56cb503d9b5a3d37))
+
+## 2024-03-01 Version 8.0.0, @legendecas
+
+### Notable changes
+
+- Support for Node.js v16.x is no longer maintained.
+
+### Commits
+
+* \[[`df2147a2b6`](https://github.com/nodejs/node-addon-api/commit/df2147a2b6)] - build(deps): bump github/codeql-action from 3.24.3 to 3.24.5 (dependabot\[bot]) [#1455](https://github.com/nodejs/node-addon-api/pull/1455)
+* \[[`eb4fa9b55a`](https://github.com/nodejs/node-addon-api/commit/eb4fa9b55a)] - build(deps): bump actions/dependency-review-action from 4.1.0 to 4.1.3 (dependabot\[bot]) [#1452](https://github.com/nodejs/node-addon-api/pull/1452)
+* \[[`f85e8146bb`](https://github.com/nodejs/node-addon-api/commit/f85e8146bb)] - build(deps): bump github/codeql-action from 3.23.2 to 3.24.3 (dependabot\[bot]) [#1448](https://github.com/nodejs/node-addon-api/pull/1448)
+* \[[`b84deb0d2f`](https://github.com/nodejs/node-addon-api/commit/b84deb0d2f)] - build(deps): bump actions/dependency-review-action from 4.0.0 to 4.1.0 (dependabot\[bot]) [#1447](https://github.com/nodejs/node-addon-api/pull/1447)
+* \[[`7dcee380cd`](https://github.com/nodejs/node-addon-api/commit/7dcee380cd)] - build(deps): bump actions/setup-node from 4.0.1 to 4.0.2 (dependabot\[bot]) [#1444](https://github.com/nodejs/node-addon-api/pull/1444)
+* \[[`a727b629fe`](https://github.com/nodejs/node-addon-api/commit/a727b629fe)] - build(deps): bump actions/upload-artifact from 4.3.0 to 4.3.1 (dependabot\[bot]) [#1443](https://github.com/nodejs/node-addon-api/pull/1443)
+* \[[`ea712094e3`](https://github.com/nodejs/node-addon-api/commit/ea712094e3)] - build(deps): bump step-security/harden-runner from 2.6.1 to 2.7.0 (dependabot\[bot]) [#1440](https://github.com/nodejs/node-addon-api/pull/1440)
+* \[[`898e5006a5`](https://github.com/nodejs/node-addon-api/commit/898e5006a5)] - build(deps): bump github/codeql-action from 3.23.1 to 3.23.2 (dependabot\[bot]) [#1439](https://github.com/nodejs/node-addon-api/pull/1439)
+* \[[`66e6e0e4b6`](https://github.com/nodejs/node-addon-api/commit/66e6e0e4b6)] - build(deps): bump actions/upload-artifact from 4.0.0 to 4.3.0 (dependabot\[bot]) [#1438](https://github.com/nodejs/node-addon-api/pull/1438)
+* \[[`f1ca4ccd7f`](https://github.com/nodejs/node-addon-api/commit/f1ca4ccd7f)] - build(deps): bump actions/dependency-review-action from 3.1.5 to 4.0.0 (dependabot\[bot]) [#1433](https://github.com/nodejs/node-addon-api/pull/1433)
+* \[[`c58112d52e`](https://github.com/nodejs/node-addon-api/commit/c58112d52e)] - build(deps): bump github/codeql-action from 3.23.0 to 3.23.1 (dependabot\[bot]) [#1430](https://github.com/nodejs/node-addon-api/pull/1430)
+* \[[`f1b9c0bc24`](https://github.com/nodejs/node-addon-api/commit/f1b9c0bc24)] - **chore**: remove v16.x regular CI runs (Chengzhong Wu) [#1437](https://github.com/nodejs/node-addon-api/pull/1437)
+* \[[`c6561d90d6`](https://github.com/nodejs/node-addon-api/commit/c6561d90d6)] - **chore**: reduce dependabot noise (Chengzhong Wu) [#1436](https://github.com/nodejs/node-addon-api/pull/1436)
+* \[[`42931eeba6`](https://github.com/nodejs/node-addon-api/commit/42931eeba6)] - **doc**: reorganize readme (Chengzhong Wu) [#1441](https://github.com/nodejs/node-addon-api/pull/1441)
+* \[[`3b9f3db14e`](https://github.com/nodejs/node-addon-api/commit/3b9f3db14e)] - **doc**: update changelog maker commands (Chengzhong Wu) [#1431](https://github.com/nodejs/node-addon-api/pull/1431)
+* \[[`034c039298`](https://github.com/nodejs/node-addon-api/commit/034c039298)] - **test**: heed npm\_config\_debug (Gabriel Schulhof) [#1445](https://github.com/nodejs/node-addon-api/pull/1445)
+
+## 2024-01-18 Version 7.1.0, @legendecas
+
+### Notable changes
+
+#### API
+
+- Add Env::GetModuleFileName
+- Add SyntaxError
+- Allow NAPI\_VERSION env var and templatize AttachData callback
+- Add common gyp dependency targets.
+
+### Commits
+
+* \[[`864fed488c`](https://github.com/nodejs/node-addon-api/commit/864fed488c)] - build(deps): bump github/codeql-action from 3.22.12 to 3.23.0 (dependabot\[bot]) [#1428](https://github.com/nodejs/node-addon-api/pull/1428)
+* \[[`81a8d43130`](https://github.com/nodejs/node-addon-api/commit/81a8d43130)] - build(deps): bump actions/dependency-review-action from 3.1.4 to 3.1.5 (dependabot\[bot]) [#1427](https://github.com/nodejs/node-addon-api/pull/1427)
+* \[[`e20088941b`](https://github.com/nodejs/node-addon-api/commit/e20088941b)] - build(deps): bump github/codeql-action from 3.22.11 to 3.22.12 (dependabot\[bot]) [#1426](https://github.com/nodejs/node-addon-api/pull/1426)
+* \[[`76c7b12e4e`](https://github.com/nodejs/node-addon-api/commit/76c7b12e4e)] - build(deps): bump actions/setup-node from 4.0.0 to 4.0.1 (dependabot\[bot]) [#1425](https://github.com/nodejs/node-addon-api/pull/1425)
+* \[[`cd58edde1d`](https://github.com/nodejs/node-addon-api/commit/cd58edde1d)] - build(deps): bump actions/upload-artifact from 3.1.3 to 4.0.0 (dependabot\[bot]) [#1424](https://github.com/nodejs/node-addon-api/pull/1424)
+* \[[`0fd1b9e0e1`](https://github.com/nodejs/node-addon-api/commit/0fd1b9e0e1)] - build(deps): bump github/codeql-action from 2.22.8 to 3.22.11 (dependabot\[bot]) [#1423](https://github.com/nodejs/node-addon-api/pull/1423)
+* \[[`c181b19d68`](https://github.com/nodejs/node-addon-api/commit/c181b19d68)] - build(deps): bump actions/stale from 8.0.0 to 9.0.0 (dependabot\[bot]) [#1418](https://github.com/nodejs/node-addon-api/pull/1418)
+* \[[`6fa67791a1`](https://github.com/nodejs/node-addon-api/commit/6fa67791a1)] - build(deps): bump actions/setup-python from 4.7.1 to 5.0.0 (dependabot\[bot]) [#1417](https://github.com/nodejs/node-addon-api/pull/1417)
+* \[[`1fff346fa6`](https://github.com/nodejs/node-addon-api/commit/1fff346fa6)] - build(deps): bump actions/dependency-review-action from 3.1.3 to 3.1.4 (dependabot\[bot]) [#1415](https://github.com/nodejs/node-addon-api/pull/1415)
+* \[[`ecb9690fe5`](https://github.com/nodejs/node-addon-api/commit/ecb9690fe5)] - build(deps): bump github/codeql-action from 2.22.7 to 2.22.8 (dependabot\[bot]) [#1414](https://github.com/nodejs/node-addon-api/pull/1414)
+* \[[`969547b871`](https://github.com/nodejs/node-addon-api/commit/969547b871)] - build(deps): bump github/codeql-action from 2.22.5 to 2.22.7 (dependabot\[bot]) [#1413](https://github.com/nodejs/node-addon-api/pull/1413)
+* \[[`183d1522a9`](https://github.com/nodejs/node-addon-api/commit/183d1522a9)] - build(deps): bump step-security/harden-runner from 2.6.0 to 2.6.1 (dependabot\[bot]) [#1412](https://github.com/nodejs/node-addon-api/pull/1412)
+* \[[`25f977724a`](https://github.com/nodejs/node-addon-api/commit/25f977724a)] - build(deps): bump actions/dependency-review-action from 3.1.0 to 3.1.3 (dependabot\[bot]) [#1410](https://github.com/nodejs/node-addon-api/pull/1410)
+* \[[`f6d125a407`](https://github.com/nodejs/node-addon-api/commit/f6d125a407)] - build(deps): bump actions/setup-python from 4.7.0 to 4.7.1 (dependabot\[bot]) [#1406](https://github.com/nodejs/node-addon-api/pull/1406)
+* \[[`ce78a39ec7`](https://github.com/nodejs/node-addon-api/commit/ce78a39ec7)] - build(deps): bump github/codeql-action from 2.22.4 to 2.22.5 (dependabot\[bot]) [#1400](https://github.com/nodejs/node-addon-api/pull/1400)
+* \[[`dc211ebb48`](https://github.com/nodejs/node-addon-api/commit/dc211ebb48)] - build(deps): bump actions/setup-node from 3.8.1 to 4.0.0 (dependabot\[bot]) [#1398](https://github.com/nodejs/node-addon-api/pull/1398)
+* \[[`cab559e3bd`](https://github.com/nodejs/node-addon-api/commit/cab559e3bd)] - build(deps): bump ossf/scorecard-action from 2.3.0 to 2.3.1 (dependabot\[bot]) [#1397](https://github.com/nodejs/node-addon-api/pull/1397)
+* \[[`f71ff5582d`](https://github.com/nodejs/node-addon-api/commit/f71ff5582d)] - build(deps): bump github/codeql-action from 2.22.3 to 2.22.4 (dependabot\[bot]) [#1396](https://github.com/nodejs/node-addon-api/pull/1396)
+* \[[`21c1d08680`](https://github.com/nodejs/node-addon-api/commit/21c1d08680)] - build(deps): bump actions/checkout from 4.1.0 to 4.1.1 (dependabot\[bot]) [#1394](https://github.com/nodejs/node-addon-api/pull/1394)
+* \[[`e4eec0939c`](https://github.com/nodejs/node-addon-api/commit/e4eec0939c)] - build(deps): bump github/codeql-action from 2.21.9 to 2.22.3 (dependabot\[bot]) [#1393](https://github.com/nodejs/node-addon-api/pull/1393)
+* \[[`94f3459474`](https://github.com/nodejs/node-addon-api/commit/94f3459474)] - build(deps): bump ossf/scorecard-action from 2.2.0 to 2.3.0 (dependabot\[bot]) [#1388](https://github.com/nodejs/node-addon-api/pull/1388)
+* \[[`90a741ef10`](https://github.com/nodejs/node-addon-api/commit/90a741ef10)] - build(deps): bump step-security/harden-runner from 2.5.1 to 2.6.0 (dependabot\[bot]) [#1386](https://github.com/nodejs/node-addon-api/pull/1386)
+* \[[`7e1aa06132`](https://github.com/nodejs/node-addon-api/commit/7e1aa06132)] - Update LICENSE.md (Michael Dawson) [#1385](https://github.com/nodejs/node-addon-api/pull/1385)
+* \[[`0a0612362e`](https://github.com/nodejs/node-addon-api/commit/0a0612362e)] - build(deps): bump github/codeql-action from 2.21.7 to 2.21.9 (dependabot\[bot]) [#1384](https://github.com/nodejs/node-addon-api/pull/1384)
+* \[[`47bd430da2`](https://github.com/nodejs/node-addon-api/commit/47bd430da2)] - build(deps): bump actions/checkout from 4.0.0 to 4.1.0 (dependabot\[bot]) [#1383](https://github.com/nodejs/node-addon-api/pull/1383)
+* \[[`b3f7f73cb9`](https://github.com/nodejs/node-addon-api/commit/b3f7f73cb9)] - build(deps): bump actions/dependency-review-action from 3.0.8 to 3.1.0 (dependabot\[bot]) [#1377](https://github.com/nodejs/node-addon-api/pull/1377)
+* \[[`12c1655387`](https://github.com/nodejs/node-addon-api/commit/12c1655387)] - build(deps): bump github/codeql-action from 2.21.6 to 2.21.7 (dependabot\[bot]) [#1380](https://github.com/nodejs/node-addon-api/pull/1380)
+* \[[`6abed318e4`](https://github.com/nodejs/node-addon-api/commit/6abed318e4)] - build(deps): bump github/codeql-action from 2.21.5 to 2.21.6 (dependabot\[bot]) [#1378](https://github.com/nodejs/node-addon-api/pull/1378)
+* \[[`89eda59930`](https://github.com/nodejs/node-addon-api/commit/89eda59930)] - build(deps): bump actions/upload-artifact from 3.1.2 to 3.1.3 (dependabot\[bot]) [#1376](https://github.com/nodejs/node-addon-api/pull/1376)
+* \[[`90870dbffa`](https://github.com/nodejs/node-addon-api/commit/90870dbffa)] - build(deps): bump actions/checkout from 3.6.0 to 4.0.0 (dependabot\[bot]) [#1375](https://github.com/nodejs/node-addon-api/pull/1375)
+* \[[`b860793eff`](https://github.com/nodejs/node-addon-api/commit/b860793eff)] - build(deps): bump github/codeql-action from 2.21.2 to 2.21.5 (dependabot\[bot]) [#1372](https://github.com/nodejs/node-addon-api/pull/1372)
+* \[[`f9b9974b4a`](https://github.com/nodejs/node-addon-api/commit/f9b9974b4a)] - build(deps): bump actions/checkout from 3.5.3 to 3.6.0 (dependabot\[bot]) [#1371](https://github.com/nodejs/node-addon-api/pull/1371)
+* \[[`9596e3de2d`](https://github.com/nodejs/node-addon-api/commit/9596e3de2d)] - build(deps): bump actions/setup-node from 3.7.0 to 3.8.1 (dependabot\[bot]) [#1370](https://github.com/nodejs/node-addon-api/pull/1370)
+* \[[`e969210747`](https://github.com/nodejs/node-addon-api/commit/e969210747)] - build(deps): bump actions/dependency-review-action from 3.0.6 to 3.0.8 (dependabot\[bot]) [#1368](https://github.com/nodejs/node-addon-api/pull/1368)
+* \[[`13ef96a5a9`](https://github.com/nodejs/node-addon-api/commit/13ef96a5a9)] - build(deps): bump step-security/harden-runner from 2.5.0 to 2.5.1 (dependabot\[bot]) [#1364](https://github.com/nodejs/node-addon-api/pull/1364)
+* \[[`9776d148b3`](https://github.com/nodejs/node-addon-api/commit/9776d148b3)] - build(deps): bump github/codeql-action from 2.21.1 to 2.21.2 (dependabot\[bot]) [#1358](https://github.com/nodejs/node-addon-api/pull/1358)
+* \[[`59dc6be097`](https://github.com/nodejs/node-addon-api/commit/59dc6be097)] - build(deps): bump github/codeql-action from 2.21.0 to 2.21.1 (dependabot\[bot]) [#1357](https://github.com/nodejs/node-addon-api/pull/1357)
+* \[[`5e72796cd5`](https://github.com/nodejs/node-addon-api/commit/5e72796cd5)] - build(deps): bump step-security/harden-runner from 2.4.1 to 2.5.0 (dependabot\[bot]) [#1356](https://github.com/nodejs/node-addon-api/pull/1356)
+* \[[`4e62db45e4`](https://github.com/nodejs/node-addon-api/commit/4e62db45e4)] - build(deps): bump github/codeql-action from 2.20.3 to 2.21.0 (dependabot\[bot]) [#1353](https://github.com/nodejs/node-addon-api/pull/1353)
+* \[[`0c093a33e8`](https://github.com/nodejs/node-addon-api/commit/0c093a33e8)] - build(deps): bump github/codeql-action from 2.20.1 to 2.20.3 (dependabot\[bot]) [#1349](https://github.com/nodejs/node-addon-api/pull/1349)
+* \[[`5523b2d3fa`](https://github.com/nodejs/node-addon-api/commit/5523b2d3fa)] - build(deps): bump actions/setup-node from 3.6.0 to 3.7.0 (dependabot\[bot]) [#1348](https://github.com/nodejs/node-addon-api/pull/1348)
+* \[[`afa494ef7f`](https://github.com/nodejs/node-addon-api/commit/afa494ef7f)] - Add Node.js version restrictions (Ingo Fischer) [#1340](https://github.com/nodejs/node-addon-api/pull/1340)
+* \[[`ac4c87f660`](https://github.com/nodejs/node-addon-api/commit/ac4c87f660)] - build(deps): bump ossf/scorecard-action from 2.0.6 to 2.2.0 (dependabot\[bot]) [#1344](https://github.com/nodejs/node-addon-api/pull/1344)
+* \[[`47aeb6689d`](https://github.com/nodejs/node-addon-api/commit/47aeb6689d)] - build(deps): bump github/codeql-action from 2.2.12 to 2.20.1 (dependabot\[bot]) [#1343](https://github.com/nodejs/node-addon-api/pull/1343)
+* \[[`bd45a8fffc`](https://github.com/nodejs/node-addon-api/commit/bd45a8fffc)] - build(deps): bump step-security/harden-runner from 2.3.0 to 2.4.1 (dependabot\[bot]) [#1342](https://github.com/nodejs/node-addon-api/pull/1342)
+* \[[`343a1e1708`](https://github.com/nodejs/node-addon-api/commit/343a1e1708)] - build(deps-dev): bump fs-extra from 9.1.0 to 11.1.1 (dependabot\[bot]) [#1335](https://github.com/nodejs/node-addon-api/pull/1335)
+* \[[`4168c10182`](https://github.com/nodejs/node-addon-api/commit/4168c10182)] - build(deps): bump actions/stale from 5.2.1 to 8.0.0 (dependabot\[bot]) [#1333](https://github.com/nodejs/node-addon-api/pull/1333)
+* \[[`1c182abd1f`](https://github.com/nodejs/node-addon-api/commit/1c182abd1f)] - build(deps): bump actions/dependency-review-action from 2.5.1 to 3.0.6 (dependabot\[bot]) [#1331](https://github.com/nodejs/node-addon-api/pull/1331)
+* \[[`717a61931d`](https://github.com/nodejs/node-addon-api/commit/717a61931d)] - build(deps): bump actions/checkout from 3.5.2 to 3.5.3 (dependabot\[bot]) [#1329](https://github.com/nodejs/node-addon-api/pull/1329)
+* \[[`d605d62c89`](https://github.com/nodejs/node-addon-api/commit/d605d62c89)] - **chore**: lock python version in actions (Chengzhong Wu) [#1403](https://github.com/nodejs/node-addon-api/pull/1403)
+* \[[`734e3f2509`](https://github.com/nodejs/node-addon-api/commit/734e3f2509)] - **doc**: fix rendering of code blocks in list (Tobias Nießen) [#1401](https://github.com/nodejs/node-addon-api/pull/1401)
+* \[[`dfdf6eb6e6`](https://github.com/nodejs/node-addon-api/commit/dfdf6eb6e6)] - **doc**: add missing title IsBigInt (Marx) [#1352](https://github.com/nodejs/node-addon-api/pull/1352)
+* \[[`8850997f38`](https://github.com/nodejs/node-addon-api/commit/8850997f38)] - **doc**: fix typo AsyncProgressWorker::ExecutionProgress (JerryZhongJ) [#1350](https://github.com/nodejs/node-addon-api/pull/1350)
+* \[[`8192a471a1`](https://github.com/nodejs/node-addon-api/commit/8192a471a1)] - **docs**: fixed Broken Links (Ömer AKGÜL) [#1405](https://github.com/nodejs/node-addon-api/pull/1405)
+* \[[`16a18c047a`](https://github.com/nodejs/node-addon-api/commit/16a18c047a)] - **fix**: handle c++ exception in TSFN callback (Chengzhong Wu) [#1345](https://github.com/nodejs/node-addon-api/pull/1345)
+* \[[`ab14347080`](https://github.com/nodejs/node-addon-api/commit/ab14347080)] - **gyp**: add common targets (Chengzhong Wu) [#1389](https://github.com/nodejs/node-addon-api/pull/1389)
+* \[[`fa3518bc08`](https://github.com/nodejs/node-addon-api/commit/fa3518bc08)] - **src**: remove duplicate buffer info calls (Chengzhong Wu) [#1354](https://github.com/nodejs/node-addon-api/pull/1354)
+* \[[`b83e453e6e`](https://github.com/nodejs/node-addon-api/commit/b83e453e6e)] - **src**: add Env::GetModuleFileName (Kevin Eady) [#1327](https://github.com/nodejs/node-addon-api/pull/1327)
+* \[[`d9828c6264`](https://github.com/nodejs/node-addon-api/commit/d9828c6264)] - **src**: add SyntaxError (Kevin Eady) [#1326](https://github.com/nodejs/node-addon-api/pull/1326)
+* \[[`c52e764bb2`](https://github.com/nodejs/node-addon-api/commit/c52e764bb2)] - **src,test,build**: allow NAPI\_VERSION env var and templatize AttachData callback (Gabriel Schulhof) [#1399](https://github.com/nodejs/node-addon-api/pull/1399)
+* \[[`8f028d630a`](https://github.com/nodejs/node-addon-api/commit/8f028d630a)] - **test**: remove experimental flag from bigint (Gabriel Schulhof) [#1395](https://github.com/nodejs/node-addon-api/pull/1395)
+* \[[`414be9e000`](https://github.com/nodejs/node-addon-api/commit/414be9e000)] - **test**: run interfering tests in their own process (Gabriel Schulhof) [#1325](https://github.com/nodejs/node-addon-api/pull/1325)
+
## 2023-06-13 Version 7.0.0, @KevinEady
### Notable changes
@@ -1097,5 +1301,3 @@ yet backported in the previous Node.js version.
* [0a899bf1c5] - doc: update indication of latest version (Michael Dawson) https://github.com/nodejs/node-addon-api/pull/211
* [17c74e5a5e] - n-api: RangeError in napi_create_dataview() (Jinho Bang) https://github.com/nodejs/node-addon-api/pull/214
* [4058a29989] - n-api: fix memory leak in napi_async_destroy() (Jinho Bang) https://github.com/nodejs/node-addon-api/pull/213
-
-
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5c6151d70..663fc2304 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,22 +1,41 @@
+# Contributing to **node-addon-api**
-# Developer's Certificate of Origin 1.1
+* [Code of Conduct](#code-of-conduct)
+* [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin)
+* [Tests](#tests)
+* [Debug](#debug)
+* [Benchmarks](#benchmarks)
+* [node-addon-api Contribution Philosophy](#node-addon-api-contribution-philosophy)
+## Code of Conduct
+
+The Node.js project has a
+[Code of Conduct](https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md)
+to which all contributors must adhere.
+
+See [details on our policy on Code of Conduct](https://github.com/nodejs/node/blob/main/doc/contributing/code-of-conduct.md).
+
+
+
+## Developer's Certificate of Origin 1.1
+
+
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
- have the right to submit it under the open-source license
+ have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
- by me, under the same open-source license (unless I am
+ by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
- person who certified (a), (b), or (c) and I have not modified
+ person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
@@ -24,17 +43,118 @@ By making a contribution to this project, I certify that:
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
+
+
+
+## Tests
+
+To run the **node-addon-api** tests do:
+
+```
+npm install
+npm test
+```
+
+To avoid testing the deprecated portions of the API run
+```
+npm install
+npm test --disable-deprecated
+```
+
+To run the tests targeting a specific version of Node-API run
+```
+npm install
+export NAPI_VERSION=X
+npm test --NAPI_VERSION=X
+```
+
+where X is the version of Node-API you want to target.
+
+To run a subset of the test suite, filter conditions are available.
+The `--filter` option limits which JavaScript test modules are executed by
+`node test`. The default `pretest` step is still `node-gyp rebuild -C test`,
+so `npm test --filter=...` still performs a full rebuild of the test addon
+targets before the filtered tests run.
+
+**Example:**
+ perform the default test rebuild, then run only the `objectwrap` test module
+ ```
+ npm test --filter=objectwrap
+ ```
+
+Multiple test modules can be selected with wildcards.
+
+**Example:**
+perform the default test rebuild, then run all test modules ending with
+`reference`:
+`function_reference`, `object_reference`, and `reference`
+ ```
+ npm test --filter=*reference
+ ```
+
+Multiple filter conditions can be joined to broaden the test selection.
+
+**Example:**
+ perform the default test rebuild, then run all tests under
+ `threadsafe_function` and `typed_threadsafe_function`, and also the
+ `objectwrap` test module
+ ```
+ npm test --filter='*function objectwrap'
+ ```
-# **node-addon-api** Contribution Philosophy
+As an alternative, `ninja` can be used to build the tests. Please
+follow the instructions in [Build with ninja](doc/contributing/build_with_ninja.md).
+
+## Debug
+
+To run the **node-addon-api** tests with `--debug` option:
+
+```
+npm run-script dev
+```
+
+If you want a faster build, you might use the following option:
+
+```
+npm run-script dev:incremental
+```
+
+Take a look and get inspired by our **[test suite](https://github.com/nodejs/node-addon-api/tree/HEAD/test)**
+
+## Benchmarks
+
+You can run the available benchmarks using the following command:
+
+```
+npm run-script benchmark
+```
+
+See [benchmark/README.md](benchmark/README.md) for more details about running and adding benchmarks.
+
+## **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
+- [New APIs](#new-apis)
+- [Source code fixes](#source-changes)
- Additional tests
- Documentation improvements
- Joining the Node-API working group and participating in meetings
-## Source changes
+### New APIs
+
+As new APIs are added to Node-API, node-addon-api must be updated to provide
+wrappers for those new APIs. For this reason, node-addon-api provides
+methods that allow callers to obtain the underlying Node-API handles so
+direct calls to Node-API and the use of the objects/methods provided by
+node-addon-api can be used together. For example, in order to be able
+to use an API for which the node-addon-api does not yet provide a wrapper.
+
+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**.
+
+### Source changes
**node-addon-api** is meant to be a thin convenience wrapper around Node-API. With this
in mind, contributions of any new APIs that wrap around a core Node-API API will
@@ -56,6 +176,7 @@ idioms while writing native addons with **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.
@@ -65,6 +186,7 @@ The downside of the approach is the following:
- More maintenance burden on the Node-API WG core team.
#### Extras Package
+
This involves us spinning up a new package that contains the utility classes
and methods. This has the benefit of having a separate module where helpers
make it easier to implement certain patterns and idioms for native addons
@@ -78,6 +200,7 @@ belongs in **node-addon-api** vs **node-addon-api-extras**)
- Unclear if the maintenance burden on the Node-API WG is reduced or not
#### Ecosystem
+
This doesn't require a ton of up-front work from the Node-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
@@ -90,4 +213,3 @@ The downside of this approach is the following:
authors might not find the right patterns and instead implement things themselves
- There might be greater friction for the Node-API WG in evolving APIs since the
ecosystem would have taken dependencies on the API shape of **node-addon-api**
-
diff --git a/LICENSE.md b/LICENSE.md
index e2fad6667..819d91a5b 100644
--- a/LICENSE.md
+++ b/LICENSE.md
@@ -1,13 +1,9 @@
The MIT License (MIT)
-=====================
-Copyright (c) 2017 Node.js API collaborators
------------------------------------
-
-*Node.js API collaborators listed at *
+Copyright (c) 2017 [Node.js API collaborators](https://github.com/nodejs/node-addon-api#collaborators)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ No newline at end of file
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/README.md b/README.md
index c7c16a162..221592218 100644
--- a/README.md
+++ b/README.md
@@ -1,266 +1,37 @@
-NOTE: The default branch has been renamed!
-master is now named main
+# **node-addon-api module**
-If you have a local clone, you can update it by running:
+[](https://app.codecov.io/gh/nodejs/node-addon-api/tree/main)
-```shell
-git branch -m master main
-git fetch origin
-git branch -u origin/main main
-```
+[](https://nodei.co/npm/node-addon-api/) [](https://nodei.co/npm/node-addon-api/)
-# **node-addon-api module**
This module contains **header-only C++ wrapper classes** which simplify
the use of the C based [Node-API](https://nodejs.org/dist/latest/docs/api/n-api.html)
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: Node-API, nan, or direct
-use of internal V8, libuv, and Node.js libraries. Unless there is a need for
-direct access to functionality that is not exposed by Node-API as outlined
-in [C/C++ addons](https://nodejs.org/dist/latest/docs/api/addons.html)
-in Node.js core, use Node-API. Refer to
-[C/C++ addons with Node-API](https://nodejs.org/dist/latest/docs/api/n-api.html)
-for more information on Node-API.
-
-Node-API is an ABI stable C interface provided by Node.js for building native
-addons. It is independent of the underlying JavaScript runtime (e.g. V8 or ChakraCore)
-and is maintained as part of Node.js itself. It is intended to insulate
-native addons from changes in the underlying JavaScript engine and allow
-modules compiled for one version to run on later versions of Node.js without
-recompilation.
-
-The `node-addon-api` module, which is not part of Node.js, preserves the benefits
-of the Node-API as it consists only of inline code that depends only on the stable API
-provided by Node-API. As such, modules built against one version of Node.js
-using node-addon-api should run without having to be rebuilt with newer versions
-of Node.js.
-
-It is important to remember that *other* Node.js interfaces such as
-`libuv` (included in a project via `#include `) are not ABI-stable across
-Node.js major versions. Thus, an addon must use Node-API and/or `node-addon-api`
-exclusively and build against a version of Node.js that includes an
-implementation of Node-API (meaning an active LTS version of Node.js) in
-order to benefit from ABI stability across Node.js major versions. Node.js
-provides an [ABI stability guide][] containing a detailed explanation of ABI
-stability in general, and the Node-API ABI stability guarantee in particular.
-
-As new APIs are added to Node-API, node-addon-api must be updated to provide
-wrappers for those new APIs. For this reason, node-addon-api provides
-methods that allow callers to obtain the underlying Node-API handles so
-direct calls to Node-API and the use of the objects/methods provided by
-node-addon-api can be used together. For example, in order to be able
-to use an API for which the node-addon-api does not yet provide a wrapper.
-
-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**.
+- [API References](doc/README.md)
+- [Badges](#badges)
+- [Contributing](#contributing)
+- [License](#license)
-The [Node-API Resource](https://nodejs.github.io/node-addon-examples/) offers an
-excellent orientation and tips for developers just getting started with Node-API
-and node-addon-api.
+## API References
-- **[Setup](#setup)**
-- **[API Documentation](#api)**
-- **[Examples](#examples)**
-- **[Tests](#tests)**
-- **[More resource and info about native Addons](#resources)**
-- **[Badges](#badges)**
-- **[Code of Conduct](CODE_OF_CONDUCT.md)**
-- **[Contributors](#contributors)**
-- **[License](#license)**
+API references are available in the [doc](doc/README.md) directory.
-## **Current version: 7.0.0**
+
+## Current version: 8.8.0
+
(See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)
-[](https://nodei.co/npm/node-addon-api/) [](https://nodei.co/npm/node-addon-api/)
-
-
-
node-addon-api is based on [Node-API](https://nodejs.org/api/n-api.html) and supports using different Node-API versions.
This allows addons built with it to run with Node.js versions which support the targeted Node-API version.
**However** the node-addon-api support model is to support only the active LTS Node.js versions. This means that
every year there will be a new major which drops support for the Node.js LTS version which has gone out of service.
-The oldest Node.js version supported by the current version of node-addon-api is Node.js 16.x.
-
-## Setup
- - [Installation and usage](doc/setup.md)
- - [node-gyp](doc/node-gyp.md)
- - [cmake-js](doc/cmake-js.md)
- - [Conversion tool](doc/conversion-tool.md)
- - [Checker tool](doc/checker-tool.md)
- - [Generator](doc/generator.md)
- - [Prebuild tools](doc/prebuild_tools.md)
-
-
-
-### **API Documentation**
-
-The following is the documentation for node-addon-api.
-
- - [Full Class Hierarchy](doc/hierarchy.md)
- - [Addon Structure](doc/addon.md)
- - Data Types:
- - [Env](doc/env.md)
- - [CallbackInfo](doc/callbackinfo.md)
- - [Reference](doc/reference.md)
- - [Value](doc/value.md)
- - [Name](doc/name.md)
- - [Symbol](doc/symbol.md)
- - [String](doc/string.md)
- - [Number](doc/number.md)
- - [Date](doc/date.md)
- - [BigInt](doc/bigint.md)
- - [Boolean](doc/boolean.md)
- - [External](doc/external.md)
- - [Object](doc/object.md)
- - [Array](doc/array.md)
- - [ObjectReference](doc/object_reference.md)
- - [PropertyDescriptor](doc/property_descriptor.md)
- - [Function](doc/function.md)
- - [FunctionReference](doc/function_reference.md)
- - [ObjectWrap](doc/object_wrap.md)
- - [ClassPropertyDescriptor](doc/class_property_descriptor.md)
- - [Buffer](doc/buffer.md)
- - [ArrayBuffer](doc/array_buffer.md)
- - [TypedArray](doc/typed_array.md)
- - [TypedArrayOf](doc/typed_array_of.md)
- - [DataView](doc/dataview.md)
- - [Error Handling](doc/error_handling.md)
- - [Error](doc/error.md)
- - [TypeError](doc/type_error.md)
- - [RangeError](doc/range_error.md)
- - [SyntaxError](doc/syntax_error.md)
- - [Object Lifetime Management](doc/object_lifetime_management.md)
- - [HandleScope](doc/handle_scope.md)
- - [EscapableHandleScope](doc/escapable_handle_scope.md)
- - [Memory Management](doc/memory_management.md)
- - [Async Operations](doc/async_operations.md)
- - [AsyncWorker](doc/async_worker.md)
- - [AsyncContext](doc/async_context.md)
- - [AsyncWorker Variants](doc/async_worker_variants.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)
-
-
-
-### **Examples**
-
-Are you new to **node-addon-api**? Take a look at our **[examples](https://github.com/nodejs/node-addon-examples)**
-
-- **[Hello World](https://github.com/nodejs/node-addon-examples/tree/HEAD/1_hello_world/node-addon-api)**
-- **[Pass arguments to a function](https://github.com/nodejs/node-addon-examples/tree/HEAD/2_function_arguments/node-addon-api)**
-- **[Callbacks](https://github.com/nodejs/node-addon-examples/tree/HEAD/3_callbacks/node-addon-api)**
-- **[Object factory](https://github.com/nodejs/node-addon-examples/tree/HEAD/4_object_factory/node-addon-api)**
-- **[Function factory](https://github.com/nodejs/node-addon-examples/tree/HEAD/5_function_factory/node-addon-api)**
-- **[Wrapping C++ Object](https://github.com/nodejs/node-addon-examples/tree/HEAD/6_object_wrap/node-addon-api)**
-- **[Factory of wrapped object](https://github.com/nodejs/node-addon-examples/tree/HEAD/7_factory_wrap/node-addon-api)**
-- **[Passing wrapped object around](https://github.com/nodejs/node-addon-examples/tree/HEAD/8_passing_wrapped/node-addon-api)**
-
-
-
-### **Tests**
-
-To run the **node-addon-api** tests do:
-
-```
-npm install
-npm test
-```
-
-To avoid testing the deprecated portions of the API run
-```
-npm install
-npm test --disable-deprecated
-```
-
-To run the tests targeting a specific version of Node-API run
-```
-npm install
-export NAPI_VERSION=X
-npm test --NAPI_VERSION=X
-```
-
-where X is the version of Node-API you want to target.
-
-To run a specific unit test, filter conditions are available
-
-**Example:**
- compile and run only tests on objectwrap.cc and objectwrap.js
- ```
- npm run unit --filter=objectwrap
- ```
+The oldest Node.js version supported by the current version of node-addon-api is Node.js 18.x.
-Multiple unit tests cane be selected with wildcards
-
-**Example:**
-compile and run all test files ending with "reference" -> function_reference.cc, object_reference.cc, reference.cc
- ```
- npm run unit --filter=*reference
- ```
-
-Multiple filter conditions can be joined to broaden the test selection
-
-**Example:**
- compile and run all tests under folders threadsafe_function and typed_threadsafe_function and also the objectwrap.cc file
- npm run unit --filter='*function objectwrap'
-
-### **Debug**
-
-To run the **node-addon-api** tests with `--debug` option:
-
-```
-npm run-script dev
-```
-
-If you want a faster build, you might use the following option:
-
-```
-npm run-script dev:incremental
-```
-
-Take a look and get inspired by our **[test suite](https://github.com/nodejs/node-addon-api/tree/HEAD/test)**
-
-### **Benchmarks**
-
-You can run the available benchmarks using the following command:
-
-```
-npm run-script benchmark
-```
-
-See [benchmark/README.md](benchmark/README.md) for more details about running and adding benchmarks.
-
-
-
-### **More resource and info about native Addons**
-- **[C++ Addons](https://nodejs.org/dist/latest/docs/api/addons.html)**
-- **[Node-API](https://nodejs.org/dist/latest/docs/api/n-api.html)**
-- **[Node-API - Next Generation Node API for Native Modules](https://youtu.be/-Oniup60Afs)**
-- **[How We Migrated Realm JavaScript From NAN to Node-API](https://developer.mongodb.com/article/realm-javascript-nan-to-n-api)**
-
-As node-addon-api's core mission is to expose the plain C Node-API as C++
-wrappers, tools that facilitate n-api/node-addon-api providing more
-convenient patterns for developing a Node.js add-on with n-api/node-addon-api
-can be published to NPM as standalone packages. It is also recommended to tag
-such packages with `node-addon-api` to provide more visibility to the community.
-
-Quick links to NPM searches: [keywords:node-addon-api](https://www.npmjs.com/search?q=keywords%3Anode-addon-api).
-
-
-
-### **Other bindings**
-
-- **[napi-rs](https://napi.rs)** - (`Rust`)
-
-
-
-### **Badges**
+## Badges
The use of badges is recommended to indicate the minimum version of Node-API
required for the module. This helps to determine which Node.js major versions are
@@ -279,16 +50,15 @@ available:
-## **Contributing**
+## 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.
-
-
## Team members
### Active
+
| Name | GitHub Link |
| ------------------- | ----------------------------------------------------- |
| Anna Henningsen | [addaleax](https://github.com/addaleax) |
@@ -299,7 +69,12 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on our philosophy around
| Nicola Del Gobbo | [NickNaso](https://github.com/NickNaso) |
| Vladimir Morozov | [vmoroz](https://github.com/vmoroz) |
+
+
+Emeritus
+
### Emeritus
+
| Name | GitHub Link |
| ------------------- | ----------------------------------------------------- |
| Arunesh Chandra | [aruneshchandra](https://github.com/aruneshchandra) |
@@ -311,9 +86,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on our philosophy around
| Sampson Gao | [sampsongao](https://github.com/sampsongao) |
| Taylor Woll | [boingoing](https://github.com/boingoing) |
-
+
+
+## License
Licensed under [MIT](./LICENSE.md)
-[ABI stability guide]: https://nodejs.org/en/docs/guides/abi-stability/
-[Node-API support matrix]: https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api_version_matrix
+[Node-API support matrix]: https://nodejs.org/dist/latest/docs/api/n-api.html#node-api-version-matrix
diff --git a/benchmark/binding.gyp b/benchmark/binding.gyp
index 72f68a13e..879d4a569 100644
--- a/benchmark/binding.gyp
+++ b/benchmark/binding.gyp
@@ -4,22 +4,22 @@
{
'target_name': 'function_args',
'sources': [ 'function_args.cc' ],
- 'includes': [ '../except.gypi' ],
+ 'dependencies': ['../node_addon_api.gyp:node_addon_api_except'],
},
{
'target_name': 'function_args_noexcept',
'sources': [ 'function_args.cc' ],
- 'includes': [ '../noexcept.gypi' ],
+ 'dependencies': ['../node_addon_api.gyp:node_addon_api'],
},
{
'target_name': 'property_descriptor',
'sources': [ 'property_descriptor.cc' ],
- 'includes': [ '../except.gypi' ],
+ 'dependencies': ['../node_addon_api.gyp:node_addon_api_except'],
},
{
'target_name': 'property_descriptor_noexcept',
'sources': [ 'property_descriptor.cc' ],
- 'includes': [ '../noexcept.gypi' ],
+ 'dependencies': ['../node_addon_api.gyp:node_addon_api'],
},
]
}
diff --git a/common.gypi b/common.gypi
index 9be254f0b..5fda7e77a 100644
--- a/common.gypi
+++ b/common.gypi
@@ -1,10 +1,11 @@
{
'variables': {
- 'NAPI_VERSION%': "
+
+## API Documentation
+
+The following is the documentation for node-addon-api.
+
+ - [Full Class Hierarchy](hierarchy.md)
+ - [Addon Structure](addon.md)
+ - Data Types:
+ - [BasicEnv](basic_env.md)
+ - [Env](env.md)
+ - [CallbackInfo](callbackinfo.md)
+ - [Reference](reference.md)
+ - [Value](value.md)
+ - [Name](name.md)
+ - [Symbol](symbol.md)
+ - [String](string.md)
+ - [Number](number.md)
+ - [Date](date.md)
+ - [BigInt](bigint.md)
+ - [Boolean](boolean.md)
+ - [External](external.md)
+ - [Object](object.md)
+ - [Array](array.md)
+ - [ObjectReference](object_reference.md)
+ - [PropertyDescriptor](property_descriptor.md)
+ - [Function](function.md)
+ - [FunctionReference](function_reference.md)
+ - [ObjectWrap](object_wrap.md)
+ - [ClassPropertyDescriptor](class_property_descriptor.md)
+ - [Buffer](buffer.md)
+ - [ArrayBuffer](array_buffer.md)
+ - [SharedArrayBuffer](shared_array_buffer.md)
+ - [TypedArray](typed_array.md)
+ - [TypedArrayOf](typed_array_of.md)
+ - [DataView](dataview.md)
+ - [Error Handling](error_handling.md)
+ - [Error](error.md)
+ - [TypeError](type_error.md)
+ - [RangeError](range_error.md)
+ - [SyntaxError](syntax_error.md)
+ - [Object Lifetime Management](object_lifetime_management.md)
+ - [HandleScope](handle_scope.md)
+ - [EscapableHandleScope](escapable_handle_scope.md)
+ - [Finalization](finalization.md)
+ - [Memory Management](memory_management.md)
+ - [Async Operations](async_operations.md)
+ - [AsyncWorker](async_worker.md)
+ - [AsyncContext](async_context.md)
+ - [AsyncWorker Variants](async_worker_variants.md)
+ - [Thread-safe Functions](threadsafe.md)
+ - [ThreadSafeFunction](threadsafe_function.md)
+ - [TypedThreadSafeFunction](typed_threadsafe_function.md)
+ - [Promises](promises.md)
+ - [Version management](version_management.md)
+
+
+
+## Examples
+
+Are you new to **node-addon-api**? Take a look at our **[examples](https://github.com/nodejs/node-addon-examples)**
+
+- [Hello World](https://github.com/nodejs/node-addon-examples/tree/main/src/1-getting-started/1_hello_world)
+- [Pass arguments to a function](https://github.com/nodejs/node-addon-examples/tree/main/src/1-getting-started/2_function_arguments/node-addon-api)
+- [Callbacks](https://github.com/nodejs/node-addon-examples/tree/main/src/1-getting-started/3_callbacks/node-addon-api)
+- [Object factory](https://github.com/nodejs/node-addon-examples/tree/main/src/1-getting-started/4_object_factory/node-addon-api)
+- [Function factory](https://github.com/nodejs/node-addon-examples/tree/main/src/1-getting-started/5_function_factory/node-addon-api)
+- [Wrapping C++ Object](https://github.com/nodejs/node-addon-examples/tree/main/src/1-getting-started/6_object_wrap/node-addon-api)
+- [Factory of wrapped object](https://github.com/nodejs/node-addon-examples/tree/main/src/1-getting-started/7_factory_wrap/node-addon-api)
+- [Passing wrapped object around](https://github.com/nodejs/node-addon-examples/tree/main/src/2-js-to-native-conversion/8_passing_wrapped/node-addon-api)
+
+
+
+## ABI Stability Guideline
+
+It is important to remember that *other* Node.js interfaces such as
+`libuv` (included in a project via `#include `) are not ABI-stable across
+Node.js major versions. Thus, an addon must use Node-API and/or `node-addon-api`
+exclusively and build against a version of Node.js that includes an
+implementation of Node-API (meaning an active LTS version of Node.js) in
+order to benefit from ABI stability across Node.js major versions. Node.js
+provides an [ABI stability guide][] containing a detailed explanation of ABI
+stability in general, and the Node-API ABI stability guarantee in particular.
+
+
+
+## More resource and info about native Addons
+
+There are three options for implementing addons: Node-API, nan, or direct
+use of internal V8, libuv, and Node.js libraries. Unless there is a need for
+direct access to functionality that is not exposed by Node-API as outlined
+in [C/C++ addons](https://nodejs.org/dist/latest/docs/api/addons.html)
+in Node.js core, use Node-API. Refer to
+[C/C++ addons with Node-API](https://nodejs.org/dist/latest/docs/api/n-api.html)
+for more information on Node-API.
+
+- [C++ Addons](https://nodejs.org/dist/latest/docs/api/addons.html)
+- [Node-API](https://nodejs.org/dist/latest/docs/api/n-api.html)
+- [Node-API - Next Generation Node API for Native Modules](https://youtu.be/-Oniup60Afs)
+- [How We Migrated Realm JavaScript From NAN to Node-API](https://developer.mongodb.com/article/realm-javascript-nan-to-n-api)
+
+As node-addon-api's core mission is to expose the plain C Node-API as C++
+wrappers, tools that facilitate n-api/node-addon-api providing more
+convenient patterns for developing a Node.js add-on with n-api/node-addon-api
+can be published to NPM as standalone packages. It is also recommended to tag
+such packages with `node-addon-api` to provide more visibility to the community.
+
+Quick links to NPM searches: [keywords:node-addon-api](https://www.npmjs.com/search?q=keywords%3Anode-addon-api).
+
+
+
+## Other bindings
+
+- [napi-rs](https://napi.rs) - (`Rust`)
+
+[ABI stability guide]: https://nodejs.org/en/docs/guides/abi-stability/
diff --git a/doc/array.md b/doc/array.md
index 934808ba4..34badc243 100644
--- a/doc/array.md
+++ b/doc/array.md
@@ -9,7 +9,7 @@ around `napi_value` representing a JavaScript Array.
types such as [`Napi::Int32Array`][] and [`Napi::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/HEAD/array_buffer_to_native/node-addon-api).
+`ArrayBuffer` in native code is available [here](https://github.com/nodejs/node-addon-examples/tree/main/src/2-js-to-native-conversion/array_buffer_to_native/node-addon-api).
## Constructor
```cpp
diff --git a/doc/array_buffer.md b/doc/array_buffer.md
index 3be6b42a2..de05e55b3 100644
--- a/doc/array_buffer.md
+++ b/doc/array_buffer.md
@@ -31,13 +31,13 @@ Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
The `Napi::ArrayBuffer` instance does not assume ownership for the data and
expects it to be valid for the lifetime of the instance. Since the
`Napi::ArrayBuffer` is subject to garbage collection this overload is only
-suitable for data which is static and never needs to be freed.
-This factory method will not provide the caller with an opportunity to free the
-data when the `Napi::ArrayBuffer` gets garbage-collected. If you need to free
-the data retained by the `Napi::ArrayBuffer` object please use other
-variants of the `Napi::ArrayBuffer::New` factory method that accept
-`Napi::Finalizer`, which is a function that will be invoked when the
-`Napi::ArrayBuffer` object has been destroyed.
+suitable for data which is static and never needs to be freed. This factory
+method will not provide the caller with an opportunity to free the data when the
+`Napi::ArrayBuffer` gets garbage-collected. If you need to free the data
+retained by the `Napi::ArrayBuffer` object please use other variants of the
+`Napi::ArrayBuffer::New` factory method that accept `Napi::Finalizer`, which is
+a function that will be invoked when the `Napi::ArrayBuffer` object has been
+destroyed. See [Finalization][] for more details.
```cpp
static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength);
@@ -72,9 +72,9 @@ static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
- `[in] externalData`: The pointer to the external data to wrap.
- `[in] byteLength`: The length of the `externalData`, in bytes.
-- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
- destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the
- `externalData` pointer), and return `void`.
+- `[in] finalizeCallback`: A function called when the engine destroys the
+ `Napi::ArrayBuffer` object, implementing `operator()(Napi::BasicEnv, void*)`.
+ See [Finalization][] for more details.
Returns a new `Napi::ArrayBuffer` instance.
@@ -102,11 +102,10 @@ static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
- `[in] externalData`: The pointer to the external data to wrap.
- `[in] byteLength`: The length of the `externalData`, in bytes.
-- `[in] finalizeCallback`: The function to be called when the `Napi::ArrayBuffer` is
- destroyed. It must implement `operator()`, accept an Napi::Env, a `void*` (which is the
- `externalData` pointer) and `Hint*`, and return `void`.
-- `[in] finalizeHint`: The hint to be passed as the second parameter of the
- finalize callback.
+- `[in] finalizeCallback`: A function called when the engine destroys the
+ `Napi::ArrayBuffer` object, implementing `operator()(Napi::BasicEnv, void*,
+ Hint*)`. See [Finalization][] for more details.
+- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
Returns a new `Napi::ArrayBuffer` instance.
@@ -163,3 +162,4 @@ Returns `true` if this `ArrayBuffer` has been detached.
[`Napi::Object`]: ./object.md
[External Buffer]: ./external_buffer.md
+[Finalization]: ./finalization.md
diff --git a/doc/async_worker_variants.md b/doc/async_worker_variants.md
index d2d32af0a..876131aa8 100644
--- a/doc/async_worker_variants.md
+++ b/doc/async_worker_variants.md
@@ -52,9 +52,9 @@ virtual void Napi::AsyncProgressWorker::OnOK();
### OnProgress
This method is invoked when the computation in the
-`Napi::AsyncProgressWorker::ExecutionProcess::Send` method was called during
+`Napi::AsyncProgressWorker::ExecutionProgress::Send` method was called during
worker thread execution. This method can also be triggered via a call to
-`Napi::AsyncProgress[Queue]Worker::ExecutionProcess::Signal`, in which case the
+`Napi::AsyncProgress[Queue]Worker::ExecutionProgress::Signal`, in which case the
`data` parameter will be `nullptr`.
```cpp
@@ -227,7 +227,7 @@ unexpected upcoming thread safe calls.
virtual Napi::AsyncProgressWorker::~AsyncProgressWorker();
```
-# AsyncProgressWorker::ExecutionProcess
+# AsyncProgressWorker::ExecutionProgress
A bridge class created before the worker thread execution of `Napi::AsyncProgressWorker::Execute`.
@@ -235,15 +235,15 @@ A bridge class created before the worker thread execution of `Napi::AsyncProgres
### Send
-`Napi::AsyncProgressWorker::ExecutionProcess::Send` takes two arguments, a pointer
+`Napi::AsyncProgressWorker::ExecutionProgress::Send` takes two arguments, a pointer
to a generic type of data, and a `size_t` to indicate how many items the pointer is
pointing to.
The data pointed to will be copied to internal slots of `Napi::AsyncProgressWorker` so
-after the call to `Napi::AsyncProgressWorker::ExecutionProcess::Send` the data can
+after the call to `Napi::AsyncProgressWorker::ExecutionProgress::Send` the data can
be safely released.
-Note that `Napi::AsyncProgressWorker::ExecutionProcess::Send` merely guarantees
+Note that `Napi::AsyncProgressWorker::ExecutionProgress::Send` merely guarantees
**eventual** invocation of `Napi::AsyncProgressWorker::OnProgress`, which means
multiple send might be coalesced into single invocation of `Napi::AsyncProgressWorker::OnProgress`
with latest data. If you would like to guarantee that there is one invocation of
@@ -251,16 +251,16 @@ with latest data. If you would like to guarantee that there is one invocation of
class instead which is documented further down this page.
```cpp
-void Napi::AsyncProgressWorker::ExecutionProcess::Send(const T* data, size_t count) const;
+void Napi::AsyncProgressWorker::ExecutionProgress::Send(const T* data, size_t count) const;
```
### Signal
-`Napi::AsyncProgressWorker::ExecutionProcess::Signal` triggers an invocation of
+`Napi::AsyncProgressWorker::ExecutionProgress::Signal` triggers an invocation of
`Napi::AsyncProgressWorker::OnProgress` with `nullptr` as the `data` parameter.
```cpp
-void Napi::AsyncProgressWorker::ExecutionProcess::Signal();
+void Napi::AsyncProgressWorker::ExecutionProgress::Signal();
```
## Example
@@ -402,7 +402,7 @@ thread in the order it was committed.
For the most basic use, only the `Napi::AsyncProgressQueueWorker::Execute` and
`Napi::AsyncProgressQueueWorker::OnProgress` method must be implemented in a subclass.
-# AsyncProgressQueueWorker::ExecutionProcess
+# AsyncProgressQueueWorker::ExecutionProgress
A bridge class created before the worker thread execution of `Napi::AsyncProgressQueueWorker::Execute`.
@@ -410,30 +410,30 @@ A bridge class created before the worker thread execution of `Napi::AsyncProgres
### Send
-`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` takes two arguments, a pointer
+`Napi::AsyncProgressQueueWorker::ExecutionProgress::Send` takes two arguments, a pointer
to a generic type of data, and a `size_t` to indicate how many items the pointer is
pointing to.
The data pointed to will be copied to internal slots of `Napi::AsyncProgressQueueWorker` so
-after the call to `Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` the data can
+after the call to `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send` the data can
be safely released.
-`Napi::AsyncProgressQueueWorker::ExecutionProcess::Send` guarantees invocation
+`Napi::AsyncProgressQueueWorker::ExecutionProgress::Send` guarantees invocation
of `Napi::AsyncProgressQueueWorker::OnProgress`, which means multiple `Send`
call will result in the in-order invocation of `Napi::AsyncProgressQueueWorker::OnProgress`
with each data item.
```cpp
-void Napi::AsyncProgressQueueWorker::ExecutionProcess::Send(const T* data, size_t count) const;
+void Napi::AsyncProgressQueueWorker::ExecutionProgress::Send(const T* data, size_t count) const;
```
### Signal
-`Napi::AsyncProgressQueueWorker::ExecutionProcess::Signal` triggers an invocation of
+`Napi::AsyncProgressQueueWorker::ExecutionProgress::Signal` triggers an invocation of
`Napi::AsyncProgressQueueWorker::OnProgress` with `nullptr` as the `data` parameter.
```cpp
-void Napi::AsyncProgressQueueWorker::ExecutionProcess::Signal() const;
+void Napi::AsyncProgressQueueWorker::ExecutionProgress::Signal() const;
```
## Example
diff --git a/doc/basic_env.md b/doc/basic_env.md
new file mode 100644
index 000000000..7a5b430f1
--- /dev/null
+++ b/doc/basic_env.md
@@ -0,0 +1,200 @@
+# BasicEnv
+
+The data structure containing the environment in which the request is being run.
+
+The `Napi::BasicEnv` object is usually created and passed by the Node.js runtime
+or node-addon-api infrastructure.
+
+The `Napi::BasicEnv` object represents an environment that has a limited subset
+of APIs when compared to `Napi::Env` and can be used in basic finalizers. See
+[Finalization][] for more details.
+
+## Methods
+
+### Constructor
+
+```cpp
+Napi::BasicEnv::BasicEnv(node_api_nogc_env env);
+```
+
+- `[in] env`: The `node_api_nogc_env` environment from which to construct the
+ `Napi::BasicEnv` object.
+
+### node_api_nogc_env
+
+```cpp
+operator node_api_nogc_env() const;
+```
+
+Returns the `node_api_nogc_env` opaque data structure representing the
+environment.
+
+### GetInstanceData
+```cpp
+template T* GetInstanceData() const;
+```
+
+Returns the instance data that was previously associated with the environment,
+or `nullptr` if none was associated.
+
+### SetInstanceData
+
+
+```cpp
+template using Finalizer = void (*)(Env, T*);
+template fini = Env::DefaultFini>
+void SetInstanceData(T* data) const;
+```
+
+- `[template] fini`: A function to call when the instance data is to be deleted.
+Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
+not given, the default finalizer will be used, which simply uses the `delete`
+operator to destroy `T*` when the add-on instance is unloaded.
+- `[in] data`: A pointer to data that will be associated with the instance of
+the add-on for the duration of its lifecycle.
+
+Associates a data item stored at `T* data` with the current instance of the
+add-on. The item will be passed to the function `fini` which gets called when an
+instance of the add-on is unloaded.
+
+### SetInstanceData
+
+```cpp
+template
+using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
+template fini =
+ Env::DefaultFiniWithHint>
+void SetInstanceData(DataType* data, HintType* hint) const;
+```
+
+- `[template] fini`: A function to call when the instance data is to be deleted.
+Accepts a function of the form `void CleanupData(Napi::Env env, DataType* data,
+HintType* hint)`. If not given, the default finalizer will be used, which simply
+uses the `delete` operator to destroy `T*` when the add-on instance is unloaded.
+- `[in] data`: A pointer to data that will be associated with the instance of
+the add-on for the duration of its lifecycle.
+- `[in] hint`: A pointer to data that will be associated with the instance of
+the add-on for the duration of its lifecycle and will be passed as a hint to
+`fini` when the add-on instance is unloaded.
+
+Associates a data item stored at `T* data` with the current instance of the
+add-on. The item will be passed to the function `fini` which gets called when an
+instance of the add-on is unloaded. This overload accepts an additional hint to
+be passed to `fini`.
+
+### GetModuleFileName
+
+```cpp
+const char* Napi::Env::GetModuleFileName() const;
+```
+
+Returns a URL containing the absolute path of the location from which the add-on
+was loaded. For a file on the local file system it will start with `file://`.
+The string is null-terminated and owned by env and must thus not be modified or
+freed. It is only valid while the add-on is loaded.
+
+### AddCleanupHook
+
+```cpp
+template
+CleanupHook AddCleanupHook(Hook hook);
+```
+
+- `[in] hook`: A function to call when the environment exits. Accepts a function
+ of the form `void ()`.
+
+Registers `hook` as a function to be run once the current Node.js environment
+exits. Unlike the underlying C-based Node-API, providing the same `hook`
+multiple times **is** allowed. The hooks will be called in reverse order, i.e.
+the most recently added one will be called first.
+
+Returns an `Env::CleanupHook` object, which can be used to remove the hook via
+its `Remove()` method.
+
+### PostFinalizer
+
+```cpp
+template
+inline void PostFinalizer(FinalizerType finalizeCallback) const;
+```
+
+- `[in] finalizeCallback`: The function to queue for execution outside of the GC
+ finalization, implementing `operator()(Napi::Env)`. See [Finalization][] for
+ more details.
+
+### PostFinalizer
+
+```cpp
+template
+inline void PostFinalizer(FinalizerType finalizeCallback, T* data) const;
+```
+
+- `[in] finalizeCallback`: The function to queue for execution outside of the GC
+ finalization, implementing `operator()(Napi::Env, T*)`. See [Finalization][]
+ for more details.
+- `[in] data`: The data to associate with the object.
+
+### PostFinalizer
+
+```cpp
+template
+inline void PostFinalizer(FinalizerType finalizeCallback,
+ T* data,
+ Hint* finalizeHint) const;
+```
+
+- `[in] finalizeCallback`: The function to queue for execution outside of the GC
+ finalization, implementing `operator()(Napi::Env, T*, Hint*)`. See
+ [Finalization][] for more details.
+- `[in] data`: The data to associate with the object.
+- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
+
+### AddCleanupHook
+
+```cpp
+template
+CleanupHook AddCleanupHook(Hook hook, Arg* arg);
+```
+
+- `[in] hook`: A function to call when the environment exits. Accepts a function
+ of the form `void (Arg* arg)`.
+- `[in] arg`: A pointer to data that will be passed as the argument to `hook`.
+
+Registers `hook` as a function to be run with the `arg` parameter once the
+current Node.js environment exits. Unlike the underlying C-based Node-API,
+providing the same `hook` and `arg` pair multiple times **is** allowed. The
+hooks will be called in reverse order, i.e. the most recently added one will be
+called first.
+
+Returns an `Env::CleanupHook` object, which can be used to remove the hook via
+its `Remove()` method.
+
+# Env::CleanupHook
+
+The `Env::CleanupHook` object allows removal of the hook added via
+`Env::AddCleanupHook()`
+
+## Methods
+
+### IsEmpty
+
+```cpp
+bool IsEmpty();
+```
+
+Returns `true` if the cleanup hook was **not** successfully registered.
+
+### Remove
+
+```cpp
+bool Remove(Env env);
+```
+
+Unregisters the hook from running once the current Node.js environment exits.
+
+Returns `true` if the hook was successfully removed from the Node.js
+environment.
+
+[Finalization]: ./finalization.md
diff --git a/doc/buffer.md b/doc/buffer.md
index 427eeee2f..548400481 100644
--- a/doc/buffer.md
+++ b/doc/buffer.md
@@ -27,16 +27,15 @@ Returns a new `Napi::Buffer` object.
Wraps the provided external data into a new `Napi::Buffer` object.
-The `Napi::Buffer` object does not assume ownership for the data and expects it to be
-valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage
-collection this overload is only suitable for data which is static and never
-needs to be freed.
-This factory method will not provide the caller with an opportunity to free the
-data when the `Napi::Buffer` gets garbage-collected. If you need to free the
-data retained by the `Napi::Buffer` object please use other variants of the
-`Napi::Buffer::New` factory method that accept `Napi::Finalizer`, which is a
-function that will be invoked when the `Napi::Buffer` object has been
-destroyed.
+The `Napi::Buffer` object does not assume ownership for the data and expects it
+to be valid for the lifetime of the object. Since the `Napi::Buffer` is subject
+to garbage collection this overload is only suitable for data which is static
+and never needs to be freed. This factory method will not provide the caller
+with an opportunity to free the data when the `Napi::Buffer` gets
+garbage-collected. If you need to free the data retained by the `Napi::Buffer`
+object please use other variants of the `Napi::Buffer::New` factory method that
+accept `Finalizer`, which is a function that will be invoked when the
+`Napi::Buffer` object has been destroyed. See [Finalization][] for more details.
```cpp
static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length);
@@ -70,9 +69,9 @@ static Napi::Buffer Napi::Buffer::New(napi_env env,
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
-- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
- destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
- external data pointer), and return `void`.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+ `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*)`. See
+ [Finalization][] for more details.
Returns a new `Napi::Buffer` object.
@@ -99,11 +98,10 @@ static Napi::Buffer Napi::Buffer::New(napi_env env,
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
-- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
- destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
- external data pointer) and `Hint*`, and return `void`.
-- `[in] finalizeHint`: The hint to be passed as the second parameter of the
- finalize callback.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+ `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`.
+ See [Finalization][] for more details.
+- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
Returns a new `Napi::Buffer` object.
@@ -157,9 +155,9 @@ static Napi::Buffer Napi::Buffer::NewOrCopy(napi_env env,
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
-- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
- destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
- external data pointer), and return `void`.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+ `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*)`. See
+ [Finalization][] for more details.
Returns a new `Napi::Buffer` object.
@@ -186,11 +184,10 @@ static Napi::Buffer Napi::Buffer::NewOrCopy(napi_env env,
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
-- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
- destroyed. It must implement `operator()`, accept an Napi::Env, a `T*` (which is the
- external data pointer) and `Hint*`, and return `void`.
-- `[in] finalizeHint`: The hint to be passed as the second parameter of the
- finalize callback.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+ `Napi::Buffer` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`.
+ See [Finalization][] for more details.
+- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
Returns a new `Napi::Buffer` object.
@@ -245,3 +242,4 @@ Returns the number of `T` elements in the external data.
[`Napi::Uint8Array`]: ./typed_array_of.md
[External Buffer]: ./external_buffer.md
+[Finalization]: ./finalization.md
diff --git a/doc/cmake-js.md b/doc/cmake-js.md
index bbd73d687..1d5df91ca 100644
--- a/doc/cmake-js.md
+++ b/doc/cmake-js.md
@@ -45,13 +45,32 @@ The following line in the `CMakeLists.txt` file will enable Node-API experimenta
add_definitions(-DNAPI_EXPERIMENTAL)
```
+### Exception Handling
+
+To enable C++ exception handling (for more info see: [Setup](setup.md)), define
+the corresponding preprocessor directives depending on which exception handling
+behavior is desired.
+
+To enable C++ exception handling with `Napi::Error` objects only:
+
+```
+add_definitions(-DNODE_ADDON_API_CPP_EXCEPTIONS)
+```
+
+To enable C++ exception handling for all exceptions thrown:
+
+```
+add_definitions(-DNODE_ADDON_API_CPP_EXCEPTIONS)
+add_definitions(-DNODE_ADDON_API_CPP_EXCEPTIONS_ALL)
+```
+
### node-addon-api
If your Node-API native add-on uses the optional [**node-addon-api**](https://github.com/nodejs/node-addon-api#node-addon-api-module) C++ wrapper, the `CMakeLists.txt` file requires additional configuration information as described on the [CMake.js README file](https://github.com/cmake-js/cmake-js#node-api-and-node-addon-api).
## Example
-A working example of an Node-API native addon built using CMake.js can be found on the [node-addon-examples repository](https://github.com/nodejs/node-addon-examples/tree/HEAD/build_with_cmake#building-n-api-addons-using-cmakejs).
+A working example of an Node-API native addon built using CMake.js can be found on the [node-addon-examples repository](https://github.com/nodejs/node-addon-examples/tree/main/src/8-tooling/build_with_cmake#building-node-api-addons-using-cmakejs).
## **CMake** Reference
diff --git a/doc/contributing/build_with_ninja.md b/doc/contributing/build_with_ninja.md
new file mode 100644
index 000000000..d59e9bbef
--- /dev/null
+++ b/doc/contributing/build_with_ninja.md
@@ -0,0 +1,16 @@
+# Build Test with Ninja
+
+Ninja can be used to speed up building tests with optimized parallelism.
+
+To build the tests with ninja and node-gyp, run the following commands:
+
+```sh
+/node-addon-api $ node-gyp configure -C test -- -f ninja
+/node-addon-api $ ninja -C test/build/Release
+# Run tests
+/node-addon-api $ node ./test/index.js
+
+# Run tests with debug addon
+/node-addon-api $ ninja -C test/build/Debug
+/node-addon-api $ NODE_API_BUILD_CONFIG=Debug node ./test/index.js
+```
diff --git a/doc/creating_a_release.md b/doc/contributing/creating_a_release.md
similarity index 82%
rename from doc/creating_a_release.md
rename to doc/contributing/creating_a_release.md
index 8b7bdd3fd..02e9cbc53 100644
--- a/doc/creating_a_release.md
+++ b/doc/contributing/creating_a_release.md
@@ -6,7 +6,17 @@ collaborators to add you. If necessary you can ask the build
Working Group who manages the Node.js npm user to add you if
there are no other active collaborators.
-## Prerequisites
+Generally, the release is handled by the
+[release-please](https://github.com/nodejs/node-addon-api/blob/main/.github/workflows/release-please.yml)
+GitHub action. It will bump the version in `package.json` and publish
+node-addon-api to npm.
+
+In cases that the release-please action is not working, please follow the steps
+below to publish node-addon-api manually.
+
+## Publish new release manually
+
+### Prerequisites
Before to start creating a new release check if you have installed the following
tools:
@@ -16,7 +26,7 @@ tools:
If not please follow the instruction reported in the tool's documentation to
install it.
-## Publish new release
+### Steps
These are the steps to follow to create a new release:
@@ -34,14 +44,16 @@ to show the new version as the latest.
the route folder of the repo launch the following command:
```bash
- > changelog-maker
+ > changelog-maker --md --group --filter-release
```
* Use the output generated by **changelog maker** to update the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/main/CHANGELOG.md)
following the style used in publishing the previous release.
* Add any new contributors to the "contributors" section in the package.json
-* Validate all tests pass by running `npm test` on the `main` branch.
+* Commit with a message containing _only_ an x.y.z semver designator. "x.y.z" (so that the commit can be filtered by changelog-maker)
+
+* Create a release proposal pull request.
* Use **[CI](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api-new/)**
to validate tests pass (note there are still some issues on SmartOS and
diff --git a/doc/dataview.md b/doc/dataview.md
index 66fb28919..619ceecca 100644
--- a/doc/dataview.md
+++ b/doc/dataview.md
@@ -6,6 +6,11 @@ The `Napi::DataView` class corresponds to the
[JavaScript `DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)
class.
+**NOTE**: The support for `Napi::DataView::New()` overloads accepting an
+`Napi::SharedArrayBuffer` parameter is only available when using
+`NAPI_EXPERIMENTAL` and building against Node.js headers that support this
+feature.
+
## Methods
### New
@@ -50,6 +55,48 @@ static Napi::DataView Napi::DataView::New(napi_env env, Napi::ArrayBuffer arrayB
Returns a new `Napi::DataView` instance.
+### New
+
+Allocates a new `Napi::DataView` instance with a given `Napi::SharedArrayBuffer`.
+
+```cpp
+static Napi::DataView Napi::DataView::New(napi_env env, Napi::SharedArrayBuffer sharedArrayBuffer);
+```
+
+- `[in] env`: The environment in which to create the `Napi::DataView` instance.
+- `[in] sharedArrayBuffer` : `Napi::SharedArrayBuffer` underlying the `Napi::DataView`.
+
+Returns a new `Napi::DataView` instance.
+
+### New
+
+Allocates a new `Napi::DataView` instance with a given `Napi::SharedArrayBuffer`.
+
+```cpp
+static Napi::DataView Napi::DataView::New(napi_env env, Napi::SharedArrayBuffer sharedArrayBuffer, size_t byteOffset);
+```
+
+- `[in] env`: The environment in which to create the `Napi::DataView` instance.
+- `[in] sharedArrayBuffer` : `Napi::SharedArrayBuffer` underlying the `Napi::DataView`.
+- `[in] byteOffset` : The byte offset within the `Napi::SharedArrayBuffer` from which to start projecting the `Napi::DataView`.
+
+Returns a new `Napi::DataView` instance.
+
+### New
+
+Allocates a new `Napi::DataView` instance with a given `Napi::SharedArrayBuffer`.
+
+```cpp
+static Napi::DataView Napi::DataView::New(napi_env env, Napi::SharedArrayBuffer sharedArrayBuffer, size_t byteOffset, size_t byteLength);
+```
+
+- `[in] env`: The environment in which to create the `Napi::DataView` instance.
+- `[in] sharedArrayBuffer` : `Napi::SharedArrayBuffer` underlying the `Napi::DataView`.
+- `[in] byteOffset` : The byte offset within the `Napi::SharedArrayBuffer` from which to start projecting the `Napi::DataView`.
+- `[in] byteLength` : Number of elements in the `Napi::DataView`.
+
+Returns a new `Napi::DataView` instance.
+
### Constructor
Initializes an empty instance of the `Napi::DataView` class.
@@ -75,7 +122,22 @@ Napi::DataView(napi_env env, napi_value value);
Napi::ArrayBuffer Napi::DataView::ArrayBuffer() const;
```
-Returns the backing array buffer.
+Returns the backing array buffer as an `Napi::ArrayBuffer`.
+
+**NOTE**: If the `Napi::DataView` is not backed by an `Napi::ArrayBuffer`, this
+method will terminate the process with a fatal error when using
+`NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` or exhibit undefined behavior
+otherwise. Use `Buffer()` instead to get the backing buffer without assuming its
+type.
+
+### Buffer
+
+```cpp
+Napi::Value Napi::DataView::Buffer() const;
+```
+
+Returns the backing array buffer as a generic `Napi::Value`, allowing optional
+type-checking with `Is*()` and type-casting with `As<>()` methods.
### ByteOffset
diff --git a/doc/date.md b/doc/date.md
index 4c5fefa5e..7131b016f 100644
--- a/doc/date.md
+++ b/doc/date.md
@@ -37,6 +37,20 @@ static Napi::Date Napi::Date::New(Napi::Env env, double value);
Returns a new instance of `Napi::Date` object.
+### New
+
+Creates a new instance of a `Napi::Date` object.
+
+```cpp
+static Napi::Date Napi::Date::New(napi_env env, std::chrono::system_clock::time_point time_point);
+```
+
+ - `[in] env`: The environment in which to construct the `Napi::Date` object.
+ - `[in] value`: The point in time, represented by an
+ `std::chrono::system_clock::time_point`.
+
+Returns a new instance of `Napi::Date` object.
+
### ValueOf
```cpp
diff --git a/doc/env.md b/doc/env.md
index 456cfda73..7773275ee 100644
--- a/doc/env.md
+++ b/doc/env.md
@@ -1,8 +1,15 @@
# Env
-The opaque data structure containing the environment in which the request is being run.
+Class `Napi::Env` inherits from class [`Napi::BasicEnv`][].
-The Env object is usually created and passed by the Node.js runtime or node-addon-api infrastructure.
+The data structure containing the environment in which the request is being run.
+
+The `Napi::Env` object is usually created and passed by the Node.js runtime or
+node-addon-api infrastructure.
+
+The `Napi::Env` object represents an environment that has a superset of APIs
+when compared to `Napi::BasicEnv` and therefore _cannot_ be used in basic
+finalizers. See [Finalization][] for more details.
## Methods
@@ -76,121 +83,5 @@ The `script` can be any of the following types:
- `const char *`
- `const std::string &`
-### GetInstanceData
-```cpp
-template T* GetInstanceData() const;
-```
-
-Returns the instance data that was previously associated with the environment,
-or `nullptr` if none was associated.
-
-### SetInstanceData
-
-```cpp
-template using Finalizer = void (*)(Env, T*);
-template fini = Env::DefaultFini>
-void SetInstanceData(T* data) const;
-```
-
-- `[template] fini`: A function to call when the instance data is to be deleted.
-Accepts a function of the form `void CleanupData(Napi::Env env, T* data)`. If
-not given, the default finalizer will be used, which simply uses the `delete`
-operator to destroy `T*` when the addon instance is unloaded.
-- `[in] data`: A pointer to data that will be associated with the instance of
-the addon for the duration of its lifecycle.
-
-Associates a data item stored at `T* data` with the current instance of the
-addon. The item will be passed to the function `fini` which gets called when an
-instance of the addon is unloaded.
-
-### SetInstanceData
-
-```cpp
-template
-using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
-template fini =
- Env::DefaultFiniWithHint>
-void SetInstanceData(DataType* data, HintType* hint) const;
-```
-
-- `[template] fini`: A function to call when the instance data is to be deleted.
-Accepts a function of the form
-`void CleanupData(Napi::Env env, DataType* data, HintType* hint)`. If not given,
-the default finalizer will be used, which simply uses the `delete` operator to
-destroy `T*` when the addon instance is unloaded.
-- `[in] data`: A pointer to data that will be associated with the instance of
-the addon for the duration of its lifecycle.
-- `[in] hint`: A pointer to data that will be associated with the instance of
-the addon for the duration of its lifecycle and will be passed as a hint to
-`fini` when the addon instance is unloaded.
-
-Associates a data item stored at `T* data` with the current instance of the
-addon. The item will be passed to the function `fini` which gets called when an
-instance of the addon is unloaded. This overload accepts an additional hint to
-be passed to `fini`.
-
-### AddCleanupHook
-
-```cpp
-template
-CleanupHook AddCleanupHook(Hook hook);
-```
-
-- `[in] hook`: A function to call when the environment exits. Accepts a
- function of the form `void ()`.
-
-Registers `hook` as a function to be run once the current Node.js environment
-exits. Unlike the underlying C-based Node-API, providing the same `hook`
-multiple times **is** allowed. The hooks will be called in reverse order, i.e.
-the most recently added one will be called first.
-
-Returns an `Env::CleanupHook` object, which can be used to remove the hook via
-its `Remove()` method.
-
-### AddCleanupHook
-
-```cpp
-template
-CleanupHook AddCleanupHook(Hook hook, Arg* arg);
-```
-
-- `[in] hook`: A function to call when the environment exits. Accepts a
- function of the form `void (Arg* arg)`.
-- `[in] arg`: A pointer to data that will be passed as the argument to `hook`.
-
-Registers `hook` as a function to be run with the `arg` parameter once the
-current Node.js environment exits. Unlike the underlying C-based Node-API,
-providing the same `hook` and `arg` pair multiple times **is** allowed. The
-hooks will be called in reverse order, i.e. the most recently added one will be
-called first.
-
-Returns an `Env::CleanupHook` object, which can be used to remove the hook via
-its `Remove()` method.
-
-# Env::CleanupHook
-
-The `Env::CleanupHook` object allows removal of the hook added via
-`Env::AddCleanupHook()`
-
-## Methods
-
-### IsEmpty
-
-```cpp
-bool IsEmpty();
-```
-
-Returns `true` if the cleanup hook was **not** successfully registered.
-
-### Remove
-
-```cpp
-bool Remove(Env env);
-```
-
-Unregisters the hook from running once the current Node.js environment exits.
-
-Returns `true` if the hook was successfully removed from the Node.js
-environment.
+[`Napi::BasicEnv`]: ./basic_env.md
+[Finalization]: ./finalization.md
diff --git a/doc/error_handling.md b/doc/error_handling.md
index 5bb7481aa..b4b4ca238 100644
--- a/doc/error_handling.md
+++ b/doc/error_handling.md
@@ -48,6 +48,18 @@ method.
If a C++ exception of type `Napi::Error` escapes from a Node-API C++ callback, then
the Node-API wrapper automatically converts and throws it as a JavaScript exception.
+If other types of C++ exceptions are thrown, node-addon-api will either abort
+the process or wrap the exception in an `Napi::Error` in order to throw it as a
+JavaScript exception. This behavior is determined by which node-gyp dependency
+used:
+
+- When using the `node_addon_api_except` dependency, only `Napi::Error` objects
+ will be handled.
+- When using the `node_addon_api_except_all` dependency, all exceptions will be
+handled. For exceptions derived from `std::exception`, an `Napi::Error` will be
+created with the message of the exception's `what()` member function. For all
+other exceptions, an `Napi::Error` will be created with a generic error message.
+
On return from a native method, node-addon-api will automatically convert a pending
`Napi::Error` C++ exception to a JavaScript exception.
diff --git a/doc/external.md b/doc/external.md
index ce42e112a..4b4603e8e 100644
--- a/doc/external.md
+++ b/doc/external.md
@@ -4,7 +4,11 @@ Class `Napi::External` inherits from class [`Napi::TypeTaggable`][].
The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data.
-`Napi::External` objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your `Napi::External` object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function.
+`Napi::External` objects can be created with an optional Finalizer function and
+optional Hint value. The `Finalizer` function, if specified, is called when your
+`Napi::External` object is released by Node's garbage collector. It gives your
+code the opportunity to free any dynamically created data. If you specify a Hint
+value, it is passed to your `Finalizer` function. See [Finalization][] for more details.
Note that `Napi::Value::IsExternal()` will return `true` for any external value.
It does not differentiate between the templated parameter `T` in
@@ -38,7 +42,9 @@ static Napi::External Napi::External::New(napi_env env,
- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
-- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting a T* and returning void.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+ `Napi::External` object, implementing `operator()(Napi::BasicEnv, T*)`. See
+ [Finalization][] for more details.
Returns the created `Napi::External` object.
@@ -54,8 +60,10 @@ static Napi::External Napi::External::New(napi_env env,
- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
-- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting T* and Hint* parameters and returning void.
-- `[in] finalizeHint`: A hint value passed to the `finalizeCallback` function.
+- `[in] finalizeCallback`: The function called when the engine destroys the
+ `Napi::External` object, implementing `operator()(Napi::BasicEnv, T*, Hint*)`.
+ See [Finalization][] for more details.
+- `[in] finalizeHint`: The hint value passed to the `finalizeCallback` function.
Returns the created `Napi::External` object.
@@ -67,4 +75,5 @@ T* Napi::External::Data() const;
Returns a pointer to the arbitrary C++ data held by the `Napi::External` object.
+[Finalization]: ./finalization.md
[`Napi::TypeTaggable`]: ./type_taggable.md
diff --git a/doc/finalization.md b/doc/finalization.md
new file mode 100644
index 000000000..3dc4e7860
--- /dev/null
+++ b/doc/finalization.md
@@ -0,0 +1,153 @@
+# Finalization
+
+Various node-addon-api methods accept a templated `Finalizer finalizeCallback`
+parameter. This parameter represents a native callback function that runs in
+response to a garbage collection event. A finalizer is considered a _basic_
+finalizer if the callback only utilizes a certain subset of APIs, which may
+provide more efficient memory management, optimizations, improved execution, or
+other benefits.
+
+In general, it is best to use basic finalizers whenever possible (eg. when
+access to JavaScript is _not_ needed). The
+`NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS` preprocessor directive can be defined
+to ensure that all finalizers are basic.
+
+## Finalizers
+
+The callback takes `Napi::Env` as its first argument:
+
+### Example
+
+```cpp
+Napi::External::New(Env(), new int(1), [](Napi::Env env, int* data) {
+ env.RunScript("console.log('Finalizer called')");
+ delete data;
+});
+```
+
+## Basic Finalizers
+
+Use of basic finalizers may allow the engine to perform optimizations when
+scheduling or executing the callback. For example, V8 does not allow access to
+the engine heap during garbage collection. Restricting finalizers from accessing
+the engine heap allows the callback to execute during garbage collection,
+providing a chance to free native memory eagerly.
+
+In general, APIs that access engine heap are not allowed in basic finalizers.
+
+The callback takes `Napi::BasicEnv` as its first argument:
+
+### Example
+
+```cpp
+Napi::ArrayBuffer::New(
+ Env(), data, length, [](Napi::BasicEnv /*env*/, void* finalizeData) {
+ delete[] static_cast(finalizeData);
+ });
+```
+
+## Scheduling Finalizers
+
+In addition to passing finalizers to `Napi::External`s and other Node-API
+constructs, `Napi::BasicEnv::PostFinalize(Napi::BasicEnv, Finalizer)` can be
+used to schedule a callback to run outside of the garbage collector
+finalization. Since the associated native memory may already be freed by the
+basic finalizer, any additional data may be passed eg. via the finalizer's
+parameters (`T data*`, `Hint hint*`) or via lambda capture. This allows for
+freeing native data in a basic finalizer, while executing any JavaScript code in
+an additional finalizer.
+
+### Example
+
+```cpp
+// Native Add-on
+
+#include
+#include
+#include "napi.h"
+
+using namespace Napi;
+
+// A structure representing some data that uses a "large" amount of memory.
+class LargeData {
+ public:
+ LargeData() : id(instances++) {}
+ size_t id;
+
+ static size_t instances;
+};
+
+size_t LargeData::instances = 0;
+
+// Basic finalizer to free `LargeData`. Takes ownership of the pointer and
+// frees its memory after use.
+void MyBasicFinalizer(Napi::BasicEnv env, LargeData* data) {
+ std::unique_ptr instance(data);
+ std::cout << "Basic finalizer for instance " << instance->id
+ << " called\n";
+
+ // Register a finalizer. Since the instance will be deleted by
+ // the time this callback executes, pass the instance's `id` via lambda copy
+ // capture and _not_ a reference capture that accesses `this`.
+ env.PostFinalizer([instanceId = instance->id](Napi::Env env) {
+ env.RunScript("console.log('Finalizer for instance " +
+ std::to_string(instanceId) + " called');");
+ });
+
+ // Free the `LargeData` held in `data` once `instance` goes out of scope.
+}
+
+Value CreateExternal(const CallbackInfo& info) {
+ // Create a new instance of LargeData.
+ auto instance = std::make_unique();
+
+ // Wrap the instance in an External object, registering a basic
+ // finalizer that will delete the instance to free the "large" amount of
+ // memory.
+ return External::New(info.Env(), instance.release(), MyBasicFinalizer);
+}
+
+Object Init(Napi::Env env, Object exports) {
+ exports["createExternal"] = Function::New(env, CreateExternal);
+ return exports;
+}
+
+NODE_API_MODULE(addon, Init)
+```
+
+```js
+// JavaScript
+
+const { createExternal } = require('./addon.node');
+
+for (let i = 0; i < 5; i++) {
+ const ext = createExternal();
+ // ... do something with `ext` ..
+}
+
+console.log('Loop complete');
+await new Promise(resolve => setImmediate(resolve));
+console.log('Next event loop cycle');
+```
+
+Possible output:
+
+```
+Basic finalizer for instance 0 called
+Basic finalizer for instance 1 called
+Basic finalizer for instance 2 called
+Basic finalizer for instance 3 called
+Basic finalizer for instance 4 called
+Loop complete
+Finalizer for instance 3 called
+Finalizer for instance 4 called
+Finalizer for instance 1 called
+Finalizer for instance 2 called
+Finalizer for instance 0 called
+Next event loop cycle
+```
+
+If the garbage collector runs during the loop, the basic finalizers execute and
+display their logging message synchronously during the loop execution. The
+additional finalizers execute at some later point after the garbage collection
+cycle.
diff --git a/doc/memory_management.md b/doc/memory_management.md
index afa622550..882c0f802 100644
--- a/doc/memory_management.md
+++ b/doc/memory_management.md
@@ -17,7 +17,7 @@ more often than it would otherwise in an attempt to garbage collect the JavaScri
objects that keep the externally allocated memory alive.
```cpp
-static int64_t Napi::MemoryManagement::AdjustExternalMemory(Napi::Env env, int64_t change_in_bytes);
+static int64_t Napi::MemoryManagement::AdjustExternalMemory(Napi::BasicEnv env, int64_t change_in_bytes);
```
- `[in] env`: The environment in which the API is invoked under.
diff --git a/doc/node-gyp.md b/doc/node-gyp.md
index 529aa0ea2..a39d5b8c0 100644
--- a/doc/node-gyp.md
+++ b/doc/node-gyp.md
@@ -4,19 +4,19 @@ C++ code needs to be compiled into executable form whether it be as an object
file to linked with others, a shared library, or a standalone executable.
The main reason for this is that we need to link to the Node.js dependencies and
-headers correctly, another reason is that we need a cross platform way to build
+headers correctly. Another reason is that we need a cross-platform way to build
C++ source into binary for the target platform.
-Until now **node-gyp** is the **de-facto** standard build tool for writing
-Node.js addons. It's based on Google's **gyp** build tool, which abstract away
-many of the tedious issues related to cross platform building.
+**node-gyp** remains the **de-facto** standard build tool for writing
+Node.js addons. It's based on Google's **gyp** build tool, which abstracts away
+many of the tedious issues related to cross-platform building.
-**node-gyp** uses a file called ```binding.gyp``` that is located on the root of
+**node-gyp** uses a file called `binding.gyp` that is located in the root of
your addon project.
-```binding.gyp``` file, contains all building configurations organized with a
-JSON like syntax. The most important parameter is the **target** that must be
-set to the same value used on the initialization code of the addon as in the
+The `binding.gyp` file contains all building configurations organized with a
+JSON-like syntax. The most important parameter is the **target** that must be
+set to the same value used in the initialization code of the addon, as in the
examples reported below:
### **binding.gyp**
@@ -41,8 +41,8 @@ examples reported below:
// ...
/**
-* This code is our entry-point. We receive two arguments here, the first is the
-* environment that represent an independent instance of the JavaScript runtime,
+* This code is our entry point. We receive two arguments here: the first is the
+* environment that represent an independent instance of the JavaScript runtime;
* the second is exports, the same as module.exports in a .js file.
* You can either add properties to the exports object passed in or create your
* own exports object. In either case you must return the object to be used as
@@ -56,7 +56,7 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
}
/**
-* This code defines the entry-point for the Node addon, it tells Node where to go
+* This code defines the entry point for the Node addon. It tells Node where to go
* once the library has been loaded into active memory. The first argument must
* match the "target" in our *binding.gyp*. Using NODE_GYP_MODULE_NAME ensures
* that the argument will be correct, as long as the module is built with
@@ -75,8 +75,8 @@ NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
- [Command options](https://www.npmjs.com/package/node-gyp#command-options)
- [Configuration](https://www.npmjs.com/package/node-gyp#configuration)
-Sometimes finding the right settings for ```binding.gyp``` is not easy so to
-accomplish at most complicated task please refer to:
+Sometimes finding the right settings for `binding.gyp` is not easy, so to
+accomplish the most complicated tasks, please refer to:
- [GYP documentation](https://gyp.gsrc.io/index.md)
-- [node-gyp wiki](https://github.com/nodejs/node-gyp/wiki)
+- [node-gyp wiki](https://github.com/nodejs/node-gyp/tree/main/docs)
diff --git a/doc/object.md b/doc/object.md
index a4d3280b8..fb7d53ad1 100644
--- a/doc/object.md
+++ b/doc/object.md
@@ -241,6 +241,28 @@ from being added to it and marking all existing properties as non-configurable.
Values of present properties can still be changed as long as they are
writable.
+### GetPrototype()
+
+```cpp
+Napi::Object Napi::Object::GetPrototype() const;
+```
+
+The `Napi::Object::GetPrototype()` method returns the prototype of the object.
+
+### SetPrototype()
+
+```cpp
+bool Napi::Object::SetPrototype(const Napi::Object& value) const;
+```
+
+- `[in] value`: The prototype value.
+
+The `Napi::Object::SetPrototype()` method sets the prototype of the object.
+
+**NOTE**: The support for `Napi::Object::SetPrototype` is only available when
+using `NAPI_EXPERIMENTAL` and building against Node.js headers that support this
+feature.
+
### operator\[\]()
```cpp
diff --git a/doc/object_wrap.md b/doc/object_wrap.md
index 43546646a..40fb3bf12 100644
--- a/doc/object_wrap.md
+++ b/doc/object_wrap.md
@@ -241,9 +241,24 @@ request being made.
### Finalize
-Provides an opportunity to run cleanup code that requires access to the
-`Napi::Env` before the wrapped native object instance is freed. Override to
-implement.
+Provides an opportunity to run cleanup code that only utilizes basic Node APIs, if any.
+Override to implement. See [Finalization][] for more details.
+
+```cpp
+virtual void Finalize(Napi::BasicEnv env);
+```
+
+- `[in] env`: `Napi::Env`.
+
+### Finalize
+
+Provides an opportunity to run cleanup code that utilizes non-basic Node APIs.
+Override to implement.
+
+*NOTE*: Defining this method causes the deletion of the underlying `T* data` to
+be postponed until _after_ the garbage collection cycle. Since an `Napi::Env`
+has access to non-basic Node APIs, it cannot run in the same current tick as the
+garbage collector.
```cpp
virtual void Finalize(Napi::Env env);
@@ -586,3 +601,4 @@ Returns `Napi::PropertyDescriptor` object that represents an static value
property of a JavaScript class
[`Napi::InstanceWrap`]: ./instance_wrap.md
+[Finalization]: ./finalization.md
diff --git a/doc/promises.md b/doc/promises.md
index 21594c6b8..b4ab83389 100644
--- a/doc/promises.md
+++ b/doc/promises.md
@@ -75,5 +75,56 @@ Rejects the Promise object held by the `Napi::Promise::Deferred` object.
* `[in] value`: The Node-API primitive value with which to reject the `Napi::Promise`.
+## Promise Methods
+
+### Then
+
+```cpp
+Napi::Promise Napi::Promise::Then(napi_value onFulfilled) const;
+Napi::Promise Napi::Promise::Then(const Function& onFulfilled) const;
+```
+
+Attaches a fulfillment handler to the promise and returns a new promise.
+
+**Parameters:**
+* `[in] onFulfilled`: The fulfillment handler for the promise. May be any of:
+ - `napi_value` – a JavaScript function to be called when the promise is fulfilled.
+ - `const Function&` – the [`Napi::Function`](function.md) to be called when the promise is fulfilled.
+
+**Returns:** A new `Napi::Promise` that resolves or rejects based on the handler's result.
+
+### Then
+
+```cpp
+Napi::Promise Napi::Promise::Then(napi_value onFulfilled, napi_value onRejected) const;
+Napi::Promise Napi::Promise::Then(const Function& onFulfilled,
+ const Function& onRejected) const;
+```
+
+Attaches a fulfillment and rejection handlers to the promise and returns a new promise.
+
+**Parameters:**
+* `[in] onFulfilled`: The fulfillment handler for the promise. May be any of:
+ - `napi_value` – a JavaScript function to be called when the promise is fulfilled.
+ - `const Function&` – the [`Napi::Function`](function.md) to be called when the promise is fulfilled.
+* `[in] onRejected` (optional): The rejection handler for the promise. May be any of:
+ - `napi_value` – a JavaScript function to be called when the promise is rejected.
+ - `const Function&` – the [`Napi::Function`](function.md) to be called when the promise is rejected.
+
+### Catch
+```cpp
+Napi::Promise Napi::Promise::Catch(napi_value onRejected) const;
+Napi::Promise Napi::Promise::Catch(const Function& onRejected) const;
+```
+
+Attaches a rejection handler to the promise and returns a new promise.
+
+**Parameters:**
+* `[in] onRejected`: The rejection handler for the promise. May be any of:
+ - `napi_value` – a JavaScript function to be called when the promise is rejected.
+ - `const Function&` – the [`Napi::Function`](function.md) to be called when the promise is rejected.
+
+**Returns:** A new `Napi::Promise` that handles rejection cases.
[`Napi::Object`]: ./object.md
+[`Napi::Function`]: ./function.md
diff --git a/doc/setup.md b/doc/setup.md
index 49e039c8f..b3b7effc6 100644
--- a/doc/setup.md
+++ b/doc/setup.md
@@ -17,94 +17,99 @@ To use **Node-API** in a native module:
1. Add a dependency on this package to `package.json`:
-```json
- "dependencies": {
- "node-addon-api": "*",
- }
-```
-
- 2. Reference this package's include directory and gyp file in `binding.gyp`:
-
-```gyp
- 'include_dirs': ["()` methods.
+
### ElementSize
```cpp
diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md
index a982b80e5..4ced5841c 100644
--- a/doc/typed_array_of.md
+++ b/doc/typed_array_of.md
@@ -77,6 +77,34 @@ static Napi::TypedArrayOf Napi::TypedArrayOf::New(napi_env env,
Returns a new `Napi::TypedArrayOf` instance.
+### New
+
+Wraps the provided `Napi::SharedArrayBuffer` into a new `Napi::TypedArray` instance.
+
+The array `type` parameter can normally be omitted (because it is inferred from
+the template parameter `T`), except when creating a "clamped" array.
+
+```cpp
+static Napi::TypedArrayOf Napi::TypedArrayOf::New(napi_env env,
+ size_t elementLength,
+ Napi::SharedArrayBuffer arrayBuffer,
+ size_t bufferOffset,
+ napi_typedarray_type type);
+```
+
+- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` instance.
+- `[in] elementLength`: The length to array, in elements.
+- `[in] arrayBuffer`: The backing `Napi::SharedArrayBuffer` instance.
+- `[in] bufferOffset`: The offset into the `Napi::SharedArrayBuffer` where the array starts,
+ in bytes.
+- `[in] type`: The type of array to allocate (optional).
+
+Returns a new `Napi::TypedArrayOf` instance.
+
+**NOTE**: The support for this overload of `Napi::TypedArrayOf::New()` is only
+available when using `NAPI_EXPERIMENTAL` and building against Node.js headers
+that supports this feature.
+
### Constructor
Initializes an empty instance of the `Napi::TypedArrayOf` class.
diff --git a/doc/value.md b/doc/value.md
index ed92520e7..f61a36ecf 100644
--- a/doc/value.md
+++ b/doc/value.md
@@ -86,6 +86,19 @@ In order to enforce expected type, use `Napi::Value::Is*()` methods to check
the type before calling `Napi::Value::As()`, or compile with definition
`NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` to enforce type checks.
+### UnsafeAs
+
+```cpp
+template T Napi::Value::UnsafeAs() const;
+```
+
+Casts to another type of `Napi::Value`, when the actual type is known or
+assumed.
+
+This conversion does not coerce the type. This does not check the type even if
+`NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` is defined. This indicates intentional
+unsafe type cast. Use `Napi::Value::As()` if possible.
+
### Env
```cpp
@@ -141,6 +154,8 @@ bool Napi::Value::IsArrayBuffer() const;
Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or
`false` otherwise.
+### IsBigInt
+
```cpp
bool Napi::Value::IsBigInt() const;
```
@@ -253,6 +268,19 @@ bool Napi::Value::IsPromise() const;
Returns `true` if the underlying value is a JavaScript `Napi::Promise` or
`false` otherwise.
+### IsSharedArrayBuffer
+
+```cpp
+bool Napi::Value::IsSharedArrayBuffer() const;
+```
+
+Returns `true` if the underlying value is a JavaScript
+`Napi::IsSharedArrayBuffer` or `false` otherwise.
+
+**NOTE**: The support for `Napi::SharedArrayBuffer` is only available when using
+`NAPI_EXPERIMENTAL` and building against Node.js headers that support this
+feature.
+
### IsString
```cpp
diff --git a/doc/version_management.md b/doc/version_management.md
index 1cdc48321..b289f1b1d 100644
--- a/doc/version_management.md
+++ b/doc/version_management.md
@@ -11,7 +11,7 @@ important to make decisions based on different versions of the system.
Retrieves the highest Node-API version supported by Node.js runtime.
```cpp
-static uint32_t Napi::VersionManagement::GetNapiVersion(Env env);
+static uint32_t Napi::VersionManagement::GetNapiVersion(Napi::BasicEnv env);
```
- `[in] env`: The environment in which the API is invoked under.
@@ -34,7 +34,7 @@ typedef struct {
````
```cpp
-static const napi_node_version* Napi::VersionManagement::GetNodeVersion(Env env);
+static const napi_node_version* Napi::VersionManagement::GetNodeVersion(Napi::BasicEnv env);
```
- `[in] env`: The environment in which the API is invoked under.
diff --git a/eslint.config.js b/eslint.config.js
new file mode 100644
index 000000000..d02c6f529
--- /dev/null
+++ b/eslint.config.js
@@ -0,0 +1,5 @@
+'use strict';
+
+module.exports = require('neostandard')({
+ semi: true,
+});
diff --git a/index.js b/index.js
index 52f53e3c2..e235cc3e9 100644
--- a/index.js
+++ b/index.js
@@ -1,11 +1,14 @@
const path = require('path');
+const { version } = require('./package.json');
const includeDir = path.relative('.', __dirname);
module.exports = {
include: `"${__dirname}"`, // deprecated, can be removed as part of 4.0.0
include_dir: includeDir,
- gyp: path.join(includeDir, 'node_api.gyp:nothing'),
+ gyp: path.join(includeDir, 'node_api.gyp:nothing'), // deprecated.
+ targets: path.join(includeDir, 'node_addon_api.gyp'),
+ version,
isNodeApiBuiltin: true,
needsFlag: false
};
diff --git a/napi-inl.h b/napi-inl.h
index 441fa53ed..9c0c47859 100644
--- a/napi-inl.h
+++ b/napi-inl.h
@@ -9,15 +9,25 @@
////////////////////////////////////////////////////////////////////////////////
// Note: Do not include this file directly! Include "napi.h" instead.
+// This should be a no-op and is intended for better IDE integration.
+#include "napi.h"
#include
+#include
#include
#if NAPI_HAS_THREADS
#include
#endif // NAPI_HAS_THREADS
+#include
#include
#include
+#if defined(__clang__) || defined(__GNUC__)
+#define NAPI_NO_SANITIZE_VPTR __attribute__((no_sanitize("vptr")))
+#else
+#define NAPI_NO_SANITIZE_VPTR
+#endif
+
namespace Napi {
#ifdef NAPI_CPP_CUSTOM_NAMESPACE
@@ -31,22 +41,25 @@ namespace details {
// Node.js releases. Only necessary when they are used in napi.h and napi-inl.h.
constexpr int napi_no_external_buffers_allowed = 22;
+template
+inline void default_basic_finalizer(node_addon_api_basic_env /*env*/,
+ void* data,
+ void* /*hint*/) {
+ delete static_cast(data);
+}
+
// Attach a data item to an object and delete it when the object gets
// garbage-collected.
// TODO: Replace this code with `napi_add_finalizer()` whenever it becomes
// available on all supported versions of Node.js.
-template
+template <
+ typename FreeType,
+ node_addon_api_basic_finalize finalizer = default_basic_finalizer>
inline napi_status AttachData(napi_env env,
napi_value obj,
FreeType* data,
- napi_finalize finalizer = nullptr,
void* hint = nullptr) {
napi_status status;
- if (finalizer == nullptr) {
- finalizer = [](napi_env /*env*/, void* data, void* /*hint*/) {
- delete static_cast(data);
- };
- }
#if (NAPI_VERSION < 5)
napi_value symbol, external;
status = napi_create_symbol(env, nullptr, &symbol);
@@ -73,19 +86,33 @@ inline napi_status AttachData(napi_env env,
// For use in JS to C++ callback wrappers to catch any Napi::Error exceptions
// and rethrow them as JavaScript exceptions before returning from the callback.
template
-inline napi_value WrapCallback(Callable callback) {
-#ifdef NAPI_CPP_EXCEPTIONS
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS_ALL
+inline napi_value WrapCallback(napi_env env, Callable callback) {
+#else
+inline napi_value WrapCallback(napi_env, Callable callback) {
+#endif
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS
try {
return callback();
} catch (const Error& e) {
e.ThrowAsJavaScriptException();
return nullptr;
}
-#else // NAPI_CPP_EXCEPTIONS
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS_ALL
+ catch (const std::exception& e) {
+ Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
+ return nullptr;
+ } catch (...) {
+ Napi::Error::New(env, "A native exception was thrown")
+ .ThrowAsJavaScriptException();
+ return nullptr;
+ }
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS_ALL
+#else // NODE_ADDON_API_CPP_EXCEPTIONS
// When C++ exceptions are disabled, errors are immediately thrown as JS
// exceptions, so there is no need to catch and rethrow them here.
return callback();
-#endif // NAPI_CPP_EXCEPTIONS
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS
}
// For use in JS to C++ void callback wrappers to catch any Napi::Error
@@ -93,7 +120,7 @@ inline napi_value WrapCallback(Callable callback) {
// the callback.
template
inline void WrapVoidCallback(Callable callback) {
-#ifdef NAPI_CPP_EXCEPTIONS
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS
try {
callback();
} catch (const Error& e) {
@@ -106,10 +133,41 @@ inline void WrapVoidCallback(Callable callback) {
#endif // NAPI_CPP_EXCEPTIONS
}
+// For use in JS to C++ void callback wrappers to catch _any_ thrown exception
+// and rethrow them as JavaScript exceptions before returning from the callback,
+// wrapping in an Napi::Error as needed.
+template
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS_ALL
+inline void WrapVoidCallback(napi_env env, Callable callback) {
+#else
+inline void WrapVoidCallback(napi_env, Callable callback) {
+#endif
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS
+ try {
+ callback();
+ } catch (const Error& e) {
+ e.ThrowAsJavaScriptException();
+ }
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS_ALL
+ catch (const std::exception& e) {
+ Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
+ } catch (...) {
+ Napi::Error::New(env, "A native exception was thrown")
+ .ThrowAsJavaScriptException();
+ }
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS_ALL
+#else
+ // When C++ exceptions are disabled, there is no need to catch and rethrow C++
+ // exceptions. JS errors should be thrown with
+ // `Error::ThrowAsJavaScriptException`.
+ callback();
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS
+}
+
template
struct CallbackData {
static inline napi_value Wrapper(napi_env env, napi_callback_info info) {
- return details::WrapCallback([&] {
+ return details::WrapCallback(env, [&] {
CallbackInfo callbackInfo(env, info);
CallbackData* callbackData =
static_cast(callbackInfo.Data());
@@ -125,7 +183,7 @@ struct CallbackData {
template
struct CallbackData {
static inline napi_value Wrapper(napi_env env, napi_callback_info info) {
- return details::WrapCallback([&] {
+ return details::WrapCallback(env, [&] {
CallbackInfo callbackInfo(env, info);
CallbackData* callbackData =
static_cast(callbackInfo.Data());
@@ -142,7 +200,7 @@ struct CallbackData {
template
napi_value TemplatedVoidCallback(napi_env env,
napi_callback_info info) NAPI_NOEXCEPT {
- return details::WrapCallback([&] {
+ return details::WrapCallback(env, [&] {
CallbackInfo cbInfo(env, info);
Callback(cbInfo);
return nullptr;
@@ -152,9 +210,12 @@ napi_value TemplatedVoidCallback(napi_env env,
template
napi_value TemplatedCallback(napi_env env,
napi_callback_info info) NAPI_NOEXCEPT {
- return details::WrapCallback([&] {
+ return details::WrapCallback(env, [&] {
CallbackInfo cbInfo(env, info);
- return Callback(cbInfo);
+ // MSVC requires to copy 'Callback' function pointer to a local variable
+ // before invoking it.
+ auto callback = Callback;
+ return callback(cbInfo);
});
}
@@ -162,7 +223,7 @@ template
napi_value TemplatedInstanceCallback(napi_env env,
napi_callback_info info) NAPI_NOEXCEPT {
- return details::WrapCallback([&] {
+ return details::WrapCallback(env, [&] {
CallbackInfo cbInfo(env, info);
T* instance = T::Unwrap(cbInfo.This().As