pax_global_header00006660000000000000000000000064147561227310014522gustar00rootroot0000000000000052 comment=723f094374bc3ae9bd94d9bcc4b44604c70a5425 node-addon-api-8.3.1/000077500000000000000000000000001475612273100143125ustar00rootroot00000000000000node-addon-api-8.3.1/.clang-format000066400000000000000000000061631475612273100166730ustar00rootroot00000000000000--- Language: Cpp # BasedOnStyle: Google AccessModifierOffset: -1 AlignAfterOpenBracket: Align AlignConsecutiveAssignments: false AlignConsecutiveDeclarations: false AlignEscapedNewlines: Right AlignOperands: true AlignTrailingComments: true AllowAllParametersOfDeclarationOnNextLine: true AllowShortBlocksOnASingleLine: false AllowShortCaseLabelsOnASingleLine: false AllowShortFunctionsOnASingleLine: Inline AllowShortIfStatementsOnASingleLine: true AllowShortLoopsOnASingleLine: true AlwaysBreakAfterDefinitionReturnType: None AlwaysBreakAfterReturnType: None AlwaysBreakBeforeMultilineStrings: false AlwaysBreakTemplateDeclarations: true BinPackArguments: false BinPackParameters: false BraceWrapping: AfterClass: false AfterControlStatement: false AfterEnum: false AfterFunction: false AfterNamespace: false AfterObjCDeclaration: false AfterStruct: false AfterUnion: false AfterExternBlock: false BeforeCatch: false BeforeElse: false IndentBraces: false SplitEmptyFunction: true SplitEmptyRecord: true SplitEmptyNamespace: true BreakBeforeBinaryOperators: None BreakBeforeBraces: Attach BreakBeforeInheritanceComma: false BreakBeforeTernaryOperators: true BreakConstructorInitializersBeforeComma: false BreakConstructorInitializers: BeforeColon BreakAfterJavaFieldAnnotations: false BreakStringLiterals: true ColumnLimit: 80 CommentPragmas: '^ IWYU pragma:' CompactNamespaces: false ConstructorInitializerAllOnOneLineOrOnePerLine: true ConstructorInitializerIndentWidth: 4 ContinuationIndentWidth: 4 Cpp11BracedListStyle: true DerivePointerAlignment: false DisableFormat: false ExperimentalAutoDetectBinPacking: false FixNamespaceComments: true ForEachMacros: - foreach - Q_FOREACH - BOOST_FOREACH IncludeBlocks: Preserve IncludeCategories: - Regex: '^' Priority: 2 - Regex: '^<.*\.h>' Priority: 1 - Regex: '^<.*' Priority: 2 - Regex: '.*' Priority: 3 IncludeIsMainRegex: '([-_](test|unittest))?$' IndentCaseLabels: true IndentPPDirectives: None IndentWidth: 2 IndentWrappedFunctionNames: false JavaScriptQuotes: Leave JavaScriptWrapImports: true KeepEmptyLinesAtTheStartOfBlocks: false MacroBlockBegin: '' MacroBlockEnd: '' MaxEmptyLinesToKeep: 1 NamespaceIndentation: None ObjCBlockIndentWidth: 2 ObjCSpaceAfterProperty: false ObjCSpaceBeforeProtocolList: false PenaltyBreakAssignment: 2 PenaltyBreakBeforeFirstCallParameter: 1 PenaltyBreakComment: 300 PenaltyBreakFirstLessLess: 120 PenaltyBreakString: 1000 PenaltyExcessCharacter: 1000000 PenaltyReturnTypeOnItsOwnLine: 200 PointerAlignment: Left ReflowComments: true SortIncludes: true SortUsingDeclarations: true SpaceAfterCStyleCast: false SpaceAfterTemplateKeyword: true SpaceBeforeAssignmentOperators: true SpaceBeforeParens: ControlStatements SpaceInEmptyParentheses: false SpacesBeforeTrailingComments: 2 SpacesInAngles: false SpacesInContainerLiterals: true SpacesInCStyleCastParentheses: false SpacesInParentheses: false SpacesInSquareBrackets: false Standard: Auto TabWidth: 8 UseTab: Never node-addon-api-8.3.1/.editorconfig000066400000000000000000000002021475612273100167610ustar00rootroot00000000000000root = true [*] charset = utf-8 trim_trailing_whitespace = true insert_final_newline = true indent_style = space indent_size = 2 node-addon-api-8.3.1/.github/000077500000000000000000000000001475612273100156525ustar00rootroot00000000000000node-addon-api-8.3.1/.github/PULL_REQUEST_TEMPLATE.md000066400000000000000000000023471475612273100214610ustar00rootroot00000000000000 node-addon-api-8.3.1/.github/dependabot.yml000066400000000000000000000007151475612273100205050ustar00rootroot00000000000000version: 2 updates: - package-ecosystem: github-actions directory: / schedule: interval: weekly groups: all: patterns: - '*' - package-ecosystem: npm directory: / schedule: interval: weekly groups: all: patterns: - '*' - package-ecosystem: npm directory: /test/addon_build/tpl schedule: interval: weekly groups: all: patterns: - '*' node-addon-api-8.3.1/.github/workflows/000077500000000000000000000000001475612273100177075ustar00rootroot00000000000000node-addon-api-8.3.1/.github/workflows/ci-win.yml000066400000000000000000000030221475612273100216150ustar00rootroot00000000000000name: Node.js CI Windows Platform on: [push, pull_request] env: PYTHON_VERSION: '3.11' permissions: contents: read jobs: test: timeout-minutes: 30 strategy: fail-fast: false matrix: api_version: - standard - experimental node-version: - 18.x - 20.x - 22.x architecture: [x64, x86] os: - windows-2019 - windows-2022 runs-on: ${{ matrix.os }} steps: - name: Harden Runner uses: step-security/harden-runner@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - name: Set up Python ${{ env.PYTHON_VERSION }} uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0 with: python-version: ${{ env.PYTHON_VERSION }} - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0 with: node-version: ${{ matrix.node-version }} architecture: ${{ matrix.architecture }} - name: Check Node.js installation run: | node --version npm --version - name: Install dependencies 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 node-addon-api-8.3.1/.github/workflows/ci.yml000066400000000000000000000040751475612273100210330ustar00rootroot00000000000000name: Node.js CI Unix Platform on: [push, pull_request] env: PYTHON_VERSION: '3.11' permissions: contents: read jobs: test: timeout-minutes: 30 strategy: fail-fast: false matrix: api_version: - standard - experimental node-version: - 18.x - 20.x - 22.x os: - macos-latest - ubuntu-latest compiler: - clang - gcc exclude: - os: macos-latest compiler: gcc # GCC is an alias for clang on the MacOS image. runs-on: ${{ matrix.os }} steps: - name: Harden Runner uses: step-security/harden-runner@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - name: Set up Python ${{ env.PYTHON_VERSION }} uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0 with: python-version: ${{ env.PYTHON_VERSION }} - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0 with: node-version: ${{ matrix.node-version }} - name: Check Node.js installation run: | node --version npm --version - name: Install dependencies run: | 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 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" echo "CFLAGS=\"$CFLAGS\" LDFLAGS=\"$LDFLAGS\"" npm run pretest -- --verbose node test node-addon-api-8.3.1/.github/workflows/codeql.yml000066400000000000000000000061131475612273100217020ustar00rootroot00000000000000# For most projects, this workflow file will not need changing; you simply need # to commit it to your repository. # # You may wish to alter this file to override the set of languages analyzed, # or to provide custom queries or build logic. # # ******** NOTE ******** # We have attempted to detect the languages in your repository. Please check # the `language` matrix defined below to confirm you have the correct set of # supported CodeQL languages. # name: "CodeQL" on: push: branches: ["main"] pull_request: # The branches below must be a subset of the branches above branches: ["main"] schedule: - cron: "0 0 * * 1" permissions: contents: read jobs: analyze: name: Analyze runs-on: ubuntu-latest permissions: actions: read contents: read security-events: write strategy: fail-fast: false matrix: language: ["cpp", "javascript"] # CodeQL supports [ $supported-codeql-languages ] # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support steps: - name: Harden Runner uses: step-security/harden-runner@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs - name: Checkout repository uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 # Initializes the CodeQL tools for scanning. - name: Initialize CodeQL uses: github/codeql-action/init@9e8d0789d4a0fa9ceb6b1738f7e269594bdd67f0 # v3.28.9 with: languages: ${{ matrix.language }} # If you wish to specify custom queries, you can do so here or in a config file. # By default, queries listed here will override any specified in a config file. # Prefix the list here with "+" to use these queries and those in the config file. # Autobuild attempts to build any compiled languages (C/C++, C#, or Java). # If this step fails, then you should remove it and run the build manually (see below) # - name: Autobuild # uses: github/codeql-action/autobuild@7df0ce34898d659f95c0c4a09eaa8d4e32ee64db # v2.2.12 # ℹ️ Command-line programs to run using the OS shell. # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun # If the Autobuild fails above, remove it and uncomment the following three lines. # modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance. - name: Use Node.js v18.x if: matrix.language == 'cpp' uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0 with: node-version: 18.x - name: Build cpp if: matrix.language == 'cpp' run: | npx node-gyp rebuild -C test - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@9e8d0789d4a0fa9ceb6b1738f7e269594bdd67f0 # v3.28.9 with: category: "/language:${{matrix.language}}" node-addon-api-8.3.1/.github/workflows/coverage-linux.yml000066400000000000000000000034651475612273100233720ustar00rootroot00000000000000name: 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@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: persist-credentials: false - name: Set up Python ${{ env.PYTHON_VERSION }} uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0 with: python-version: ${{ env.PYTHON_VERSION }} - name: Use Node.js ${{ env.NODE_VERSION }} uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.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@13ce06bfc6bbe3ecf90edbbf1bc32fe5978ca1d3 # v5.3.1 with: directory: ./coverage-xml node-addon-api-8.3.1/.github/workflows/dependency-review.yml000066400000000000000000000020111475612273100240410ustar00rootroot00000000000000# Dependency Review Action # # This Action will scan dependency manifest files that change as part of a Pull Request, # surfacing known-vulnerable versions of the packages declared or updated in the PR. # Once installed, if the workflow run is marked as required, # PRs introducing known-vulnerable packages will be blocked from merging. # # Source repository: https://github.com/actions/dependency-review-action name: 'Dependency Review' on: [pull_request] permissions: contents: read jobs: dependency-review: runs-on: ubuntu-latest steps: - name: Harden Runner uses: step-security/harden-runner@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs - name: 'Checkout Repository' uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - name: 'Dependency Review' uses: actions/dependency-review-action@3b139cfc5fae8b618d3eae3675e383bb1769c019 # v4.5.0 node-addon-api-8.3.1/.github/workflows/linter.yml000066400000000000000000000015171475612273100217330ustar00rootroot00000000000000name: Style Checks on: [push, pull_request] permissions: contents: read jobs: lint: if: github.repository == 'nodejs/node-addon-api' strategy: matrix: node-version: [22.x] os: [ubuntu-latest] runs-on: ${{ matrix.os }} steps: - name: Harden Runner uses: step-security/harden-runner@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: fetch-depth: 0 - run: git branch -a - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0 with: node-version: ${{ matrix.node-version }} - run: npm install - run: FORMAT_START=refs/remotes/origin/main npm run lint node-addon-api-8.3.1/.github/workflows/node-api-headers.yml000066400000000000000000000037671475612273100235540ustar00rootroot00000000000000name: 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@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - name: Set up Python ${{ env.PYTHON_VERSION }} uses: actions/setup-python@42375524e23c412d93fb67b49958b491fce71c38 # v5.4.0 with: python-version: ${{ env.PYTHON_VERSION }} - name: Use Node.js ${{ matrix.node-version }} uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.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 node-addon-api-8.3.1/.github/workflows/release-please.yml000066400000000000000000000026431475612273100233260ustar00rootroot00000000000000name: release-please on: push: branches: - main workflow_dispatch: 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@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit - uses: googleapis/release-please-action@7987652d64b4581673a76e33ad5e98e3dd56832f # v4.1.3 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@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 - uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4.2.0 with: node-version: lts/* registry-url: 'https://registry.npmjs.org' - run: npm publish --provenance --access public env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} node-addon-api-8.3.1/.github/workflows/scorecards.yml000066400000000000000000000060631475612273100225670ustar00rootroot00000000000000# This workflow uses actions that are not certified by GitHub. They are provided # by a third-party and are governed by separate terms of service, privacy # policy, and support documentation. name: Scorecard supply-chain security on: # For Branch-Protection check. Only the default branch is supported. See # https://github.com/ossf/scorecard/blob/main/docs/checks.md#branch-protection branch_protection_rule: # To guarantee Maintained check is occasionally updated. See # https://github.com/ossf/scorecard/blob/main/docs/checks.md#maintained schedule: - cron: '20 7 * * 2' push: branches: ["main"] # Declare default permissions as read only. permissions: read-all jobs: analysis: name: Scorecard analysis runs-on: ubuntu-latest permissions: # Needed to upload the results to code-scanning dashboard. security-events: write # Needed to publish results and get a badge (see publish_results below). id-token: write contents: read actions: read steps: - name: Harden Runner uses: step-security/harden-runner@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs - name: "Checkout code" uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: persist-credentials: false - name: "Run analysis" uses: ossf/scorecard-action@62b2cac7ed8198b15735ed49ab1e5cf35480ba46 # v2.4.0 with: results_file: results.sarif results_format: sarif # (Optional) "write" PAT token. Uncomment the `repo_token` line below if: # - you want to enable the Branch-Protection check on a *public* repository, or # - you are installing Scorecards on a *private* repository # To create the PAT, follow the steps in https://github.com/ossf/scorecard-action#authentication-with-pat. # repo_token: ${{ secrets.SCORECARD_TOKEN }} # Public repositories: # - Publish results to OpenSSF REST API for easy access by consumers # - Allows the repository to include the Scorecard badge. # - See https://github.com/ossf/scorecard-action#publishing-results. # For private repositories: # - `publish_results` will always be set to `false`, regardless # of the value entered here. publish_results: true # 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@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0 with: name: SARIF file path: results.sarif retention-days: 5 # Upload the results to GitHub's code scanning dashboard. - name: "Upload to code-scanning" uses: github/codeql-action/upload-sarif@9e8d0789d4a0fa9ceb6b1738f7e269594bdd67f0 # v3.28.9 with: sarif_file: results.sarif node-addon-api-8.3.1/.github/workflows/stale.yml000066400000000000000000000016221475612273100215430ustar00rootroot00000000000000name: "Close stale issues" on: schedule: - cron: "0 0 * * *" permissions: contents: read jobs: stale: permissions: issues: write # for actions/stale to close stale issues pull-requests: write # for actions/stale to close stale PRs runs-on: ubuntu-latest steps: - name: Harden Runner uses: step-security/harden-runner@cb605e52c26070c328afc4562f0b4ada7618a84e # v2.10.4 with: egress-policy: audit - uses: actions/stale@5bef64f19d7facfb25b37b414482c7164d639639 # v9.1.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.' stale-issue-label: 'stale' exempt-issue-labels: 'never-stale' days-before-stale: 90 days-before-close: 30 node-addon-api-8.3.1/.gitignore000066400000000000000000000005571475612273100163110ustar00rootroot00000000000000/node_modules /build /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/ node-addon-api-8.3.1/.npmrc000066400000000000000000000000231475612273100154250ustar00rootroot00000000000000package-lock=false node-addon-api-8.3.1/.release-please-manifest.json000066400000000000000000000000231475612273100217510ustar00rootroot00000000000000{ ".": "8.3.1" } node-addon-api-8.3.1/CHANGELOG.md000066400000000000000000003416771475612273100161450ustar00rootroot00000000000000# node-addon-api Changelog ## [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 #### API - Drop support for Node.js v14.x and v19.x. - Ensure native receiver exists when calling instance methods and properties. - Fix issue when creating `Napi::Error` instances that wrap primitives values. #### TEST - Added tests for `Napi::AsyncProgressQueueWorker` class. - Added tests for `Napi::AsyncProgressWorker` class. ### Documentation - Added documentation for `Napi::Value::IsBigInt()`. ### Commits * \[[`de5c899400`](https://github.com/nodejs/node-addon-api/commit/de5c899400)] - **doc,chore**: drop support for Node.js v14, v19 (Kevin Eady) [#1324](https://github.com/nodejs/node-addon-api/pull/1324) * \[[`3083b7f148`](https://github.com/nodejs/node-addon-api/commit/3083b7f148)] - \[StepSecurity] Apply security best practices (StepSecurity Bot) [#1308](https://github.com/nodejs/node-addon-api/pull/1308) * \[[`a198e24a15`](https://github.com/nodejs/node-addon-api/commit/a198e24a15)] - \[Test] Add tests for async progress queue worker (Jack) [#1316](https://github.com/nodejs/node-addon-api/pull/1316) * \[[`665f4aa845`](https://github.com/nodejs/node-addon-api/commit/665f4aa845)] - **doc**: add missing Value::IsBigInt (Kevin Eady) [#1319](https://github.com/nodejs/node-addon-api/pull/1319) * \[[`358b2d3b4f`](https://github.com/nodejs/node-addon-api/commit/358b2d3b4f)] - **doc**: complete code curly braces in async\_worker.md (wanlu) [#1317](https://github.com/nodejs/node-addon-api/pull/1317) * \[[`858942ce31`](https://github.com/nodejs/node-addon-api/commit/858942ce31)] - **src**: avoid calling into C++ with a null this (Caleb Hearon) [#1313](https://github.com/nodejs/node-addon-api/pull/1313) * \[[`64f6515331`](https://github.com/nodejs/node-addon-api/commit/64f6515331)] - **src**: handle failure during error wrap of primitive (Gabriel Schulhof) [#1310](https://github.com/nodejs/node-addon-api/pull/1310) * \[[`dfad6b45fe`](https://github.com/nodejs/node-addon-api/commit/dfad6b45fe)] - \[test] Add test coverage for AsyncProgressWorker (Jack) [#1307](https://github.com/nodejs/node-addon-api/pull/1307) * \[[`0e34f22839`](https://github.com/nodejs/node-addon-api/commit/0e34f22839)] - **release**: v6.1.0. (Nicola Del Gobbo) ## 2023-04-20 Version 6.1.0, @NickNaso ### Notable changes #### API - Enforce type checks on `Napi::Value::As()`. - Added `Napi::TypeTaggable` class. - Defined `NAPI_HAS_THREADS` to make TSFN available on Emscripten. - Defined `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` and `Napi::Buffer::NewOrCopy()` to handle the support for external buffers. #### TEST - Added tests for `Napi::Reference` class. - Added tests for copy/move semantics. - Added tests for `Napi::RangeError` and `Napi::TypeError` class. - Fixed inconsistent failure executing test suite. - Added tests for `Napi::ObjectReference` class. - Added tests for `Napi::ObjectWrap` class. ### Documentation - Added documentation for `Napi::TypeTaggable`. - Some minor fixes all over the documentation. ### Commits - \[[`5adb896782`](https://github.com/nodejs/node-addon-api/commit/5adb896782)] - **src**: enforce type checks on Napi::Value::As() (#1281) (Chengzhong Wu) - \[[`d9faac7ec2`](https://github.com/nodejs/node-addon-api/commit/d9faac7ec2)] - Fix exits/exists typo in docs for Env::AddCleanupHook() (#1306) (Mathias Stearn) - \[[`164459ca03`](https://github.com/nodejs/node-addon-api/commit/164459ca03)] - **doc**: update class hierarchy for TypeTaggable (Gabriel Schulhof) [#1303](https://github.com/nodejs/node-addon-api/pull/1303) - \[[`d01304437c`](https://github.com/nodejs/node-addon-api/commit/d01304437c)] - **src**: interject class TypeTaggable (Gabriel Schulhof) [#1298](https://github.com/nodejs/node-addon-api/pull/1298) - \[[`d4942ccd4f`](https://github.com/nodejs/node-addon-api/commit/d4942ccd4f)] - **test**: Complete test coverage for Reference\ class (#1277) (Jack) - \[[`a8ad7e7a7b`](https://github.com/nodejs/node-addon-api/commit/a8ad7e7a7b)] - **test**: Add tests for copy/move semantics (JckXia) [#1295](https://github.com/nodejs/node-addon-api/pull/1295) - \[[`e484327344`](https://github.com/nodejs/node-addon-api/commit/e484327344)] - Add test coverage for typed and range err (#1280) (Jack) - \[[`ebc7858593`](https://github.com/nodejs/node-addon-api/commit/ebc7858593)] - **test**: Update wait with a condition (#1297) (Jack) - \[[`0b53d885f5`](https://github.com/nodejs/node-addon-api/commit/0b53d885f5)] - **src**: define `NAPI_HAS_THREADS` (toyobayashi) [#1283](https://github.com/nodejs/node-addon-api/pull/1283) - \[[`464610babf`](https://github.com/nodejs/node-addon-api/commit/464610babf)] - **test**: complete objectRefs tests (JckXia) [#1274](https://github.com/nodejs/node-addon-api/pull/1274) - \[[`b16c762a19`](https://github.com/nodejs/node-addon-api/commit/b16c762a19)] - **src**: handle no support for external buffers (legendecas) [#1273](https://github.com/nodejs/node-addon-api/pull/1273) - \[[`61b8e28720`](https://github.com/nodejs/node-addon-api/commit/61b8e28720)] - **test**: Add test covg for obj wrap (#1269) (Jack) ## 2023-02-03 Version 6.0.0, @NickNaso ### Notable changes #### API - Added `Napi::Object::TypeTag()` and `Napi::Object::CheckTypeTag()` methods. - Made operator `napi_callback_info` explicit. #### TEST - Some minor fixes all over the test suite. - Added tests related to `Napi::Object::TypeTag()` and `Napi::Object::CheckTypeTag()` methods. - Added tests related to `Napi::CallbackScope`. - Added tests related to `Napi::EscapableHandleScope`. - Added tests related to `Napi::Maybe`. - Added tests related to `Napi::ThreadSafeFuntion`. - Changed some tests related to `Napi::AsyncWorker`. ### Documentation - Added documentation for `Napi::Object::TypeTag()` and `Napi::Object::CheckTypeTag()` methods. - Added documentation about how to run a specific unit test. ### TOOL - Added `x86` architecture to the CI matrix. ### Commits * \[[`e2726193f1`](https://github.com/nodejs/node-addon-api/commit/e2726193f1)] - **src**: remove AsyncWorker move and complete tests (JckXia) [#1266](https://github.com/nodejs/node-addon-api/pull/1266) * \[[`ff969485ea`](https://github.com/nodejs/node-addon-api/commit/ff969485ea)] - **chore**: build node-addon-api against X86 (JckXia) [#1276](https://github.com/nodejs/node-addon-api/pull/1276) * \[[`a70564cdfd`](https://github.com/nodejs/node-addon-api/commit/a70564cdfd)] - **test**: add cov for ThreadSafeFunction new overloads (JckXia) [#1251](https://github.com/nodejs/node-addon-api/pull/1251) * \[[`53f7cf1d48`](https://github.com/nodejs/node-addon-api/commit/53f7cf1d48)] - **src**: make operator napi\_callback\_info explicit (Kevin Eady) [#1275](https://github.com/nodejs/node-addon-api/pull/1275) * \[[`78b5a15533`](https://github.com/nodejs/node-addon-api/commit/78b5a15533)] - **test**: Add tests for ThreadSafeFunction's NonBlock function overloads (#1249) (Jack) * \[[`fdc6263034`](https://github.com/nodejs/node-addon-api/commit/fdc6263034)] - **test**: Add test covg for Maybe\ (#1270) (Jack) * \[[`35d9d669b3`](https://github.com/nodejs/node-addon-api/commit/35d9d669b3)] - **test**: add test covg for handle and escapehandle scopes (JckXia) [#1263](https://github.com/nodejs/node-addon-api/pull/1263) * \[[`021313409e`](https://github.com/nodejs/node-addon-api/commit/021313409e)] - **test**: add unit test covg for callbackscopes (JckXia) [#1262](https://github.com/nodejs/node-addon-api/pull/1262) * \[[`b11e4de2cf`](https://github.com/nodejs/node-addon-api/commit/b11e4de2cf)] - **src**: add Object::TypeTag, Object::CheckTypeTag (Kevin Eady) [#1261](https://github.com/nodejs/node-addon-api/pull/1261) ## 2023-01-13 Version 5.1.0, @NickNaso ### Notable changes #### API - Fixed memory leak in `Napi::AsyncProgressWorkerBase`. - Added api to get `callback_info` from `Napi::CallBackInfo`. - Fixed erros and warning in VS 2017. - Made `Npi::Env::CleanupHook` public. - Removed `Napi::TypedArray::unknown_array_type`. #### TEST - Some minor fixes all over the test suite. - Added tests related to `Napi::Env`. - Added tests related to `Napi::TypedArray`. - Added tests related to `Napi::AsyncWorker`. - Added tests related to `Napi::TypedThreadSafeFunction`. - Added tests related to `Napi::Value`. - Added test related to `Napi::Promise`. ### Documentation - Some minor fixes all over the documentation. - Added `Napi::HandleScope` example. - Added documentation about how to run a specific unit test. ### TOOL - Added Windows with VS 2022 and Node.JS 19.x to the CI matrix. - Fixed stale workflow. - Updated Node.js versions on CI component. - Added condition for Window to find eslint. ### Commits * \[[`79a446fb9c`](https://github.com/nodejs/node-addon-api/commit/79a446fb9c)] - Update contributors (#1265) (Kevin Eady) * \[[`01c61690c6`](https://github.com/nodejs/node-addon-api/commit/01c61690c6)] - **src**: napi-inl: Fix a memory leak bug in `AsyncProgressWorkerBase` (Ammar Faizi) [#1264](https://github.com/nodejs/node-addon-api/pull/1264) * \[[`55bd08ee26`](https://github.com/nodejs/node-addon-api/commit/55bd08ee26)] - **src**: api to get callback\_info from CallBackInfo (JckXia) [#1253](https://github.com/nodejs/node-addon-api/pull/1253) * \[[`ad76256714`](https://github.com/nodejs/node-addon-api/commit/ad76256714)] - **test**: add tests related to env (JckXia) [#1254](https://github.com/nodejs/node-addon-api/pull/1254) * \[[`5c3937365d`](https://github.com/nodejs/node-addon-api/commit/5c3937365d)] - **chore**: add Windows with VS 2022 and Node.JS 19.x to the CI matrix (#1252) (Vladimir Morozov) * \[[`97736c93f4`](https://github.com/nodejs/node-addon-api/commit/97736c93f4)] - **src**: fix errors and warnings in VS 2017 (Vladimir Morozov) [#1245](https://github.com/nodejs/node-addon-api/pull/1245) * \[[`ad7ff92c16`](https://github.com/nodejs/node-addon-api/commit/ad7ff92c16)] - **src**: refactor call js wrapper (#1242) (Jack) * \[[`39267baf1b`](https://github.com/nodejs/node-addon-api/commit/39267baf1b)] - **src**: make CleanupHook public (Julian Mesa) [#1240](https://github.com/nodejs/node-addon-api/pull/1240) * \[[`edf630cc79`](https://github.com/nodejs/node-addon-api/commit/edf630cc79)] - **src**: fix implementation of Signal (Kevin Eady) [#1216](https://github.com/nodejs/node-addon-api/pull/1216) * \[[`de5a502f3c`](https://github.com/nodejs/node-addon-api/commit/de5a502f3c)] - **doc**: Napi::Error is caught (Nicola Del Gobbo) [#1241](https://github.com/nodejs/node-addon-api/pull/1241) * \[[`10ad762807`](https://github.com/nodejs/node-addon-api/commit/10ad762807)] - **test**: removed the usage of default\_configuration. (Nicola Del Gobbo) [#1226](https://github.com/nodejs/node-addon-api/pull/1226) * \[[`e9db2adef2`](https://github.com/nodejs/node-addon-api/commit/e9db2adef2)] - **test**: Add test coverage to TSFN::New() overloads (#1201) (Jack) * \[[`c849ad3f6a`](https://github.com/nodejs/node-addon-api/commit/c849ad3f6a)] - **chore**: fix stale workflow (#1228) (Richard Lau) * \[[`e408804ad8`](https://github.com/nodejs/node-addon-api/commit/e408804ad8)] - **test**: adding ref for threadsafefunctions (JckXia) [#1222](https://github.com/nodejs/node-addon-api/pull/1222) * \[[`a8afb2d73c`](https://github.com/nodejs/node-addon-api/commit/a8afb2d73c)] - **src**: remove TypedArray::unknown\_array\_type (Kevin Eady) [#1209](https://github.com/nodejs/node-addon-api/pull/1209) * \[[`257a52f823`](https://github.com/nodejs/node-addon-api/commit/257a52f823)] - **test**: Add test cased for failed task cancellations (#1214) (Jack) * \[[`793268c59f`](https://github.com/nodejs/node-addon-api/commit/793268c59f)] - **test**: Add test case for canceling async worker tasks (#1202) (Jack) * \[[`1331856ef1`](https://github.com/nodejs/node-addon-api/commit/1331856ef1)] - **doc**: add HandleScope example (#1210) (Kevin Eady) * \[[`d5fc875e5d`](https://github.com/nodejs/node-addon-api/commit/d5fc875e5d)] - **test**: remove update to process.config (#1208) (Michael Dawson) * \[[`30cd4a37f0`](https://github.com/nodejs/node-addon-api/commit/30cd4a37f0)] - **test**: add tests for .Data method (JckXia) [#1203](https://github.com/nodejs/node-addon-api/pull/1203) * \[[`225ca35963`](https://github.com/nodejs/node-addon-api/commit/225ca35963)] - **test**: Add test coverage for "TSFN::Ref()" (#1196) (Jack) * \[[`5a5a213985`](https://github.com/nodejs/node-addon-api/commit/5a5a213985)] - Update CI component versions (#1200) (Vladimir Morozov) * \[[`fb27e72b0c`](https://github.com/nodejs/node-addon-api/commit/fb27e72b0c)] - **doc**: Update CONTRIBUTING.md (Saint Gabriel) [#1185](https://github.com/nodejs/node-addon-api/pull/1185) * \[[`e9def3ed72`](https://github.com/nodejs/node-addon-api/commit/e9def3ed72)] - **doc**: Update Readme for filter conditions in unit tests (Deepak Rajamohan) [#1199](https://github.com/nodejs/node-addon-api/pull/1199) * \[[`efd67876e1`](https://github.com/nodejs/node-addon-api/commit/efd67876e1)] - **doc**: updated npm script for focused tests (Peter Šándor) * \[[`134961d853`](https://github.com/nodejs/node-addon-api/commit/134961d853)] - **test**: CallbackInfo NewTarget() basic coverage (#1048) (Peter Šándor) * \[[`1dfd03bdd5`](https://github.com/nodejs/node-addon-api/commit/1dfd03bdd5)] - Update README.md (#1187) (Saint Gabriel) * \[[`576128fd19`](https://github.com/nodejs/node-addon-api/commit/576128fd19)] - **doc**: fix typo in async\_operations.md (#1189) (Tobias Nießen) * \[[`63d3c30ec1`](https://github.com/nodejs/node-addon-api/commit/63d3c30ec1)] - **test**: add tests for TypedArray (Dante Calderon) [#1179](https://github.com/nodejs/node-addon-api/pull/1179) * \[[`358ac2f080`](https://github.com/nodejs/node-addon-api/commit/358ac2f080)] - Fix link to CMake.js documentation (#1180) (Kyle Kovacs) * \[[`dc4f2bbe4a`](https://github.com/nodejs/node-addon-api/commit/dc4f2bbe4a)] - **test**: Add promise unit test (#1173) (Jenny) * \[[`f3124ae0ed`](https://github.com/nodejs/node-addon-api/commit/f3124ae0ed)] - **doc**: fix broken `Napi::ThreadSafeFunction` link (#1172) (Feng Yu) * \[[`10b440fe27`](https://github.com/nodejs/node-addon-api/commit/10b440fe27)] - **src**: reformat all code (Kevin Eady) [#1160](https://github.com/nodejs/node-addon-api/pull/1160) * \[[`33e402971e`](https://github.com/nodejs/node-addon-api/commit/33e402971e)] - **test**: Add condition for window to find eslint (#1176) (Jack) * \[[`d53843b83b`](https://github.com/nodejs/node-addon-api/commit/d53843b83b)] - **test**: add missing value tests (JckXia) [#1170](https://github.com/nodejs/node-addon-api/pull/1170) ## 2022-05-02 Version 5.0.0, @NickNaso ### Notable changes: #### API - Marked methods of wrapper classes `const`. - Enabled wrapping `Napi` namespace with custom namespace. - Added an override to `Napi::Function::Call` to call it with a c-style array of `Napi::Value`'s. - Some other minor fixes. #### TEST - Improved the test framework. Added the possibility to run subsets of tests more easily. - Added test for `Napi::AsyncContext` class. - Fixed ramdom failure on test for `Napi::ThreadSafeFunction` e `Napi::TypedThreadSafeFunction` class. - Fixed compilation problem on debian 8 system. - Added test for `Napi::Object::Set()` method. ### Documentation - Added some clarifications for `Napi::ClassPropertyDescriptor`. - Added clarification about weak reference for `Napi::ObjectWrap`. - Some minor fixes all over the documentation. ### TOOL - Fixed `eslint` configuration. - Fixed CI configuration for Windows. - Enabled pre-commit `ClangFormat` on Windows. ### Commits * \[[`f32db917f3`](https://github.com/nodejs/node-addon-api/commit/f32db917f3)] - Add test coverage for async contexts (#1164) (Jack) * \[[`24455f88af`](https://github.com/nodejs/node-addon-api/commit/24455f88af)] - **src**: check for tsfn in conditional\_variable wait (Kevin Eady) [#1168](https://github.com/nodejs/node-addon-api/pull/1168) * \[[`40ed7ce409`](https://github.com/nodejs/node-addon-api/commit/40ed7ce409)] - **src**: fix regression introduced by #874 (Michael Dawson) * \[[`9bea434326`](https://github.com/nodejs/node-addon-api/commit/9bea434326)] - **doc**: added some comments to ClassPropertyDescriptor. (#1149) (Nicola Del Gobbo) * \[[`57c212e15f`](https://github.com/nodejs/node-addon-api/commit/57c212e15f)] - **buld**: Enable running pre-commit ClangFormat on Win (Vladimir Morozov) * \[[`8c46a9501a`](https://github.com/nodejs/node-addon-api/commit/8c46a9501a)] - **doc**: clarify ObjectWrap weak ref behavior (#1155) (Alba Mendez) * \[[`01274966d5`](https://github.com/nodejs/node-addon-api/commit/01274966d5)] - **build**: run Windows CI only on nondeprecated build configurations (#1152) (Darshan Sen) * \[[`b8449e17e0`](https://github.com/nodejs/node-addon-api/commit/b8449e17e0)] - **src**: mark methods of wrapper classes const (Nikolai Vavilov) [#874](https://github.com/nodejs/node-addon-api/pull/874) * \[[`5e2c1f24f8`](https://github.com/nodejs/node-addon-api/commit/5e2c1f24f8)] - **lint**: set sourceType to 'script' (#1141) (Anna Henningsen) * \[[`da8af20152`](https://github.com/nodejs/node-addon-api/commit/da8af20152)] - **doc**: mention Napi::Env arg for Finalization callback (#1139) (extremeheat) * \[[`5b51864a39`](https://github.com/nodejs/node-addon-api/commit/5b51864a39)] - **src**: enable wrapping Napi namespace with custom namespace (#1135) (Anna Henningsen) * \[[`c54aeef5fd`](https://github.com/nodejs/node-addon-api/commit/c54aeef5fd)] - Add Function::Call Napi::Value override (#1026) (rgerd) * \[[`e906b5a7ce`](https://github.com/nodejs/node-addon-api/commit/e906b5a7ce)] - **test**: fix compilation problem on debian 8 (NickNaso) [#1138](https://github.com/nodejs/node-addon-api/pull/1138) * \[[`5790c55784`](https://github.com/nodejs/node-addon-api/commit/5790c55784)] - **src**: do not use non-static class member for constant value (#1134) (Anna Henningsen) * \[[`b7659db945`](https://github.com/nodejs/node-addon-api/commit/b7659db945)] - Merge pull request #1130 from meixg/main (Jack) * \[[`a840d51d21`](https://github.com/nodejs/node-addon-api/commit/a840d51d21)] - Add test case for Object Set using uint32 as key (meixg) * \[[`2c88a7ec4c`](https://github.com/nodejs/node-addon-api/commit/2c88a7ec4c)] - Merge pull request #1132 from JckXia/test-wfl-run (Jack) * \[[`d3a5ed3869`](https://github.com/nodejs/node-addon-api/commit/d3a5ed3869)] - _**Revert**_ "window CI to running on 2019" (JckXia) * \[[`cee899ade5`](https://github.com/nodejs/node-addon-api/commit/cee899ade5)] - **src**: allow customization of ObjectWrap behavior (Aaron Meriwether) [#1125](https://github.com/nodejs/node-addon-api/pull/1125) * \[[`91879b4082`](https://github.com/nodejs/node-addon-api/commit/91879b4082)] - remove window-latest to debug (JckXia) * \[[`1593ef46ee`](https://github.com/nodejs/node-addon-api/commit/1593ef46ee)] - Testing CI run (JckXia) * \[[`744c8d2410`](https://github.com/nodejs/node-addon-api/commit/744c8d2410)] - **test**: enhance the test framework (Deepak Rajamohan) ## 2022-01-21 Version 4.3.0, @NickNaso ### Notable changes: #### API - Added iterator for `Napi::Object`. - Fixed usage of `napi_extended_error_info` in `Napi::Error::New()`. - Added unwrapping logic to handle graceful error handling for primitives. #### TEST - Removed travis config. - Updated compiler used for testing. - Added BigInt value test. - Minor fixes all overtest suite. ### Documentation - Documentation of iterator for `Napi::Object`. - Minor fixes all over documentation. ### Commits * [[`7046834305`](https://github.com/nodejs/node-addon-api/commit/7046834305)] - Update to use recent version of stale action (Michael Dawson) * [[`293c7327ad`](https://github.com/nodejs/node-addon-api/commit/293c7327ad)] - Merge pull request #1075 from JckXia/handle-error-thrown (Jack) * [[`706b19986d`](https://github.com/nodejs/node-addon-api/commit/706b19986d)] - **test**: create tools/eslint-format (Doni Rubiagatra) [#1080](https://github.com/nodejs/node-addon-api/pull/1080) * [[`e0567d098a`](https://github.com/nodejs/node-addon-api/commit/e0567d098a)] - Update documents (JckXia) * [[`691813842e`](https://github.com/nodejs/node-addon-api/commit/691813842e)] - Refactor code. Using hard coded string instead of using symbol (JckXia) * [[`7423cc5025`](https://github.com/nodejs/node-addon-api/commit/7423cc5025)] - Update object\_wrap.md (#1094) (Alexander Floh) * [[`5aab27e6e1`](https://github.com/nodejs/node-addon-api/commit/5aab27e6e1)] - **doc**: add blurb about SetInstanceData (Gabriel Schulhof) * [[`e439222fe6`](https://github.com/nodejs/node-addon-api/commit/e439222fe6)] - **test**: add bigint value test (WenheLI) [#1096](https://github.com/nodejs/node-addon-api/pull/1096) * [[`0dfa89f4ef`](https://github.com/nodejs/node-addon-api/commit/0dfa89f4ef)] - **doc**: document object iterators (#1090) (Darshan Sen) * [[`04b26a9d9b`](https://github.com/nodejs/node-addon-api/commit/04b26a9d9b)] - **test**: add first set of func Ref tests (JckXia) [#1035](https://github.com/nodejs/node-addon-api/pull/1035) * [[`a0b3fe9197`](https://github.com/nodejs/node-addon-api/commit/a0b3fe9197)] - Replace magic value with symbol (JckXia) * [[`173c5bc9d9`](https://github.com/nodejs/node-addon-api/commit/173c5bc9d9)] - Update PR based on review comments (JckXia) * [[`02bcfbccfd`](https://github.com/nodejs/node-addon-api/commit/02bcfbccfd)] - Update doc and appending GUID to object property (JckXia) * [[`c89f0bfb0b`](https://github.com/nodejs/node-addon-api/commit/c89f0bfb0b)] - Remove un-necessary comment/iostream and updated docs to reflect on limitations with this impl (JckXia) * [[`ed4d1c51c4`](https://github.com/nodejs/node-addon-api/commit/ed4d1c51c4)] - Added unwrapping logic to handle graceful error handling for primitives (JckXia) * [[`4663453eae`](https://github.com/nodejs/node-addon-api/commit/4663453eae)] - **src**: fix usage of `napi_extended_error_info` in `Error::New()` (Darshan Sen) [#1092](https://github.com/nodejs/node-addon-api/pull/1092) * [[`cb228418e6`](https://github.com/nodejs/node-addon-api/commit/cb228418e6)] - **doc**: fix typo in TypedThreadSafeFunction example (#1083) (Tobias Nießen) * [[`b70acdda1f`](https://github.com/nodejs/node-addon-api/commit/b70acdda1f)] - **test**: remove travis config (#1082) (Michael Dawson) * [[`1404b7cbea`](https://github.com/nodejs/node-addon-api/commit/1404b7cbea)] - **test**: update compiler used for testing (#1079) (Michael Dawson) * [[`4351bffd53`](https://github.com/nodejs/node-addon-api/commit/4351bffd53)] - **doc**: fixup to meet lint rules (Michael Dawson) [#1077](https://github.com/nodejs/node-addon-api/pull/1077) * [[`bd8f6e6d1a`](https://github.com/nodejs/node-addon-api/commit/bd8f6e6d1a)] - **src**: add iterator for Object (Darshan Sen) * [[`d8fc7b869a`](https://github.com/nodejs/node-addon-api/commit/d8fc7b869a)] - **lint**: add eslint based on config-semistandard (#1067) (Doni Rubiagatra) ## 2021-09-17 Version 4.2.0, @NickNaso ### Notable changes: #### API - Allow creating Function with move-only functor. - Fixed casts to not be undefined behavior. #### TEST - Fixed the way to enable C++ exceptions. - Run tests with options to prefix build root path. ### Documentation - Fixed documentation about how to enable C++ exception. - Minor fixes all over documentation. ### Commits * [[`2dc1f5b66c`](https://github.com/nodejs/node-addon-api/commit/2dc1f5b66c)] - Merge pull request #1065 from strager/move-only-functor (Nicola Del Gobbo) * [[`2b57a4aa4c`](https://github.com/nodejs/node-addon-api/commit/2b57a4aa4c)] - **src**: fix casts to not be undefined behavior (Anna Henningsen) [#1070](https://github.com/nodejs/node-addon-api/pull/1070) * [[`76de4d8222`](https://github.com/nodejs/node-addon-api/commit/76de4d8222)] - **docs**: fix typos (#1068) (todoroff) * [[`22a2f3c926`](https://github.com/nodejs/node-addon-api/commit/22a2f3c926)] - **docs**: fix typo and formatting (#1062) (strager) * [[`62b666c34c`](https://github.com/nodejs/node-addon-api/commit/62b666c34c)] - **test**: run tests with opts to prefix bld root path (Deepak Rajamohan) [#1055](https://github.com/nodejs/node-addon-api/pull/1055) * [[`cbac3aac5d`](https://github.com/nodejs/node-addon-api/commit/cbac3aac5d)] - **test**: standardize unit test file names (Deepak Rajamohan) [#1056](https://github.com/nodejs/node-addon-api/pull/1056) * [[`3e5897a78b`](https://github.com/nodejs/node-addon-api/commit/3e5897a78b)] - **src,test**: allow creating Function with move-only functor (Matthew "strager" Glazar) * [[`da2e754a02`](https://github.com/nodejs/node-addon-api/commit/da2e754a02)] - **test**: fix errors reported by newer compiler (Michael Dawson) * [[`9aaf3b1324`](https://github.com/nodejs/node-addon-api/commit/9aaf3b1324)] - **doc**: fix documentation about how to enable C++ exception (#1059) (Nicola Del Gobbo) [#1059](https://github.com/nodejs/node-addon-api/pull/1059) * [[`b2f861987f`](https://github.com/nodejs/node-addon-api/commit/b2f861987f)] - **test**: fixed the way to enable C++ exceptions. (#1061) (Nicola Del Gobbo) [#1061](https://github.com/nodejs/node-addon-api/pull/1061) ## 2021-08-25 Version 4.1.0, @NickNaso ### Notable changes: #### API - `Napi::Reference` updated the default value to reflect the most possible values when there are any errors occurred on `napi_reference_unref`. - Added the check for nullpointer on `Napi::String` initialization. - Added the wraps for `napi_add_env_cleanup_hook` and `napi_remove_env_cleanup_hook`. - Added `Napi::Maybe` class to handle pending exception when cpp exception disabled. #### TEST - Added first set of tests for `Napi::Symbol`. - Updated test suite to avoid parallel running. ### Documentation - Updated example for context sensitivity. ### Commits * [[`3615041423`](https://github.com/nodejs/node-addon-api/commit/3615041423)] - **src**: return Maybe on pending exception when cpp exception disabled (legendecas) [#927](https://github.com/nodejs/node-addon-api/pull/927) * [[`10564a43c6`](https://github.com/nodejs/node-addon-api/commit/10564a43c6)] - **src**: add AddCleanupHook (Kevin Eady) [#1014](https://github.com/nodejs/node-addon-api/pull/1014) * [[`a459f5cc8f`](https://github.com/nodejs/node-addon-api/commit/a459f5cc8f)] - **doc**: update tests to avoid running in parallel (Michael Dawson) [#1024](https://github.com/nodejs/node-addon-api/pull/1024) * [[`6697c51d1d`](https://github.com/nodejs/node-addon-api/commit/6697c51d1d)] - **src,test**: fix up null char \* exception thrown (Gabriel Schulhof) [#1019](https://github.com/nodejs/node-addon-api/pull/1019) * [[`e02e8a4ce3`](https://github.com/nodejs/node-addon-api/commit/e02e8a4ce3)] - **test**: add first set of symbol tests (JckXia) [#972](https://github.com/nodejs/node-addon-api/pull/972) * [[`da50b51398`](https://github.com/nodejs/node-addon-api/commit/da50b51398)] - **test**: dd check for nullptr inside String init (JckXia) [#1015](https://github.com/nodejs/node-addon-api/pull/1015) * [[`627dbf3c37`](https://github.com/nodejs/node-addon-api/commit/627dbf3c37)] - **doc**: update examples for context sensitivity (Kevin Eady) [#1013](https://github.com/nodejs/node-addon-api/pull/1013) * [[`37a9b8e753`](https://github.com/nodejs/node-addon-api/commit/37a9b8e753)] - **src**: set default return value of Reference Ref/Unref to 0 (legendecas) [#1004](https://github.com/nodejs/node-addon-api/pull/1004) ## 2021-06-15 Version 4.0.0, @NickNaso ### Notable changes: #### API - Fixed a crashing issue in `Napi::Error::ThrowAsJavaScriptException` introducing the preprocessor directive `NODE_API_SWALLOW_UNTHROWABLE_EXCEPTIONS`. - Fixed compilation problem for GCC 11 and C++20. #### TEST - Added test for function reference call and contructor. ### Documentation - Updated the oldest Node.js version supported from `10.x` to `12.x`. ### Commits * [[`028107f686`](https://github.com/nodejs/node-addon-api/commit/028107f686)] - **src**: fix Error::ThrowAsJavaScriptException crash (rudolftam) [#975](https://github.com/nodejs/node-addon-api/pull/975) * [[`fed13534c5`](https://github.com/nodejs/node-addon-api/commit/fed13534c5)] - **src**: fix gcc-11 c++20 compilation (Kevin Eady) [#1009](https://github.com/nodejs/node-addon-api/pull/1009) * [[`b75afc4d29`](https://github.com/nodejs/node-addon-api/commit/b75afc4d29)] - **test**: function reference call & construct (legendecas) [#1005](https://github.com/nodejs/node-addon-api/pull/1005) ## 2021-05-28 Version 3.2.1, @NickNaso ### Notable changes: #### Documentation - Fixed documentation about the oldest Node.js version supported. ### Commits * [[`6d41ee5a3a`](https://github.com/nodejs/node-addon-api/commit/6d41ee5a3a)] - Fixed readme for new release. (NickNaso) ## 2021-05-17 Version 3.2.0, @NickNaso ### Notable changes: #### API - Remove unnecessary symbol exposure. - Fixed leak in `Napi::ObjectWrap` instance for getter and setter method. - Added `Napi::Object::Freeze` and `Napi::object::Seal` methods. - `Napi::Reference` is now copyable. #### Documentation - Added docuemtnation for `Napi::Object::PropertyLValue`. - Changed all N-API references to Node-API. - Some minor corrections all over the documentation. #### TEST - Added tests relating to fetch property from Global Object. - Added addtiona tests for `Napi::Object`. - Added test for `Napi::Function` contructors. - Fixed intermittent failure for `Napi::ThreadSafeFunction` test. - Some minor corrections all over the test suite. ### TOOL - Added Node.js v16.x to CI. - Added CI configuration for Windows. - Some fixex on linter command. ### Commits * [[`52721312f6`](https://github.com/nodejs/node-addon-api/commit/52721312f6)] - **docs**: add napi-rs iin Other Bindings section (#999) (LongYinan) * [[`78a6570a42`](https://github.com/nodejs/node-addon-api/commit/78a6570a42)] - **doc**: fix typo in code example (#997) (Tobias Nießen) * [[`da3bd5778f`](https://github.com/nodejs/node-addon-api/commit/da3bd5778f)] - **test**: fix undoc assumptions about the timing of tsfn calls (legendecas) [#995](https://github.com/nodejs/node-addon-api/pull/995) * [[`410cf6a81e`](https://github.com/nodejs/node-addon-api/commit/410cf6a81e)] - **src**: return bool on object freeze and seal (#991) (legendecas) * [[`93f1898312`](https://github.com/nodejs/node-addon-api/commit/93f1898312)] - **src**: return bool on object set and define property (#977) (legendecas) * [[`331c2ee274`](https://github.com/nodejs/node-addon-api/commit/331c2ee274)] - **build**: add Node.js v16.x to CI (#983) (legendecas) * [[`b6f5eb15e6`](https://github.com/nodejs/node-addon-api/commit/b6f5eb15e6)] - **test**: run test suites with helpers (legendecas) [#976](https://github.com/nodejs/node-addon-api/pull/976) * [[`fbcdf00ea0`](https://github.com/nodejs/node-addon-api/commit/fbcdf00ea0)] - **test**: rename misspelled parameters (Tobias Nießen) [#973](https://github.com/nodejs/node-addon-api/pull/973) * [[`63a6c32e80`](https://github.com/nodejs/node-addon-api/commit/63a6c32e80)] - **test**: fix intermittent TSFN crashes (Kevin Eady) [#974](https://github.com/nodejs/node-addon-api/pull/974) * [[`8f120b033f`](https://github.com/nodejs/node-addon-api/commit/8f120b033f)] - **fix**: key for wapping drawing's system condition (#970) (Kévin VOYER) * [[`1c9d528d66`](https://github.com/nodejs/node-addon-api/commit/1c9d528d66)] - **doc**: correct struct definition (#969) (Darshan Sen) * [[`5e64d1fa61`](https://github.com/nodejs/node-addon-api/commit/5e64d1fa61)] - Added badges for Node-API v7 and v8. (#954) (Nicola Del Gobbo) * [[`6ce629b3fa`](https://github.com/nodejs/node-addon-api/commit/6ce629b3fa)] - **src**: add pull request template (#967) (Michael Dawson) * [[`98126661af`](https://github.com/nodejs/node-addon-api/commit/98126661af)] - Update CONTRIBUTING.md (#966) (Michael Dawson) * [[`77350eee98`](https://github.com/nodejs/node-addon-api/commit/77350eee98)] - **src**: added Freeze and Seal method to Object class. (NickNaso) [#955](https://github.com/nodejs/node-addon-api/pull/955) * [[`bc5147cc4a`](https://github.com/nodejs/node-addon-api/commit/bc5147cc4a)] - Finished tests relating to fetch property from Global Object (JckXia) * [[`0127813111`](https://github.com/nodejs/node-addon-api/commit/0127813111)] - **doc**: unambiguously mark deprecated signatures (Tobias Nießen) [#942](https://github.com/nodejs/node-addon-api/pull/942) * [[`787e216105`](https://github.com/nodejs/node-addon-api/commit/787e216105)] - **doc**: rename N-API with Node-API (Darshan Sen) [#951](https://github.com/nodejs/node-addon-api/pull/951) * [[`628023689a`](https://github.com/nodejs/node-addon-api/commit/628023689a)] - **src**: rename N-API with Node-API on comments (NickNaso) [#953](https://github.com/nodejs/node-addon-api/pull/953) * [[`5c6391578f`](https://github.com/nodejs/node-addon-api/commit/5c6391578f)] - **build**: add CI configuration for Windows (NickNaso) [#948](https://github.com/nodejs/node-addon-api/pull/948) * [[`8ef07251ec`](https://github.com/nodejs/node-addon-api/commit/8ef07251ec)] - **doc**: added some warnings for buffer and array buffer factory method. (#929) (Nicola Del Gobbo) * [[`6490b1f730`](https://github.com/nodejs/node-addon-api/commit/6490b1f730)] - **doc**: sync Object::Set value arg with Value::From (#933) (Tobias Nießen) * [[`7319a0d7a2`](https://github.com/nodejs/node-addon-api/commit/7319a0d7a2)] - Fix tab indent (#938) (Tobias Nießen) * [[`1916cb937e`](https://github.com/nodejs/node-addon-api/commit/1916cb937e)] - **chore**: fixup linter commands (#940) (legendecas) * [[`fc4585fa23`](https://github.com/nodejs/node-addon-api/commit/fc4585fa23)] - **test**: dd tests for Function constructors (JoseExposito) [#937](https://github.com/nodejs/node-addon-api/pull/937) * [[`87b7aae469`](https://github.com/nodejs/node-addon-api/commit/87b7aae469)] - **doc**: warn about SuppressDestruct() (#926) (Anna Henningsen) * [[`71494a49a3`](https://github.com/nodejs/node-addon-api/commit/71494a49a3)] - **src,doc**: refactor to replace typedefs with usings (Darshan Sen) [#910](https://github.com/nodejs/node-addon-api/pull/910) * [[`298ff8d9d2`](https://github.com/nodejs/node-addon-api/commit/298ff8d9d2)] - **test**: add additional tests for Object (JoseExposito) [#923](https://github.com/nodejs/node-addon-api/pull/923) * [[`8a1147b430`](https://github.com/nodejs/node-addon-api/commit/8a1147b430)] - **revert**: src: add additional tests for Function (Michael Dawson) * [[`bb56ffaa6f`](https://github.com/nodejs/node-addon-api/commit/bb56ffaa6f)] - **doc**: fix documentation for object api (Nicola Del Gobbo) [#931](https://github.com/nodejs/node-addon-api/pull/931) * [[`3b8bddab49`](https://github.com/nodejs/node-addon-api/commit/3b8bddab49)] - **src**: add additional tests for Function (José Expósito) [#928](https://github.com/nodejs/node-addon-api/pull/928) * [[`74ab50c775`](https://github.com/nodejs/node-addon-api/commit/74ab50c775)] - **src**: allow references to be copyable in APIs (legendecas) [#915](https://github.com/nodejs/node-addon-api/pull/915) * [[`929709d0fe`](https://github.com/nodejs/node-addon-api/commit/929709d0fe)] - **doc**: add propertylvalue.md (#925) (Gabriel Schulhof) * [[`69d0d98be4`](https://github.com/nodejs/node-addon-api/commit/69d0d98be4)] - fixup (Anna Henningsen) * [[`46e41d961b`](https://github.com/nodejs/node-addon-api/commit/46e41d961b)] - fixup (Anna Henningsen) * [[`1af1642fb7`](https://github.com/nodejs/node-addon-api/commit/1af1642fb7)] - **doc**: warn about SuppressDestruct() (Anna Henningsen) * [[`12c548b2ff`](https://github.com/nodejs/node-addon-api/commit/12c548b2ff)] - **tools**: fix error detection (#914) (Darshan Sen) * [[`458d895d5b`](https://github.com/nodejs/node-addon-api/commit/458d895d5b)] - **packaging**: list files to be published to npm (Lovell Fuller) [#889](https://github.com/nodejs/node-addon-api/pull/889) * [[`f7ed2490d4`](https://github.com/nodejs/node-addon-api/commit/f7ed2490d4)] - **test**: remove outdated V8 flag (Darshan Sen) [#895](https://github.com/nodejs/node-addon-api/pull/895) * [[`a575a6ec60`](https://github.com/nodejs/node-addon-api/commit/a575a6ec60)] - **src**: fix leak in ObjectWrap instance set/getters (Kevin Eady) [#899](https://github.com/nodejs/node-addon-api/pull/899) * [[`b6e844e0b0`](https://github.com/nodejs/node-addon-api/commit/b6e844e0b0)] - **doc**: fix spelling of "targeted" and "targeting" (#904) (Tobias Nießen) * [[`4d856f6e91`](https://github.com/nodejs/node-addon-api/commit/4d856f6e91)] - **src**: remove unnecessary symbol exposure (Gabriel Schulhof) [#896](https://github.com/nodejs/node-addon-api/pull/896) * [[`f35bb7d0d7`](https://github.com/nodejs/node-addon-api/commit/f35bb7d0d7)] - **doc**: Update GitHub URL references from 'master' to 'HEAD' (#898) (Jim Schlight) * [[`286ae215d1`](https://github.com/nodejs/node-addon-api/commit/286ae215d1)] - Add warning about branch rename (Michael Dawson) * [[`a4a7b28288`](https://github.com/nodejs/node-addon-api/commit/a4a7b28288)] - Update branch references from master to main (#886) (Jim Schlight) * [[`a2ad0a107a`](https://github.com/nodejs/node-addon-api/commit/a2ad0a107a)] - **docs**: add NAN to N-API resource link (#880) (kidneysolo) * [[`1c040eeb63`](https://github.com/nodejs/node-addon-api/commit/1c040eeb63)] - **test**: load testModules automatically (raisinten) [#876](https://github.com/nodejs/node-addon-api/pull/876) * [[`bf478e4496`](https://github.com/nodejs/node-addon-api/commit/bf478e4496)] - **src**: use NAPI\_NOEXCEPT macro instead of noexcept (NickNaso) [#864](https://github.com/nodejs/node-addon-api/pull/864) * [[`744705f2eb`](https://github.com/nodejs/node-addon-api/commit/744705f2eb)] - **test**: refactor remove repeated execution index.js (raisinten) [#839](https://github.com/nodejs/node-addon-api/pull/839) * [[`db62e3c811`](https://github.com/nodejs/node-addon-api/commit/db62e3c811)] - Update team members (Michael Dawson) ## 2020-12-17 Version 3.1.0, @NickNaso ### Notable changes: #### API - Added `Napi::TypedThreadSafeFunction` class that is a new implementation for thread-safe functions. - Fixed leak on `Napi::AsyncProgressWorkerBase`. - Fixed empty data on `Napi::AsyncProgressWorker::OnProgress` caused by race conditions of `Napi::AsyncProgressWorker`. - Added `Napi::ArrayBuffer::Detach()` and `Napi::ArrayBuffer::IsDetached()`. - Fixed problem on `Napi::FinalizeCallback` it needs to create a `Napi::HandleScope` when it calls `Napi::ObjectWrap::~ObjectWrap()`. #### Documentation - Added documentation for `Napi::TypedThreadSafeFunction`. - Removed unsued Doxygen file. - Clarified when to use N-API. - Added support information. - Some minor corrections all over the documentation. #### TEST - Added test for `Napi::TypedThreadSafeFunction`. - Fixed testing for specific N-API version. - Some minor corrections all over the test suite. ### TOOL - Setup github actions for tests. - Added stale action. - Removed `sudo` tag from Travis CI. - Added clang-format. - Added pre-commit package for linting. ### Commits * [[`ff642c5b85`](https://github.com/nodejs/node-addon-api/commit/ff642c5b85)] - **doc**: fix tsfn docs to reflect true implementation (#860) (Kevin Eady) * [[`86feeebf54`](https://github.com/nodejs/node-addon-api/commit/86feeebf54)] - **src**: empty data OnProgress in AsyncProgressWorker (legendecas) [#853](https://github.com/nodejs/node-addon-api/pull/853) * [[`a7fb5fb31c`](https://github.com/nodejs/node-addon-api/commit/a7fb5fb31c)] - **action**: add stale action (#856) (Michael Dawson) * [[`fd44609885`](https://github.com/nodejs/node-addon-api/commit/fd44609885)] - **chore**: setup github actions for tests (#854) (legendecas) [#854](https://github.com/nodejs/node-addon-api/pull/854) * [[`c52ace4813`](https://github.com/nodejs/node-addon-api/commit/c52ace4813)] - **script**: fix complains that js files are not supported on npm run lint:fix (#852) (legendecas) * [[`b4a3364ad5`](https://github.com/nodejs/node-addon-api/commit/b4a3364ad5)] - **doc**: remove unused Doxygen file (#851) (Michael Dawson) * [[`b810466ae2`](https://github.com/nodejs/node-addon-api/commit/b810466ae2)] - **doc**: clarify when to use N-API (#849) (Michael Dawson) * [[`528b9f6832`](https://github.com/nodejs/node-addon-api/commit/528b9f6832)] - **test**: remove sudo from travis (#850) (Michael Dawson) * [[`4bb680de4e`](https://github.com/nodejs/node-addon-api/commit/4bb680de4e)] - Remove misleading sentence (#847) (Nikolai Vavilov) [#847](https://github.com/nodejs/node-addon-api/pull/847) * [[`48e6b584a3`](https://github.com/nodejs/node-addon-api/commit/48e6b584a3)] - Merge pull request #742 from KevinEady/contexted-tsfn-api-gcc-4 (Gabriel Schulhof) * [[`d5e37210cc`](https://github.com/nodejs/node-addon-api/commit/d5e37210cc)] - **tools**: print more instructions on clang-format check failed (#846) (legendecas) [#846](https://github.com/nodejs/node-addon-api/pull/846) * [[`d9e11ff2c9`](https://github.com/nodejs/node-addon-api/commit/d9e11ff2c9)] - **doc**: add support info (#843) (Michael Dawson) [#843](https://github.com/nodejs/node-addon-api/pull/843) * [[`356e93d69a`](https://github.com/nodejs/node-addon-api/commit/356e93d69a)] - **test**: fixup testing for specific N-API version (#840) (Michael Dawson) [#840](https://github.com/nodejs/node-addon-api/pull/840) * [[`5e5b9ce1b7`](https://github.com/nodejs/node-addon-api/commit/5e5b9ce1b7)] - Apply formatting changes (Kevin Eady) * [[`559ad8c0c0`](https://github.com/nodejs/node-addon-api/commit/559ad8c0c0)] - Merge remote-tracking branch 'upstream/master' into contexted-tsfn-api-gcc-4 (Kevin Eady) * [[`c24c455ced`](https://github.com/nodejs/node-addon-api/commit/c24c455ced)] - Rename to TypedThreadSafeFunction (Kevin Eady) * [[`63b43f4125`](https://github.com/nodejs/node-addon-api/commit/63b43f4125)] - **test**: fix buildType bug objectwrap\_worker\_thread (raisinten) [#837](https://github.com/nodejs/node-addon-api/pull/837) * [[`6321f2ba1a`](https://github.com/nodejs/node-addon-api/commit/6321f2ba1a)] - **test**: fix typos in addon\_build/index.js (raisinten) [#838](https://github.com/nodejs/node-addon-api/pull/838) * [[`59c6a6aeb0`](https://github.com/nodejs/node-addon-api/commit/59c6a6aeb0)] - **fix**: git-clang-format doesn't recognize no changes requested on given files (#835) (legendecas) * [[`1427b3ef78`](https://github.com/nodejs/node-addon-api/commit/1427b3ef78)] - **src**: create a HandleScope in FinalizeCallback (blagoev) [#832](https://github.com/nodejs/node-addon-api/pull/832) * [[`8fb5820557`](https://github.com/nodejs/node-addon-api/commit/8fb5820557)] - **build**: add incremental clang-format checks (legendecas) [#819](https://github.com/nodejs/node-addon-api/pull/819) * [[`2c02d317e5`](https://github.com/nodejs/node-addon-api/commit/2c02d317e5)] - **build**: add pre-commit package for linting (#823) (Kevin Eady) * [[`1b52c28eb8`](https://github.com/nodejs/node-addon-api/commit/1b52c28eb8)] - Clean up AsyncProgressWorker documentation (#831) (mastergberry) * [[`4abe7cfe30`](https://github.com/nodejs/node-addon-api/commit/4abe7cfe30)] - **test**: rename tsfnex test files (Kevin Eady) * [[`c9563caa25`](https://github.com/nodejs/node-addon-api/commit/c9563caa25)] - **src**: add ArrayBuffer::Detach() and ::IsDetached() (Tobias Nießen) [#659](https://github.com/nodejs/node-addon-api/pull/659) * [[`c79cabaed2`](https://github.com/nodejs/node-addon-api/commit/c79cabaed2)] - **doc**: avoid directing users to HTTP (#828) (Tobias Nießen) * [[`7a13f861ab`](https://github.com/nodejs/node-addon-api/commit/7a13f861ab)] - **doc**: fix additional typo (Kevin Eady) * [[`7ec9741dd2`](https://github.com/nodejs/node-addon-api/commit/7ec9741dd2)] - Merge remote-tracking branch 'upstream/master' into contexted-tsfn-api-gcc-4 (Kevin Eady) * [[`f5fad239fa`](https://github.com/nodejs/node-addon-api/commit/f5fad239fa)] - Update object\_reference.md (#827) (kidneysolo) * [[`35b65712c2`](https://github.com/nodejs/node-addon-api/commit/35b65712c2)] - **Fix**: some typos in documentation (#826) (Helio Frota) * [[`8983383000`](https://github.com/nodejs/node-addon-api/commit/8983383000)] - **Fix**: some typos in the document (#825) (Ziqiu Zhao) * [[`826e466ef6`](https://github.com/nodejs/node-addon-api/commit/826e466ef6)] - Fixed example in addon.md. (#820) (nempoBu4) [#820](https://github.com/nodejs/node-addon-api/pull/820) * [[`b54f5eb788`](https://github.com/nodejs/node-addon-api/commit/b54f5eb788)] - Additional changes from review (Kevin Eady) * [[`59f27dac9a`](https://github.com/nodejs/node-addon-api/commit/59f27dac9a)] - Fix common.gypi (Kevin Eady) * [[`151a914c99`](https://github.com/nodejs/node-addon-api/commit/151a914c99)] - Apply documentation suggestions from code review (Kevin Eady) * [[`ceb27d4949`](https://github.com/nodejs/node-addon-api/commit/ceb27d4949)] - **src**: fix leak in AsyncProgressWorkerBase\ (Ferdinand Holzer) [#795](https://github.com/nodejs/node-addon-api/pull/795) ## 2020-09-18 Version 3.0.2, @NickNaso ### Notable changes: #### API - Introduced `include_dir` for use with **gyp** in a scalar context. - Added `Napi::Addon` to help handle the loading of a native add-on into multiple threads and or multiple times in the same thread. - Concentrate callbacks provided to core N-API. - Make sure wrapcallback is used. #### Documentation - Added documentation for `Napi::Addon`. - Added documentation that reports the full class hierarchy. - Added link to N-API tutorial website. - Some minor corrections all over the documentation. #### TEST - Added tests to check the build process. - Refactored test for threasfafe function using async/await. - Converted tests that gc into async functions that await 10 ticks after each gc. - Some minor corrections all over the test suite. ### Commits * [[`51e25f7c39`](https://github.com/nodejs/node-addon-api/commit/51e25f7c39)] - **doc**: remove a file (#815) (Gabriel Schulhof) * [[`8c9f1809a2`](https://github.com/nodejs/node-addon-api/commit/8c9f1809a2)] - **doc**: add inheritance links and other changes (Gabriel Schulhof) [#798](https://github.com/nodejs/node-addon-api/pull/798) * [[`6562e6b0ab`](https://github.com/nodejs/node-addon-api/commit/6562e6b0ab)] - **test**: added tests to check the build process (NickNaso) [#808](https://github.com/nodejs/node-addon-api/pull/808) * [[`a13b36c96e`](https://github.com/nodejs/node-addon-api/commit/a13b36c96e)] - **test**: fix the threasfafe function test (NickNaso) [#807](https://github.com/nodejs/node-addon-api/pull/807) * [[`f27623ff61`](https://github.com/nodejs/node-addon-api/commit/f27623ff61)] - **build**: introduce include\_dir (Lovell Fuller) [#766](https://github.com/nodejs/node-addon-api/pull/766) * [[`9aceea71fc`](https://github.com/nodejs/node-addon-api/commit/9aceea71fc)] - **src**: concentrate callbacks provided to core N-API (Gabriel Schulhof) [#786](https://github.com/nodejs/node-addon-api/pull/786) * [[`2bc45bbffd`](https://github.com/nodejs/node-addon-api/commit/2bc45bbffd)] - **test**: refactor test to use async/await (Velmisov) [#787](https://github.com/nodejs/node-addon-api/pull/787) * [[`518cfdcdc1`](https://github.com/nodejs/node-addon-api/commit/518cfdcdc1)] - **test**: test ObjectWrap destructor - no HandleScope (David Halls) [#729](https://github.com/nodejs/node-addon-api/pull/729) * [[`c2cbbd9191`](https://github.com/nodejs/node-addon-api/commit/c2cbbd9191)] - **doc**: add link to n-api tutorial website (#794) (Jim Schlight) [#794](https://github.com/nodejs/node-addon-api/pull/794) * [[`1c2a8d59b5`](https://github.com/nodejs/node-addon-api/commit/1c2a8d59b5)] - **doc**: Added required return to example (#793) (pacop) [#793](https://github.com/nodejs/node-addon-api/pull/793) * [[`cec2c76941`](https://github.com/nodejs/node-addon-api/commit/cec2c76941)] - **src**: wrap finalizer callback (Gabriel Schulhof) [#762](https://github.com/nodejs/node-addon-api/pull/762) * [[`4ce40d22a6`](https://github.com/nodejs/node-addon-api/commit/4ce40d22a6)] - **test**: use assert.strictEqual() (Koki Nishihara) [#777](https://github.com/nodejs/node-addon-api/pull/777) * [[`461e3640c6`](https://github.com/nodejs/node-addon-api/commit/461e3640c6)] - **test**: string tests together (Gabriel Schulhof) [#773](https://github.com/nodejs/node-addon-api/pull/773) * [[`5af645f649`](https://github.com/nodejs/node-addon-api/commit/5af645f649)] - **src**: add Addon\ class (Gabriel Schulhof) [#749](https://github.com/nodejs/node-addon-api/pull/749) * [[`6148fb4bcc`](https://github.com/nodejs/node-addon-api/commit/6148fb4bcc)] - Synchronise Node.js versions in Appveyor Windows CI with Travis (#768) (Lovell Fuller) ## 2020-07-13 Version 3.0.1, @NickNaso ### Notable changes: #### API - Fixed the usage of `Napi::Reference` with `Napi::TypedArray`. - Fixed `Napi::ObjectWrap` inheritance. #### Documentation - Updated the example for `Napi::ObjectWrap`. - Added documentation for instance data APIs. - Some minor corrections all over the documentation. #### TEST - Fixed test for `Napi::ArrayBuffer` and `Napi::Buffer`. - Some minor corrections all over the test suite. ### Commits * [[`40c7926342`](https://github.com/nodejs/node-addon-api/commit/40c7926342)] - **build**: ensure paths with spaces can be used (Lovell Fuller) [#757](https://github.com/nodejs/node-addon-api/pull/757) * [[`ef16dfb4a2`](https://github.com/nodejs/node-addon-api/commit/ef16dfb4a2)] - **doc**: update ObjectWrap example (Gabriel Schulhof) [#754](https://github.com/nodejs/node-addon-api/pull/754) * [[`48f6762bf6`](https://github.com/nodejs/node-addon-api/commit/48f6762bf6)] - **src**: add \_\_wasm32\_\_ guards (Gus Caplan) * [[`bd2c5ec502`](https://github.com/nodejs/node-addon-api/commit/bd2c5ec502)] - Fixes issue 745. (#748) (Nicola Del Gobbo) * [[`4c01af2d87`](https://github.com/nodejs/node-addon-api/commit/4c01af2d87)] - Fix typo in CHANGELOG (#715) (Kasumi Hanazuki) * [[`36e1af96d5`](https://github.com/nodejs/node-addon-api/commit/36e1af96d5)] - **src**: fix use of Reference with typed arrays (Michael Dawson) [#726](https://github.com/nodejs/node-addon-api/pull/726) * [[`d463f02bc7`](https://github.com/nodejs/node-addon-api/commit/d463f02bc7)] - **src**: fix testEnumerables on ObjectWrap (Ferdinand Holzer) [#736](https://github.com/nodejs/node-addon-api/pull/736) * [[`ba7ad37d44`](https://github.com/nodejs/node-addon-api/commit/ba7ad37d44)] - **src**: fix ObjectWrap inheritance (David Halls) [#732](https://github.com/nodejs/node-addon-api/pull/732) * [[`31504c862b`](https://github.com/nodejs/node-addon-api/commit/31504c862b)] - **doc**: fix minor typo in object\_wrap.md (#741) (Daniel Bevenius) [#741](https://github.com/nodejs/node-addon-api/pull/741) * [[`beccf2145d`](https://github.com/nodejs/node-addon-api/commit/beccf2145d)] - **test**: fix up delays for array buffer test (Michael Dawson) [#737](https://github.com/nodejs/node-addon-api/pull/737) * [[`45cb1d9748`](https://github.com/nodejs/node-addon-api/commit/45cb1d9748)] - Correct AsyncProgressWorker link in README (#716) (Jeroen Janssen) * [[`381c0da60c`](https://github.com/nodejs/node-addon-api/commit/381c0da60c)] - **doc**: add instance data APIs (Gabriel Schulhof) [#708](https://github.com/nodejs/node-addon-api/pull/708) ## 2020-04-30 Version 3.0.0, @NickNaso ### Notable changes: #### API - `Napi::Object` added templated property descriptors. - `Napi::ObjectWrap` added templated methods. - `Napi::ObjectWrap` the wrap is removed only on failure. - `Napi::ObjectWrap` the constructor's exceptions are gracefully handled. - `Napi::Function` added templated factory functions. - Added `Env::RunScript` method to run JavaScript code contained in a string. - Added templated version of `Napi::Function`. - Added benchmarking framework. - Added support for native addon instance data. - Added `Napi::AsyncProgressQueueWorker` api. - Changed the guards to `NAPI_VERSION > 5`. - Removed N-API implementation (v6.x and v8.x support). - `Napi::AsyncWorker::OnWorkComplete` and `Napi::AsyncWorker::OnExecute` methods are override-able. - Removed erroneous finalizer cleanup in `Napi::ThreadSafeFunction`. - Disabled caching in `Napi::ArrayBuffer`. - Explicitly disallow assign and copy operator. - Some minor corrections and improvements. #### Documentation - Updated documentation for `Napi::Object`. - Updated documentation for `Napi::Function`. - Updated documentation for `Napi::ObjectWrap`. - Added documentation on how to add benchmark. - Added documentation for `Napi::AsyncProgressQueueWorker`. - Added suggestion about tags to use on NPM. - Added reference to N-API badges. - Some minor corrections all over the documentation. #### TEST - Updated test cases for `Napi::Object`. - Updated test cases for `Napi::Function`. - Updated test cases for `Napi::ObjectWrap`. - Updated test cases for `Napi::Env`. - Added test cases for `Napi::AsyncProgressQueueWorker`. - Some minor corrections all over the test suite. ### Commits * [[`187318e37f`](https://github.com/nodejs/node-addon-api/commit/187318e37f)] - **doc**: Removed references to Node.js lower than 10.x. (#709) (Nicola Del Gobbo) * [[`9c9accfbbe`](https://github.com/nodejs/node-addon-api/commit/9c9accfbbe)] - **src**: add support for addon instance data (Gabriel Schulhof) [#663](https://github.com/nodejs/node-addon-api/pull/663) * [[`82a96502a4`](https://github.com/nodejs/node-addon-api/commit/82a96502a4)] - **src**: change guards to NAPI\_VERSION \> 5 (Gabriel Schulhof) [#697](https://github.com/nodejs/node-addon-api/pull/697) * [[`a64e8a5641`](https://github.com/nodejs/node-addon-api/commit/a64e8a5641)] - **ci**: move travis from 13 to 14 (#707) (Gabriel Schulhof) * [[`4de23c9d6b`](https://github.com/nodejs/node-addon-api/commit/4de23c9d6b)] - **doc**: fix support bigint64/biguint64 guards (Yulong Wang) [#705](https://github.com/nodejs/node-addon-api/pull/705) * [[`fedc8195e3`](https://github.com/nodejs/node-addon-api/commit/fedc8195e3)] - **doc**: fix semicolon missing in async\_worker.md (Azlan Mukhtar) [#701](https://github.com/nodejs/node-addon-api/pull/701) * [[`cdb662506c`](https://github.com/nodejs/node-addon-api/commit/cdb662506c)] - **doc**: fix typo in bigint.md (#700) (Kelvin) * [[`e1a827ae29`](https://github.com/nodejs/node-addon-api/commit/e1a827ae29)] - **src**: fix AsyncProgressQueueWorker compilation (#696) (Gabriel Schulhof) [#696](https://github.com/nodejs/node-addon-api/pull/696) * [[`2c3d5df463`](https://github.com/nodejs/node-addon-api/commit/2c3d5df463)] - Merge pull request #692 from kelvinhammond/patch-1 (Nicola Del Gobbo) * [[`623e876949`](https://github.com/nodejs/node-addon-api/commit/623e876949)] - Merge pull request #688 from NickNaso/badges (Nicola Del Gobbo) * [[`6c97913d1f`](https://github.com/nodejs/node-addon-api/commit/6c97913d1f)] - Fix minor typo in object\_lifetime\_management.md (Kelvin) * [[`6b8dd47c55`](https://github.com/nodejs/node-addon-api/commit/6b8dd47c55)] - Added badge section to documentation. (NickNaso) * [[`89e62a9154`](https://github.com/nodejs/node-addon-api/commit/89e62a9154)] - **doc**: recommend tags of addon helpers (legendecas) [#683](https://github.com/nodejs/node-addon-api/pull/683) * [[`ab018444ae`](https://github.com/nodejs/node-addon-api/commit/ab018444ae)] - **src**: implement AsyncProgressQueueWorker (legendecas) [#585](https://github.com/nodejs/node-addon-api/pull/585) * [[`d43da6ac2b`](https://github.com/nodejs/node-addon-api/commit/d43da6ac2b)] - **doc**: add @legendecas to active member list (legendecas) * [[`cb498bbe7f`](https://github.com/nodejs/node-addon-api/commit/cb498bbe7f)] - **doc**: Add Napi::BigInt::New() overload for uint64\_t (ikokostya) * [[`baaaa8452c`](https://github.com/nodejs/node-addon-api/commit/baaaa8452c)] - **doc**: link threadsafe function from JS function (legendecas) * [[`7f56a78ff7`](https://github.com/nodejs/node-addon-api/commit/7f56a78ff7)] - **objectwrap**: remove wrap only on failure (Gabriel Schulhof) * [[`4d816183da`](https://github.com/nodejs/node-addon-api/commit/4d816183da)] - **doc**: fix example code (András Timár, Dr) [#657](https://github.com/nodejs/node-addon-api/pull/657) * [[`7ac6e21801`](https://github.com/nodejs/node-addon-api/commit/7ac6e21801)] - **gyp**: fix gypfile name in index.js (Anna Henningsen) [#658](https://github.com/nodejs/node-addon-api/pull/658) * [[`46484202ca`](https://github.com/nodejs/node-addon-api/commit/46484202ca)] - **test**: user data in function property descriptor (Kevin Eady) [#652](https://github.com/nodejs/node-addon-api/pull/652) * [[`0f8d730483`](https://github.com/nodejs/node-addon-api/commit/0f8d730483)] - **doc**: fix syntax error in example (András Timár, Dr) [#650](https://github.com/nodejs/node-addon-api/pull/650) * [[`4e885069f1`](https://github.com/nodejs/node-addon-api/commit/4e885069f1)] - **src**: call `napi\_remove\_wrap()` in `ObjectWrap` dtor (Anna Henningsen) [#475](https://github.com/nodejs/node-addon-api/pull/475) * [[`2fde5c3ca3`](https://github.com/nodejs/node-addon-api/commit/2fde5c3ca3)] - **test**: update BigInt test for recent change in core (Michael Dawson) [#649](https://github.com/nodejs/node-addon-api/pull/649) * [[`e8935bd8d9`](https://github.com/nodejs/node-addon-api/commit/e8935bd8d9)] - **test**: add test for own properties on ObjectWrap (Guenter Sandner) [#645](https://github.com/nodejs/node-addon-api/pull/645) * [[`23ff7f0b24`](https://github.com/nodejs/node-addon-api/commit/23ff7f0b24)] - **src**: make OnWorkComplete and OnExecute override-able (legendecas) [#589](https://github.com/nodejs/node-addon-api/pull/589) * [[`86384f94d3`](https://github.com/nodejs/node-addon-api/commit/86384f94d3)] - **objectwrap**: gracefully handle constructor exceptions (Gabriel Schulhof) * [[`9af69da01f`](https://github.com/nodejs/node-addon-api/commit/9af69da01f)] - remove N-API implementation, v6.x and v8.x support (Gabriel Schulhof) [#643](https://github.com/nodejs/node-addon-api/pull/643) * [[`920d544779`](https://github.com/nodejs/node-addon-api/commit/920d544779)] - **benchmark**: add templated version of Function (Gabriel Schulhof) [#637](https://github.com/nodejs/node-addon-api/pull/637) * [[`03759f7759`](https://github.com/nodejs/node-addon-api/commit/03759f7759)] - ignore benchmark built archives (legendecas) [#631](https://github.com/nodejs/node-addon-api/pull/631) * [[`5eeabb0214`](https://github.com/nodejs/node-addon-api/commit/5eeabb0214)] - **tsfn**: Remove erroneous finalizer cleanup (Kevin Eady) [#636](https://github.com/nodejs/node-addon-api/pull/636) * [[`9e0e0f31e4`](https://github.com/nodejs/node-addon-api/commit/9e0e0f31e4)] - **src**: remove unnecessary forward declarations (Gabriel Schulhof) [#633](https://github.com/nodejs/node-addon-api/pull/633) * [[`79deefb6f3`](https://github.com/nodejs/node-addon-api/commit/79deefb6f3)] - **src**: explicitly disallow assign and copy (legendecas) [#590](https://github.com/nodejs/node-addon-api/pull/590) * [[`af50ac281b`](https://github.com/nodejs/node-addon-api/commit/af50ac281b)] - **error**: do not replace pending exception (Gabriel Schulhof) [#629](https://github.com/nodejs/node-addon-api/pull/629) * [[`b72f1d6978`](https://github.com/nodejs/node-addon-api/commit/b72f1d6978)] - Disable caching in ArrayBuffer (Tobias Nießen) [#611](https://github.com/nodejs/node-addon-api/pull/611) * [[`0e7483eb7b`](https://github.com/nodejs/node-addon-api/commit/0e7483eb7b)] - Fix code format in tests (Tobias Nießen) [#617](https://github.com/nodejs/node-addon-api/pull/617) * [[`6a0646356d`](https://github.com/nodejs/node-addon-api/commit/6a0646356d)] - add benchmarking framework (Gabriel Schulhof) [#623](https://github.com/nodejs/node-addon-api/pull/623) * [[`ffc71edd54`](https://github.com/nodejs/node-addon-api/commit/ffc71edd54)] - Add Env::RunScript (Tobias Nießen) [#616](https://github.com/nodejs/node-addon-api/pull/616) * [[`a1b106066e`](https://github.com/nodejs/node-addon-api/commit/a1b106066e)] - **src**: add templated function factories (Gabriel Schulhof) [#608](https://github.com/nodejs/node-addon-api/pull/608) * [[`c584343217`](https://github.com/nodejs/node-addon-api/commit/c584343217)] - Add GetPropertyNames, HasOwnProperty, Delete (#615) (Tobias Nießen) [#615](https://github.com/nodejs/node-addon-api/pull/615) * [[`3acc4b32f5`](https://github.com/nodejs/node-addon-api/commit/3acc4b32f5)] - Fix std::string encoding (#619) (Tobias Nießen) [#619](https://github.com/nodejs/node-addon-api/pull/619) * [[`e71d0eadcc`](https://github.com/nodejs/node-addon-api/commit/e71d0eadcc)] - \[doc\] Fixed links to array documentation (#613) (Nicola Del Gobbo) * [[`3dfb1f0591`](https://github.com/nodejs/node-addon-api/commit/3dfb1f0591)] - Change "WG" to "team" (Tobias Nießen) * [[`ce91e14860`](https://github.com/nodejs/node-addon-api/commit/ce91e14860)] - **objectwrap**: add template methods (Dmitry Ashkadov) [#604](https://github.com/nodejs/node-addon-api/pull/604) * [[`cfa71b60f7`](https://github.com/nodejs/node-addon-api/commit/cfa71b60f7)] - **object**: add templated property descriptors (Gabriel Schulhof) [#610](https://github.com/nodejs/node-addon-api/pull/610) * [[`734725e971`](https://github.com/nodejs/node-addon-api/commit/734725e971)] - Correctly define copy assignment operators. (Rolf Timmermans) ## 2019-11-21 Version 2.0.0, @NickNaso ### Notable changes: #### API - Added `Napi::AsyncProgressWorker` api. - Added error checking on `Napi::ThreadSafeFunction::GetContext`. - Added copy constructor to `Napi::ThreadSafeFunction`. - Added `Napi::ThreadSafeFunction::Ref` and `Napi::ThreadSafeFunction::Unref` to `Napi::ThreadSafeFunction`. - Added `Napi::Object::AddFinalizer` method. - Use `napi_add_finalizer()` to attach data when building against N-API 5. - Added `Napi::Date` api. - Added `Napi::ObjectWrap::Finalize` method. #### Documentation - Added documentation for `Napi::AsyncProgressWorker`. - Improve `Napi::AsyncWorker` documentation. - Added documentation for `Napi::Object::AddFinalizer` method. - Improved documentation for `Napi::ThreadSafeFunction`. - Improved documentation about the usage of CMake as build tool. - Some minor corrections all over the documentation. #### TEST - Added test cases for `Napi::AsyncProgressWorker` api. - Added test cases for `Napi::Date` api. - Added test cases for new features added to `Napi::ThreadSafeFunction`. ### Commits * [[`c881168d49`](https://github.com/nodejs/node-addon-api/commit/c881168d49)] - **tsfn**: add error checking on GetContext (#583) (Kevin Eady) [#583](https://github.com/nodejs/node-addon-api/pull/583) * [[`24d75dd82f`](https://github.com/nodejs/node-addon-api/commit/24d75dd82f)] - Merge pull request #588 from NickNaso/add-asyncprogress-worker-readme (Nicola Del Gobbo) * [[`aa79e37b62`](https://github.com/nodejs/node-addon-api/commit/aa79e37b62)] - Merge pull request #587 from timrach/patch-1 (Nicola Del Gobbo) * [[`df75e08c2b`](https://github.com/nodejs/node-addon-api/commit/df75e08c2b)] - **tsfn**: support direct calls to underlying napi\_tsfn (Kevin Eady) [#58](https://github.com/nodejs/node-addon-api/pull/58) * [[`2298dfae58`](https://github.com/nodejs/node-addon-api/commit/2298dfae58)] - **doc**: Added AsyncProgressWorker to readme (NickNaso) * [[`b3609d33b6`](https://github.com/nodejs/node-addon-api/commit/b3609d33b6)] - Fix return type and declaration of setter callback (Tim Rach) * [[`295e560f55`](https://github.com/nodejs/node-addon-api/commit/295e560f55)] - **test**: improve guards for experimental features (legendecas) * [[`2e71842f63`](https://github.com/nodejs/node-addon-api/commit/2e71842f63)] - **tsfn**: Implement copy constructor (Kevin Eady) [#546](https://github.com/nodejs/node-addon-api/pull/546) * [[`650562cab9`](https://github.com/nodejs/node-addon-api/commit/650562cab9)] - **src**: implement AsyncProgressWorker (legendecas) [#529](https://github.com/nodejs/node-addon-api/pull/529) * [[`bdfd14101f`](https://github.com/nodejs/node-addon-api/commit/bdfd14101f)] - **src**: attach data with napi\_add\_finalizer (Gabriel Schulhof) [#577](https://github.com/nodejs/node-addon-api/pull/577) * [[`9e955a802b`](https://github.com/nodejs/node-addon-api/commit/9e955a802b)] - **doc**: change node.js to Node.js per guideline (#579) (Tobias Nießen) [#579](https://github.com/nodejs/node-addon-api/pull/579) * [[`b42e21e3a9`](https://github.com/nodejs/node-addon-api/commit/b42e21e3a9)] - **build**: move node/6 to travis allowed failures and add node/13 (#573) (Gabriel Schulhof) * [[`8d6132f609`](https://github.com/nodejs/node-addon-api/commit/8d6132f609)] - **doc**: improve AsyncWorker docs (#571) (legendecas) [#571](https://github.com/nodejs/node-addon-api/pull/571) * [[`bc8fc23627`](https://github.com/nodejs/node-addon-api/commit/bc8fc23627)] - **test**: do not run TSFN tests on NAPI\_VERSION \< 4 (legendecas) [#576](https://github.com/nodejs/node-addon-api/pull/576) * [[`bcc1d58fc4`](https://github.com/nodejs/node-addon-api/commit/bcc1d58fc4)] - implement Object::AddFinalizer (Gabriel Schulhof) * [[`e9a4bcd52a`](https://github.com/nodejs/node-addon-api/commit/e9a4bcd52a)] - **doc**: updates Make.js doc to current best practices (Jim Schlight) [#558](https://github.com/nodejs/node-addon-api/pull/558) * [[`b513d1aa7a`](https://github.com/nodejs/node-addon-api/commit/b513d1aa7a)] - **doc**: fix return type of ArrayBuffer::Data (Tobias Nießen) [#552](https://github.com/nodejs/node-addon-api/pull/552) * [[`34c11cf0a4`](https://github.com/nodejs/node-addon-api/commit/34c11cf0a4)] - **src**: disallow copying, double close of scopes (legendecas) [#566](https://github.com/nodejs/node-addon-api/pull/566) * [[`ce139a05e8`](https://github.com/nodejs/node-addon-api/commit/ce139a05e8)] - **src**: make failure of closing scopes fatal (legendecas) [#566](https://github.com/nodejs/node-addon-api/pull/566) * [[`740c79823e`](https://github.com/nodejs/node-addon-api/commit/740c79823e)] - **src**: add Env() to AsyncContext (Rolf Timmermans) [#568](https://github.com/nodejs/node-addon-api/pull/568) * [[`ea9ce1c801`](https://github.com/nodejs/node-addon-api/commit/ea9ce1c801)] - **tsfn**: add wrappers for Ref and Unref (Kevin Eady) [#561](https://github.com/nodejs/node-addon-api/pull/561) * [[`2e1769e1a3`](https://github.com/nodejs/node-addon-api/commit/2e1769e1a3)] - **error**: remove unnecessary if condition (legendecas) [#562](https://github.com/nodejs/node-addon-api/pull/562) * [[`828f223a87`](https://github.com/nodejs/node-addon-api/commit/828f223a87)] - **doc**: fix spelling in ObjectWrap doc (#563) (Tobias Nießen) [#563](https://github.com/nodejs/node-addon-api/pull/563) * [[`dd9fa8a4a8`](https://github.com/nodejs/node-addon-api/commit/dd9fa8a4a8)] - **doc**: move Arunesh and Taylor to Emeritus (#540) (Michael Dawson) [#540](https://github.com/nodejs/node-addon-api/pull/540) * [[`cf8b8415df`](https://github.com/nodejs/node-addon-api/commit/cf8b8415df)] - **doc**: add Kevin to the list of collaborators (#539) (Michael Dawson) [#539](https://github.com/nodejs/node-addon-api/pull/539) * [[`5d6aeae7b5`](https://github.com/nodejs/node-addon-api/commit/5d6aeae7b5)] - **build**: enable travis for fast PR check (legendecas) * [[`6192e705cd`](https://github.com/nodejs/node-addon-api/commit/6192e705cd)] - **src**: add napi\_date (Mathias Küsel) [#497](https://github.com/nodejs/node-addon-api/pull/497) * [[`7b1ee96d52`](https://github.com/nodejs/node-addon-api/commit/7b1ee96d52)] - **doc**: update prebuild\_tools.md (Nurbol Alpysbayev) [#527](https://github.com/nodejs/node-addon-api/pull/527) * [[`0b4f3a5b8c`](https://github.com/nodejs/node-addon-api/commit/0b4f3a5b8c)] - **tsfn**: fix crash on releasing tsfn (legendecas) [#532](https://github.com/nodejs/node-addon-api/pull/532) * [[`c3c8814d2f`](https://github.com/nodejs/node-addon-api/commit/c3c8814d2f)] - implement virutal ObjectWrap::Finalize (Michael Price) [#515](https://github.com/nodejs/node-addon-api/pull/515) ## 2019-07-23 Version 1.7.1, @NickNaso ### Notable changes: #### API - Fixed compilation problems that happen on Node.js with N-API version less than 4. ### Commits * [[`c20bcbd069`](https://github.com/nodejs/node-addon-api/commit/c20bcbd069)] - Merge pull request #518 from NickNaso/master (Nicola Del Gobbo) * [[`6720d57253`](https://github.com/nodejs/node-addon-api/commit/6720d57253)] - Create the native threadsafe\_function for test only for N-API greater than 3. (NickNaso) * [[`37b6c185ad`](https://github.com/nodejs/node-addon-api/commit/37b6c185ad)] - Fix compilation breakage on 1.7.0 (NickNaso) ## 2019-07-23 Version 1.7.0, @NickNaso ### Notable changes: #### API - Added `Napi::ThreadSafeFunction` api. - Added `Napi::AsyncWorker::GetResult()` method to `Napi::AsyncWorker`. - Added `Napi::AsyncWorker::Destroy()()` method to `Napi::AsyncWorker`. - Use full namespace on macros that create the errors. #### Documentation - Added documentation about contribution philosophy. - Added documentation for `Napi::ThreadSafeFunction`. - Some minor corrections all over the documentation. #### TEST - Added test case for bool operator. - Fixed test case for `Napi::ObjectWrap`. ### Commits * [[`717c9ab163`](https://github.com/nodejs/node-addon-api/commit/717c9ab163)] - **AsyncWorker**: add GetResult() method (Kevin Eady) [#512](https://github.com/nodejs/node-addon-api/pull/512) * [[`d9d991bbc9`](https://github.com/nodejs/node-addon-api/commit/d9d991bbc9)] - **doc**: add ThreadSafeFunction to main README (#513) (Kevin Eady) [#513](https://github.com/nodejs/node-addon-api/pull/513) * [[`ac6000d0fd`](https://github.com/nodejs/node-addon-api/commit/ac6000d0fd)] - **doc**: fix minor typo (Yohei Kishimoto) [#510](https://github.com/nodejs/node-addon-api/pull/510) * [[`e9fa1eaa86`](https://github.com/nodejs/node-addon-api/commit/e9fa1eaa86)] - **doc**: document ThreadSafeFunction (#494) (Kevin Eady) [#494](https://github.com/nodejs/node-addon-api/pull/494) * [[`cab3b1e2a2`](https://github.com/nodejs/node-addon-api/commit/cab3b1e2a2)] - **doc**: ClassPropertyDescriptor example (Ross Weir) [#507](https://github.com/nodejs/node-addon-api/pull/507) * [[`c32d7dbdcf`](https://github.com/nodejs/node-addon-api/commit/c32d7dbdcf)] - **macros**: create errors fully namespaced (Gabriel Schulhof) [#506](https://github.com/nodejs/node-addon-api/pull/506) * [[`0a90df2fcb`](https://github.com/nodejs/node-addon-api/commit/0a90df2fcb)] - Implement ThreadSafeFunction class (Jinho Bang) * [[`1fb540eeb5`](https://github.com/nodejs/node-addon-api/commit/1fb540eeb5)] - Use curly brackets to include node\_api.h (NickNaso) [#493](https://github.com/nodejs/node-addon-api/pull/493) * [[`b2b08122ea`](https://github.com/nodejs/node-addon-api/commit/b2b08122ea)] - **AsyncWorker**: make callback optional (Kevin Eady) [#489](https://github.com/nodejs/node-addon-api/pull/489) * [[`a0cac77c82`](https://github.com/nodejs/node-addon-api/commit/a0cac77c82)] - Added test for bool operator (NickNaso) [#490](https://github.com/nodejs/node-addon-api/pull/490) * [[`ab7d8fcc48`](https://github.com/nodejs/node-addon-api/commit/ab7d8fcc48)] - **src**: fix objectwrap test case (Michael Dawson) [#495](https://github.com/nodejs/node-addon-api/pull/495) * [[`3b6b9eb88a`](https://github.com/nodejs/node-addon-api/commit/3b6b9eb88a)] - **AsyncWorker**: introduce Destroy() method (Gabriel Schulhof) [#488](https://github.com/nodejs/node-addon-api/pull/488) * [[`f633fbd95d`](https://github.com/nodejs/node-addon-api/commit/f633fbd95d)] - string.md: Document existing New(env, value, length) APIs (Tux3) [#486](https://github.com/nodejs/node-addon-api/pull/486) * [[`aaea55eda9`](https://github.com/nodejs/node-addon-api/commit/aaea55eda9)] - Little fix on code example (Nicola Del Gobbo) [#470](https://github.com/nodejs/node-addon-api/pull/470) * [[`e1cf9a35a1`](https://github.com/nodejs/node-addon-api/commit/e1cf9a35a1)] - Use `Value::IsEmpty` to check for empty value (NickNaso) [#478](https://github.com/nodejs/node-addon-api/pull/478) * [[`3ad5dfc7d9`](https://github.com/nodejs/node-addon-api/commit/3ad5dfc7d9)] - Fix link (Alba Mendez) [#481](https://github.com/nodejs/node-addon-api/pull/481) * [[`a3b4d99c45`](https://github.com/nodejs/node-addon-api/commit/a3b4d99c45)] - **doc**: Add contribution philosophy doc (Hitesh Kanwathirtha) * [[`36863f087b`](https://github.com/nodejs/node-addon-api/commit/36863f087b)] - **doc**: refer to TypedArray and ArrayBuffer from Array (Gabriel "_|Nix|_" Schulhof) [#465](https://github.com/nodejs/node-addon-api/pull/465) ## 2019-04-03 Version 1.6.3, @NickNaso ### Notable changes: #### API - Added `SuppressDestruct` method to `Napi::AsyncWorker`. - Added new build targets for debug. - Exposed macros that throw errors. - Fixed memory leaks caused by callback data when a napi error occurs. - Fixed missing `void *data` usage in `Napi::PropertyDescriptors`. #### Documentation - Some minor corrections all over the documentation. ### Commits * [[`83b41c2fe4`](https://github.com/nodejs/node-addon-api/commit/83b41c2fe4)] - Document adding -fvisibility=hidden flag for macOS users (Nicola Del Gobbo) [#460](https://github.com/nodejs/node-addon-api/pull/460) * [[`1ed7ad8769`](https://github.com/nodejs/node-addon-api/commit/1ed7ad8769)] - **doc**: correct return type of Int32Value to int32\_t (Bill Gallafent) [#459](https://github.com/nodejs/node-addon-api/pull/459) * [[`b0f6b601aa`](https://github.com/nodejs/node-addon-api/commit/b0f6b601aa)] - **src**: add AsyncWorker destruction suppression (Gabriel Schulhof) [#407](https://github.com/nodejs/node-addon-api/pull/407) * [[`72b1975cff`](https://github.com/nodejs/node-addon-api/commit/72b1975cff)] - **doc**: fix links to the Property Descriptor docs (Ryuichi Okumura) [#458](https://github.com/nodejs/node-addon-api/pull/458) * [[`fcfc612728`](https://github.com/nodejs/node-addon-api/commit/fcfc612728)] - **build**: new build targets for debug purposes (Jinho Bang) [#186](https://github.com/nodejs/node-addon-api/pull/186) * [[`c629553cd7`](https://github.com/nodejs/node-addon-api/commit/c629553cd7)] - **doc**: minor doc corrections and clarifications (Bruce A. MacNaughton) [#426](https://github.com/nodejs/node-addon-api/pull/426) * [[`7b87e0b999`](https://github.com/nodejs/node-addon-api/commit/7b87e0b999)] - **doc**: update number.md (Bernardo Heynemann) [#436](https://github.com/nodejs/node-addon-api/pull/436) * [[`fcf173d2a1`](https://github.com/nodejs/node-addon-api/commit/fcf173d2a1)] - **src**: expose macros that throw errors (Gabriel Schulhof) [#448](https://github.com/nodejs/node-addon-api/pull/448) * [[`b409a2f987`](https://github.com/nodejs/node-addon-api/commit/b409a2f987)] - **package**: add npm search keywords (Sam Roberts) [#452](https://github.com/nodejs/node-addon-api/pull/452) * [[`0bc7987806`](https://github.com/nodejs/node-addon-api/commit/0bc7987806)] - **doc**: fix references to Weak and Persistent (Jake Barnes) [#428](https://github.com/nodejs/node-addon-api/pull/428) * [[`ad6f569f85`](https://github.com/nodejs/node-addon-api/commit/ad6f569f85)] - **doc**: dix typo (Abhishek Kumar Singh) [#435](https://github.com/nodejs/node-addon-api/pull/435) * [[`28df833a49`](https://github.com/nodejs/node-addon-api/commit/28df833a49)] - Merge pull request #441 from jschlight/master (Jim Schlight) * [[`4921e74d83`](https://github.com/nodejs/node-addon-api/commit/4921e74d83)] - Rearranges names to be alphabetical (Jim Schlight) * [[`48220335b0`](https://github.com/nodejs/node-addon-api/commit/48220335b0)] - Membership review update (Jim Schlight) * [[`44f0695533`](https://github.com/nodejs/node-addon-api/commit/44f0695533)] - Merge pull request #394 from NickNaso/create\_release (Nicola DelGobbo) * [[`fa49d68416`](https://github.com/nodejs/node-addon-api/commit/fa49d68416)] - **doc**: fix some `Finalizer` signatures (Philipp Renoth) [#414](https://github.com/nodejs/node-addon-api/pull/414) * [[`020ac4a628`](https://github.com/nodejs/node-addon-api/commit/020ac4a628)] - **src**: make `Object::GetPropertyNames()` const (Philipp Renoth)[#415](https://github.com/nodejs/node-addon-api/pull/415) * [[`91eaa6f4cb`](https://github.com/nodejs/node-addon-api/commit/91eaa6f4cb)] - **src**: fix callbackData leaks on error napi status (Philipp Renoth) [#417](https://github.com/nodejs/node-addon-api/pull/417) * [[`0b40275752`](https://github.com/nodejs/node-addon-api/commit/0b40275752)] - **src**: fix noexcept control flow issues (Philipp Renoth) [#420](https://github.com/nodejs/node-addon-api/pull/420) * [[`c1ff2936f9`](https://github.com/nodejs/node-addon-api/commit/c1ff2936f9)] - **src**: fix missing void\*data usage in PropertyDescriptors (Luciano Martorella) [#374](https://github.com/nodejs/node-addon-api/pull/374) ## 2018-11-29 Version 1.6.2, @NickNaso ### Notable changes: #### API - Fixed selection logic for version 6.x. ### Commmits * [[`07a0fc4e95`](https://github.com/nodejs/node-addon-api/commit/07a0fc4e95)] - **src**: fix selection logic for 6.x (Michael Dawson) [#402](https://github.com/nodejs/node-addon-api/pull/402) ## 2018-11-14 Version 1.6.1, @NickNaso ### Notable changes: #### Documentation - Updated links for examples to point to node-addon-examples repo. - Fixed typos on some parts of documentation. #### API - Removed unused member on `Napi::CallbackScope`. - Enabled `Napi::CallbackScope` only with N-API v3. ### Commits * [[`e7cd292a74`](https://github.com/nodejs/node-addon-api/commit/e7cd292a74)] - **src**: remove unused CallbackScope member (Gabriel Schulhof) [#391](https://github.com/nodejs/node-addon-api/pull/391) * [[`d47399fe25`](https://github.com/nodejs/node-addon-api/commit/d47399fe25)] - **src**: guard CallbackScope with N-API v3 (Michael Dawson) [#395](https://github.com/nodejs/node-addon-api/pull/395) * [[`29a0262ab9`](https://github.com/nodejs/node-addon-api/commit/29a0262ab9)] - **doc**: fix typo (Dongjin Na) [#385](https://github.com/nodejs/node-addon-api/pull/385) * [[`b6dc15b88d`](https://github.com/nodejs/node-addon-api/commit/b6dc15b88d)] - **doc**: make links point to node-addon-examples repo (Nicola Del Gobbo) [#389](https://github.com/nodejs/node-addon-api/pull/389) ## 2018-11-02 Version 1.6.0, @NickNaso ### Notable changes: #### Documentation - Improved documentation about ABI stability. #### API - Add `Napi::CallbackScope` class that help to have the equivalent of the scope associated with a callback in place when making certain N-API calls #### TEST - Added tests for `Napi::Array` class. - Added tests for `Napi::ArrayBuffer` class. ### Commits * [[`8ce605c657`](https://github.com/nodejs/node-addon-api/commit/8ce605c657)] - **build**: avoid using package-lock.json (Jaeseok Yoon) [#359](https://github.com/nodejs/node-addon-api/pull/359) * [[`fa3a6150b3`](https://github.com/nodejs/node-addon-api/commit/fa3a6150b3)] - **src**: use MakeCallback() -\> Call() in AsyncWorker (Jinho Bang) [#361](https://github.com/nodejs/node-addon-api/pull/361) * [[`2342415463`](https://github.com/nodejs/node-addon-api/commit/2342415463)] - **test**: create test objects in the stack instead of the heap (Dongjin Na) [#371](https://github.com/nodejs/node-addon-api/pull/371) * [[`67b7db0a6f`](https://github.com/nodejs/node-addon-api/commit/67b7db0a6f)] - **test**: write tests for Array class (Jaeseok Yoon) [#363](https://github.com/nodejs/node-addon-api/pull/363) * [[`729f6dc4ee`](https://github.com/nodejs/node-addon-api/commit/729f6dc4ee)] - **test**: add arraybuffer tests (Dongjin Na) [#369](https://github.com/nodejs/node-addon-api/pull/369) * [[`405f3e5b5b`](https://github.com/nodejs/node-addon-api/commit/405f3e5b5b)] - **src**: implement CallbackScope class (Jinho Bang) [#362](https://github.com/nodejs/node-addon-api/pull/362) * [[`015d95312f`](https://github.com/nodejs/node-addon-api/commit/015d95312f)] - **doc**: fix Napi::Reference link (Gentilhomme) [#365](https://github.com/nodejs/node-addon-api/pull/365) * [[`fd65078e3c`](https://github.com/nodejs/node-addon-api/commit/fd65078e3c)] - README.md: link to new ABI stability guide (Gabriel Schulhof) [#367](https://github.com/nodejs/node-addon-api/pull/367) * [[`ffebf9ba9a`](https://github.com/nodejs/node-addon-api/commit/ffebf9ba9a)] - Updates for release 1.5.0 (NickNaso) ## 2018-10-03 Version 1.5.0, @NickNaso ### Notable changes: #### Documentation - Completed the documentation to cover all the API surface. - Numerous fixes to make documentation more consistent in all of its parts. #### API - Add `Napi::AsyncContext` class to handle asynchronous operation. - Add `Napi::BigInt` class to work with BigInt type. - Add `Napi::VersionManagement` class to retrieve the versions of Node.js and N-API. - Fix potential memory leaks. - DataView feature is enabled by default - Add descriptor for Symbols - Add new methods on `Napi::FunctionReference`. - Add the possibility to retrieve the environment on `Napi::Promise::Deferred` #### TOOL - Add tool to check if a native add-on is built using N-API #### TEST - Start to increase the test coverage - Fix in the test suite to better handle the experimental features that are not yet backported in the previous Node.js version. ### Commits * [[`2009c019af`](https://github.com/nodejs/node-addon-api/commit/2009c019af)] - Merge pull request #292 from devsnek/feature/bigint (Gus Caplan) * [[`e44aca985e`](https://github.com/nodejs/node-addon-api/commit/e44aca985e)] - add bigint class (Gus Caplan) * [[`a3951ab973`](https://github.com/nodejs/node-addon-api/commit/a3951ab973)] - Add documentation for Env(). (Rolf Timmermans) [#318](https://github.com/nodejs/node-addon-api/pull/318) * [[`a6f7a6ad51`](https://github.com/nodejs/node-addon-api/commit/a6f7a6ad51)] - Add Env() to Promise::Deferred. (Rolf Timmermans) * [[`0097e96b92`](https://github.com/nodejs/node-addon-api/commit/0097e96b92)] - Fixed broken links for Symbol and String (NickNaso) * [[`b0ecd38d76`](https://github.com/nodejs/node-addon-api/commit/b0ecd38d76)] - Fix Code of conduct link properly (#323) (Jake Yoon) [#323](https://github.com/nodejs/node-addon-api/pull/323) * [[`223474900f`](https://github.com/nodejs/node-addon-api/commit/223474900f)] - **doc**: update Version management (Dongjin Na) [#360](https://github.com/nodejs/node-addon-api/pull/360) * [[`4f76262a10`](https://github.com/nodejs/node-addon-api/commit/4f76262a10)] - **doc**: some fix on `Napi::Boolean` documentation (NickNaso) [#354](https://github.com/nodejs/node-addon-api/pull/354) * [[`78374f72d2`](https://github.com/nodejs/node-addon-api/commit/78374f72d2)] - **doc**: number documentation (NickNaso) [#356](https://github.com/nodejs/node-addon-api/pull/356) * [[`51ffe453f8`](https://github.com/nodejs/node-addon-api/commit/51ffe453f8)] - **doc**: doc cleanup (NickNaso) [#353](https://github.com/nodejs/node-addon-api/pull/353) * [[`fc11c944b2`](https://github.com/nodejs/node-addon-api/commit/fc11c944b2)] - **doc**: major doc cleanup (NickNaso) [#335](https://github.com/nodejs/node-addon-api/pull/335) * [[`100d0a7cb2`](https://github.com/nodejs/node-addon-api/commit/100d0a7cb2)] - **doc**: first pass on objectwrap documentation (NickNaso) [#321](https://github.com/nodejs/node-addon-api/pull/321) * [[`c7d54180ff`](https://github.com/nodejs/node-addon-api/commit/c7d54180ff)] - **doc**: the Napi::ObjectWrap example does not compile (Arnaud Botella) [#339](https://github.com/nodejs/node-addon-api/pull/339) * [[`7cdd78726a`](https://github.com/nodejs/node-addon-api/commit/7cdd78726a)] - **doc**: added cpp highlight for string.md (Jaeseok Yoon) [#329](https://github.com/nodejs/node-addon-api/pull/329) * [[`8ed29f547c`](https://github.com/nodejs/node-addon-api/commit/8ed29f547c)] - **doc**: add blurb about ABI stability (Gabriel Schulhof) [#326](https://github.com/nodejs/node-addon-api/pull/326) * [[`757eb1f5a3`](https://github.com/nodejs/node-addon-api/commit/757eb1f5a3)] - **doc**: add function and function reference doc (NickNaso) [#299](https://github.com/nodejs/node-addon-api/pull/299) * [[`2885c18591`](https://github.com/nodejs/node-addon-api/commit/2885c18591)] - **doc**: Create changelog for release 1.4.0 (Nicola Del Gobbo) * [[`917bd60baa`](https://github.com/nodejs/node-addon-api/commit/917bd60baa)] - **src**: remove TODOs by fixing memory leaks (Gabriel Schulhof) [#343](https://github.com/nodejs/node-addon-api/pull/343) * [[`dfcb93945f`](https://github.com/nodejs/node-addon-api/commit/dfcb93945f)] - **src**: implement AsyncContext class (Jinho Bang) [#252](https://github.com/nodejs/node-addon-api/pull/252) * [[`211ed38d0d`](https://github.com/nodejs/node-addon-api/commit/211ed38d0d)] - **src**: make 'nothing' target a static library (Gabriel Schulhof) [#348](https://github.com/nodejs/node-addon-api/pull/348) * [[`97c4ab5cf2`](https://github.com/nodejs/node-addon-api/commit/97c4ab5cf2)] - **src**: add Call and MakeCallback that accept cargs (NickNaso) [#344](https://github.com/nodejs/node-addon-api/pull/344) * [[`b6e2d92c09`](https://github.com/nodejs/node-addon-api/commit/b6e2d92c09)] - **src**: enable DataView feature by default (Jinho) [#331](https://github.com/nodejs/node-addon-api/pull/331) * [[`0a00e7c97b`](https://github.com/nodejs/node-addon-api/commit/0a00e7c97b)] - **src**: implement missing descriptor defs for symbols (Philipp Renoth) [#280](https://github.com/nodejs/node-addon-api/pull/280) * [[`38e01b7e3b`](https://github.com/nodejs/node-addon-api/commit/38e01b7e3b)] - **src**: first pass on adding version management apis (NickNaso) [#325](https://github.com/nodejs/node-addon-api/pull/325) * [[`79ee8381d2`](https://github.com/nodejs/node-addon-api/commit/79ee8381d2)] - **src**: fix compile failure in test (Michael Dawson) [#345](https://github.com/nodejs/node-addon-api/pull/345) * [[`4d92a6066f`](https://github.com/nodejs/node-addon-api/commit/4d92a6066f)] - **src**: Add ObjectReference test case (Anisha Rohra) [#212](https://github.com/nodejs/node-addon-api/pull/212) * [[`779560f397`](https://github.com/nodejs/node-addon-api/commit/779560f397)] - **test**: add operator overloading tests in Number (Your Name) [#355](https://github.com/nodejs/node-addon-api/pull/355) * [[`73fed84ceb`](https://github.com/nodejs/node-addon-api/commit/73fed84ceb)] - **test**: add ability to control experimental tests (Michael Dawson) [#350](https://github.com/nodejs/node-addon-api/pull/350) * [[`14c69abd46`](https://github.com/nodejs/node-addon-api/commit/14c69abd46)] - **test**: write tests for Boolean class (Jaeseok Yoon) [#328](https://github.com/nodejs/node-addon-api/pull/328) * [[`2ad47a83b1`](https://github.com/nodejs/node-addon-api/commit/2ad47a83b1)] - **test**: explicitly cast to uint32\_t in test (Gabriel Schulhof) [#341](https://github.com/nodejs/node-addon-api/pull/341) * [[`622ffaea76`](https://github.com/nodejs/node-addon-api/commit/622ffaea76)] - **test**: Tighten up compiler warnings (Mikhail Cheshkov) [#315](https://github.com/nodejs/node-addon-api/pull/315) * [[`fd3c37b0f2`](https://github.com/nodejs/node-addon-api/commit/fd3c37b0f2)] - **tools**: add tool to check for N-API modules (Gabriel Schulhof) [#346](https://github.com/nodejs/node-addon-api/pull/346) ## 2018-07-19 Version 1.4.0, @NickNaso ### Notable changes: #### Documentation - Numerous additions to the documentation, filling out coverage of API surface #### API - Add resource parameters to AsyncWorker constructor - Add memory management feature ### Commits * [[`7dc5ac8bc3`](https://github.com/nodejs/node-addon-api/commit/7dc5ac8bc3)] - **doc**: update metadata for release (Nicola Del Gobbo) * [[`d68e86adb4`](https://github.com/nodejs/node-addon-api/commit/d68e86adb4)] - **doc**: Added documentation for PropertyDescriptor (Anisha Rohra) [#309](https://github.com/nodejs/node-addon-api/pull/309) * [[`968a5f2000`](https://github.com/nodejs/node-addon-api/commit/968a5f2000)] - **doc**: Add documentation for ObjectReference.md (Anisha Rohra) [#307](https://github.com/nodejs/node-addon-api/pull/307) * [[`908cdc314c`](https://github.com/nodejs/node-addon-api/commit/908cdc314c)] - **doc**: add `TypedArray` and `TypedArrayOf` (Kyle Farnung) [#305](https://github.com/nodejs/node-addon-api/pull/305) * [[`2ff776ffe3`](https://github.com/nodejs/node-addon-api/commit/2ff776ffe3)] - backport node::Persistent (Gabriel Schulhof) [#300](https://github.com/nodejs/node-addon-api/pull/300) * [[`98161970c9`](https://github.com/nodejs/node-addon-api/commit/98161970c9)] - Backport perf, crash and exception handling fixes (Gabriel Schulhof) [#295](https://github.com/nodejs/node-addon-api/pull/295) * [[`dd1191e086`](https://github.com/nodejs/node-addon-api/commit/dd1191e086)] - **test**: fix asyncworker test so it runs on 6.x (Michael Dawson) [#298](https://github.com/nodejs/node-addon-api/pull/298) * [[`11697fcecd`](https://github.com/nodejs/node-addon-api/commit/11697fcecd)] - **doc**: ArrayBuffer and Buffer documentation (Kyle Farnung) [#256](https://github.com/nodejs/node-addon-api/pull/256) * [[`605aa2babf`](https://github.com/nodejs/node-addon-api/commit/605aa2babf)] - Add memory management feature (NickNaso) [#286](https://github.com/nodejs/node-addon-api/pull/286) * [[`86be13a611`](https://github.com/nodejs/node-addon-api/commit/86be13a611)] - **doc**: Fix HandleScope docs (Ben Berman) [#287](https://github.com/nodejs/node-addon-api/pull/287) * [[`90f92c4dc0`](https://github.com/nodejs/node-addon-api/commit/90f92c4dc0)] - **doc**: Update broken links in README.md (Hitesh Kanwathirtha) [#290](https://github.com/nodejs/node-addon-api/pull/290) * [[`c2a620dc11`](https://github.com/nodejs/node-addon-api/commit/c2a620dc11)] - **doc**: Clarify positioning versus N-API (Michael Dawson) [#288](https://github.com/nodejs/node-addon-api/pull/288) * [[`6cff890ee5`](https://github.com/nodejs/node-addon-api/commit/6cff890ee5)] - **doc**: Fix typo in docs (Ben Berman) [#284](https://github.com/nodejs/node-addon-api/pull/284) * [[`7394bfd154`](https://github.com/nodejs/node-addon-api/commit/7394bfd154)] - **doc**: Fix typo in docs (Ben Berman) [#285](https://github.com/nodejs/node-addon-api/pull/285) * [[`12b2cdeed3`](https://github.com/nodejs/node-addon-api/commit/12b2cdeed3)] - fix test files (Kyle Farnung) [#257](https://github.com/nodejs/node-addon-api/pull/257) * [[`9ab6607242`](https://github.com/nodejs/node-addon-api/commit/9ab6607242)] - **doc**: Update Doc Version Number (joshgarde) [#277](https://github.com/nodejs/node-addon-api/pull/277) * [[`e029a076c6`](https://github.com/nodejs/node-addon-api/commit/e029a076c6)] - **doc**: First pass at basic Node Addon API docs (Hitesh Kanwathirtha) [#268](https://github.com/nodejs/node-addon-api/pull/268) * [[`74ff79717e`](https://github.com/nodejs/node-addon-api/commit/74ff79717e)] - **doc**: fix link to async\_worker.md (Michael Dawson) * [[`5a63f45eda`](https://github.com/nodejs/node-addon-api/commit/5a63f45eda)] - **doc**: First step of error and async doc (NickNaso) [#272](https://github.com/nodejs/node-addon-api/pull/272) * [[`9d38f61afb`](https://github.com/nodejs/node-addon-api/commit/9d38f61afb)] - **doc**: New Promise and Reference docs (Jim Schlight) [#243](https://github.com/nodejs/node-addon-api/pull/243) * [[`43ff9fa836`](https://github.com/nodejs/node-addon-api/commit/43ff9fa836)] - **doc**: Updated Object documentation (Anisha Rohra) [#254](https://github.com/nodejs/node-addon-api/pull/254) * [[`b197f7cc8b`](https://github.com/nodejs/node-addon-api/commit/b197f7cc8b)] - **doc**: minor typos (Nick Soggin) [#248](https://github.com/nodejs/node-addon-api/pull/248) * [[`4b8918b352`](https://github.com/nodejs/node-addon-api/commit/4b8918b352)] - Add resource parameters to AsyncWorker constructor (Jinho Bang) [#253](https://github.com/nodejs/node-addon-api/pull/253) * [[`1ecf7c19b6`](https://github.com/nodejs/node-addon-api/commit/1ecf7c19b6)] - **doc**: fix wrong link in readme (miloas) [#255](https://github.com/nodejs/node-addon-api/pull/255) * [[`a750ed1932`](https://github.com/nodejs/node-addon-api/commit/a750ed1932)] - **release**: updates to metadata for next release (Michael Dawson) ## 2018-05-08 Version 1.3.0, @mhdawson ### Notable changes: #### Documentation - Added documentation for Scopes - Added documentation for migration from NAN - Update documentation to better explain the use of NODE_ADDON_API #### API - Implement data manipulation methods for dataview - Use built-in N-API on Node.js >= 6.14.2 - Value - Added IsExternal() - IsObject() allow functions - String - Fixed initialization of std::string to nullptr #### Tests - Fix test failures on linuxOne and AIX - Added basic tests for Scopes - Fix MSVC warning C4244 in tests ### Commits * [386c2aeb74] - test: remove dep on later C++ feature (Michael Dawson) https://github.com/nodejs/node-addon-api/pull/267 * [10697734da] - Use built-in N-API on Node.js >= 6.14.2 (Gabriel Schulhof) * [75086da273] - test: add basic tests and doc for scopes (Michael Dawson) https://github.com/nodejs/node-addon-api/pull/250 * [341dbd25d5] - doc: update blurb explaining NODE_ADDON_API (Gabriel Schulhof) https://github.com/nodejs/node-addon-api/pull/251 * [cf6c93e4ee] - don't try to escape null (Michael Dawson) https://github.com/nodejs/node-addon-api/pull/245 * [15e4b35fc2] - test: fix MSVC warning C4244 in tests (Kyle Farnung) https://github.com/nodejs/node-addon-api/pull/236 * [7f3ca03b8e] - Create a doc for migration (Sampson Gao) https://github.com/nodejs/node-addon-api/pull/118 * [0a2177debe] - Fix test failures on linuxOne and AIX (Jinho Bang) https://github.com/nodejs/node-addon-api/pull/232 * [d567f4b6b5] - Added Napi::Value::IsExternal() (Eric Bickle) https://github.com/nodejs/node-addon-api/pull/227 * [1b0f0e004a] - Update node-gyp.md (Michele Campus) https://github.com/nodejs/node-addon-api/pull/226 * [faf19c4f7a] - Fixed initialization of std::string to nullptr (Eric Bickle) https://github.com/nodejs/node-addon-api/pull/228 * [9c4d321b57] - Implement data manipulation methods for dataview (Jinho Bang) https://github.com/nodejs/node-addon-api/pull/218 * [5a39fdca6f] - n-api: throw RangeError napi_create_typedarray() (Jinho Bang) https://github.com/nodejs/node-addon-api/pull/216 * [1376377202] - Make IsObject() allow functions (Jinho Bang) https://github.com/nodejs/node-addon-api/pull/217 * [673b59d319] - src: Initial implementation of DataView class (Jinho Bang) https://github.com/nodejs/node-addon-api/pull/205 * [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 node-addon-api-8.3.1/CODE_OF_CONDUCT.md000066400000000000000000000002351475612273100171110ustar00rootroot00000000000000# Code of Conduct The Node.js Code of Conduct, which applies to this project, can be found at https://github.com/nodejs/admin/blob/HEAD/CODE_OF_CONDUCT.md. node-addon-api-8.3.1/CONTRIBUTING.md000066400000000000000000000162371475612273100165540ustar00rootroot00000000000000# Contributing to **node-addon-api** * [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
     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
     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
     it.

 (d) I understand and agree that this project and the contribution
     are public and that a record of the contribution (including all
     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 specific unit test, filter conditions are available **Example:** compile and run only tests on objectwrap.cc and objectwrap.js ``` npm run unit --filter=objectwrap ``` 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. ## **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**: - [New APIs](#new-apis) - [Source code fixes](#source-changes) - Additional tests - Documentation improvements - Joining the Node-API working group and participating in meetings ### 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 be considered for merging. However, changes that wrap existing **node-addon-api** APIs are encouraged to instead be provided as an ecosystem module. The **node-addon-api** team is happy to link to a curated set of modules that build on top of **node-addon-api** if they have broad usefulness to the community and promote a recommended idiom or pattern. ### Rationale The Node-API team considered a couple of different approaches with regard to changes extending **node-addon-api** - Larger core module - Incorporate these helpers and patterns into **node-addon-api** - Extras package - Create a new package (strawman name '**node-addon-api**-extras') that contain utility classes and methods that help promote good patterns and idioms while writing native addons with **node-addon-api**. - Ecosystem - Encourage the creation of a module ecosystem around **node-addon-api** where folks can build on top of it. #### Larger Core This is probably our simplest option in terms of immediate action needed. It would involve landing any open PRs against **node-addon-api**, and continuing to encourage folks to make PRs for utility helpers against the same repository. The downside of the approach is the following: - Less coherency for our API set - More maintenance burden on the 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 easier. The downside of this approach is the following: - Potential for confusion - we'll need to provide clear documentation to help the community understand where a particular contribution should be directed to (what belongs in **node-addon-api** vs **node-addon-api-extras**) - Need to define the level of support/API guarantees - Unclear if the maintenance burden on the 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 build on top of **node-addon-api**, and provide some level of advertising for these modules (listing them out on the repository/wiki, using them in workshops/tutorials etc). The downside of this approach is the following: - Potential for lack of visibility. Evangelism and education are hard, and module 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** node-addon-api-8.3.1/LICENSE.md000066400000000000000000000021761475612273100157240ustar00rootroot00000000000000The MIT License (MIT) Copyright (c) 2017 [Node.js API collaborators](https://github.com/nodejs/node-addon-api#collaborators) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. node-addon-api-8.3.1/README.md000066400000000000000000000116051475612273100155740ustar00rootroot00000000000000# **node-addon-api module** [![codecov](https://codecov.io/gh/nodejs/node-addon-api/branch/main/graph/badge.svg)](https://app.codecov.io/gh/nodejs/node-addon-api/tree/main) [![NPM](https://nodei.co/npm/node-addon-api.png?downloads=true&downloadRank=true)](https://nodei.co/npm/node-addon-api/) [![NPM](https://nodei.co/npm-dl/node-addon-api.png?months=6&height=1)](https://nodei.co/npm/node-addon-api/) 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. - [API References](doc/README.md) - [Badges](#badges) - [Contributing](#contributing) - [License](#license) ## API References API references are available in the [doc](doc/README.md) directory. ## Current version: 8.3.1 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog) 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 18.x. ## 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 supported. Addon maintainers can consult the [Node-API support matrix][] to determine which Node.js versions provide a given Node-API version. The following badges are available: ![Node-API v1 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v1%20Badge.svg) ![Node-API v2 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v2%20Badge.svg) ![Node-API v3 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v3%20Badge.svg) ![Node-API v4 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v4%20Badge.svg) ![Node-API v5 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v5%20Badge.svg) ![Node-API v6 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v6%20Badge.svg) ![Node-API v7 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v7%20Badge.svg) ![Node-API v8 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v8%20Badge.svg) ![Node-API v9 Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20v9%20Badge.svg) ![Node-API Experimental Version Badge](https://github.com/nodejs/abi-stable-node/blob/doc/assets/Node-API%20Experimental%20Version%20Badge.svg) ## 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) | | Chengzhong Wu | [legendecas](https://github.com/legendecas) | | Jack Xia | [JckXia](https://github.com/JckXia) | | Kevin Eady | [KevinEady](https://github.com/KevinEady) | | Michael Dawson | [mhdawson](https://github.com/mhdawson) | | 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) | | Benjamin Byholm | [kkoopa](https://github.com/kkoopa) | | Gabriel Schulhof | [gabrielschulhof](https://github.com/gabrielschulhof) | | Hitesh Kanwathirtha | [digitalinfinity](https://github.com/digitalinfinity) | | Jason Ginchereau | [jasongin](https://github.com/jasongin) | | Jim Schlight | [jschlight](https://github.com/jschlight) | | Sampson Gao | [sampsongao](https://github.com/sampsongao) | | Taylor Woll | [boingoing](https://github.com/boingoing) |
## License Licensed under [MIT](./LICENSE.md) [Node-API support matrix]: https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api_version_matrix node-addon-api-8.3.1/appveyor.yml000066400000000000000000000013021475612273100166760ustar00rootroot00000000000000environment: # https://github.com/jasongin/nvs/blob/HEAD/doc/CI.md NVS_VERSION: 1.4.2 matrix: - NODEJS_VERSION: node/10 - NODEJS_VERSION: node/12 - NODEJS_VERSION: node/14 - NODEJS_VERSION: nightly os: Visual Studio 2017 platform: - x86 - x64 install: # nvs - git clone --branch v%NVS_VERSION% --depth 1 https://github.com/jasongin/nvs %LOCALAPPDATA%\nvs - set PATH=%LOCALAPPDATA%\nvs;%PATH% - nvs --version # node.js - nvs add %NODEJS_VERSION%/%PLATFORM% - nvs use %NODEJS_VERSION%/%PLATFORM% - node --version - node -p process.arch - npm --version # app - npm install test_script: - npm test build: off version: "{build}" cache: - node_modules node-addon-api-8.3.1/benchmark/000077500000000000000000000000001475612273100162445ustar00rootroot00000000000000node-addon-api-8.3.1/benchmark/README.md000066400000000000000000000027661475612273100175360ustar00rootroot00000000000000# Benchmarks ## Running the benchmarks From the parent directory, run ```bash npm run-script benchmark ``` The above script supports the following arguments: * `--benchmarks=...`: A semicolon-separated list of benchmark names. These names will be mapped to file names in this directory by appending `.js`. ## Adding benchmarks The steps below should be followed when adding new benchmarks. 0. Decide on a name for the benchmark. This name will be used in several places. This example will use the name `new_benchmark`. 0. Create files `new_benchmark.cc` and `new_benchmark.js` in this directory. 0. Copy an existing benchmark in `binding.gyp` and change the target name prefix and the source file name to `new_benchmark`. This should result in two new targets which look like this: ```gyp { 'target_name': 'new_benchmark', 'sources': [ 'new_benchmark.cc' ], 'includes': [ '../except.gypi' ], }, { 'target_name': 'new_benchmark_noexcept', 'sources': [ 'new_benchmark.cc' ], 'includes': [ '../noexcept.gypi' ], }, ``` There should always be a pair of targets: one bearing the name of the benchmark and configured with C++ exceptions enabled, and one bearing the same name followed by the suffix `_noexcept` and configured with C++ exceptions disabled. This will ensure that the benchmark can be written to cover both the case where C++ exceptions are enabled and the case where they are disabled. node-addon-api-8.3.1/benchmark/binding.gyp000066400000000000000000000013701475612273100204000ustar00rootroot00000000000000{ 'target_defaults': { 'includes': ['../common.gypi'] }, 'targets': [ { 'target_name': 'function_args', 'sources': [ 'function_args.cc' ], 'dependencies': ['../node_addon_api.gyp:node_addon_api_except'], }, { 'target_name': 'function_args_noexcept', 'sources': [ 'function_args.cc' ], 'dependencies': ['../node_addon_api.gyp:node_addon_api'], }, { 'target_name': 'property_descriptor', 'sources': [ 'property_descriptor.cc' ], 'dependencies': ['../node_addon_api.gyp:node_addon_api_except'], }, { 'target_name': 'property_descriptor_noexcept', 'sources': [ 'property_descriptor.cc' ], 'dependencies': ['../node_addon_api.gyp:node_addon_api'], }, ] } node-addon-api-8.3.1/benchmark/function_args.cc000066400000000000000000000202251475612273100214150ustar00rootroot00000000000000#include "napi.h" static napi_value NoArgFunction_Core(napi_env env, napi_callback_info info) { (void)env; (void)info; return nullptr; } static napi_value OneArgFunction_Core(napi_env env, napi_callback_info info) { size_t argc = 1; napi_value argv; if (napi_get_cb_info(env, info, &argc, &argv, nullptr, nullptr) != napi_ok) { return nullptr; } (void)argv; return nullptr; } static napi_value TwoArgFunction_Core(napi_env env, napi_callback_info info) { size_t argc = 2; napi_value argv[2]; if (napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr) != napi_ok) { return nullptr; } (void)argv[0]; (void)argv[1]; return nullptr; } static napi_value ThreeArgFunction_Core(napi_env env, napi_callback_info info) { size_t argc = 3; napi_value argv[3]; if (napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr) != napi_ok) { return nullptr; } (void)argv[0]; (void)argv[1]; (void)argv[2]; return nullptr; } static napi_value FourArgFunction_Core(napi_env env, napi_callback_info info) { size_t argc = 4; napi_value argv[4]; if (napi_get_cb_info(env, info, &argc, argv, nullptr, nullptr) != napi_ok) { return nullptr; } (void)argv[0]; (void)argv[1]; (void)argv[2]; (void)argv[3]; return nullptr; } static void NoArgFunction(const Napi::CallbackInfo& info) { (void)info; } static void OneArgFunction(const Napi::CallbackInfo& info) { Napi::Value argv0 = info[0]; (void)argv0; } static void TwoArgFunction(const Napi::CallbackInfo& info) { Napi::Value argv0 = info[0]; (void)argv0; Napi::Value argv1 = info[1]; (void)argv1; } static void ThreeArgFunction(const Napi::CallbackInfo& info) { Napi::Value argv0 = info[0]; (void)argv0; Napi::Value argv1 = info[1]; (void)argv1; Napi::Value argv2 = info[2]; (void)argv2; } static void FourArgFunction(const Napi::CallbackInfo& info) { Napi::Value argv0 = info[0]; (void)argv0; Napi::Value argv1 = info[1]; (void)argv1; Napi::Value argv2 = info[2]; (void)argv2; Napi::Value argv3 = info[3]; (void)argv3; } #if NAPI_VERSION > 5 class FunctionArgsBenchmark : public Napi::Addon { public: FunctionArgsBenchmark(Napi::Env env, Napi::Object exports) { DefineAddon( exports, { InstanceValue( "addon", DefineProperties( Napi::Object::New(env), { InstanceMethod("noArgFunction", &FunctionArgsBenchmark::NoArgFunction), InstanceMethod("oneArgFunction", &FunctionArgsBenchmark::OneArgFunction), InstanceMethod("twoArgFunction", &FunctionArgsBenchmark::TwoArgFunction), InstanceMethod( "threeArgFunction", &FunctionArgsBenchmark::ThreeArgFunction), InstanceMethod("fourArgFunction", &FunctionArgsBenchmark::FourArgFunction), }), napi_enumerable), InstanceValue( "addon_templated", DefineProperties( Napi::Object::New(env), { InstanceMethod<&FunctionArgsBenchmark::NoArgFunction>( "noArgFunction"), InstanceMethod<&FunctionArgsBenchmark::OneArgFunction>( "oneArgFunction"), InstanceMethod<&FunctionArgsBenchmark::TwoArgFunction>( "twoArgFunction"), InstanceMethod< &FunctionArgsBenchmark::ThreeArgFunction>( "threeArgFunction"), InstanceMethod<&FunctionArgsBenchmark::FourArgFunction>( "fourArgFunction"), }), napi_enumerable), }); } private: void NoArgFunction(const Napi::CallbackInfo& info) { (void)info; } void OneArgFunction(const Napi::CallbackInfo& info) { Napi::Value argv0 = info[0]; (void)argv0; } void TwoArgFunction(const Napi::CallbackInfo& info) { Napi::Value argv0 = info[0]; (void)argv0; Napi::Value argv1 = info[1]; (void)argv1; } void ThreeArgFunction(const Napi::CallbackInfo& info) { Napi::Value argv0 = info[0]; (void)argv0; Napi::Value argv1 = info[1]; (void)argv1; Napi::Value argv2 = info[2]; (void)argv2; } void FourArgFunction(const Napi::CallbackInfo& info) { Napi::Value argv0 = info[0]; (void)argv0; Napi::Value argv1 = info[1]; (void)argv1; Napi::Value argv2 = info[2]; (void)argv2; Napi::Value argv3 = info[3]; (void)argv3; } }; #endif // NAPI_VERSION > 5 static Napi::Object Init(Napi::Env env, Napi::Object exports) { napi_value no_arg_function, one_arg_function, two_arg_function, three_arg_function, four_arg_function; napi_status status; status = napi_create_function(env, "noArgFunction", NAPI_AUTO_LENGTH, NoArgFunction_Core, nullptr, &no_arg_function); NAPI_THROW_IF_FAILED(env, status, Napi::Object()); status = napi_create_function(env, "oneArgFunction", NAPI_AUTO_LENGTH, OneArgFunction_Core, nullptr, &one_arg_function); NAPI_THROW_IF_FAILED(env, status, Napi::Object()); status = napi_create_function(env, "twoArgFunction", NAPI_AUTO_LENGTH, TwoArgFunction_Core, nullptr, &two_arg_function); NAPI_THROW_IF_FAILED(env, status, Napi::Object()); status = napi_create_function(env, "threeArgFunction", NAPI_AUTO_LENGTH, ThreeArgFunction_Core, nullptr, &three_arg_function); NAPI_THROW_IF_FAILED(env, status, Napi::Object()); status = napi_create_function(env, "fourArgFunction", NAPI_AUTO_LENGTH, FourArgFunction_Core, nullptr, &four_arg_function); NAPI_THROW_IF_FAILED(env, status, Napi::Object()); Napi::Object core = Napi::Object::New(env); core["noArgFunction"] = Napi::Value(env, no_arg_function); core["oneArgFunction"] = Napi::Value(env, one_arg_function); core["twoArgFunction"] = Napi::Value(env, two_arg_function); core["threeArgFunction"] = Napi::Value(env, three_arg_function); core["fourArgFunction"] = Napi::Value(env, four_arg_function); exports["core"] = core; Napi::Object cplusplus = Napi::Object::New(env); cplusplus["noArgFunction"] = Napi::Function::New(env, NoArgFunction); cplusplus["oneArgFunction"] = Napi::Function::New(env, OneArgFunction); cplusplus["twoArgFunction"] = Napi::Function::New(env, TwoArgFunction); cplusplus["threeArgFunction"] = Napi::Function::New(env, ThreeArgFunction); cplusplus["fourArgFunction"] = Napi::Function::New(env, FourArgFunction); exports["cplusplus"] = cplusplus; Napi::Object templated = Napi::Object::New(env); templated["noArgFunction"] = Napi::Function::New(env); templated["oneArgFunction"] = Napi::Function::New(env); templated["twoArgFunction"] = Napi::Function::New(env); templated["threeArgFunction"] = Napi::Function::New(env); templated["fourArgFunction"] = Napi::Function::New(env); exports["templated"] = templated; #if NAPI_VERSION > 5 FunctionArgsBenchmark::Init(env, exports); #endif // NAPI_VERSION > 5 return exports; } NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) node-addon-api-8.3.1/benchmark/function_args.js000066400000000000000000000041421475612273100214440ustar00rootroot00000000000000const path = require('path'); const Benchmark = require('benchmark'); const addonName = path.basename(__filename, '.js'); [addonName, addonName + '_noexcept'] .forEach((addonName) => { const rootAddon = require('bindings')({ bindings: addonName, module_root: __dirname }); delete rootAddon.path; const implems = Object.keys(rootAddon); const maxNameLength = implems.reduce((soFar, value) => Math.max(soFar, value.length), 0); const anObject = {}; console.log(`\n${addonName}: `); console.log('no arguments:'); implems.reduce((suite, implem) => { const fn = rootAddon[implem].noArgFunction; return suite.add(implem.padStart(maxNameLength, ' '), () => fn()); }, new Benchmark.Suite()) .on('cycle', (event) => console.log(String(event.target))) .run(); console.log('one argument:'); implems.reduce((suite, implem) => { const fn = rootAddon[implem].oneArgFunction; return suite.add(implem.padStart(maxNameLength, ' '), () => fn('x')); }, new Benchmark.Suite()) .on('cycle', (event) => console.log(String(event.target))) .run(); console.log('two arguments:'); implems.reduce((suite, implem) => { const fn = rootAddon[implem].twoArgFunction; return suite.add(implem.padStart(maxNameLength, ' '), () => fn('x', 12)); }, new Benchmark.Suite()) .on('cycle', (event) => console.log(String(event.target))) .run(); console.log('three arguments:'); implems.reduce((suite, implem) => { const fn = rootAddon[implem].threeArgFunction; return suite.add(implem.padStart(maxNameLength, ' '), () => fn('x', 12, true)); }, new Benchmark.Suite()) .on('cycle', (event) => console.log(String(event.target))) .run(); console.log('four arguments:'); implems.reduce((suite, implem) => { const fn = rootAddon[implem].fourArgFunction; return suite.add(implem.padStart(maxNameLength, ' '), () => fn('x', 12, true, anObject)); }, new Benchmark.Suite()) .on('cycle', (event) => console.log(String(event.target))) .run(); }); node-addon-api-8.3.1/benchmark/index.js000066400000000000000000000017111475612273100177110ustar00rootroot00000000000000'use strict'; const { readdirSync } = require('fs'); const { spawnSync } = require('child_process'); const path = require('path'); let benchmarks = []; if (process.env.npm_config_benchmarks) { benchmarks = process.env.npm_config_benchmarks .split(';') .map((item) => (item + '.js')); } // Run each file in this directory or the list given on the command line except // index.js as a Node.js process. (benchmarks.length > 0 ? benchmarks : readdirSync(__dirname)) .filter((item) => (item !== 'index.js' && item.match(/\.js$/))) .map((item) => path.join(__dirname, item)) .forEach((item) => { const child = spawnSync(process.execPath, [ '--expose-gc', item ], { stdio: 'inherit' }); if (child.signal) { console.error(`Tests aborted with ${child.signal}`); process.exitCode = 1; } else { process.exitCode = child.status; } if (child.status !== 0) { process.exit(process.exitCode); } }); node-addon-api-8.3.1/benchmark/property_descriptor.cc000066400000000000000000000051031475612273100226740ustar00rootroot00000000000000#include "napi.h" static napi_value Getter_Core(napi_env env, napi_callback_info info) { (void)info; napi_value result; napi_status status = napi_create_uint32(env, 42, &result); NAPI_THROW_IF_FAILED(env, status, nullptr); return result; } static napi_value Setter_Core(napi_env env, napi_callback_info info) { size_t argc = 1; napi_value argv; napi_status status = napi_get_cb_info(env, info, &argc, &argv, nullptr, nullptr); NAPI_THROW_IF_FAILED(env, status, nullptr); (void)argv; return nullptr; } static Napi::Value Getter(const Napi::CallbackInfo& info) { return Napi::Number::New(info.Env(), 42); } static void Setter(const Napi::CallbackInfo& info) { (void)info[0]; } #if NAPI_VERSION > 5 class PropDescBenchmark : public Napi::Addon { public: PropDescBenchmark(Napi::Env, Napi::Object exports) { DefineAddon(exports, { InstanceAccessor("addon", &PropDescBenchmark::Getter, &PropDescBenchmark::Setter, napi_enumerable), InstanceAccessor<&PropDescBenchmark::Getter, &PropDescBenchmark::Setter>( "addon_templated", napi_enumerable), }); } private: Napi::Value Getter(const Napi::CallbackInfo& info) { return Napi::Number::New(info.Env(), 42); } void Setter(const Napi::CallbackInfo& info, const Napi::Value& val) { (void)info[0]; (void)val; } }; #endif // NAPI_VERSION > 5 static Napi::Object Init(Napi::Env env, Napi::Object exports) { napi_status status; napi_property_descriptor core_prop = {"core", nullptr, nullptr, Getter_Core, Setter_Core, nullptr, napi_enumerable, nullptr}; status = napi_define_properties(env, exports, 1, &core_prop); NAPI_THROW_IF_FAILED(env, status, Napi::Object()); exports.DefineProperty(Napi::PropertyDescriptor::Accessor( env, exports, "cplusplus", Getter, Setter, napi_enumerable)); exports.DefineProperty(Napi::PropertyDescriptor::Accessor( "templated", napi_enumerable)); #if NAPI_VERSION > 5 PropDescBenchmark::Init(env, exports); #endif // NAPI_VERSION > 5 return exports; } NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) node-addon-api-8.3.1/benchmark/property_descriptor.js000066400000000000000000000021211475612273100227200ustar00rootroot00000000000000const path = require('path'); const Benchmark = require('benchmark'); const addonName = path.basename(__filename, '.js'); [addonName, addonName + '_noexcept'] .forEach((addonName) => { const rootAddon = require('bindings')({ bindings: addonName, module_root: __dirname }); delete rootAddon.path; const getters = new Benchmark.Suite(); const setters = new Benchmark.Suite(); const maxNameLength = Object.keys(rootAddon) .reduce((soFar, value) => Math.max(soFar, value.length), 0); console.log(`\n${addonName}: `); Object.keys(rootAddon).forEach((key) => { getters.add(`${key} getter`.padStart(maxNameLength + 7), () => { // eslint-disable-next-line no-unused-vars const x = rootAddon[key]; }); setters.add(`${key} setter`.padStart(maxNameLength + 7), () => { rootAddon[key] = 5; }); }); getters .on('cycle', (event) => console.log(String(event.target))) .run(); console.log(''); setters .on('cycle', (event) => console.log(String(event.target))) .run(); }); node-addon-api-8.3.1/common.gypi000066400000000000000000000014351475612273100164770ustar00rootroot00000000000000{ 'variables': { 'NAPI_VERSION%': " ## API Documentation The following is the documentation for node-addon-api. - [Full Class Hierarchy](hierarchy.md) - [Addon Structure](addon.md) - Data Types: - [BasicEnv](basic_env.md) - [Env](env.md) - [CallbackInfo](callbackinfo.md) - [Reference](reference.md) - [Value](value.md) - [Name](name.md) - [Symbol](symbol.md) - [String](string.md) - [Number](number.md) - [Date](date.md) - [BigInt](bigint.md) - [Boolean](boolean.md) - [External](external.md) - [Object](object.md) - [Array](array.md) - [ObjectReference](object_reference.md) - [PropertyDescriptor](property_descriptor.md) - [Function](function.md) - [FunctionReference](function_reference.md) - [ObjectWrap](object_wrap.md) - [ClassPropertyDescriptor](class_property_descriptor.md) - [Buffer](buffer.md) - [ArrayBuffer](array_buffer.md) - [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/ node-addon-api-8.3.1/doc/addon.md000066400000000000000000000142531475612273100164730ustar00rootroot00000000000000# Add-on Structure Class `Napi::Addon` inherits from class [`Napi::InstanceWrap`][]. Creating add-ons that work correctly when loaded multiple times from the same source package into multiple Node.js threads and/or multiple times into the same Node.js thread requires that all global data they hold be associated with the environment in which they run. It is not safe to store global data in static variables because doing so does not take into account the fact that an add-on may be loaded into multiple threads nor that an add-on may be loaded multiple times into a single thread. The `Napi::Addon` class can be used to define an entire add-on. Instances of `Napi::Addon` subclasses become instances of the add-on, stored safely by Node.js on its various threads and into its various contexts. Thus, any data stored in the instance variables of a `Napi::Addon` subclass instance are stored safely by Node.js. Functions exposed to JavaScript using `Napi::Addon::InstanceMethod` and/or `Napi::Addon::DefineAddon` are instance methods of the `Napi::Addon` subclass and thus have access to data stored inside the instance. `Napi::Addon::DefineProperties` may be used to attach `Napi::Addon` subclass instance methods to objects other than the one that will be returned to Node.js as the add-on instance. The `Napi::Addon` class can be used together with the `NODE_API_ADDON()` and `NODE_API_NAMED_ADDON()` macros to define add-ons. ## Example ```cpp #include class ExampleAddon : public Napi::Addon { public: ExampleAddon(Napi::Env env, Napi::Object exports) { // In the constructor we declare the functions the add-on makes available // to JavaScript. DefineAddon(exports, { InstanceMethod("increment", &ExampleAddon::Increment), // We can also attach plain objects to `exports`, and instance methods as // properties of those sub-objects. InstanceValue("subObject", DefineProperties(Napi::Object::New(env), { InstanceMethod("decrement", &ExampleAddon::Decrement) }), napi_enumerable) }); } private: // This method has access to the data stored in the environment because it is // an instance method of `ExampleAddon` and because it was listed among the // property descriptors passed to `DefineAddon()` in the constructor. Napi::Value Increment(const Napi::CallbackInfo& info) { return Napi::Number::New(info.Env(), ++value); } // This method has access to the data stored in the environment because it is // an instance method of `ExampleAddon` and because it was exposed to // JavaScript by calling `DefineProperties()` with the object onto which it is // attached. Napi::Value Decrement(const Napi::CallbackInfo& info) { return Napi::Number::New(info.Env(), --value); } // Data stored in these variables is unique to each instance of the add-on. uint32_t value = 42; }; // The macro announces that instances of the class `ExampleAddon` will be // created for each instance of the add-on that must be loaded into Node.js. NODE_API_ADDON(ExampleAddon) ``` The above code can be used from JavaScript as follows: ```js 'use strict' const exampleAddon = require('bindings')('example_addon'); console.log(exampleAddon.increment()); // prints 43 console.log(exampleAddon.increment()); // prints 44 console.log(exampleAddon.subObject.decrement()); // prints 43 ``` When Node.js loads an instance of the add-on, a new instance of the class is created. Its constructor receives the environment `Napi::Env env` and the exports object `Napi::Object exports`. It can then use the method `DefineAddon` to either attach methods, accessors, and/or values to the `exports` object or to create its own `exports` object and attach methods, accessors, and/or values to it. **Note:** `Napi::Addon` uses `Napi::Env::SetInstanceData()` internally. This means that the add-on should only use `Napi::Env::GetInstanceData` explicitly to retrieve the instance of the `Napi::Addon` class. Variables whose scope would otherwise be global should be stored as instance variables in the `Napi::Addon` class. Functions created with `Napi::Function::New()`, accessors created with `PropertyDescriptor::Accessor()`, and values can also be attached. If their implementation requires the `ExampleAddon` instance, it can be retrieved from the `Napi::Env env` with `GetInstanceData()`: ```cpp void ExampleBinding(const Napi::CallbackInfo& info) { ExampleAddon* addon = info.Env().GetInstanceData(); } ``` ## Methods ### Constructor Creates a new instance of the add-on. ```cpp Napi::Addon(Napi::Env env, Napi::Object exports); ``` - `[in] env`: The environment into which the add-on is being loaded. - `[in] exports`: The exports object received from JavaScript. Typically, the constructor calls `DefineAddon()` to attach methods, accessors, and/or values to `exports`. The constructor may also create a new object and pass it to `DefineAddon()` as its first parameter if it wishes to replace the `exports` object as provided by Node.js. ### DefineAddon Defines an add-on instance with functions, accessors, and/or values. ```cpp template void Napi::Addon::DefineAddon(Napi::Object exports, const std::initializer_list& properties); ``` * `[in] exports`: The object to return to Node.js as an instance of the add-on. * `[in] properties`: Initializer list of add-on property descriptors of the methods, property accessors, and values that define the add-on. They will be set on `exports`. See: [`Class property and descriptor`](class_property_descriptor.md). ### DefineProperties Defines function, accessor, and/or value properties on an object using add-on instance methods. ```cpp template Napi::Object Napi::Addon::DefineProperties(Napi::Object object, const std::initializer_list& properties); ``` * `[in] object`: The object that will receive the new properties. * `[in] properties`: Initializer list of property descriptors of the methods, property accessors, and values to attach to `object`. See: [`Class property and descriptor`](class_property_descriptor.md). Returns `object`. [`Napi::InstanceWrap`]: ./instance_wrap.md node-addon-api-8.3.1/doc/array.md000066400000000000000000000052441475612273100165240ustar00rootroot00000000000000# Array Class [`Napi::Array`][] inherits from class [`Napi::Object`][]. Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper around `napi_value` representing a JavaScript Array. [`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data types such as [`Napi::Int32Array`][] and [`Napi::ArrayBuffer`][], respectively, that can be used for transferring large amounts of data from JavaScript to the native side. An example illustrating the use of a JavaScript-provided `ArrayBuffer` in native code is available [here](https://github.com/nodejs/node-addon-examples/tree/main/src/2-js-to-native-conversion/array_buffer_to_native/node-addon-api). ## Constructor ```cpp Napi::Array::Array(); ``` Returns an empty array. If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. ```cpp Napi::Array::Array(napi_env env, napi_value value); ``` - `[in] env` - The environment in which to create the array. - `[in] value` - The primitive to wrap. Returns a `Napi::Array` wrapping a `napi_value`. If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. ## Methods ### New ```cpp static Napi::Array Napi::Array::New(napi_env env); ``` - `[in] env` - The environment in which to create the array. Returns a new `Napi::Array`. If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. ### New ```cpp static Napi::Array Napi::Array::New(napi_env env, size_t length); ``` - `[in] env` - The environment in which to create the array. - `[in] length` - The length of the array. Returns a new `Napi::Array` with the given length. If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. ### Length ```cpp uint32_t Napi::Array::Length() const; ``` Returns the length of the array. Note: This can execute JavaScript code implicitly according to JavaScript semantics. If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. [`Napi::ArrayBuffer`]: ./array_buffer.md [`Napi::Int32Array`]: ./typed_array_of.md [`Napi::Object`]: ./object.md [`Napi::TypedArray`]: ./typed_array.md node-addon-api-8.3.1/doc/array_buffer.md000066400000000000000000000125521475612273100200550ustar00rootroot00000000000000# ArrayBuffer Class `Napi::ArrayBuffer` inherits from class [`Napi::Object`][]. The `Napi::ArrayBuffer` class corresponds to the [JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) class. ## Methods ### New Allocates a new `Napi::ArrayBuffer` instance with a given length. ```cpp static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, size_t byteLength); ``` - `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. - `[in] byteLength`: The length to be allocated, in bytes. Returns a new `Napi::ArrayBuffer` instance. ### New > When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available. > See [External Buffer][] for more information. 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. See [Finalization][] for more details. ```cpp static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength); ``` - `[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. Returns a new `Napi::ArrayBuffer` instance. ### New > When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available. > See [External Buffer][] for more information. 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. The data can only be freed once the `finalizeCallback` is invoked to indicate that the `Napi::ArrayBuffer` has been released. ```cpp template static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength, Finalizer finalizeCallback); ``` - `[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 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. ### New > When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available. > See [External Buffer][] for more information. 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. The data can only be freed once the `finalizeCallback` is invoked to indicate that the `Napi::ArrayBuffer` has been released. ```cpp template static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength, Finalizer finalizeCallback, Hint* finalizeHint); ``` - `[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 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. ### Constructor Initializes an empty instance of the `Napi::ArrayBuffer` class. ```cpp Napi::ArrayBuffer::ArrayBuffer(); ``` ### Constructor Initializes a wrapper instance of an existing `Napi::ArrayBuffer` object. ```cpp Napi::ArrayBuffer::ArrayBuffer(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. - `[in] value`: The `Napi::ArrayBuffer` reference to wrap. ### ByteLength ```cpp size_t Napi::ArrayBuffer::ByteLength() const; ``` Returns the length of the wrapped data, in bytes. ### Data ```cpp void* Napi::ArrayBuffer::Data() const; ``` Returns a pointer the wrapped data. ### Detach ```cpp void Napi::ArrayBuffer::Detach(); ``` Invokes the `ArrayBuffer` detach operation on a detachable `ArrayBuffer`. ### IsDetached ```cpp bool Napi::ArrayBuffer::IsDetached() const; ``` Returns `true` if this `ArrayBuffer` has been detached. [`Napi::Object`]: ./object.md [External Buffer]: ./external_buffer.md [Finalization]: ./finalization.md node-addon-api-8.3.1/doc/async_context.md000066400000000000000000000050511475612273100202630ustar00rootroot00000000000000# AsyncContext The [Napi::AsyncWorker](async_worker.md) class may not be appropriate for every scenario. When using any other async mechanism, introducing a new class `Napi::AsyncContext` is necessary to ensure an async operation is properly tracked by the runtime. The `Napi::AsyncContext` class can be passed to [Napi::Function::MakeCallback()](function.md) method to properly restore the correct async execution context. ## Methods ### Constructor Creates a new `Napi::AsyncContext`. ```cpp explicit Napi::AsyncContext::AsyncContext(napi_env env, const char* resource_name); ``` - `[in] env`: The environment in which to create the `Napi::AsyncContext`. - `[in] resource_name`: Null-terminated strings that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the `async_hooks` API. ### Constructor Creates a new `Napi::AsyncContext`. ```cpp explicit Napi::AsyncContext::AsyncContext(napi_env env, const char* resource_name, const Napi::Object& resource); ``` - `[in] env`: The environment in which to create the `Napi::AsyncContext`. - `[in] resource_name`: Null-terminated strings that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the `async_hooks` API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible `async_hooks`. ### Destructor The `Napi::AsyncContext` to be destroyed. ```cpp virtual Napi::AsyncContext::~AsyncContext(); ``` ### Env Requests the environment in which the async context has been initially created. ```cpp Napi::Env Env() const; ``` Returns the `Napi::Env` environment in which the async context has been created. ## Operator ```cpp Napi::AsyncContext::operator napi_async_context() const; ``` Returns the Node-API `napi_async_context` wrapped by the `Napi::AsyncContext` object. This can be used to mix usage of the C Node-API and node-addon-api. ## Example ```cpp #include "napi.h" void MakeCallbackWithAsyncContext(const Napi::CallbackInfo& info) { Napi::Function callback = info[0].As(); Napi::Object resource = info[1].As(); // Create a new async context instance. Napi::AsyncContext context(info.Env(), "async_context_test", resource); // Invoke the callback with the async context instance. callback.MakeCallback(Napi::Object::New(info.Env()), std::initializer_list{}, context); // The async context instance is automatically destroyed here because it's // block-scope like `Napi::HandleScope`. } ``` node-addon-api-8.3.1/doc/async_operations.md000066400000000000000000000025301475612273100207610ustar00rootroot00000000000000# Asynchronous operations Node.js native add-ons often need to execute long running tasks and to avoid blocking the **event loop** they have to run them asynchronously from the **event loop**. In the Node.js model of execution the event loop thread represents the thread where JavaScript code is executing. The Node.js guidance is to avoid blocking other work queued on the event loop thread. Therefore, we need to do this work on another thread. All this means that native add-ons need to leverage async helpers from libuv as part of their implementation. This allows them to schedule work to be executed asynchronously so that their methods can return in advance of the work being completed. Node Addon API provides an interface to support functions that cover the most common asynchronous use cases. There is an abstract classes to implement asynchronous operations: - **[`Napi::AsyncWorker`](async_worker.md)** This class helps manage asynchronous operations through an abstraction of the concept of moving data between the **event loop** and **worker threads**. Also, the above class may not be appropriate for every scenario. When using any other asynchronous mechanism, the following API is necessary to ensure an asynchronous operation is properly tracked by the runtime: - **[AsyncContext](async_context.md)** - **[CallbackScope](callback_scope.md)** node-addon-api-8.3.1/doc/async_worker.md000066400000000000000000000344671475612273100201250ustar00rootroot00000000000000# AsyncWorker `Napi::AsyncWorker` is an abstract class that you can subclass to remove many of the tedious tasks of moving data between the event loop and worker threads. This class internally handles all the details of creating and executing an asynchronous operation. Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When a thread is available for execution the `Napi::AsyncWorker::Execute` method will be invoked. Once `Napi::AsyncWorker::Execute` completes either `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are complete the `Napi::AsyncWorker` instance is destructed. For the most basic use, only the `Napi::AsyncWorker::Execute` method must be implemented in a subclass. ## Methods ### Env Requests the environment in which the async worker has been initially created. ```cpp Napi::Env Napi::AsyncWorker::Env() const; ``` Returns the environment in which the async worker has been created. ### Queue Requests that the work be queued for execution. ```cpp void Napi::AsyncWorker::Queue(); ``` ### Cancel Cancels queued work if it has not yet been started. If it has already started executing, it cannot be cancelled. If cancelled successfully neither `OnOK` nor `OnError` will be called. ```cpp void Napi::AsyncWorker::Cancel(); ``` ### Receiver ```cpp Napi::ObjectReference& Napi::AsyncWorker::Receiver(); ``` Returns the persistent object reference of the receiver object set when the async worker was created. ### Callback ```cpp Napi::FunctionReference& Napi::AsyncWorker::Callback(); ``` Returns the persistent function reference of the callback set when the async worker was created. The returned function reference will receive the results of the computation that happened in the `Napi::AsyncWorker::Execute` method, unless the default implementation of `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` is overridden. ### SuppressDestruct ```cpp void Napi::AsyncWorker::SuppressDestruct(); ``` Prevents the destruction of the `Napi::AsyncWorker` instance upon completion of the `Napi::AsyncWorker::OnOK` callback. ### SetError Sets the error message for the error that happened during the execution. Setting an error message will cause the `Napi::AsyncWorker::OnError` method to be invoked instead of `Napi::AsyncWorker::OnOK` once the `Napi::AsyncWorker::Execute` method completes. ```cpp void Napi::AsyncWorker::SetError(const std::string& error); ``` - `[in] error`: The reference to the string that represent the message of the error. ### Execute This method is used to execute some tasks outside of the **event loop** on a libuv worker thread. Subclasses must implement this method and the method is run on a thread other than that running the main event loop. As the method is not running on the main event loop, it must avoid calling any methods from node-addon-api or running any code that might invoke JavaScript. Instead, once this method is complete any interaction through node-addon-api with JavaScript should be implemented in the `Napi::AsyncWorker::OnOK` method and `Napi::AsyncWorker::OnError` which run on the main thread and are invoked when the `Napi::AsyncWorker::Execute` method completes. ```cpp virtual void Napi::AsyncWorker::Execute() = 0; ``` ### OnOK This method is invoked when the computation in the `Execute` method ends. The default implementation runs the `Callback` optionally provided when the `AsyncWorker` class was created. The `Callback` will by default receive no arguments. The arguments to the `Callback` can be provided by overriding the `GetResult()` method. ```cpp virtual void Napi::AsyncWorker::OnOK(); ``` ### GetResult This method returns the arguments passed to the `Callback` invoked by the default `OnOK()` implementation. The default implementation returns an empty vector, providing no arguments to the `Callback`. ```cpp virtual std::vector Napi::AsyncWorker::GetResult(Napi::Env env); ``` ### OnError This method is invoked after `Napi::AsyncWorker::Execute` completes if an error occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`. The default implementation calls the `Callback` provided when the `Napi::AsyncWorker` class was created, passing in the error as the first parameter. ```cpp virtual void Napi::AsyncWorker::OnError(const Napi::Error& e); ``` ### OnWorkComplete This method is invoked after the work has completed on JavaScript thread. The default implementation of this method checks the status of the work and tries to dispatch the result to `Napi::AsyncWorker::OnOk` or `Napi::AsyncWorker::Error` if the work has committed an error. If the work was cancelled, neither `Napi::AsyncWorker::OnOk` nor `Napi::AsyncWorker::Error` will be invoked. After the result is dispatched, the default implementation will call into `Napi::AsyncWorker::Destroy` if `SuppressDestruct()` was not called. ```cpp virtual void OnWorkComplete(Napi::Env env, napi_status status); ``` ### OnExecute This method is invoked immediately on the work thread when scheduled. The default implementation of this method just calls the `Napi::AsyncWorker::Execute` and handles exceptions if cpp exceptions were enabled. The `OnExecute` method receives an `napi_env` argument. However, the `napi_env` must NOT be used within this method, as it does not run on the JavaScript thread and must not run any method that would cause JavaScript to run. In practice, this means that almost any use of `napi_env` will be incorrect. ```cpp virtual void OnExecute(Napi::Env env); ``` ### Destroy This method is invoked when the instance must be deallocated. If `SuppressDestruct()` was not called then this method will be called after either `OnError()` or `OnOK()` complete. The default implementation of this method causes the instance to delete itself using the `delete` operator. The method is provided so as to ensure that instances allocated by means other than the `new` operator can be deallocated upon work completion. ```cpp virtual void Napi::AsyncWorker::Destroy(); ``` ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(const Napi::Function& callback); ``` - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling `Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_name); ``` - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_name, const Napi::Object& resource); ``` - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback); ``` - `[in] receiver`: The `this` object passed to the called function. - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name); ``` - `[in] receiver`: The `this` object passed to the called function. - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name, const Napi::Object& resource); ``` - `[in] receiver`: The `this` object passed to the called function. - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(Napi::Env env); ``` - `[in] env`: The environment in which to create the `Napi::AsyncWorker`. Returns an `Napi::AsyncWorker` instance which can later be queued for execution by calling `Napi::AsyncWorker::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name); ``` - `[in] env`: The environment in which to create the `Napi::AsyncWorker`. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling `Napi::AsyncWorker::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource); ``` - `[in] env`: The environment in which to create the `Napi::AsyncWorker`. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling `Napi::AsyncWorker::Queue`. ### Destructor Deletes the created work object that is used to execute logic asynchronously. ```cpp virtual Napi::AsyncWorker::~AsyncWorker(); ``` ## Operator ```cpp Napi::AsyncWorker::operator napi_async_work() const; ``` Returns the Node-API `napi_async_work` wrapped by the `Napi::AsyncWorker` object. This can be used to mix usage of the C Node-API and node-addon-api. ## Example The first step to use the `Napi::AsyncWorker` class is to create a new class that inherits from it and implement the `Napi::AsyncWorker::Execute` abstract method. Typically input to your worker will be saved within class' fields generally passed in through its constructor. When the `Napi::AsyncWorker::Execute` method completes without errors the `Napi::AsyncWorker::OnOK` function callback will be invoked. In this function the results of the computation will be reassembled and returned back to the initial JavaScript context. `Napi::AsyncWorker` ensures that all the code in the `Napi::AsyncWorker::Execute` function runs in the background out of the **event loop** thread and at the end the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` function will be called and are executed as part of the event loop. The code below shows a basic example of `Napi::AsyncWorker` the implementation: ```cpp #include #include #include using namespace Napi; class EchoWorker : public AsyncWorker { public: EchoWorker(Function& callback, std::string& echo) : AsyncWorker(callback), echo(echo) {} ~EchoWorker() {} // This code will be executed on the worker thread void Execute() override { // Need to simulate cpu heavy task std::this_thread::sleep_for(std::chrono::seconds(1)); } void OnOK() override { HandleScope scope(Env()); Callback().Call({Env().Null(), String::New(Env(), echo)}); } private: std::string echo; }; ``` The `EchoWorker`'s constructor calls the base class' constructor to pass in the callback that the `Napi::AsyncWorker` base class will store persistently. When the work on the `Napi::AsyncWorker::Execute` method is done the `Napi::AsyncWorker::OnOk` method is called and the results return back to JavaScript invoking the stored callback with its associated environment. The following code shows an example of how to create and use an `Napi::AsyncWorker`. ```cpp #include // Include EchoWorker class // .. using namespace Napi; Value Echo(const CallbackInfo& info) { // You need to validate the arguments here. Function cb = info[1].As(); std::string in = info[0].As(); EchoWorker* wk = new EchoWorker(cb, in); wk->Queue(); return info.Env().Undefined(); } ``` Using the implementation of a `Napi::AsyncWorker` is straight forward. You only need to create a new instance and pass to its constructor the callback you want to execute when your asynchronous task ends and other data you need for your computation. Once created the only other action you have to do is to call the `Napi::AsyncWorker::Queue` method that will queue the created worker for execution. node-addon-api-8.3.1/doc/async_worker_variants.md000066400000000000000000000514371475612273100220300ustar00rootroot00000000000000# AsyncProgressWorker `Napi::AsyncProgressWorker` is an abstract class which implements `Napi::AsyncWorker` while extending `Napi::AsyncWorker` internally with `Napi::ThreadSafeFunction` for moving work progress reports from worker thread(s) to event loop threads. Like `Napi::AsyncWorker`, once created, execution is requested by calling `Napi::AsyncProgressWorker::Queue`. When a thread is available for execution the `Napi::AsyncProgressWorker::Execute` method will be invoked. During the execution, `Napi::AsyncProgressWorker::ExecutionProgress::Send` can be used to indicate execution process, which will eventually invoke `Napi::AsyncProgressWorker::OnProgress` on the JavaScript thread to safely call into JavaScript. Once `Napi::AsyncProgressWorker::Execute` completes either `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` will be invoked. Once the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` methods are complete the `Napi::AsyncProgressWorker` instance is destructed. For the most basic use, only the `Napi::AsyncProgressWorker::Execute` and `Napi::AsyncProgressWorker::OnProgress` method must be implemented in a subclass. ## Methods [`Napi::AsyncWorker`][] provides detailed descriptions for most methods. ### Execute This method is used to execute some tasks outside of the **event loop** on a libuv worker thread. Subclasses must implement this method and the method is run on a thread other than that running the main event loop. As the method is not running on the main event loop, it must avoid calling any methods from node-addon-api or running any code that might invoke JavaScript. Instead, once this method is complete any interaction through node-addon-api with JavaScript should be implemented in the `Napi::AsyncProgressWorker::OnOK` method and/or `Napi::AsyncProgressWorker::OnError` which run on the main thread and are invoked when the `Napi::AsyncProgressWorker::Execute` method completes. ```cpp virtual void Napi::AsyncProgressWorker::Execute(const ExecutionProgress& progress) = 0; ``` ### OnOK This method is invoked when the computation in the `Execute` method ends. The default implementation runs the `Callback` optionally provided when the `AsyncProgressWorker` class was created. The `Callback` will by default receive no arguments. Arguments to the callback can be provided by overriding the `GetResult()` method. ```cpp virtual void Napi::AsyncProgressWorker::OnOK(); ``` ### OnProgress This method is invoked when the computation in the `Napi::AsyncProgressWorker::ExecutionProgress::Send` method was called during worker thread execution. This method can also be triggered via a call to `Napi::AsyncProgress[Queue]Worker::ExecutionProgress::Signal`, in which case the `data` parameter will be `nullptr`. ```cpp virtual void Napi::AsyncProgressWorker::OnProgress(const T* data, size_t count) ``` ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(const Napi::Function& callback); ``` - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name); ``` - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(const Napi::Function& callback, const char* resource_name, const Napi::Object& resource); ``` - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback); ``` - `[in] receiver`: The `this` object passed to the called function. - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name); ``` - `[in] receiver`: The `this` object passed to the called function. - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name, const Napi::Object& resource); ``` - `[in] receiver`: The `this` object to be passed to the called function. - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(Napi::Env env); ``` - `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`. Returns an `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling `Napi::AsyncProgressWorker::Queue`. Available with `NAPI_VERSION` equal to or greater than 5. ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name); ``` - `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling `Napi::AsyncProgressWorker::Queue`. Available with `NAPI_VERSION` equal to or greater than 5. ### Constructor Creates a new `Napi::AsyncProgressWorker`. ```cpp explicit Napi::AsyncProgressWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource); ``` - `[in] env`: The environment in which to create the `Napi::AsyncProgressWorker`. - `[in] resource_name`: Null-terminated string that represents the identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. Returns a `Napi::AsyncProgressWorker` instance which can later be queued for execution by calling `Napi::AsyncProgressWorker::Queue`. Available with `NAPI_VERSION` equal to or greater than 5. ### Destructor Deletes the created work object that is used to execute logic asynchronously and release the internal `Napi::ThreadSafeFunction`, which will be aborted to prevent unexpected upcoming thread safe calls. ```cpp virtual Napi::AsyncProgressWorker::~AsyncProgressWorker(); ``` # AsyncProgressWorker::ExecutionProgress A bridge class created before the worker thread execution of `Napi::AsyncProgressWorker::Execute`. ## Methods ### Send `Napi::AsyncProgressWorker::ExecutionProgress::Send` takes two arguments, a pointer to a generic type of data, and a `size_t` to indicate how many items the pointer is pointing to. The data pointed to will be copied to internal slots of `Napi::AsyncProgressWorker` so after the call to `Napi::AsyncProgressWorker::ExecutionProgress::Send` the data can be safely released. Note that `Napi::AsyncProgressWorker::ExecutionProgress::Send` merely guarantees **eventual** invocation of `Napi::AsyncProgressWorker::OnProgress`, which means multiple send might be coalesced into single invocation of `Napi::AsyncProgressWorker::OnProgress` with latest data. If you would like to guarantee that there is one invocation of `OnProgress` for every `Send` call, you should use the `Napi::AsyncProgressQueueWorker` class instead which is documented further down this page. ```cpp void Napi::AsyncProgressWorker::ExecutionProgress::Send(const T* data, size_t count) const; ``` ### Signal `Napi::AsyncProgressWorker::ExecutionProgress::Signal` triggers an invocation of `Napi::AsyncProgressWorker::OnProgress` with `nullptr` as the `data` parameter. ```cpp void Napi::AsyncProgressWorker::ExecutionProgress::Signal(); ``` ## Example The first step to use the `Napi::AsyncProgressWorker` class is to create a new class that inherits from it and implement the `Napi::AsyncProgressWorker::Execute` abstract method. Typically input to the worker will be saved within the class' fields generally passed in through its constructor. During the worker thread execution, the first argument of `Napi::AsyncProgressWorker::Execute` can be used to report the progress of the execution. When the `Napi::AsyncProgressWorker::Execute` method completes without errors the `Napi::AsyncProgressWorker::OnOK` function callback will be invoked. In this function the results of the computation will be reassembled and returned back to the initial JavaScript context. `Napi::AsyncProgressWorker` ensures that all the code in the `Napi::AsyncProgressWorker::Execute` function runs in the background out of the **event loop** thread and at the end the `Napi::AsyncProgressWorker::OnOK` or `Napi::AsyncProgressWorker::OnError` function will be called and are executed as part of the event loop. The code below shows a basic example of the `Napi::AsyncProgressWorker` implementation along with an example of how the counterpart in Javascript would appear: ```cpp #include #include #include using namespace Napi; class EchoWorker : public AsyncProgressWorker { public: EchoWorker(Function& okCallback, std::string& echo) : AsyncProgressWorker(okCallback), echo(echo) {} ~EchoWorker() {} // This code will be executed on the worker thread void Execute(const ExecutionProgress& progress) { // Need to simulate cpu heavy task // Note: This Send() call is not guaranteed to trigger an equal // number of OnProgress calls (read documentation above for more info) for (uint32_t i = 0; i < 100; ++i) { progress.Send(&i, 1) } } void OnError(const Error &e) { HandleScope scope(Env()); // Pass error onto JS, no data for other parameters Callback().Call({String::New(Env(), e.Message())}); } void OnOK() { HandleScope scope(Env()); // Pass no error, give back original data Callback().Call({Env().Null(), String::New(Env(), echo)}); } void OnProgress(const uint32_t* data, size_t /* count */) { HandleScope scope(Env()); // Pass no error, no echo data, but do pass on the progress data Callback().Call({Env().Null(), Env().Null(), Number::New(Env(), *data)}); } private: std::string echo; }; ``` The `EchoWorker`'s constructor calls the base class' constructor to pass in the callback that the `Napi::AsyncProgressWorker` base class will store persistently. When the work on the `Napi::AsyncProgressWorker::Execute` method is done the `Napi::AsyncProgressWorker::OnOk` method is called and the results are return back to JavaScript when the stored callback is invoked with its associated environment. The following code shows an example of how to create and use an `Napi::AsyncProgressWorker` ```cpp #include // Include EchoWorker class // .. using namespace Napi; Value Echo(const CallbackInfo& info) { // We need to validate the arguments here std::string in = info[0].As(); Function cb = info[1].As(); EchoWorker* wk = new EchoWorker(cb, in); wk->Queue(); return info.Env().Undefined(); } // Register the native method for JS to access Object Init(Env env, Object exports) { exports.Set(String::New(env, "echo"), Function::New(env, Echo)); return exports; } // Register our native addon NODE_API_MODULE(nativeAddon, Init) ``` The implementation of a `Napi::AsyncProgressWorker` can be used by creating a new instance and passing to its constructor the callback to execute when the asynchronous task ends and other data needed for the computation. Once created, the only other action needed is to call the `Napi::AsyncProgressWorker::Queue` method that will queue the created worker for execution. Lastly, the following Javascript (ES6+) code would be associated the above example: ```js const { nativeAddon } = require('binding.node'); const exampleCallback = (errorResponse, okResponse, progressData) => { // Use the data accordingly // ... }; // Call our native addon with the parameters of a string and a function nativeAddon.echo("example", exampleCallback); ``` # AsyncProgressQueueWorker `Napi::AsyncProgressQueueWorker` acts exactly like `Napi::AsyncProgressWorker` except that each progress committed by `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send` during `Napi::AsyncProgressQueueWorker::Execute` is guaranteed to be processed by `Napi::AsyncProgressQueueWorker::OnProgress` on the JavaScript thread in the order it was committed. For the most basic use, only the `Napi::AsyncProgressQueueWorker::Execute` and `Napi::AsyncProgressQueueWorker::OnProgress` method must be implemented in a subclass. # AsyncProgressQueueWorker::ExecutionProgress A bridge class created before the worker thread execution of `Napi::AsyncProgressQueueWorker::Execute`. ## Methods ### Send `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send` takes two arguments, a pointer to a generic type of data, and a `size_t` to indicate how many items the pointer is pointing to. The data pointed to will be copied to internal slots of `Napi::AsyncProgressQueueWorker` so after the call to `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send` the data can be safely released. `Napi::AsyncProgressQueueWorker::ExecutionProgress::Send` guarantees invocation of `Napi::AsyncProgressQueueWorker::OnProgress`, which means multiple `Send` call will result in the in-order invocation of `Napi::AsyncProgressQueueWorker::OnProgress` with each data item. ```cpp void Napi::AsyncProgressQueueWorker::ExecutionProgress::Send(const T* data, size_t count) const; ``` ### Signal `Napi::AsyncProgressQueueWorker::ExecutionProgress::Signal` triggers an invocation of `Napi::AsyncProgressQueueWorker::OnProgress` with `nullptr` as the `data` parameter. ```cpp void Napi::AsyncProgressQueueWorker::ExecutionProgress::Signal() const; ``` ## Example The code below shows an example of the `Napi::AsyncProgressQueueWorker` implementation, but also demonstrates how to use multiple `Napi::Function`'s if you wish to provide multiple callback functions for more object-oriented code: ```cpp #include #include #include using namespace Napi; class EchoWorker : public AsyncProgressQueueWorker { public: EchoWorker(Function& okCallback, Function& errorCallback, Function& progressCallback, std::string& echo) : AsyncProgressQueueWorker(okCallback), echo(echo) { // Set our function references to use them below this->errorCallback.Reset(errorCallback, 1); this->progressCallback.Reset(progressCallback, 1); } ~EchoWorker() {} // This code will be executed on the worker thread void Execute(const ExecutionProgress& progress) { // Need to simulate cpu heavy task to demonstrate that // every call to Send() will trigger an OnProgress function call for (uint32_t i = 0; i < 100; ++i) { progress.Send(&i, 1); } } void OnOK() { HandleScope scope(Env()); // Call our onOkCallback in javascript with the data we were given originally Callback().Call({String::New(Env(), echo)}); } void OnError(const Error &e) { HandleScope scope(Env()); // We call our callback provided in the constructor with 2 parameters if (!this->errorCallback.IsEmpty()) { // Call our onErrorCallback in javascript with the error message this->errorCallback.Call(Receiver().Value(), {String::New(Env(), e.Message())}); } } void OnProgress(const uint32_t* data, size_t /* count */) { HandleScope scope(Env()); if (!this->progressCallback.IsEmpty()) { // Call our onProgressCallback in javascript with each integer from 0 to 99 (inclusive) // as this function is triggered from the above Send() calls this->progressCallback.Call(Receiver().Value(), {Number::New(Env(), *data)}); } } private: std::string echo; FunctionReference progressCallback; FunctionReference errorCallback; }; ``` The `EchoWorker`'s constructor calls the base class' constructor to pass in the callback that the `Napi::AsyncProgressQueueWorker` base class will store persistently. When the work on the `Napi::AsyncProgressQueueWorker::Execute` method is done the `Napi::AsyncProgressQueueWorker::OnOk` method is called and the results are returned back to JavaScript when the stored callback is invoked with its associated environment. The following code shows an example of how to create and use an `Napi::AsyncProgressQueueWorker`. ```cpp #include // Include EchoWorker class // .. using namespace Napi; Value Echo(const CallbackInfo& info) { // We need to validate the arguments here. std::string in = info[0].As(); Function errorCb = info[1].As(); Function okCb = info[2].As(); Function progressCb = info[3].As(); EchoWorker* wk = new EchoWorker(okCb, errorCb, progressCb, in); wk->Queue(); return info.Env().Undefined(); } // Register the native method for JS to access Object Init(Env env, Object exports) { exports.Set(String::New(env, "echo"), Function::New(env, Echo)); return exports; } // Register our native addon NODE_API_MODULE(nativeAddon, Init) ``` The implementation of a `Napi::AsyncProgressQueueWorker` can be used by creating a new instance and passing to its constructor the callback to execute when the asynchronous task ends and other data needed for the computation. Once created, the only other action needed is to call the `Napi::AsyncProgressQueueWorker::Queue` method that will queue the created worker for execution. Lastly, the following Javascript (ES6+) code would be associated the above example: ```js const { nativeAddon } = require('binding.node'); const onErrorCallback = (msg) => { // Use the data accordingly // ... }; const onOkCallback = (echo) => { // Use the data accordingly // ... }; const onProgressCallback = (num) => { // Use the data accordingly // ... }; // Call our native addon with the parameters of a string and three callback functions nativeAddon.echo("example", onErrorCallback, onOkCallback, onProgressCallback); ``` [`Napi::AsyncWorker`]: ./async_worker.md node-addon-api-8.3.1/doc/basic_env.md000066400000000000000000000145461475612273100173440ustar00rootroot00000000000000# 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 node-addon-api-8.3.1/doc/bigint.md000066400000000000000000000052401475612273100166560ustar00rootroot00000000000000# BigInt Class `Napi::Bigint` inherits from class [`Napi::Value`][]. A JavaScript BigInt value. ## Methods ### New ```cpp static Napi::BigInt Napi::BigInt::New(Napi::Env env, int64_t value); static Napi::BigInt Napi::BigInt::New(Napi::Env env, uint64_t value); ``` - `[in] env`: The environment in which to construct the `Napi::BigInt` object. - `[in] value`: The value the JavaScript `BigInt` will contain These APIs convert the C `int64_t` and `uint64_t` types to the JavaScript `BigInt` type. ```cpp static Napi::BigInt Napi::BigInt::New(Napi::Env env, int sign_bit, size_t word_count, const uint64_t* words); ``` - `[in] env`: The environment in which to construct the `Napi::BigInt` object. - `[in] sign_bit`: Determines if the resulting `BigInt` will be positive or negative. - `[in] word_count`: The length of the words array. - `[in] words`: An array of `uint64_t` little-endian 64-bit words. This API converts an array of unsigned 64-bit words into a single `BigInt` value. The resulting `BigInt` is calculated as: (–1)`sign_bit` (`words[0]` × (264)0 + `words[1]` × (264)1 + …) Returns a new JavaScript `BigInt`. ### Constructor ```cpp Napi::BigInt(); ``` Returns a new empty JavaScript `Napi::BigInt`. ### Int64Value ```cpp int64_t Napi::BigInt::Int64Value(bool* lossless) const; ``` - `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly. Returns the C `int64_t` primitive equivalent of the given JavaScript `BigInt`. If needed it will truncate the value, setting lossless to false. ### Uint64Value ```cpp uint64_t Napi::BigInt::Uint64Value(bool* lossless) const; ``` - `[out] lossless`: Indicates whether the `BigInt` value was converted losslessly. Returns the C `uint64_t` primitive equivalent of the given JavaScript `BigInt`. If needed it will truncate the value, setting lossless to false. ### WordCount ```cpp size_t Napi::BigInt::WordCount() const; ``` Returns the number of words needed to store this `BigInt` value. ### ToWords ```cpp void Napi::BigInt::ToWords(int* sign_bit, size_t* word_count, uint64_t* words); ``` - `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive or negative. - `[in/out] word_count`: Must be initialized to the length of the words array. Upon return, it will be set to the actual number of words that would be needed to store this `BigInt`. - `[out] words`: Pointer to a pre-allocated 64-bit word array. Returns a single `BigInt` value into a sign bit, 64-bit little-endian array, and the number of elements in the array. [`Napi::Value`]: ./value.md node-addon-api-8.3.1/doc/boolean.md000066400000000000000000000030751475612273100170250ustar00rootroot00000000000000# Boolean Class `Napi::Boolean` inherits from class [`Napi::Value`][]. `Napi::Boolean` class is a representation of the JavaScript `Boolean` object. The `Napi::Boolean` class inherits its behavior from the `Napi::Value` class (for more info see: [`Napi::Value`](value.md)). ## Methods ### Constructor Creates a new empty instance of an `Napi::Boolean` object. ```cpp Napi::Boolean::Boolean(); ``` Returns a new _empty_ `Napi::Boolean` object. ### Constructor Creates a new instance of the `Napi::Boolean` object. ```cpp Napi::Boolean(napi_env env, napi_value value); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Boolean` object. - `[in] value`: The `napi_value` which is a handle for a JavaScript `Boolean`. Returns a non-empty `Napi::Boolean` object. ### New Initializes a new instance of the `Napi::Boolean` object. ```cpp Napi::Boolean Napi::Boolean::New(napi_env env, bool value); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Boolean` object. - `[in] value`: The primitive boolean value (`true` or `false`). Returns a new instance of the `Napi::Boolean` object. ### Value Converts a `Napi::Boolean` value to a boolean primitive. ```cpp bool Napi::Boolean::Value() const; ``` Returns the boolean primitive type of the corresponding `Napi::Boolean` object. ## Operators ### operator bool Converts a `Napi::Boolean` value to a boolean primitive. ```cpp Napi::Boolean::operator bool() const; ``` Returns the boolean primitive type of the corresponding `Napi::Boolean` object. [`Napi::Value`]: ./value.md node-addon-api-8.3.1/doc/buffer.md000066400000000000000000000216471475612273100166640ustar00rootroot00000000000000# Buffer Class `Napi::Buffer` inherits from class [`Napi::Uint8Array`][]. The `Napi::Buffer` class creates a projection of raw data that can be consumed by script. ## Methods ### New Allocates a new `Napi::Buffer` object with a given length. ```cpp static Napi::Buffer Napi::Buffer::New(napi_env env, size_t length); ``` - `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] length`: The number of `T` elements to allocate. Returns a new `Napi::Buffer` object. ### New > When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available. > See [External Buffer][] for more information. 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 `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); ``` - `[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. Returns a new `Napi::Buffer` object. ### New > When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available. > See [External Buffer][] for more information. 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. The data can only be freed once the `finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released. ```cpp template static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length, Finalizer finalizeCallback); ``` - `[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 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. ### New > When `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` is defined, this method is not available. > See [External Buffer][] for more information. 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. The data can only be freed once the `finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released. ```cpp template static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length, Finalizer finalizeCallback, Hint* finalizeHint); ``` - `[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 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. ### NewOrCopy Wraps the provided external data into a new `Napi::Buffer` object. When the [external buffer][] is not supported, allocates a new `Napi::Buffer` object and copies the provided external data into it. 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. ```cpp static Napi::Buffer Napi::Buffer::NewOrCopy(napi_env env, T* data, size_t length); ``` - `[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. Returns a new `Napi::Buffer` object. ### NewOrCopy Wraps the provided external data into a new `Napi::Buffer` object. When the [external buffer][] is not supported, allocates a new `Napi::Buffer` object and copies the provided external data into it and the `finalizeCallback` is invoked immediately. The `Napi::Buffer` object does not assume ownership for the data and expects it to be valid for the lifetime of the object. The data can only be freed once the `finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released. ```cpp template static Napi::Buffer Napi::Buffer::NewOrCopy(napi_env env, T* data, size_t length, Finalizer finalizeCallback); ``` - `[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 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. ### NewOrCopy Wraps the provided external data into a new `Napi::Buffer` object. When the [external buffer][] is not supported, allocates a new `Napi::Buffer` object and copies the provided external data into it and the `finalizeCallback` is invoked immediately. The `Napi::Buffer` object does not assume ownership for the data and expects it to be valid for the lifetime of the object. The data can only be freed once the `finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released. ```cpp template static Napi::Buffer Napi::Buffer::NewOrCopy(napi_env env, T* data, size_t length, Finalizer finalizeCallback, Hint* finalizeHint); ``` - `[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 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. ### Copy Allocates a new `Napi::Buffer` object and copies the provided external data into it. ```cpp static Napi::Buffer Napi::Buffer::Copy(napi_env env, const T* data, size_t length); ``` - `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] data`: The pointer to the external data to copy. - `[in] length`: The number of `T` elements in the external data. Returns a new `Napi::Buffer` object containing a copy of the data. ### Constructor Initializes an empty instance of the `Napi::Buffer` class. ```cpp Napi::Buffer::Buffer(); ``` ### Constructor Initializes the `Napi::Buffer` object using an existing Uint8Array. ```cpp Napi::Buffer::Buffer(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] value`: The Uint8Array reference to wrap. ### Data ```cpp T* Napi::Buffer::Data() const; ``` Returns a pointer the external data. ### Length ```cpp size_t Napi::Buffer::Length() const; ``` Returns the number of `T` elements in the external data. [`Napi::Uint8Array`]: ./typed_array_of.md [External Buffer]: ./external_buffer.md [Finalization]: ./finalization.md node-addon-api-8.3.1/doc/callback_scope.md000066400000000000000000000024701475612273100203310ustar00rootroot00000000000000# CallbackScope There are cases (for example, resolving promises) where it is necessary to have the equivalent of the scope associated with a callback in place when making certain Node-API calls. ## Methods ### Constructor Creates a new callback scope on the stack. ```cpp Napi::CallbackScope::CallbackScope(napi_env env, napi_callback_scope scope); ``` - `[in] env`: The environment in which to create the `Napi::CallbackScope`. - `[in] scope`: The pre-existing `napi_callback_scope` or `Napi::CallbackScope`. ### Constructor Creates a new callback scope on the stack. ```cpp Napi::CallbackScope::CallbackScope(napi_env env, napi_async_context context); ``` - `[in] env`: The environment in which to create the `Napi::CallbackScope`. - `[in] async_context`: The pre-existing `napi_async_context` or `Napi::AsyncContext`. ### Destructor Deletes the instance of `Napi::CallbackScope` object. ```cpp virtual Napi::CallbackScope::~CallbackScope(); ``` ### Env ```cpp Napi::Env Napi::CallbackScope::Env() const; ``` Returns the `Napi::Env` associated with the `Napi::CallbackScope`. ## Operator ```cpp Napi::CallbackScope::operator napi_callback_scope() const; ``` Returns the Node-API `napi_callback_scope` wrapped by the `Napi::CallbackScope` object. This can be used to mix usage of the C Node-API and node-addon-api. node-addon-api-8.3.1/doc/callbackinfo.md000066400000000000000000000047631475612273100200230ustar00rootroot00000000000000# CallbackInfo The object representing the components of the JavaScript request being made. The `Napi::CallbackInfo` object is usually created and passed by the Node.js runtime or node-addon-api infrastructure. The `Napi::CallbackInfo` object contains the arguments passed by the caller. The number of arguments is returned by the `Length` method. Each individual argument can be accessed using the `operator[]` method. The `SetData` and `Data` methods are used to set and retrieve the data pointer contained in the `Napi::CallbackInfo` object. ## Methods ### Constructor ```cpp Napi::CallbackInfo::CallbackInfo(napi_env env, napi_callback_info info); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::CallbackInfo` object. - `[in] info`: The `napi_callback_info` data structure from which to construct the `Napi::CallbackInfo` object. ### Env ```cpp Napi::Env Napi::CallbackInfo::Env() const; ``` Returns the `Env` object in which the request is being made. ### NewTarget ```cpp Napi::Value Napi::CallbackInfo::NewTarget() const; ``` Returns the `new.target` value of the constructor call. If the function that was invoked (and for which the `Napi::NCallbackInfo` was passed) is not a constructor call, a call to `IsEmpty()` on the returned value returns true. ### IsConstructCall ```cpp bool Napi::CallbackInfo::IsConstructCall() const; ``` Returns a `bool` indicating if the function that was invoked (and for which the `Napi::CallbackInfo` was passed) is a constructor call. ### Length ```cpp size_t Napi::CallbackInfo::Length() const; ``` Returns the number of arguments passed in the `Napi::CallbackInfo` object. ### operator [] ```cpp const Napi::Value operator [](size_t index) const; ``` - `[in] index`: The zero-based index of the requested argument. Returns a `Napi::Value` object containing the requested argument. ### This ```cpp Napi::Value Napi::CallbackInfo::This() const; ``` Returns the JavaScript `this` value for the call ### Data ```cpp void* Napi::CallbackInfo::Data() const; ``` Returns the data pointer for the callback. ### SetData ```cpp void Napi::CallbackInfo::SetData(void* data); ``` - `[in] data`: The new data pointer to associate with this `Napi::CallbackInfo` object. Returns `void`. ### Not documented here ```cpp Napi::CallbackInfo::~CallbackInfo(); // Disallow copying to prevent multiple free of _dynamicArgs Napi::CallbackInfo::CallbackInfo(CallbackInfo const &) = delete; void Napi::CallbackInfo::operator=(CallbackInfo const &) = delete; ``` node-addon-api-8.3.1/doc/checker-tool.md000066400000000000000000000020031475612273100177530ustar00rootroot00000000000000# Checker Tool **node-addon-api** provides a [checker tool][] that will inspect a given directory tree, identifying all Node.js native addons therein, and further indicating for each addon whether it is an Node-API addon. ## To use the checker tool: 1. Install the application with `npm install`. 2. If the application does not depend on **node-addon-api**, copy the checker tool into the application's directory. 3. If the application does not depend on **node-addon-api**, run the checker tool from the application's directory: ```sh node ./check-napi.js ``` Otherwise, the checker tool can be run from the application's `node_modules/` subdirectory: ```sh node ./node_modules/node-addon-api/tools/check-napi.js ``` The tool accepts the root directory from which to start checking for Node.js native addons as a single optional command line parameter. If omitted it will start checking from the current directory (`.`). [checker tool]: ../tools/check-napi.js node-addon-api-8.3.1/doc/class_property_descriptor.md000066400000000000000000000070151475612273100227130ustar00rootroot00000000000000# Class property and descriptor Property descriptor for use with `Napi::ObjectWrap` and `Napi::InstanceWrap`. This is different from the standalone `Napi::PropertyDescriptor` because it is specific to each `Napi::ObjectWrap` and `Napi::InstanceWrap` subclasses. This prevents using descriptors from a different class when defining a new class (preventing the callbacks from having incorrect `this` pointers). `Napi::ClassPropertyDescriptor` is a helper class created with `Napi::ObjectWrap` and `Napi::InstanceWrap`. For more reference about it see: - [InstanceWrap](./instance_wrap.md) - [ObjectWrap](./object_wrap.md) ## Example ```cpp #include class Example : public Napi::ObjectWrap { public: static Napi::Object Init(Napi::Env env, Napi::Object exports); Example(const Napi::CallbackInfo &info); private: double _value; Napi::Value GetValue(const Napi::CallbackInfo &info); void SetValue(const Napi::CallbackInfo &info, const Napi::Value &value); }; Napi::Object Example::Init(Napi::Env env, Napi::Object exports) { Napi::Function func = DefineClass(env, "Example", { // Register a class instance accessor with getter and setter functions. InstanceAccessor<&Example::GetValue, &Example::SetValue>("value"), // We can also register a readonly accessor by omitting the setter. InstanceAccessor<&Example::GetValue>("readOnlyProp") }); Napi::FunctionReference *constructor = new Napi::FunctionReference(); *constructor = Napi::Persistent(func); env.SetInstanceData(constructor); exports.Set("Example", func); return exports; } Example::Example(const Napi::CallbackInfo &info) : Napi::ObjectWrap(info) { Napi::Env env = info.Env(); // ... Napi::Number value = info[0].As(); this->_value = value.DoubleValue(); } Napi::Value Example::GetValue(const Napi::CallbackInfo &info) { Napi::Env env = info.Env(); return Napi::Number::New(env, this->_value); } void Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) { Napi::Env env = info.Env(); // ... Napi::Number arg = value.As(); this->_value = arg.DoubleValue(); } // Initialize native add-on Napi::Object Init (Napi::Env env, Napi::Object exports) { Example::Init(env, exports); return exports; } // Register and initialize native add-on NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) ``` The above code can be used from JavaScript as follows: ```js 'use strict'; const { Example } = require('bindings')('addon'); const example = new Example(11); console.log(example.value); // It prints 11 example.value = 19; console.log(example.value); // It prints 19 example.readOnlyProp = 500; console.log(example.readOnlyProp); // Unchanged. It prints 19 ``` ## Methods ### Constructor Creates new instance of `Napi::ClassPropertyDescriptor` descriptor object. ```cpp Napi::ClassPropertyDescriptor(napi_property_descriptor desc) : _desc(desc) {} ``` - `[in] desc`: The `napi_property_descriptor` Returns new instance of `Napi::ClassPropertyDescriptor` that is used as property descriptor inside the `Napi::ObjectWrap` class. ### Operator ```cpp operator napi_property_descriptor&() { return _desc; } ``` Returns the original Node-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor` ```cpp operator const napi_property_descriptor&() const { return _desc; } ``` Returns the original Node-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor` node-addon-api-8.3.1/doc/cmake-js.md000066400000000000000000000070161475612273100170770ustar00rootroot00000000000000# CMake.js [**CMake.js**](https://github.com/cmake-js/cmake-js) is a build tool that allow native addon developers to compile their C or C++ code into executable form. It works like **[node-gyp](node-gyp.md)** but instead of Google's [**gyp**](https://gyp.gsrc.io) tool it is based on the [**CMake**](https://cmake.org) build system. ## Quick Start ### Install CMake CMake.js requires that CMake be installed. Installers for a variety of platforms can be found on the [CMake website](https://cmake.org). ### Install CMake.js For developers, CMake.js is typically installed as a global package: ```bash npm install -g cmake-js cmake-js --help ``` > For *users* of your native addon, CMake.js should be configured as a dependency in your `package.json` as described in the [CMake.js documentation](https://github.com/cmake-js/cmake-js). ### CMakeLists.txt Your project will require a `CMakeLists.txt` file. The [CMake.js README file](https://github.com/cmake-js/cmake-js#usage) shows what's necessary. ### NAPI_VERSION When building Node-API addons, it's crucial to specify the Node-API version your code is designed to work with. With CMake.js, this information is specified in the `CMakeLists.txt` file: ``` add_definitions(-DNAPI_VERSION=3) ``` Since Node-API is ABI-stable, your Node-API addon will work, without recompilation, with the Node-API version you specify in `NAPI_VERSION` and all subsequent Node-API versions. In the absence of a need for features available only in a specific Node-API version, version 3 is a good choice as it is the version of Node-API that was active when Node-API left experimental status. ### NAPI_EXPERIMENTAL The following line in the `CMakeLists.txt` file will enable Node-API experimental features if your code requires them: ``` add_definitions(-DNAPI_EXPERIMENTAL) ``` ### Exception Handling To enable C++ exception handling (for more info see: [Setup](setup.md)), define the corresponding preprocessor directives depending on which exception handling behavior is desired. To enable C++ exception handling with `Napi::Error` objects only: ``` add_definitions(-DNODE_ADDON_API_CPP_EXCEPTIONS) ``` To enable C++ exception handling for all exceptions thrown: ``` add_definitions(-DNODE_ADDON_API_CPP_EXCEPTIONS) add_definitions(-DNODE_ADDON_API_CPP_EXCEPTIONS_ALL) ``` ### node-addon-api If your Node-API native add-on uses the optional [**node-addon-api**](https://github.com/nodejs/node-addon-api#node-addon-api-module) C++ wrapper, the `CMakeLists.txt` file requires additional configuration information as described on the [CMake.js README file](https://github.com/cmake-js/cmake-js#node-api-and-node-addon-api). ## Example A working example of an Node-API native addon built using CMake.js can be found on the [node-addon-examples repository](https://github.com/nodejs/node-addon-examples/tree/main/src/8-tooling/build_with_cmake#building-node-api-addons-using-cmakejs). ## **CMake** Reference - [Installation](https://github.com/cmake-js/cmake-js#installation) - [How to use](https://github.com/cmake-js/cmake-js#usage) - [Using Node-API and node-addon-api](https://github.com/cmake-js/cmake-js#n-api-and-node-addon-api) - [Tutorials](https://github.com/cmake-js/cmake-js#tutorials) - [Use case in the works - ArrayFire.js](https://github.com/cmake-js/cmake-js#use-case-in-the-works---arrayfirejs) Sometimes finding the right settings is not easy so to accomplish at most complicated task please refer to: - [CMake documentation](https://cmake.org/) - [CMake.js wiki](https://github.com/cmake-js/cmake-js/wiki) node-addon-api-8.3.1/doc/contributing/000077500000000000000000000000001475612273100175665ustar00rootroot00000000000000node-addon-api-8.3.1/doc/contributing/creating_a_release.md000066400000000000000000000071461475612273100237140ustar00rootroot00000000000000# Creating a release Only collaborators in npm for **node-addon-api** can create releases. If you want to be able to do releases ask one of the existing 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. 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: * [Changelog maker](https://www.npmjs.com/package/changelog-maker) If not please follow the instruction reported in the tool's documentation to install it. ### Steps These are the steps to follow to create a new release: * Open an issue in the **node-addon-api** repo documenting the intent to create a new release. Give people some time to comment or suggest PRs that should land first. * Validate all tests pass by running `npm test` on the `main` branch. * Update the version in **package.json** appropriately. * Update the [README.md](https://github.com/nodejs/node-addon-api/blob/main/README.md) to show the new version as the latest. * Generate the changelog for the new version using **changelog maker** tool. From the route folder of the repo launch the following command: ```bash > 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 * 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 Windows in the testing). * Do a clean checkout of node-addon-api. * Login and then run `npm publish`. * Create a release in Github (look at existing releases for an example). * Validate that you can run `npm install node-addon-api` successfully and that the correct version is installed. * Comment on the issue opened in the first step that the release has been created and close the issue. * Tweet that the release has been created. ## Optional Steps Depending on circumstances for the release, additional steps may be required to support the release process. ### Major Releases to Drop Support Node.js Versions `node-addon-api` provides support for Node.js versions following the same [release schedule](https://nodejs.dev/en/about/releases/): once a Node.js version leaves maintenance mode, the next major version of `node-addon-api` published will drop support for that version. These are the steps to follow to drop support for a Node.js version: * Update minimum version supported in documentation ([README.md](../README.md)) * Remove from GitHub actions ([ci.yml](../.github/workflows/ci.yml) and [ci-win.yml](../.github/workflows/ci-win.yml)) * Remove from Jenkins CI ([node-test-node-addon-api-LTS versions [Jenkins]](https://ci.nodejs.org/view/x%20-%20Abi%20stable%20module%20API/job/node-test-node-addon-api-LTS%20versions/)) node-addon-api-8.3.1/doc/conversion-tool.md000066400000000000000000000012031475612273100205350ustar00rootroot00000000000000# Conversion Tool To make the migration to **node-addon-api** easier, we have provided a script to help complete some tasks. ## To use the conversion script: 1. Go to your module directory ``` cd [module_path] ``` 2. Install node-addon-api module ``` npm install node-addon-api ``` 3. Run node-addon-api conversion script ``` node ./node_modules/node-addon-api/tools/conversion.js ./ ``` 4. While this script makes conversion easier, it still cannot fully convert the module. The next step is to try to build the module and complete the remaining conversions necessary to allow it to compile and pass all of the module's tests.node-addon-api-8.3.1/doc/dataview.md000066400000000000000000000151271475612273100172130ustar00rootroot00000000000000# DataView Class `Napi::DataView` inherits from class [`Napi::Object`][]. The `Napi::DataView` class corresponds to the [JavaScript `DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) class. ## Methods ### New Allocates a new `Napi::DataView` instance with a given `Napi::ArrayBuffer`. ```cpp static Napi::DataView Napi::DataView::New(napi_env env, Napi::ArrayBuffer arrayBuffer); ``` - `[in] env`: The environment in which to create the `Napi::DataView` instance. - `[in] arrayBuffer` : `Napi::ArrayBuffer` underlying the `Napi::DataView`. Returns a new `Napi::DataView` instance. ### New Allocates a new `Napi::DataView` instance with a given `Napi::ArrayBuffer`. ```cpp static Napi::DataView Napi::DataView::New(napi_env env, Napi::ArrayBuffer arrayBuffer, size_t byteOffset); ``` - `[in] env`: The environment in which to create the `Napi::DataView` instance. - `[in] arrayBuffer` : `Napi::ArrayBuffer` underlying the `Napi::DataView`. - `[in] byteOffset` : The byte offset within the `Napi::ArrayBuffer` 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::ArrayBuffer`. ```cpp static Napi::DataView Napi::DataView::New(napi_env env, Napi::ArrayBuffer arrayBuffer, size_t byteOffset, size_t byteLength); ``` - `[in] env`: The environment in which to create the `Napi::DataView` instance. - `[in] arrayBuffer` : `Napi::ArrayBuffer` underlying the `Napi::DataView`. - `[in] byteOffset` : The byte offset within the `Napi::ArrayBuffer` 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. ```cpp Napi::DataView(); ``` ### Constructor Initializes a wrapper instance of an existing `Napi::DataView` instance. ```cpp Napi::DataView(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to create the `Napi::DataView` instance. - `[in] value`: The `Napi::DataView` reference to wrap. ### ArrayBuffer ```cpp Napi::ArrayBuffer Napi::DataView::ArrayBuffer() const; ``` Returns the backing array buffer. ### ByteOffset ```cpp size_t Napi::DataView::ByteOffset() const; ``` Returns the offset into the `Napi::DataView` where the array starts, in bytes. ### ByteLength ```cpp size_t Napi::DataView::ByteLength() const; ``` Returns the length of the array, in bytes. ### GetFloat32 ```cpp float Napi::DataView::GetFloat32(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. Returns a signed 32-bit float (float) at the specified byte offset from the start of the `Napi::DataView`. ### GetFloat64 ```cpp double Napi::DataView::GetFloat64(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. Returns a signed 64-bit float (double) at the specified byte offset from the start of the `Napi::DataView`. ### GetInt8 ```cpp int8_t Napi::DataView::GetInt8(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. Returns a signed 8-bit integer (byte) at the specified byte offset from the start of the `Napi::DataView`. ### GetInt16 ```cpp int16_t Napi::DataView::GetInt16(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. Returns a signed 16-bit integer (short) at the specified byte offset from the start of the `Napi::DataView`. ### GetInt32 ```cpp int32_t Napi::DataView::GetInt32(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. Returns a signed 32-bit integer (long) at the specified byte offset from the start of the `Napi::DataView`. ### GetUint8 ```cpp uint8_t Napi::DataView::GetUint8(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. Returns a unsigned 8-bit integer (unsigned byte) at the specified byte offset from the start of the `Napi::DataView`. ### GetUint16 ```cpp uint16_t Napi::DataView::GetUint16(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. Returns a unsigned 16-bit integer (unsigned short) at the specified byte offset from the start of the `Napi::DataView`. ### GetUint32 ```cpp uint32_t Napi::DataView::GetUint32(size_t byteOffset) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. Returns a unsigned 32-bit integer (unsigned long) at the specified byte offset from the start of the `Napi::DataView`. ### SetFloat32 ```cpp void Napi::DataView::SetFloat32(size_t byteOffset, float value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. ### SetFloat64 ```cpp void Napi::DataView::SetFloat64(size_t byteOffset, double value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. ### SetInt8 ```cpp void Napi::DataView::SetInt8(size_t byteOffset, int8_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. ### SetInt16 ```cpp void Napi::DataView::SetInt16(size_t byteOffset, int16_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. ### SetInt32 ```cpp void Napi::DataView::SetInt32(size_t byteOffset, int32_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. ### SetUint8 ```cpp void Napi::DataView::SetUint8(size_t byteOffset, uint8_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. ### SetUint16 ```cpp void Napi::DataView::SetUint16(size_t byteOffset, uint16_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. ### SetUint32 ```cpp void Napi::DataView::SetUint32(size_t byteOffset, uint32_t value) const; ``` - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. [`Napi::Object`]: ./object.md node-addon-api-8.3.1/doc/date.md000066400000000000000000000030551475612273100163210ustar00rootroot00000000000000# Date `Napi::Date` class is a representation of the JavaScript `Date` object. The `Napi::Date` class inherits its behavior from the `Napi::Value` class (for more info see [`Napi::Value`](value.md)). ## Methods ### Constructor Creates a new _empty_ instance of a `Napi::Date` object. ```cpp Napi::Date::Date(); ``` Creates a new _non-empty_ instance of a `Napi::Date` object. ```cpp Napi::Date::Date(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to construct the `Napi::Date` object. - `[in] value`: The `napi_value` which is a handle for a JavaScript `Date`. ### New Creates a new instance of a `Napi::Date` object. ```cpp static Napi::Date Napi::Date::New(Napi::Env env, double value); ``` - `[in] env`: The environment in which to construct the `Napi::Date` object. - `[in] value`: The time value the JavaScript `Date` will contain represented as the number of milliseconds since 1 January 1970 00:00:00 UTC. Returns a new instance of `Napi::Date` object. ### ValueOf ```cpp double Napi::Date::ValueOf() const; ``` Returns the time value as `double` primitive represented as the number of milliseconds since 1 January 1970 00:00:00 UTC. ## Operators ### operator double Converts a `Napi::Date` value to a `double` primitive. ```cpp Napi::Date::operator double() const; ``` ### Example The following shows an example of casting a `Napi::Date` value to a `double` primitive. ```cpp double operatorVal = Napi::Date::New(Env(), 0); // Napi::Date to double // or auto instanceVal = info[0].As().ValueOf(); ``` node-addon-api-8.3.1/doc/env.md000066400000000000000000000036421475612273100161760ustar00rootroot00000000000000# Env Class `Napi::Env` inherits from class [`Napi::BasicEnv`][]. 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 ### Constructor ```cpp Napi::Env::Env(napi_env env); ``` - `[in] env`: The `napi_env` environment from which to construct the `Napi::Env` object. ### napi_env ```cpp operator napi_env() const; ``` Returns the `napi_env` opaque data structure representing the environment. ### Global ```cpp Napi::Object Napi::Env::Global() const; ``` Returns the `Napi::Object` representing the environment's JavaScript Global Object. ### Undefined ```cpp Napi::Value Napi::Env::Undefined() const; ``` Returns the `Napi::Value` representing the environment's JavaScript Undefined Object. ### Null ```cpp Napi::Value Napi::Env::Null() const; ``` Returns the `Napi::Value` representing the environment's JavaScript Null Object. ### IsExceptionPending ```cpp bool Napi::Env::IsExceptionPending() const; ``` Returns a `bool` indicating if an exception is pending in the environment. ### GetAndClearPendingException ```cpp Napi::Error Napi::Env::GetAndClearPendingException() const; ``` Returns an `Napi::Error` object representing the environment's pending exception, if any. ### RunScript ```cpp Napi::Value Napi::Env::RunScript(____ script) const; ``` - `[in] script`: A string containing JavaScript code to execute. Runs JavaScript code contained in a string and returns its result. The `script` can be any of the following types: - [`Napi::String`](string.md) - `const char *` - `const std::string &` [`Napi::BasicEnv`]: ./basic_env.md [Finalization]: ./finalization.md node-addon-api-8.3.1/doc/error.md000066400000000000000000000063011475612273100165320ustar00rootroot00000000000000# Error Class `Napi::Error` inherits from class [`Napi::ObjectReference`][] and class [`std::exception`][]. The `Napi::Error` class is a representation of the JavaScript `Error` object that is thrown when runtime errors occur. The Error object can also be used as a base object for user-defined exceptions. The `Napi::Error` class is a persistent reference to a JavaScript error object thus inherits its behavior from the `Napi::ObjectReference` class (for more info see: [`Napi::ObjectReference`](object_reference.md)). If C++ exceptions are enabled (for more info see: [Setup](setup.md)), then the `Napi::Error` class extends `std::exception` and enables integrated error-handling for C++ exceptions and JavaScript exceptions. For more details about error handling refer to the section titled [Error handling](error_handling.md). ## Methods ### New Creates empty instance of an `Napi::Error` object for the specified environment. ```cpp Napi::Error::New(Napi::Env env); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. Returns an instance of `Napi::Error` object. ### New Creates instance of an `Napi::Error` object. ```cpp Napi::Error::New(Napi::Env env, const char* message); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. - `[in] message`: Null-terminated string to be used as the message for the `Napi::Error`. Returns instance of an `Napi::Error` object. ### New Creates instance of an `Napi::Error` object ```cpp Napi::Error::New(Napi::Env env, const std::string& message); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. - `[in] message`: Reference string to be used as the message for the `Napi::Error`. Returns instance of an `Napi::Error` object. ### Fatal In case of an unrecoverable error in a native module, a fatal error can be thrown to immediately terminate the process. ```cpp static NAPI_NO_RETURN void Napi::Error::Fatal(const char* location, const char* message); ``` The function call does not return, the process will be terminated. ### Constructor Creates empty instance of an `Napi::Error`. ```cpp Napi::Error::Error(); ``` Returns an instance of `Napi::Error` object. ### Constructor Initializes an `Napi::Error` instance from an existing JavaScript error object. ```cpp Napi::Error::Error(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to construct the error object. - `[in] value`: The `Napi::Error` reference to wrap. Returns instance of an `Napi::Error` object. ### Message ```cpp std::string& Napi::Error::Message() const NAPI_NOEXCEPT; ``` Returns the reference to the string that represent the message of the error. ### ThrowAsJavaScriptException Throw the error as JavaScript exception. ```cpp void Napi::Error::ThrowAsJavaScriptException() const; ``` Throws the error as a JavaScript exception. ### what ```cpp const char* Napi::Error::what() const NAPI_NOEXCEPT override; ``` Returns a pointer to a null-terminated string that is used to identify the exception. This method can be used only if the exception mechanism is enabled. [`Napi::ObjectReference`]: ./object_reference.md [`std::exception`]: https://cplusplus.com/reference/exception/exception/ node-addon-api-8.3.1/doc/error_handling.md000066400000000000000000000247521475612273100204100ustar00rootroot00000000000000# Error handling Error handling represents one of the most important considerations when implementing a Node.js native add-on. When an error occurs in your C++ code you have to handle and dispatch it correctly. **node-addon-api** uses return values and JavaScript exceptions for error handling. You can choose return values or exception handling based on the mechanism that works best for your add-on. The `Napi::Error` is a persistent reference (for more info see: [`Napi::ObjectReference`](object_reference.md)) to a JavaScript error object. Use of this class depends on whether C++ exceptions are enabled at compile time. If C++ exceptions are enabled (for more info see: [Setup](setup.md)), then the `Napi::Error` class extends `std::exception` and enables integrated error-handling for C++ exceptions and JavaScript exceptions. Note, that due to limitations of the Node-API, if one attempts to cast the error object wrapping a primitive inside a C++ addon, the wrapped object will be received instead. (With property `4bda9e7e-4913-4dbc-95de-891cbf66598e-errorVal` containing the primitive value thrown) The following sections explain the approach for each case: - [Handling Errors With C++ Exceptions](#exceptions) - [Handling Errors With Maybe Type and C++ Exceptions Disabled](#noexceptions-maybe) - [Handling Errors Without C++ Exceptions](#noexceptions) In most cases when an error occurs, the addon should do whatever cleanup is possible and then return to JavaScript so that the error can be propagated. In less frequent cases the addon may be able to recover from the error, clear the error and then continue. ## Handling Errors With C++ Exceptions When C++ exceptions are enabled try/catch can be used to catch exceptions thrown from calls to JavaScript and then they can either be handled or rethrown before returning from a native method. If a node-addon-api call fails without executing any JavaScript code (for example due to an invalid argument), then node-addon-api automatically converts and throws the error as a C++ exception of type `Napi::Error`. If a JavaScript function called by C++ code via node-addon-api throws a JavaScript exception, then node-addon-api automatically converts and throws it as a C++ exception of type `Napi::Error` on return from the JavaScript code to the native 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. When C++ exceptions are enabled try/catch can be used to catch exceptions thrown from calls to JavaScript and then they can either be handled or rethrown before returning from a native method. ## Examples with C++ exceptions enabled ### Throwing a C++ exception ```cpp Env env = ... throw Napi::Error::New(env, "Example exception"); // other C++ statements // ... ``` The statements following the throw statement will not be executed. The exception will bubble up as a C++ exception of type `Napi::Error`, until it is either caught while still in C++, or else automatically propagated as a JavaScript exception when returning to JavaScript. ### Propagating a Node-API C++ exception ```cpp Napi::Function jsFunctionThatThrows = someValue.As(); Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); // other C++ statements // ... ``` The C++ statements following the call to the JavaScript function will not be executed. The exception will bubble up as a C++ exception of type `Napi::Error`, until it is either caught while still in C++, or else automatically propagated as a JavaScript exception when returning to JavaScript. ### Handling a Node-API C++ exception ```cpp Napi::Function jsFunctionThatThrows = someValue.As(); Napi::Value result; try { result = jsFunctionThatThrows({ arg1, arg2 }); } catch (const Error& e) { cerr << "Caught JavaScript exception: " + e.what(); } ``` Since the exception was caught here, it will not be propagated as a JavaScript exception. ## Handling Errors With Maybe Type and C++ Exceptions Disabled If C++ exceptions are disabled (for more info see: [Setup](setup.md)), then the `Napi::Error` class does not extend `std::exception`. This means that any calls to node-addon-api functions do not throw a C++ exceptions. Instead, these node-api functions that call into JavaScript are returning with `Maybe` boxed values. In that case, the calling side should convert the `Maybe` boxed values with checks to ensure that the call did succeed and therefore no exception is pending. If the check fails, that is to say, the returning value is _empty_, the calling side should determine what to do with `env.GetAndClearPendingException()` before attempting to call another node-api (for more info see: [Env](env.md)). The conversion from the `Maybe` boxed value to the actual return value is enforced by compilers so that the exceptions must be properly handled before continuing. ## Examples with Maybe Type and C++ exceptions disabled ### Throwing a JS exception ```cpp Napi::Env env = ... Napi::Error::New(env, "Example exception").ThrowAsJavaScriptException(); return; ``` After throwing a JavaScript exception, the code should generally return immediately from the native callback, after performing any necessary cleanup. ### Propagating a Node-API JS exception ```cpp Napi::Env env = ... Napi::Function jsFunctionThatThrows = someValue.As(); Maybe maybeResult = jsFunctionThatThrows({ arg1, arg2 }); Napi::Value result; if (!maybeResult.To(&result)) { // The Maybe is empty, calling into js failed, cleaning up... // It is recommended to return an empty Maybe if the procedure failed. return result; } ``` If `maybeResult.To(&result)` returns false a JavaScript exception is pending. To let the exception propagate, the code should generally return immediately from the native callback, after performing any necessary cleanup. ### Handling a Node-API JS exception ```cpp Napi::Env env = ... Napi::Function jsFunctionThatThrows = someValue.As(); Maybe maybeResult = jsFunctionThatThrows({ arg1, arg2 }); if (maybeResult.IsNothing()) { Napi::Error e = env.GetAndClearPendingException(); cerr << "Caught JavaScript exception: " + e.Message(); } ``` Since the exception was cleared here, it will not be propagated as a JavaScript exception after the native callback returns. ## Handling Errors Without C++ Exceptions If C++ exceptions are disabled (for more info see: [Setup](setup.md)), then the `Napi::Error` class does not extend `std::exception`. This means that any calls to node-addon-api function do not throw a C++ exceptions. Instead, it raises _pending_ JavaScript exceptions and returns an _empty_ `Napi::Value`. The calling code should check `env.IsExceptionPending()` before attempting to use a returned value, and may use methods on the `Napi::Env` class to check for, get, and clear a pending JavaScript exception (for more info see: [Env](env.md)). If the pending exception is not cleared, it will be thrown when the native code returns to JavaScript. ## Examples with C++ exceptions disabled ### Throwing a JS exception ```cpp Napi::Env env = ... Napi::Error::New(env, "Example exception").ThrowAsJavaScriptException(); return; ``` After throwing a JavaScript exception, the code should generally return immediately from the native callback, after performing any necessary cleanup. ### Propagating a Node-API JS exception ```cpp Napi::Env env = ... Napi::Function jsFunctionThatThrows = someValue.As(); Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); if (env.IsExceptionPending()) { Error e = env.GetAndClearPendingException(); return e.Value(); } ``` If env.IsExceptionPending() returns true a JavaScript exception is pending. To let the exception propagate, the code should generally return immediately from the native callback, after performing any necessary cleanup. ### Handling a Node-API JS exception ```cpp Napi::Env env = ... Napi::Function jsFunctionThatThrows = someValue.As(); Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); if (env.IsExceptionPending()) { Napi::Error e = env.GetAndClearPendingException(); cerr << "Caught JavaScript exception: " + e.Message(); } ``` Since the exception was cleared here, it will not be propagated as a JavaScript exception after the native callback returns. ## Calling Node-API directly from a **node-addon-api** addon **node-addon-api** provides macros for throwing errors in response to non-OK `napi_status` results when calling [Node-API](https://nodejs.org/docs/latest/api/n-api.html) functions from within a native addon. These macros are defined differently depending on whether C++ exceptions are enabled or not, but are available for use in either case. ### `NAPI_THROW(e, ...)` This macro accepts a `Napi::Error`, throws it, and returns the value given as the last parameter. If C++ exceptions are enabled (by defining `NAPI_CPP_EXCEPTIONS` during the build), the return value will be ignored. ### `NAPI_THROW_IF_FAILED(env, status, ...)` This macro accepts a `Napi::Env` and a `napi_status`. It constructs an error from the `napi_status`, throws it, and returns the value given as the last parameter. If C++ exceptions are enabled (by defining `NAPI_CPP_EXCEPTIONS` during the build), the return value will be ignored. ### `NAPI_THROW_IF_FAILED_VOID(env, status)` This macro accepts a `Napi::Env` and a `napi_status`. It constructs an error from the `napi_status`, throws it, and returns. ### `NAPI_FATAL_IF_FAILED(status, location, message)` This macro accepts a `napi_status`, a C string indicating the location where the error occurred, and a second C string for the message to display. node-addon-api-8.3.1/doc/escapable_handle_scope.md000066400000000000000000000050361475612273100220300ustar00rootroot00000000000000# EscapableHandleScope The `Napi::EscapableHandleScope` class is used to manage the lifetime of object handles which are created through the use of node-addon-api. These handles keep an object alive in the heap in order to ensure that the objects are not collected by the garbage collector while native code is using them. A handle may be created when any new node-addon-api Value or one of its subclasses is created or returned. The `Napi::EscapableHandleScope` is a special type of `Napi::HandleScope` which allows a single handle to be "promoted" to an outer scope. For more details refer to the section titled [Object lifetime management](object_lifetime_management.md). ## Methods ### Constructor Creates a new escapable handle scope. ```cpp Napi::EscapableHandleScope Napi::EscapableHandleScope::New(Napi::Env env); ``` - `[in] Env`: The environment in which to construct the `Napi::EscapableHandleScope` object. Returns a new `Napi::EscapableHandleScope` ### Constructor Creates a new escapable handle scope. ```cpp Napi::EscapableHandleScope Napi::EscapableHandleScope::New(napi_env env, napi_handle_scope scope); ``` - `[in] env`: `napi_env` in which the scope passed in was created. - `[in] scope`: pre-existing `napi_handle_scope`. Returns a new `Napi::EscapableHandleScope` instance which wraps the `napi_escapable_handle_scope` handle passed in. This can be used to mix usage of the C Node-API and node-addon-api. ```cpp operator Napi::EscapableHandleScope::napi_escapable_handle_scope() const ``` Returns the Node-API `napi_escapable_handle_scope` wrapped by the `Napi::EscapableHandleScope` object. This can be used to mix usage of the C Node-API and node-addon-api by allowing the class to be used be converted to a `napi_escapable_handle_scope`. ### Destructor ```cpp Napi::EscapableHandleScope::~EscapableHandleScope(); ``` Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created in the scope to be collected by the garbage collector. There is no guarantee as to when the garbage collector will do this. ### Escape ```cpp napi::Value Napi::EscapableHandleScope::Escape(napi_value escapee); ``` - `[in] escapee`: `Napi::Value` or `napi_env` to promote to the outer scope Returns `Napi::Value` which can be used in the outer scope. This method can be called at most once on a given `Napi::EscapableHandleScope`. If it is called more than once an exception will be thrown. ### Env ```cpp Napi::Env Napi::EscapableHandleScope::Env() const; ``` Returns the `Napi::Env` associated with the `Napi::EscapableHandleScope`. node-addon-api-8.3.1/doc/external.md000066400000000000000000000056461475612273100172360ustar00rootroot00000000000000# External (template) 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. 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 `Napi::External`. It is up to the addon to ensure an `Napi::External` object holds the correct `T` when retrieving the data via `Napi::External::Data()`. One method to ensure an object is of a specific type is through [type tags](./object.md#TypeTag). ## Methods ### New ```cpp template static Napi::External Napi::External::New(napi_env env, T* data); ``` - `[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. Returns the created `Napi::External` object. ### New ```cpp template static Napi::External Napi::External::New(napi_env env, T* data, Finalizer finalizeCallback); ``` - `[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`: 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. ### New ```cpp template static Napi::External Napi::External::New(napi_env env, T* data, Finalizer finalizeCallback, Hint* finalizeHint); ``` - `[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`: 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. ### Data ```cpp 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 node-addon-api-8.3.1/doc/external_buffer.md000066400000000000000000000016251475612273100205600ustar00rootroot00000000000000# External Buffer **Some runtimes other than Node.js have dropped support for external buffers**. On runtimes other than Node.js, node-api methods may return `napi_no_external_buffers_allowed` to indicate that external buffers are not supported. One such runtime is Electron as described in this issue [electron/issues/35801](https://github.com/electron/electron/issues/35801). In order to maintain broadest compatibility with all runtimes, you may define `NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED` in your addon before includes for the node-api and node-addon-api headers. Doing so will hide the functions that create external buffers. This will ensure a compilation error occurs if you accidentally use one of these methods. In node-addon-api, the `Napi::Buffer::NewOrCopy` provides a convenient way to create an external buffer, or allocate a new buffer and copy the data when the external buffer is not supported. node-addon-api-8.3.1/doc/finalization.md000066400000000000000000000113101475612273100200640ustar00rootroot00000000000000# 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. node-addon-api-8.3.1/doc/function.md000066400000000000000000000312471475612273100172350ustar00rootroot00000000000000# Function The `Napi::Function` class provides a set of methods for creating a function object in native code that can later be called from JavaScript. The created function is not automatically visible from JavaScript. Instead it needs to be part of the add-on's module exports or be returned by one of the module's exported functions. In addition the `Napi::Function` class also provides methods that can be used to call functions that were created in JavaScript and passed to the native add-on. The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info see: [`Napi::Object`](object.md)). > For callbacks that will be called with asynchronous events from a > non-JavaScript thread, please refer to [`Napi::ThreadSafeFunction`][] for more > examples. ## Example ```cpp #include using namespace Napi; Value Fn(const CallbackInfo& info) { Env env = info.Env(); // ... return String::New(env, "Hello World"); } Object Init(Env env, Object exports) { exports.Set(String::New(env, "fn"), Function::New(env)); return exports; } NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) ``` The above code can be used from JavaScript as follows: ```js const addon = require('./addon'); addon.fn(); ``` With the `Napi::Function` class it is possible to call a JavaScript function object from a native add-on with two different methods: `Call` and `MakeCallback`. The API of these two methods is very similar, but they are used in different contexts. The `MakeCallback` method is used to call from native code back into JavaScript after returning from an [asynchronous operation](async_operations.md) and in general in situations which don't have an existing JavaScript function on the stack. The `Call` method is used when there is already a JavaScript function on the stack (for example when running a native method called from JavaScript). ## Type definitions ### Napi::Function::VoidCallback This is the type describing a callback returning `void` that will be invoked from JavaScript. ```cpp using VoidCallback = void (*)(const Napi::CallbackInfo& info); ``` ### Napi::Function::Callback This is the type describing a callback returning a value that will be invoked from JavaScript. ```cpp using Callback = Value (*)(const Napi::CallbackInfo& info); ``` ## Methods ### Constructor Creates a new empty instance of `Napi::Function`. ```cpp Napi::Function::Function(); ``` ### Constructor Creates a new instance of the `Napi::Function` object. ```cpp Napi::Function::Function(napi_env env, napi_value value); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] value`: The `napi_value` which is a handle for a JavaScript function. Returns a non-empty `Napi::Function` instance. ### New Creates an instance of a `Napi::Function` object. ```cpp template static Napi::Function New(napi_env env, const char* utf8name = nullptr, void* data = nullptr); ``` - `[template] cb`: The native function to invoke when the JavaScript function is invoked. - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] utf8name`: Null-terminated string to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. Returns an instance of a `Napi::Function` object. ### New Creates an instance of a `Napi::Function` object. ```cpp template static Napi::Function New(napi_env env, const char* utf8name = nullptr, void* data = nullptr); ``` - `[template] cb`: The native function to invoke when the JavaScript function is invoked. - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] utf8name`: Null-terminated string to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. Returns an instance of a `Napi::Function` object. ### New Creates an instance of a `Napi::Function` object. ```cpp template static Napi::Function New(napi_env env, const std::string& utf8name, void* data = nullptr); ``` - `[template] cb`: The native function to invoke when the JavaScript function is invoked. - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] utf8name`: String to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. Returns an instance of a `Napi::Function` object. ### New Creates an instance of a `Napi::Function` object. ```cpp template static Napi::Function New(napi_env env, const std::string& utf8name, void* data = nullptr); ``` - `[template] cb`: The native function to invoke when the JavaScript function is invoked. - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] utf8name`: String to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. Returns an instance of a `Napi::Function` object. ### New Creates an instance of a `Napi::Function` object. ```cpp template static Napi::Function Napi::Function::New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] cb`: Object that implements `Callable`. - `[in] utf8name`: Null-terminated string to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. Returns an instance of a `Napi::Function` object. ### New ```cpp template static Napi::Function Napi::Function::New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] cb`: Object that implements `Callable`. - `[in] utf8name`: String to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. Returns an instance of a `Napi::Function` object. ### New Creates a new JavaScript value from one that represents the constructor for the object. ```cpp Napi::Object Napi::Function::New(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the constructor function. Returns a new JavaScript object. ### New Creates a new JavaScript value from one that represents the constructor for the object. ```cpp Napi::Object Napi::Function::New(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the constructor function. Returns a new JavaScript object. ### New Creates a new JavaScript value from one that represents the constructor for the object. ```cpp Napi::Object Napi::Function::New(size_t argc, const napi_value* args) const; ``` - `[in] argc`: The number of the arguments passed to the constructor function. - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the constructor function. Returns a new JavaScript object. ### Call Calls a Javascript function from a native add-on. ```cpp Napi::Value Napi::Function::Call(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the function. Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a JavaScript function from a native add-on. ```cpp Napi::Value Napi::Function::Call(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the function. Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a Javascript function from a native add-on. ```cpp Napi::Value Napi::Function::Call(size_t argc, const napi_value* args) const; ``` - `[in] argc`: The number of the arguments passed to the function. - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a Javascript function from a native add-on. ```cpp Napi::Value Napi::Function::Call(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the function. Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a Javascript function from a native add-on. ```cpp Napi::Value Napi::Function::Call(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the function. Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a Javascript function from a native add-on. ```cpp Napi::Value Napi::Function::Call(napi_value recv, size_t argc, const napi_value* args) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] argc`: The number of the arguments passed to the function. - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. Returns a `Napi::Value` representing the JavaScript value returned by the function. ### MakeCallback Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::initializer_list& args, napi_async_context context = nullptr) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the function. - `[in] context`: Context for the async operation that is invoking the callback. This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md). However `nullptr` is also allowed, which indicates the current async context (if any) is to be used for the callback. Returns a `Napi::Value` representing the JavaScript value returned by the function. ### MakeCallback Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::vector& args, napi_async_context context = nullptr) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] args`: List of JavaScript values as `napi_value` representing the arguments of the function. - `[in] context`: Context for the async operation that is invoking the callback. This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md). However `nullptr` is also allowed, which indicates the current async context (if any) is to be used for the callback. Returns a `Napi::Value` representing the JavaScript value returned by the function. ### MakeCallback Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp Napi::Value Napi::Function::MakeCallback(napi_value recv, size_t argc, const napi_value* args, napi_async_context context = nullptr) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] argc`: The number of the arguments passed to the function. - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. - `[in] context`: Context for the async operation that is invoking the callback. This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md). However `nullptr` is also allowed, which indicates the current async context (if any) is to be used for the callback. Returns a `Napi::Value` representing the JavaScript value returned by the function. ## Operator ```cpp Napi::Value Napi::Function::operator ()(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value`. Returns a `Napi::Value` representing the JavaScript value returned by the function. [`Napi::ThreadSafeFunction`]: ./threadsafe_function.md node-addon-api-8.3.1/doc/function_reference.md000066400000000000000000000176171475612273100212600ustar00rootroot00000000000000# FunctionReference `Napi::FunctionReference` is a subclass of [`Napi::Reference`](reference.md), and is equivalent to an instance of `Napi::Reference`. This means that a `Napi::FunctionReference` holds a [`Napi::Function`](function.md), and a count of the number of references to that `Napi::Function`. When the count is greater than 0, a `Napi::FunctionReference` is not eligible for garbage collection. This ensures that the `Function` will remain accessible, even if the original reference to it is no longer available. `Napi::FunctionReference` allows the referenced JavaScript function object to be called from a native add-on with two different methods: `Call` and `MakeCallback`. See the documentation for [`Napi::Function`](function.md) for when `Call` should be used instead of `MakeCallback` and vice-versa. The `Napi::FunctionReference` class inherits its behavior from the `Napi::Reference` class (for more info see: [`Napi::Reference`](reference.md)). ## Methods ### Weak Creates a "weak" reference to the value, in that the initial reference count is set to 0. ```cpp static Napi::FunctionReference Napi::Weak(const Napi::Function& value); ``` - `[in] value`: The value which is to be referenced. Returns the newly created reference. ### Persistent Creates a "persistent" reference to the value, in that the initial reference count is set to 1. ```cpp static Napi::FunctionReference Napi::Persistent(const Napi::Function& value); ``` - `[in] value`: The value which is to be referenced. Returns the newly created reference. ### Constructor Creates a new empty instance of `Napi::FunctionReference`. ```cpp Napi::FunctionReference::FunctionReference(); ``` ### Constructor Creates a new instance of the `Napi::FunctionReference`. ```cpp Napi::FunctionReference::FunctionReference(napi_env env, napi_ref ref); ``` - `[in] env`: The environment in which to construct the `Napi::FunctionReference` object. - `[in] ref`: The Node-API reference to be held by the `Napi::FunctionReference`. Returns a newly created `Napi::FunctionReference` object. ### New Constructs a new instance by calling the constructor held by this reference. ```cpp Napi::Object Napi::FunctionReference::New(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the constructor function. Returns a new JavaScript object. ### New Constructs a new instance by calling the constructor held by this reference. ```cpp Napi::Object Napi::FunctionReference::New(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the constructor function. Returns a new JavaScript object. ### Call Calls a referenced Javascript function from a native add-on. ```cpp Napi::Value Napi::FunctionReference::Call(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the referenced function. Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### Call Calls a referenced JavaScript function from a native add-on. ```cpp Napi::Value Napi::FunctionReference::Call(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the referenced function. Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### Call Calls a referenced JavaScript function from a native add-on. ```cpp Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the referenced function. Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### Call Calls a referenced JavaScript function from a native add-on. ```cpp Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the referenced function. Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### Call Calls a referenced JavaScript function from a native add-on. ```cpp Napi::Value Napi::FunctionReference::Call(napi_value recv, size_t argc, const napi_value* args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. - `[in] argc`: The number of arguments passed to the referenced function. - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the referenced function. Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### MakeCallback Calls a referenced JavaScript function from a native add-on after an asynchronous operation. ```cpp Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::initializer_list& args, napi_async_context = nullptr) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the referenced function. - `[in] context`: Context for the async operation that is invoking the callback. This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md). However `nullptr` is also allowed, which indicates the current async context (if any) is to be used for the callback. Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### MakeCallback Calls a referenced JavaScript function from a native add-on after an asynchronous operation. ```cpp Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::vector& args, napi_async_context context = nullptr) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the referenced function. - `[in] context`: Context for the async operation that is invoking the callback. This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md). However `nullptr` is also allowed, which indicates the current async context (if any) is to be used for the callback. Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### MakeCallback Calls a referenced JavaScript function from a native add-on after an asynchronous operation. ```cpp Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, size_t argc, const napi_value* args, napi_async_context context = nullptr) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. - `[in] argc`: The number of arguments passed to the referenced function. - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the referenced function. - `[in] context`: Context for the async operation that is invoking the callback. This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md). However `nullptr` is also allowed, which indicates the current async context (if any) is to be used for the callback. Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ## Operator ```cpp Napi::Value operator ()(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of reference to JavaScript values as `napi_value` Returns a `Napi::Value` representing the JavaScript value returned by the referenced function. node-addon-api-8.3.1/doc/generator.md000066400000000000000000000011101475612273100173600ustar00rootroot00000000000000# Generator ## What is generator **[generator-napi-module](https://www.npmjs.com/package/generator-napi-module)** is a module to quickly generate a skeleton module using **Node-API**, the new API for Native addons. This module automatically sets up your **gyp file** to use **node-addon-api**, the C++ wrappers for Node-API and generates a wrapper JS module. Optionally, it can even configure the generated project to use **TypeScript** instead. ## **generator-napi-module** reference - [Installation and usage](https://www.npmjs.com/package/generator-napi-module#installation) node-addon-api-8.3.1/doc/handle_scope.md000066400000000000000000000043021475612273100200240ustar00rootroot00000000000000# HandleScope The HandleScope class is used to manage the lifetime of object handles which are created through the use of node-addon-api. These handles keep an object alive in the heap in order to ensure that the objects are not collected while native code is using them. A handle may be created when any new node-addon-api Value or one of its subclasses is created or returned. For more details refer to the section titled [Object lifetime management](object_lifetime_management.md). ## Methods ### Constructor Creates a new handle scope on the stack. ```cpp Napi::HandleScope::HandleScope(Napi::Env env); ``` - `[in] env`: The environment in which to construct the `Napi::HandleScope` object. Returns a new `Napi::HandleScope` ### Constructor Creates a new handle scope on the stack. ```cpp Napi::HandleScope::HandleScope(Napi::Env env, Napi::HandleScope scope); ``` - `[in] env`: `Napi::Env` in which the scope passed in was created. - `[in] scope`: pre-existing `Napi::HandleScope`. Returns a new `Napi::HandleScope` instance which wraps the `napi_handle_scope` handle passed in. This can be used to mix usage of the C Node-API and node-addon-api. ```cpp operator Napi::HandleScope::napi_handle_scope() const ``` Returns the Node-API `napi_handle_scope` wrapped by the `Napi::EscapableHandleScope` object. This can be used to mix usage of the C Node-API and node-addon-api by allowing the class to be used be converted to a `napi_handle_scope`. ### Destructor ```cpp Napi::HandleScope::~HandleScope(); ``` Deletes the `Napi::HandleScope` instance and allows any objects/handles created in the scope to be collected by the garbage collector. There is no guarantee as to when the garbage collector will do this. ### Env ```cpp Napi::Env Napi::HandleScope::Env() const; ``` Returns the `Napi::Env` associated with the `Napi::HandleScope`. ## Example ```cpp for (int i = 0; i < LOOP_MAX; i++) { Napi::HandleScope scope(info.Env()); std::string name = std::string("inner-scope") + std::to_string(i); Napi::Value newValue = Napi::String::New(info.Env(), name.c_str()); // do something with newValue }; ``` For more details refer to the section titled [Object lifetime management](object_lifetime_management.md). node-addon-api-8.3.1/doc/hierarchy.md000066400000000000000000000076441475612273100173720ustar00rootroot00000000000000# Full Class Hierarchy | Class | Parent Class(es) | |---|---| | [`Napi::Addon`][] | [`Napi::InstanceWrap`][] | | [`Napi::Array`][] | [`Napi::Object`][] | | [`Napi::ArrayBuffer`][] | [`Napi::Object`][] | | [`Napi::AsyncContext`][] | | | [`Napi::AsyncProgressQueueWorker`][] | `Napi::AsyncProgressWorkerBase` | | [`Napi::AsyncProgressWorker`][] | `Napi::AsyncProgressWorkerBase` | | [`Napi::AsyncWorker`][] | | | [`Napi::BigInt`][] | [`Napi::Value`][] | | [`Napi::Boolean`][] | [`Napi::Value`][] | | [`Napi::Buffer`][] | [`Napi::Uint8Array`][] | | [`Napi::CallbackInfo`][] | | | [`Napi::CallbackScope`][] | | | [`Napi::ClassPropertyDescriptor`][] | | | [`Napi::DataView`][] | [`Napi::Object`][] | | [`Napi::Date`][] | [`Napi::Value`][] | | [`Napi::Env`][] | | | [`Napi::Error`][] | [`Napi::ObjectReference`][], [`std::exception`][] | | [`Napi::EscapableHandleScope`][] | | | [`Napi::External`][] | [`Napi::TypeTaggable`][] | | [`Napi::Function`][] | [`Napi::Object`][] | | [`Napi::FunctionReference`][] | [`Napi::Reference`][] | | [`Napi::HandleScope`][] | | | [`Napi::InstanceWrap`][] | | | [`Napi::MemoryManagement`][] | | | [`Napi::Name`][] | [`Napi::Value`][] | | [`Napi::Number`][] | [`Napi::Value`][] | | [`Napi::Object`][] | [`Napi::TypeTaggable`][] | | [`Napi::ObjectReference`][] | [`Napi::Reference`][] | | [`Napi::ObjectWrap`][] | [`Napi::InstanceWrap`][], [`Napi::Reference`][] | | [`Napi::Promise`][] | [`Napi::Object`][] | | [`Napi::PropertyDescriptor`][] | | | [`Napi::RangeError`][] | [`Napi::Error`][] | | [`Napi::Reference`] | | | [`Napi::String`][] | [`Napi::Name`][] | | [`Napi::Symbol`][] | [`Napi::Name`][] | | [`Napi::SyntaxError`][] | [`Napi::Error`][] | | [`Napi::ThreadSafeFunction`][] | | | [`Napi::TypeTaggable`][] | [`Napi::Value][] | | [`Napi::TypeError`][] | [`Napi::Error`][] | | [`Napi::TypedArray`][] | [`Napi::Object`][] | | [`Napi::TypedArrayOf`][] | [`Napi::TypedArray`][] | | [`Napi::Value`][] | | | [`Napi::VersionManagement`][] | | [`Napi::Addon`]: ./addon.md [`Napi::Array`]: ./array.md [`Napi::ArrayBuffer`]: ./array_buffer.md [`Napi::AsyncContext`]: ./async_context.md [`Napi::AsyncProgressQueueWorker`]: ./async_worker_variants.md#asyncprogressqueueworker [`Napi::AsyncProgressWorker`]: ./async_worker_variants.md#asyncprogressworker [`Napi::AsyncWorker`]: ./async_worker.md [`Napi::BigInt`]: ./bigint.md [`Napi::Boolean`]: ./boolean.md [`Napi::Buffer`]: ./buffer.md [`Napi::CallbackInfo`]: ./callbackinfo.md [`Napi::CallbackScope`]: ./callback_scope.md [`Napi::ClassPropertyDescriptor`]: ./class_property_descriptor.md [`Napi::DataView`]: ./dataview.md [`Napi::Date`]: ./date.md [`Napi::Env`]: ./env.md [`Napi::Error`]: ./error.md [`Napi::EscapableHandleScope`]: ./escapable_handle_scope.md [`Napi::External`]: ./external.md [`Napi::Function`]: ./function.md [`Napi::FunctionReference`]: ./function_reference.md [`Napi::HandleScope`]: ./handle_scope.md [`Napi::InstanceWrap`]: ./instance_wrap.md [`Napi::MemoryManagement`]: ./memory_management.md [`Napi::Name`]: ./name.md [`Napi::Number`]: ./number.md [`Napi::Object`]: ./object.md [`Napi::ObjectReference`]: ./object_reference.md [`Napi::ObjectWrap`]: ./object_wrap.md [`Napi::Promise`]: ./promise.md [`Napi::PropertyDescriptor`]: ./property_descriptor.md [`Napi::RangeError`]: ./range_error.md [`Napi::Reference`]: ./reference.md [`Napi::Reference`]: ./reference.md [`Napi::Reference`]: ./reference.md [`Napi::String`]: ./string.md [`Napi::Symbol`]: ./symbol.md [`Napi::SyntaxError`]: ./syntax_error.md [`Napi::ThreadSafeFunction`]: ./threadsafe_function.md [`Napi::TypeError`]: ./type_error.md [`Napi::TypeTaggable`]: ./type_taggable.md [`Napi::TypedArray`]: ./typed_array.md [`Napi::TypedArrayOf`]: ./typed_array_of.md [`Napi::Uint8Array`]: ./typed_array_of.md [`Napi::Value`]: ./value.md [`Napi::VersionManagement`]: ./version_management.md [`std::exception`]: https://cplusplus.com/reference/exception/exception/ node-addon-api-8.3.1/doc/instance_wrap.md000066400000000000000000000355171475612273100202510ustar00rootroot00000000000000# InstanceWrap This class serves as the base class for [`Napi::ObjectWrap`][] and [`Napi::Addon`][]. In the case of [`Napi::Addon`][] it provides the methods for exposing functions to JavaScript on instances of an add-on. As a base class for [`Napi::ObjectWrap`][] it provides the methods for exposing instance methods of JavaScript objects instantiated from the JavaScript class corresponding to the subclass of [`Napi::ObjectWrap`][]. ## Methods ### InstanceMethod Creates a property descriptor that represents a method exposed on JavaScript instances of this class. ```cpp template static Napi::ClassPropertyDescriptor Napi::InstanceWrap::InstanceMethod(const char* utf8name, InstanceVoidMethodCallback method, napi_property_attributes attributes = napi_default, void* data = nullptr); ``` - `[in] utf8name`: Null-terminated string that represents the name of the method provided by instances of the class. - `[in] method`: The native function that represents a method provided by the add-on. - `[in] attributes`: The attributes associated with the property. One or more of `napi_property_attributes`. - `[in] data`: User-provided data passed into the method when it is invoked. Returns a `Napi::ClassPropertyDescriptor` object that represents a method provided by instances of the class. The method must be of the form ```cpp void MethodName(const Napi::CallbackInfo& info); ``` ### InstanceMethod Creates a property descriptor that represents a method exposed on JavaScript instances of this class. ```cpp template static Napi::ClassPropertyDescriptor Napi::InstanceWrap::InstanceMethod(const char* utf8name, InstanceMethodCallback method, napi_property_attributes attributes = napi_default, void* data = nullptr); ``` - `[in] utf8name`: Null-terminated string that represents the name of the method provided by instances of the class. - `[in] method`: The native function that represents a method provided by the add-on. - `[in] attributes`: The attributes associated with the property. One or more of `napi_property_attributes`. - `[in] data`: User-provided data passed into the method when it is invoked. Returns a `Napi::ClassPropertyDescriptor` object that represents a method provided by instances of the class. The method must be of the form ```cpp Napi::Value MethodName(const Napi::CallbackInfo& info); ``` ### InstanceMethod Creates a property descriptor that represents a method exposed on JavaScript instances of this class. ```cpp template static Napi::ClassPropertyDescriptor Napi::InstanceWrap::InstanceMethod(Napi::Symbol name, InstanceVoidMethodCallback method, napi_property_attributes attributes = napi_default, void* data = nullptr); ``` - `[in] name`: JavaScript symbol that represents the name of the method provided by instances of the class. - `[in] method`: The native function that represents a method provided by the add-on. - `[in] attributes`: The attributes associated with the property. One or more of `napi_property_attributes`. - `[in] data`: User-provided data passed into the method when it is invoked. Returns a `Napi::ClassPropertyDescriptor` object that represents a method provided by instances of the class. The method must be of the form ```cpp void MethodName(const Napi::CallbackInfo& info); ``` ### InstanceMethod Creates a property descriptor that represents a method exposed on JavaScript instances of this class. ```cpp template static Napi::ClassPropertyDescriptor Napi::InstanceWrap::InstanceMethod(Napi::Symbol name, InstanceMethodCallback method, napi_property_attributes attributes = napi_default, void* data = nullptr); ``` - `[in] name`: JavaScript symbol that represents the name of the method provided by instances of the class. - `[in] method`: The native function that represents a method provided by the add-on. - `[in] attributes`: The attributes associated with the property. One or more of `napi_property_attributes`. - `[in] data`: User-provided data passed into the method when it is invoked. Returns a `Napi::ClassPropertyDescriptor` object that represents a method provided by instances of the class. The method must be of the form ```cpp Napi::Value MethodName(const Napi::CallbackInfo& info); ``` ### InstanceMethod Creates a property descriptor that represents a method exposed on JavaScript instances of this class. ```cpp