Skip to content

Commit 1f09aba

Browse files
kraenhansenclaude
andcommitted
doc: clarify napi_ vs node_api_ prefix convention and fix function names
Add an "API Naming Convention" section explaining that the napi_/node_api_ prefix difference is historical (rename from "napi" to "Node API"), not an indicator of Node.js-specificity. What matters is the declaring header: js_native_api.h (engine-agnostic) vs node_api.h (runtime-specific). Also fix two function name errors in the Special Considerations section: - node_api_get_prototype → napi_get_prototype (actual name in source) - napi_is_sharedarraybuffer → node_api_is_sharedarraybuffer (correct prefix) - napi_get_typedarray_info → node_api_create_sharedarraybuffer (wrong function referenced; the real concern is backing-store allocation) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent da7001a commit 1f09aba

File tree

1 file changed

+34
-13
lines changed

1 file changed

+34
-13
lines changed

PORTING.md

Lines changed: 34 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,24 @@ This document tracks the progress of porting tests from Node.js's test suite int
44
The source directories are [`test/js-native-api`](https://github.com/nodejs/node/tree/main/test/js-native-api)
55
and [`test/node-api`](https://github.com/nodejs/node/tree/main/test/node-api) in the Node.js repository.
66

7+
## API Naming Convention
8+
9+
Node-API uses two function prefixes that are sometimes confused:
10+
11+
- **`napi_`** — the original prefix, retained for backwards compatibility
12+
- **`node_api_`** — the newer prefix, adopted after the project was renamed from "napi" to "Node API"
13+
14+
The prefix alone does **not** indicate whether a function is Node.js-specific or runtime-agnostic.
15+
What matters is which header the function is declared in:
16+
17+
- `js_native_api.h` — engine-agnostic APIs, available across all Node-API runtimes
18+
- `node_api.h` — runtime-specific APIs, currently defined by Node.js
19+
20+
For example, `node_api_is_sharedarraybuffer` carries the newer `node_api_` prefix but is declared
21+
in `js_native_api.h` and is therefore engine-agnostic.
22+
23+
## Difficulty Ratings
24+
725
Difficulty is assessed on two axes:
826
- **Size/complexity** — total lines of C/C++ and JS across all source files
927
- **Runtime-API dependence** — pure `js_native_api.h` is cheapest; Node.js extensions and direct
@@ -92,24 +110,27 @@ Tests covering the runtime-specific part of Node-API, defined in `node_api.h`.
92110
### `node_api_post_finalizer` (`6_object_wrap`, `test_finalizer`)
93111

94112
Both tests call `node_api_post_finalizer` to defer JS-touching work out of the GC finalizer and
95-
onto the main thread. This is a Node.js extension not guaranteed to be present on other engines.
96-
The CTS harness will need a platform-agnostic post-finalizer primitive that implementors can map
97-
to their own deferred-callback mechanism, or the tests need to isolate the post-finalizer cases
98-
into a Node-specific subtest.
113+
onto the main thread. The function is declared in `js_native_api.h` but is gated behind
114+
`NAPI_EXPERIMENTAL`, so not all runtimes may implement it yet. The CTS harness will need a
115+
platform-agnostic post-finalizer primitive that implementors can map to their own
116+
deferred-callback mechanism, or the tests need to isolate the post-finalizer cases behind a
117+
runtime capability check.
99118

100-
### `node_api_set_prototype` / `node_api_get_prototype` (`test_general`, js-native-api)
119+
### `node_api_set_prototype` / `napi_get_prototype` (`test_general`, js-native-api)
101120

102-
The general test suite mixes standard `js_native_api.h` assertions with calls to
103-
`node_api_set_prototype` and `node_api_get_prototype`, which are Node.js extensions. These do
104-
not exist on other engines. The CTS port should split the affected test cases into an engine-agnostic
105-
core and a Node-only annex, or guard those cases with a runtime capability check.
121+
The general test suite mixes `js_native_api.h` assertions with calls to `node_api_set_prototype`
122+
(gated behind `NAPI_EXPERIMENTAL`) and `napi_get_prototype` (standard). The experimental function
123+
may not be implemented by all runtimes yet. The CTS port should split the affected test cases into
124+
a stable core and an experimental annex, or guard the `node_api_set_prototype` cases with a
125+
runtime capability check.
106126

107127
### SharedArrayBuffer backing-store creation (`test_sharedarraybuffer`)
108128

109-
While `napi_is_sharedarraybuffer` and `napi_get_typedarray_info` are part of `js_native_api.h`,
110-
the test creates its SharedArrayBuffer via a Node-specific helper. The CTS version will need a
111-
harness-provided factory (something like `create_shared_array_buffer(size)`) that each runtime
112-
can implement using its own path.
129+
`node_api_is_sharedarraybuffer` and `node_api_create_sharedarraybuffer` are both declared in
130+
`js_native_api.h` and are engine-agnostic. However, the test also exercises creating a
131+
SharedArrayBuffer from the C side via `node_api_create_sharedarraybuffer`, which allocates
132+
backing store memory. The CTS version will need a harness-provided factory (something like
133+
`create_shared_array_buffer(size)`) that each runtime can implement using its own path.
113134

114135
### libuv dependency (multiple `node-api` tests)
115136

0 commit comments

Comments
 (0)