- refactor the n-api matrix and add v7
Signed-off-by: Michael Dawson <mdawson@devrus.com>
PR-URL: https://github.com/nodejs/node/pull/35345
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
This helps catch broken links as part of the test suite. This also
improves the user experience when browsing the markdown files.
PR-URL: https://github.com/nodejs/node/pull/35191
Fixes: https://github.com/nodejs/node/issues/35189
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Not a comprehensive edit. Just a few things I noticed.
* Favor present tense where there's a choice
* Added a comma for clarity
* Added a missing word ("in")
PR-URL: https://github.com/nodejs/node/pull/35361
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Node.js version 14.12.0 released the N-API version 7, but it's not
present on the N-API version matrix. This change should fix the problem
in the documentation.
PR-URL: https://github.com/nodejs/node/pull/35319
Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Mention null termination handling in the string size accounting and
string truncation.
PR-URL: https://github.com/nodejs/node/pull/35322
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <midawson@redhat.com>
The size of arrays is measured in bytes in C, not in the number of
elements. The napi_get_cb_info function takes the length of the
array, that is, the number of elements it can contain, and not its size.
PR-URL: https://github.com/nodejs/node/pull/35300
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
Calling napi_make_callback() with no async_context is not resulting in
using the current async context instead an empty context (id 0) is
used.
Using NULL is like using node::Makecallback without async_context which
is deprecated since Node.js 10 (DEP0099).
PR-URL: https://github.com/nodejs/node/pull/35321
Fixes: https://github.com/nodejs/node/issues/35188
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
* Rearrange sentence to avoid ambiguity whether the entire sentence
applies to a method in a JS class or just the "but not" part
* Use serial comma
* Correct spelling of _configurable_
PR-URL: https://github.com/nodejs/node/pull/35253
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Mark `napi_detach_arraybuffer` and `napi_is_detached_arraybuffer` as
stable.
Signed-off-by: Gabriel Schulhof <gabriel.schulhof@intel.com>
PR-URL: https://github.com/nodejs/node/pull/35199
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Michael Dawson <mdawson@devrus.com>
We've had a few questions about APIs not being available which
were related to not having specified `NAPI_EXPERIMENTAL`.
Add some additional documentation to explain this common
issue:
Refs: https://github.com/nodejs/node-addon-api/issues/810
Signed-off-by: Michael Dawson <mdawson@devrus.com>
PR-URL: https://github.com/nodejs/node/pull/35195
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Update n-api samples to create object properties matching to the JS defaults.
Using non configurable, non writable properties has its usecases but
the JS default for class methods is `configurable` and `writable`.
Js properties set by JS code `obj.prop = val` are `configurable`, `writable`
and `enumerable`.
Add a default value for class method and js like property in enum
napi_property_attributes.
n-api currently offers only one default which is non configurable,
non writable, non enumerable - like Object.defineProperty(). While
this is formal correct the usual way to create properties in JS is
either by defining a class or use obj.prop = value.
The defaults from these variants are now backed into enum values.
PR-URL: https://github.com/nodejs/node/pull/35214
Refs: https://github.com/nodejs/node-addon-api/issues/811
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
The compatibility matrix in the N-API doc needs row headers for
accessibility purposes. Unfortunately, those aren't possible in markdown
without resorting to HTML markup. So this converts the table from
markdown to HTML. This is less convenient for documentation authors and
for other readers of the raw markdown docs, but I believe accessibility
for the viewers of our HTML docs outweighs that concern.
PR-URL: https://github.com/nodejs/node/pull/35146
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Daijiro Wachi <daijiro.wachi@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
Reviewed-By: Zeyu Yang <himself65@outlook.com>
The `2^n` notation is common in mathematics, but even then it often
requires parentheses or braces. In JavaScript and C++, the `^` operator
stands for bitwise xor, and should be avoided in the docs. In code tags,
the JavaScript operator `**` can be used. Otherwise, the `sup` tag can
be used for formatting.
PR-URL: https://github.com/nodejs/node/pull/35050
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Derek Lewis <DerekNonGeneric@inf.is>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
This isn't needed, and was probably copy-pasted from
windows-build-tools' README.md, which has since been changed
to drop the `--production` flag from the install instructions.
PR-URL: https://github.com/nodejs/node/pull/34979
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: Jiawen Geng <technicalcute@gmail.com>
Reviewed-By: Ricky Zhou <0x19951125@gmail.com>
* Avoid passing core `void*` and function pointers into add-on.
* Document `napi_async_cleanup_hook_handle` type.
* Render receipt of the handle mandatory from the point where the
hook gets called. Removal of the handle remains mandatory.
Fixes: https://github.com/nodejs/node/issues/34715
Signed-off-by: Gabriel Schulhof <gabriel.schulhof@intel.com>
Co-authored-by: Anna Henningsen <github@addaleax.net>
PR-URL: https://github.com/nodejs/node/pull/34819
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Zeyu Yang <himself65@outlook.com>
Most of the instances of _node-addon-api_ are surrounded with backticks,
but two aren't. Add backticks for consistency.
PR-URL: https://github.com/nodejs/node/pull/34910
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
PR-URL: https://github.com/nodejs/node/pull/34641
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Sometimes addons need to perform cleanup actions, for example
closing libuv handles or waiting for requests to finish, that
cannot be performed synchronously.
Add C++ API and N-API functions that allow providing such
asynchronous cleanup hooks.
Fixes: https://github.com/nodejs/node/issues/34567
PR-URL: https://github.com/nodejs/node/pull/34572
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
The documentation said `napi_typeof` is similar to the `typeof`
operator, but the `typeof null` detects `'object'` while
`napi_typeof(a_null_value)` detects `napi_null`.
PR-URL: https://github.com/nodejs/node/pull/34577
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: David Carlier <devnexen@gmail.com>
Revise text for clarity, brevity, and conformance with our style guide.
PR-URL: https://github.com/nodejs/node/pull/34566
Reviewed-By: Gus Caplan <me@gus.host>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Richard Lau <riclau@uk.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
`napi_instanceof()` is insufficient for reliably establishing the data
type to which a pointer stored with `napi_wrap()` or
`napi_create_external()` inside a JavaScript object points. Thus, we
need a way to "mark" an object with a value that, when later retrieved,
can unambiguously tell us whether it is safe to cast the pointer stored
inside it to a certain structure.
Such a check must survive loading/unloading/multiple instances of an
addon, so we use UUIDs chosen *a priori*.
Fixes: https://github.com/nodejs/node/issues/28164
Co-authored-by: Anna Henningsen <github@addaleax.net>
PR-URL: https://github.com/nodejs/node/pull/28237
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Signed-off-by: Gabriel Schulhof <gabriel.schulhof@intel.com>
PR-URL: https://github.com/nodejs/node/pull/34158
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Anto Aravinth <anto.aravinth.cse@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Remove text regarding copying, because `napi_create_external_buffer`
does not copy.
Fixes: https://github.com/nodejs/node/issues/33471
PR-URL: https://github.com/nodejs/node/pull/34125
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Mathias Buus <mathiasbuus@gmail.com>
Reviewed-By: Zeyu Yang <himself65@outlook.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
This changes "considered" experimental" to "experimental" in the
n-api.md file and introduces some additional brevity.
PR-URL: https://github.com/nodejs/node/pull/34129
Reviewed-By: Denys Otrishko <shishugi@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Document that it is not necessary to open handle and/or callback scopes
inside finalizer, async work, thread-safe function etc. callbacks
unless for reasons documented in the section about object lifetime
management.
Link usage of callback signatures to their definition.
Fixes: https://github.com/nodejs/node/issues/33893
PR-URL: https://github.com/nodejs/node/pull/33915
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
PR-URL: https://github.com/nodejs/node/pull/33871
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
We mostly have a single space between the punctuation that ends a
sentence and the start of the next sentence. Change instances with two
spaces to one.
PR-URL: https://github.com/nodejs/node/pull/33995
Reviewed-By: Matheus Marchini <mat@mmarchini.me>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Notable changes:
* ECMAScript Modules - `--experimental-modules` flag removal
* AsyncLocalStorage API (experimental)
* REPL previews
* REPL reverse-i-search
* REPL substring-based search
* Error monitoring
* Monitoring `error` events
* Monitoring uncaught exceptions
* File system APIs
* New function: `fs.readv`
* Optional parameters in `fs.read`
* Console `groupIndentation` option
* `maxStringLength` option for `util.inspect()`
* Stable N-API release 6
* Stable diagnostic reports
* Increase of the default server headers timeout
* New `--trace-sigint` CLI flag
* Various crypto APIs now support Diffie-Hellman secrets
* Added support for the `dns.ALL` flag in `dns.lookup()`
* Added a new experimental API to interact with Source Map V3 data
* Added support for passing a `transferList` along with `workerData` to
the `Worker` constructor
PR-URL: https://github.com/nodejs/node/pull/33197
Prior to this commit, C fenced code blocks in Markdown files had
inconsistent info strings. This has been corrected to standardize on
the lowercase variant, which matches the others, is the typical file
extension for C files, and is the CSS class used by highlight.js
despite representing a minority of appearances in the doc/api/ dir.
Stats:
> 'C' => 181,
> 'c' => 3,
Refs: https://github.com/highlightjs/highlight.js/pull/2577
PR-URL: https://github.com/nodejs/node/pull/33507
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
This reverts commit d26ca06c16 because
it breaks running the tests in debug mode, as
`v8::Isolate::GetCurrent()` is not allowed if no `Isolate` is active
on the current thread.
Refs: https://github.com/nodejs/node/pull/33276
Refs: https://github.com/nodejs/node/pull/32860
PR-URL: https://github.com/nodejs/node/pull/33453
Reviewed-By: Daniel Bevenius <daniel.bevenius@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com>
Prior to this commit, C++ fenced code blocks in Markdown files had
inconsistent info strings. This has been corrected to standarize on
the one with the highest frequency in the doc/api/ dir.
Stats:
> 'cpp' => 19,
> 'C++' => 6,
> 'c++' => 3,
PR-URL: https://github.com/nodejs/node/pull/33483
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: David Carlier <devnexen@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
