@@ -4,6 +4,24 @@ This document tracks the progress of porting tests from Node.js's test suite int
44The source directories are [ ` test/js-native-api ` ] ( https://github.com/nodejs/node/tree/main/test/js-native-api )
55and [ ` 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+
725Difficulty 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
94112Both 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