doc: add porting plan with difficulty ratings#23
Merged
legendecas merged 3 commits intonodejs:mainfrom Mar 4, 2026
Merged
Conversation
This was referenced Feb 28, 2026
legendecas
reviewed
Mar 2, 2026
PORTING.md
Outdated
| ### `node_api_post_finalizer` (`6_object_wrap`, `test_finalizer`) | ||
|
|
||
| Both tests call `node_api_post_finalizer` to defer JS-touching work out of the GC finalizer and | ||
| onto the main thread. This is a Node.js extension not guaranteed to be present on other engines. |
Member
There was a problem hiding this comment.
GC finalizers are on the main thread too.
This is a new node-api. It is not accurate to say "This is a Node.js extension".
legendecas
reviewed
Mar 2, 2026
PORTING.md
Outdated
| to their own deferred-callback mechanism, or the tests need to isolate the post-finalizer cases | ||
| into a Node-specific subtest. | ||
|
|
||
| ### `node_api_set_prototype` / `node_api_get_prototype` (`test_general`, js-native-api) |
Member
There was a problem hiding this comment.
Only node_api_set_prototype is an API with the new name convention.
Suggested change
| ### `node_api_set_prototype` / `node_api_get_prototype` (`test_general`, js-native-api) | |
| ### `node_api_set_prototype` / `napi_get_prototype` (`test_general`, js-native-api) |
legendecas
reviewed
Mar 2, 2026
PORTING.md
Outdated
| ### SharedArrayBuffer backing-store creation (`test_sharedarraybuffer`) | ||
|
|
||
| While `napi_is_sharedarraybuffer` and `napi_get_typedarray_info` are part of `js_native_api.h`, | ||
| the test creates its SharedArrayBuffer via a Node-specific helper. The CTS version will need a |
Member
There was a problem hiding this comment.
I'm confused by this. What Node-specific helper is used in the tests?
legendecas
reviewed
Mar 2, 2026
| ### libuv dependency (multiple `node-api` tests) | ||
|
|
||
| The following tests call into libuv directly — `napi_get_uv_event_loop`, `uv_thread_t`, | ||
| `uv_mutex_t`, `uv_async_t`, `uv_check_t`, `uv_idle_t`, `uv_queue_work`, and related APIs: |
Member
There was a problem hiding this comment.
I think uv_mutex_t and uv_thread_t can be replaced with std APIs.
Contributor
Author
|
Added a commit that addresses two things: API Naming Convention section — adds an explanation near the top of the document clarifying that the Function name and description corrections — verified all named functions against the actual Node.js source and fixed errors:
|
kraenhansen
force-pushed
the
doc/porting-plan
branch
from
c4ab945 to
1f09aba
Compare
legendecas
reviewed
Mar 3, 2026
Enumerates all 58 test directories from Node.js's test/js-native-api and test/node-api, rates each by porting difficulty (Easy/Medium/Hard), and documents special considerations for tests with deep runtime dependencies (libuv, worker threads, SEA, node_api_post_finalizer, etc.). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
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>
Co-authored-by: Chengzhong Wu <legendecas@gmail.com>
kraenhansen
force-pushed
the
doc/porting-plan
branch
from
4af1b51 to
c5a560d
Compare
legendecas
approved these changes
Mar 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PORTING.mdenumerating all 58 test directories from Node.js'stest/js-native-apiandtest/node-apithat are candidates for porting into the CTSSpecial considerations covered
node_api_post_finalizer— needs a platform-agnostic post-finalizer primitivenode_api_set_prototype/node_api_get_prototype— Node.js-only extensions mixed into the js-native-api general testnode-apitests (event loop access, threads, mutexes)napi_get_node_version— no equivalent in other runtimesNAPI_MODULE+ NULL init🤖 Generated with Claude Code