Skip to content

Commit da944a3

Browse files
kraenhansenclaude
kraenhansen
and
claude
committed
doc: update PORTING.md with ported status and experimental API notes
Mark 17 easy js-native-api tests as Ported (test_dataview as Partial due to missing experimental SharedArrayBuffer APIs in node-api-headers). Add "Experimental Node-API Features" section documenting which tests depend on experimental APIs not yet available in node-api-headers, and the approach needed to support them. References #26. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent d712515 commit da944a3

1 file changed

Lines changed: 96 additions & 67 deletions

File tree

‎PORTING.md‎

Lines changed: 96 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -23,87 +23,115 @@ in `js_native_api.h` and is therefore engine-agnostic.
2323
## Difficulty Ratings
2424

2525
Difficulty is assessed on two axes:
26+
2627
- **Size/complexity** — total lines of C/C++ and JS across all source files
2728
- **Runtime-API dependence** — pure `js_native_api.h` is cheapest; Node.js extensions and direct
2829
libuv calls require harness work or Node-only scoping
2930

30-
| Rating | Meaning |
31-
|---|---|
32-
| Easy | Small test, pure `js_native_api.h` or trivial runtime API, straightforward 1:1 port |
33-
| Medium | Moderate size or uses a Node.js extension API that the harness will need to abstract |
34-
| Hard | Large test and/or deep libuv/worker/SEA dependency; may need new harness primitives or Node-only scoping |
31+
| Rating | Meaning |
32+
| ------ | -------------------------------------------------------------------------------------------------------- |
33+
| Easy | Small test, pure `js_native_api.h` or trivial runtime API, straightforward 1:1 port |
34+
| Medium | Moderate size or uses a Node.js extension API that the harness will need to abstract |
35+
| Hard | Large test and/or deep libuv/worker/SEA dependency; may need new harness primitives or Node-only scoping |
3536

3637
## Engine-specific (`js-native-api`)
3738

3839
Tests covering the engine-specific part of Node-API, defined in `js_native_api.h`.
3940

40-
| Directory | Status | Difficulty |
41-
|---|---|---|
42-
| `2_function_arguments` | Ported | — |
43-
| `3_callbacks` | Not ported | Easy |
44-
| `4_object_factory` | Not ported | Easy |
45-
| `5_function_factory` | Not ported | Easy |
46-
| `6_object_wrap` | Not ported | Medium |
47-
| `7_factory_wrap` | Not ported | Easy |
48-
| `8_passing_wrapped` | Not ported | Easy |
49-
| `test_array` | Not ported | Easy |
50-
| `test_bigint` | Not ported | Easy |
51-
| `test_cannot_run_js` | Not ported | Medium |
52-
| `test_constructor` | Not ported | Medium |
53-
| `test_conversions` | Not ported | Medium |
54-
| `test_dataview` | Not ported | Easy |
55-
| `test_date` | Not ported | Easy |
56-
| `test_error` | Not ported | Medium |
57-
| `test_exception` | Not ported | Medium |
58-
| `test_finalizer` | Not ported | Medium |
59-
| `test_function` | Not ported | Medium |
60-
| `test_general` | Not ported | Hard |
61-
| `test_handle_scope` | Not ported | Easy |
62-
| `test_instance_data` | Not ported | Easy |
63-
| `test_new_target` | Not ported | Easy |
64-
| `test_number` | Not ported | Easy |
65-
| `test_object` | Not ported | Hard |
66-
| `test_promise` | Not ported | Easy |
67-
| `test_properties` | Not ported | Easy |
68-
| `test_reference` | Not ported | Medium |
69-
| `test_reference_double_free` | Not ported | Easy |
70-
| `test_sharedarraybuffer` | Not ported | Medium |
71-
| `test_string` | Not ported | Medium |
72-
| `test_symbol` | Not ported | Easy |
73-
| `test_typedarray` | Not ported | Medium |
41+
| Directory | Status | Difficulty |
42+
| ---------------------------- | ---------- | ---------- |
43+
| `2_function_arguments` | Ported | — |
44+
| `3_callbacks` | Ported | Easy |
45+
| `4_object_factory` | Ported | Easy |
46+
| `5_function_factory` | Ported | Easy |
47+
| `6_object_wrap` | Not ported | Medium |
48+
| `7_factory_wrap` | Ported | Easy |
49+
| `8_passing_wrapped` | Ported | Easy |
50+
| `test_array` | Ported | Easy |
51+
| `test_bigint` | Ported | Easy |
52+
| `test_cannot_run_js` | Not ported | Medium |
53+
| `test_constructor` | Not ported | Medium |
54+
| `test_conversions` | Not ported | Medium |
55+
| `test_dataview` | Partial | Easy |
56+
| `test_date` | Ported | Easy |
57+
| `test_error` | Not ported | Medium |
58+
| `test_exception` | Not ported | Medium |
59+
| `test_finalizer` | Not ported | Medium |
60+
| `test_function` | Not ported | Medium |
61+
| `test_general` | Not ported | Hard |
62+
| `test_handle_scope` | Ported | Easy |
63+
| `test_instance_data` | Ported | Easy |
64+
| `test_new_target` | Ported | Easy |
65+
| `test_number` | Ported | Easy |
66+
| `test_object` | Not ported | Hard |
67+
| `test_promise` | Ported | Easy |
68+
| `test_properties` | Ported | Easy |
69+
| `test_reference` | Not ported | Medium |
70+
| `test_reference_double_free` | Ported | Easy |
71+
| `test_sharedarraybuffer` | Not ported | Medium |
72+
| `test_string` | Not ported | Medium |
73+
| `test_symbol` | Ported | Easy |
74+
| `test_typedarray` | Not ported | Medium |
7475

7576
## Runtime-specific (`node-api`)
7677

7778
Tests covering the runtime-specific part of Node-API, defined in `node_api.h`.
7879

79-
| Directory | Status | Difficulty |
80-
|---|---|---|
81-
| `1_hello_world` | Not ported | Easy |
82-
| `test_async` | Not ported | Hard |
83-
| `test_async_cleanup_hook` | Not ported | Hard |
84-
| `test_async_context` | Not ported | Hard |
85-
| `test_buffer` | Not ported | Medium |
86-
| `test_callback_scope` | Not ported | Hard |
87-
| `test_cleanup_hook` | Not ported | Medium |
88-
| `test_env_teardown_gc` | Not ported | Easy |
89-
| `test_exception` | Not ported | Easy |
90-
| `test_fatal` | Not ported | Hard |
91-
| `test_fatal_exception` | Not ported | Easy |
92-
| `test_general` | Not ported | Medium |
93-
| `test_init_order` | Not ported | Medium |
94-
| `test_instance_data` | Not ported | Hard |
95-
| `test_make_callback` | Not ported | Hard |
96-
| `test_make_callback_recurse` | Not ported | Hard |
97-
| `test_null_init` | Not ported | Medium |
98-
| `test_reference_by_node_api_version` | Not ported | Medium |
99-
| `test_sea_addon` | Not ported | Hard |
100-
| `test_threadsafe_function` | Not ported | Hard |
101-
| `test_threadsafe_function_shutdown` | Not ported | Hard |
102-
| `test_uv_loop` | Not ported | Hard |
103-
| `test_uv_threadpool_size` | Not ported | Hard |
104-
| `test_worker_buffer_callback` | Not ported | Hard |
105-
| `test_worker_terminate` | Not ported | Hard |
106-
| `test_worker_terminate_finalization` | Not ported | Hard |
80+
| Directory | Status | Difficulty |
81+
| ------------------------------------ | ---------- | ---------- |
82+
| `1_hello_world` | Not ported | Easy |
83+
| `test_async` | Not ported | Hard |
84+
| `test_async_cleanup_hook` | Not ported | Hard |
85+
| `test_async_context` | Not ported | Hard |
86+
| `test_buffer` | Not ported | Medium |
87+
| `test_callback_scope` | Not ported | Hard |
88+
| `test_cleanup_hook` | Not ported | Medium |
89+
| `test_env_teardown_gc` | Not ported | Easy |
90+
| `test_exception` | Not ported | Easy |
91+
| `test_fatal` | Not ported | Hard |
92+
| `test_fatal_exception` | Not ported | Easy |
93+
| `test_general` | Not ported | Medium |
94+
| `test_init_order` | Not ported | Medium |
95+
| `test_instance_data` | Not ported | Hard |
96+
| `test_make_callback` | Not ported | Hard |
97+
| `test_make_callback_recurse` | Not ported | Hard |
98+
| `test_null_init` | Not ported | Medium |
99+
| `test_reference_by_node_api_version` | Not ported | Medium |
100+
| `test_sea_addon` | Not ported | Hard |
101+
| `test_threadsafe_function` | Not ported | Hard |
102+
| `test_threadsafe_function_shutdown` | Not ported | Hard |
103+
| `test_uv_loop` | Not ported | Hard |
104+
| `test_uv_threadpool_size` | Not ported | Hard |
105+
| `test_worker_buffer_callback` | Not ported | Hard |
106+
| `test_worker_terminate` | Not ported | Hard |
107+
| `test_worker_terminate_finalization` | Not ported | Hard |
108+
109+
## Experimental Node-API Features
110+
111+
Several tests in the upstream Node.js repository use experimental APIs that are guarded behind
112+
`#ifdef NAPI_EXPERIMENTAL` in Node.js's `js_native_api.h`. The `node-api-headers` package (which
113+
the CTS uses for compilation) does not currently include any of these experimental API declarations.
114+
115+
When `NAPI_EXPERIMENTAL` is defined in Node.js, `NAPI_VERSION` is set to
116+
`NAPI_VERSION_EXPERIMENTAL (2147483647)`. The `NAPI_MODULE` macro exports this version, and the
117+
runtime uses it to decide whether to enable experimental behavior for that addon.
118+
119+
| Feature macro | APIs | Used by |
120+
| --------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------- |
121+
| `NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER` | `node_api_is_sharedarraybuffer`, `node_api_create_sharedarraybuffer` | `test_dataview`, `test_sharedarraybuffer` |
122+
| `NODE_API_EXPERIMENTAL_HAS_CREATE_OBJECT_WITH_PROPERTIES` | `node_api_create_object_with_properties` | `test_object` |
123+
| `NODE_API_EXPERIMENTAL_HAS_SET_PROTOTYPE` | `node_api_set_prototype` | `test_general` |
124+
| `NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER` | `node_api_post_finalizer` | `test_general`, `test_finalizer`, `6_object_wrap` |
125+
126+
Tests that depend on these APIs are currently ported without the experimental test cases (marked
127+
as "Partial" in the status column) or not ported at all. To fully support them, the CTS will need:
128+
129+
1. A mechanism for compiling addons with experimental API access (either from updated
130+
`node-api-headers`, CTS-provided forward declarations or copies of headers from the Node.js main repository)
131+
2. A way for implementors to declare which experimental features their runtime supports
132+
3. Conditional test execution that skips experimental assertions on runtimes that don't support them
133+
134+
See [#26](https://github.com/nodejs/node-api-cts/issues/26) for the full design discussion.
107135

108136
## Special Considerations
109137

@@ -144,6 +172,7 @@ The following tests call into libuv directly — `napi_get_uv_event_loop`, `uv_t
144172
- `test_uv_loop`, `test_uv_threadpool_size`
145173

146174
Porting options:
175+
147176
1. **Node-only scope** — mark these tests as Node.js-only and skip on other runtimes.
148177
2. **Harness abstraction** — introduce a minimal platform-agnostic threading/async API in the
149178
harness (e.g., `cts_thread_create`, `cts_async_schedule`) that implementors back with their

0 commit comments

Comments
 (0)