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 13fd005c0..4b0ebfb23 100644
--- a/.github/workflows/ci-win.yml
+++ b/.github/workflows/ci-win.yml
@@ -12,21 +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@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+ - 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@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # v4.7.1
+ 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@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+ uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
with:
node-version: ${{ matrix.node-version }}
architecture: ${{ matrix.architecture }}
@@ -38,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 64bda90dd..3813c3d62 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -12,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
@@ -25,13 +34,18 @@ jobs:
compiler: gcc # GCC is an alias for clang on the MacOS image.
runs-on: ${{ matrix.os }}
steps:
- - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+ - 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@65d7f2d534ac1bc67fcd62888c5f4f3d2cb2b236 # v4.7.1
+ 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@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.0
+ uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
with:
node-version: ${{ matrix.node-version }}
- name: Check Node.js installation
@@ -43,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 256dc9d2b..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@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+ 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@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
- uses: github/codeql-action/init@407ffafae6a767df3e0230c3df91b6443ae8df75 # v2.22.8
+ 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@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.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@407ffafae6a767df3e0230c3df91b6443ae8df75 # v2.22.8
+ 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 fbaf8acfd..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@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+ 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@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
- name: 'Dependency Review'
- uses: actions/dependency-review-action@01bc87099ba56df1e897b6874784491ea6309bc4 # v3.1.4
+ uses: actions/dependency-review-action@2031cfc080254a8a887f58cffee85186f0e49e48 # v4.9.0
diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml
index d855061a6..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@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+ - 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@8f152de45cc393bb48ce5d89d36b731f54556e65 # v4.0.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 f0afbab87..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@eb238b55efaa70779f274895e782ed17c84f2895 # v2.6.1
+ 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@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+ uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
persist-credentials: false
- name: "Run analysis"
- uses: ossf/scorecard-action@0864cf19026789058feabb7e87baa5f140aac736 # v2.3.1
+ 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@a8a3f3ad30e3422c9c7b888a15615d19a852ae32 # v3.1.3
+ 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@407ffafae6a767df3e0230c3df91b6443ae8df75 # v2.22.8
+ 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 759e9474c..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@1160a2240286f5da8ec72b1c0816ce2481aabf84 # v8.0.0
+ - 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 bcded4821..a154db646 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,8 +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..a23c78a67
--- /dev/null
+++ b/.release-please-manifest.json
@@ -0,0 +1,3 @@
+{
+ ".": "8.9.0"
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e0477814e..e3c30a2e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,216 @@
# node-addon-api Changelog
+## [8.9.0](https://github.com/nodejs/node-addon-api/compare/v8.8.0...v8.9.0) (2026-05-24)
+
+
+### Features
+
+* add support for SharedArrayBuffer in TypedArray and TypedArrayOf<T> ([#1731](https://github.com/nodejs/node-addon-api/issues/1731)) ([00b95ef](https://github.com/nodejs/node-addon-api/commit/00b95efea6522980e9661a729a59b926ecf5c6b6))
+
+## [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 +1308,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/README.md b/README.md
index 8c43818ff..3259d7743 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.9.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/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)**
-
-
-
-### **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/common.gypi b/common.gypi
index 06c0176b2..5fda7e77a 100644
--- a/common.gypi
+++ b/common.gypi
@@ -5,6 +5,7 @@
},
'conditions': [
['NAPI_VERSION!=""', { 'defines': ['NAPI_VERSION=<@(NAPI_VERSION)'] } ],
+ ['NAPI_VERSION==2147483647', { 'defines': ['NAPI_EXPERIMENTAL', 'NODE_API_EXPERIMENTAL_NO_WARNING'] } ],
['disable_deprecated=="true"', {
'defines': ['NODE_ADDON_API_DISABLE_DEPRECATED']
}],
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 000000000..e5e24dfbe
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,146 @@
+# node-addon-api Documents
+
+* [Setup](#setup)
+* [API Documentation](#api)
+* [Examples](#examples)
+* [ABI Stability Guideline](#abi-stability-guideline)
+* [More resource and info about native Addons](#resources)
+
+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.
+
+## Setup
+ - [Installation and usage](setup.md)
+ - [node-gyp](node-gyp.md)
+ - [cmake-js](cmake-js.md)
+ - [Conversion tool](conversion-tool.md)
+ - [Checker tool](checker-tool.md)
+ - [Generator](generator.md)
+ - [Prebuild tools](prebuild_tools.md)
+
+
+
+## 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_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/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 85bdf9412..1d5df91ca 100644
--- a/doc/cmake-js.md
+++ b/doc/cmake-js.md
@@ -45,6 +45,25 @@ 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).
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 29aa4459e..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,132 +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`.
-
-### GetModuleFileName
-
-```cpp
-const char* Napi::Env::GetModuleFileName() const;
-```
-
-Returns a 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.
-
-### 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 29bb1a743..b3b7effc6 100644
--- a/doc/setup.md
+++ b/doc/setup.md
@@ -38,7 +38,10 @@ To use **Node-API** in a native module:
],
```
- To enable that capability, add an alternative dependency in `binding.gyp`:
+ To enable that capability, add an alternative dependency in `binding.gyp`
+ depending on if you want to integrate C++ exception handling for exceptions
+ derived from `Napi::Error` or all C++ exceptions. To catch only
+ `Napi::Error` exceptions, use:
```gyp
'dependencies': [
@@ -46,6 +49,15 @@ To use **Node-API** in a native module:
],
```
+ Or, to allow catching all native C++ exceptions, use the
+ `node_addon_api_except_all` dependency:
+
+ ```gyp
+ 'dependencies': [
+ "()` 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 90e358236..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
@@ -255,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 4877abc97..e235cc3e9 100644
--- a/index.js
+++ b/index.js
@@ -1,4 +1,5 @@
const path = require('path');
+const { version } = require('./package.json');
const includeDir = path.relative('.', __dirname);
@@ -7,6 +8,7 @@ module.exports = {
include_dir: includeDir,
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 a5ae7af72..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
@@ -32,7 +42,9 @@ namespace details {
constexpr int napi_no_external_buffers_allowed = 22;
template
-inline void default_finalizer(napi_env /*env*/, void* data, void* /*hint*/) {
+inline void default_basic_finalizer(node_addon_api_basic_env /*env*/,
+ void* data,
+ void* /*hint*/) {
delete static_cast(data);
}
@@ -40,8 +52,9 @@ inline void default_finalizer(napi_env /*env*/, void* data, void* /*hint*/) {
// 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,
@@ -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