Repository navigation
Implement Node-API runtime functions ☂️ #56
Description
Activity
- added sub-issues
on May 14, 2025 8 remaining items
- added sub-issues
on May 14, 2025 Reference implementations for the Node-API runtime functions (linking to
napi_create_async_workin each case):- Node.js, written in C++, based on v8.
- Deno, written in Rust, based on v8.
- Bun, written in Zig, based on JSC.
- Ace, written in C++, based on an intermediate API implemented by Ark, JerryScript, QuickJS, and V8.
- node-chakracore, written in C++, based on Chakra.
- IoT.js, written in C, based on JerryScript.
Reacted by Kræn HansenWhere in the codebase are these to be implemented?
That's a great question - somewhere in the host package for sure: packages/react-native-node-api-modules/cpp their implementation likely needs to reach in to React Native APIs - perhaps even JSI? 🤔 (If the latter is the case, we might need a weak map to lookup the
jsi::Runtimebased onnapi_envtoo).I imagine we'll be implementing these functions, grouped by their Node-API version levels - we could
- start with Node-API v1 (either in order of ease of implementation or importance)
- figure out what we other (React Native) APIs we'd need access to
- figure out how we'd get to them from a function taking just the
napi_env
Status sweep against
nextAdopting Hermes' first-party Node-API (#372) and implementing
hermes_napi_host(#398) covered most of what this umbrella was tracking: the runtime-specific functions are now provided by Hermes'API/napi, with React Native supplying the pieces Hermes delegates to its embedder — a worker pool behindpost_work/cancel_work, the runtime'sCallInvokerbehindpost_taskand work completions, andfatal_exception. The buffer functions andnapi_fatal_errorremain host implementations inpackages/host/cpp/RuntimeNodeApi.cpp.Closed as completed (28) — each sub-issue has a comment pointing at what implements it:
Area Issues Where it lives Async work #59, #60, #64, #71 hermes_napi_async_work.cpp+post_work/cancel_work(HermesNapiHost.cpp)Async context & callback scopes #57, #58, #69, #74, #76 hermes_napi_async_context.cppThread-safe functions #78, #79, #80, #81, #82, #83, #84 hermes_napi_tsfn.cpp+post_task(HermesNapiHost.cpp)Cleanup hooks #73, #77, #85, #86 hermes_napi.cppBuffers #61, #62, #63, #66, #68 RuntimeNodeApi.cpp(Buffer asUint8Array)Fatal error / exception #65, #75 RuntimeNodeApi.cpp/fatal_exception(HermesNapiHost.cpp)uv event loop #72 hermes_napi.cpp— returnsnapi_generic_failure, no libuv loop by designTest coverage for the new surface:
packages/node-addon-examples/tests/async,.../tests/threadsafe-function(a port of Node'stest_threadsafe_function),.../tests/buffers(a port oftest_buffer), and the Catch2 suite inpackages/host/testsexercising the host contract on plain Linux.Still open (2):
- Implement
napi_get_node_version#67napi_get_node_version— the host shim returnsnapi_generic_failureand shadows Hermes' working implementation in the generated injector. Policy call: drop the shim or keep the failure. Details in the issue. - Implement
napi_module_register#70napi_module_register— Hermes records the module, but our loader never reads it back, so the deprecated registration path still fails to load an addon. Details in the issue.
Two caveats recorded on the closed issues rather than left implicit: Buffer fidelity versus a real
Bufferis still #171 (the host'snapi_is_bufferis also looser than Node's), and tsfnref/unrefare tracked but inert since React Native has no loop lifetime to model (#82, #84).
Generated by Claude Code
- Implement
While the current Node-API engine functions are implemented by Hermes, this issues is tracking the implementation of the remaining runtime specific functions. Each will be tracked as a sub-issue of this "umbrella" issue.