Node-API

[tmikov]

(post by @shirakaba moved to top level from #1072 (comment))

Node-API

Node-API was originally just an API for building native addons for Node.js, but has since been decoupled from Node.js (despite the name), and now serves as a universal standard for interacting with native code from any JS engine that implements Node-API (which is most of them).

Contrast to JSI

It may seem that JSI fulfils this need already. However, Node-API has a much wider feature scope, providing a broad range of low-level APIs much like the V8 APIs. It's so flexible that NodeGUI uses it to create idiomatic JS bindings to the whole of Qt, for example.

It also has a much better ecosystem story than JSI – today, many packages containing Node-API code are distributed through npm. These packages can be run directly by any runtime that implements Node-API, e.g. Node.js, Deno, or Bun. They're also easy to run headless (unlike most JSI libraries, which are only set up to be run via a React Native app), allowing for rapid development (no need to spin up a Android/iOS simulator).

Unlike JSI with its C++-based API, Node-API has an ABI-stable C API, meaning native modules using Node-API could be safely distributed as precompiled binaries, allowing for faster builds. I understand this could be solved by rewriting the JSI internals in C, of course.

Contrast to WebAssembly

This discussion is a bit of a distraction, so feel free to skip it.

See details

Putting aside the fact that WASM isn't supported in Hermes at present (#395 (comment)), let's compare the two.

There is some overlap in use-cases between Node-API and WebAssembly, but Node-API is infinitely more flexible because it is not sandboxed. While WebAssembly can be used to compile a self-contained library (one that you have all the source code for, and no dependencies beyond the C standard library) for use in JS, it cannot access system libraries like Core Foundation, which is my main interest.

An example of a Node-API module

For the curious, here's what Node-API involves. The full docs are here.

See details

Library developers would commonly write a Node-API module in C or C++, though there are other language bindings to it, too. Here's an example of a basic module written in C++:

#include <napi.h>

using namespace Napi;

Napi::String Method(const Napi::CallbackInfo& info) {
  Napi::Env env = info.Env();
  return Napi::String::New(env, "world");
}

Napi::Object Init(Napi::Env env, Napi::Object exports) {
  exports.Set(Napi::String::New(env, "HelloWorld"),
              Napi::Function::New(env, Method));
  return exports;
}

NODE_API_MODULE(addon, Init)

From userland, it is consumed just like any other Node module:

const { HelloWorld } = require('./build/Release/hello-world-native.node');

HelloWorld();

Concrete use-case

We (the NativeScript TSC) would like to bring NativeScript's ability to access native APIs to other JS engines/runtimes. In particular, we'd like to bring it to Hermes so that React Native could access the whole iOS/Android SDK directly from JS.

For an example of how much time it could save compared to writing a native module, here's what it's like to access the iOS batteryLevel API via JavaScript:

// Original Objective-C API:
float batteryLevel = [[UIDevice currentDevice] batteryLevel];

// Equivalent JavaScript API (in NativeScript):
const batteryLevel = UIDevice.currentDevice.batteryLevel;

No need to open Xcode and make a native module, no need to recompile any native code, and no need to write any bindings (all bindings to the iOS SDK are ready-generated and fully typed).

To make NativeScript embeddable into other JS engines/runtimes, we've been rewriting it using Node-API. It's already successfully working using @vmoroz's fork of Hermes for React Native Windows (that adds Node-API support), so if only Hermes could support Node-API officially – whether in its core or via a plugin – we could bring it to React Native iOS/Android as well.

We hope this could become the last native module ever written 🥹

[tmikov]

@shirakaba thank you for posting this detailed and thoughtful question.

I agree with pretty much everything you said and I think that enabling code written for Node-API to work with Hermes would be beneficial for the ecosystem. I have expressed a similar sentiment in our discussions with @vmoroz.

Can Node-API Be Maintained by Hermes

Really, the core question that must be answered first is whether the Node-API implementation can be be maintained by the Hermes team.

We have discussed that question at length internally and our conclusion is that at this time it wouldn't be practical. We have no expertise in Node-API; more importantly, we have no internal usages of it. It is very difficult to maintain something that you don't use. We wouldn't be able to diagnose problems well, answer questions, etc. At the same time, having to keep Node-API working while changing our internal API would be a continuous burden.

Unfortunately it also looks like neither JSI nor Node-API can be implemented efficiently on top of the other one, to save some work. There need to be separate implementations, existing in parallel, simultaneously accessing the same Hermes runtime using the internal APIs.

Sincere question (since I haven't followed this topic closely): are Node-API implementations for other JavaScript engines maintained by the engines themselves, or by separate organizations?

Are Other Solutions Possible

With all of that said, I am hopeful that we can find a satisfactory solution. I see three separate issues that need to be solved:

1. Maintenance. How hard would it be for a separate entity to maintain Hermes/Node-API in the face of constantly changing Hermes?
2. Coexistence. JSI assumes that it is the only API accessing Hermes. If there is another parallel API, JSI will need to be changed.
3. Distribution. How can a Hermes "plugin" accessing internal APIs (which aren't even exported by the shared library) be distributed?

I believe that the first issue is solved by a change in the Hermes release model that we will be making soon. Hermes will transition to a fixed six month release cadence, where the just released version is frozen and stable. This means that a Node-API implementation doesn't need to track a continuously changing target, but instead one changing at a fixed and predictable times.

We are aware of the second issue and I am hoping that we can change JSI can to support that. @neildhar can you comment on this topic?

The last issue is really the most interesting and challenging, particularly the "symbols not exported by the .so" part. It seems like this would have to be an additional Hermes target, build from the Hermes source + the Node API plugin source. I think we perhaps could add extension points for this in the Hermes build scripts? Any ideas on this issue (and not only, obviously) are welcome.

[tmikov]

@vmoroz I am using https://visualstudio.microsoft.com/vs/community/, literally downloaded it last week on my personal computer (I don't have a work Windows PC 😅 ) . I wonder whether it has the bug. For now I am testing only in debug mode, but it will keep it in mind, thanks!

[vmoroz]

@tmikov , I believe all MSVC compilers in VS version 17.14.x have this bug when they use the /O2 (max speed) optimization.
I tried to disable the auto-vectorization only today with no success. There are a number of tests that were continuing to fail.
Thus, the best I could do today is to enable /O1 (min size) for Release-only since it fails the Debug config: microsoft#231

[vmoroz]

@tmikov , I am getting very close to enable the unit tests for the Node-API PR. The code is rebased on static_h branch.
The tests are running, but I am suddenly having an issue with Node-API class definitions.
All my napi_define_class tests are failing because the NativeConstructor does not create this parameter anymore.
I see that it is "by design" in the latest code because the NativeConstructor is used only for internal classes which create this on their own.

Currently Hermes API (JSI or ABI JSI) does not seem to support creating native classes with finalizers.
But this API is required for Node-API.
In the past I had to extend Hermes code to add FinalizableNativeConstructor.
Later, I dropped that code in favor of NativeConstructor + NativeState.
Now, I am planning to add the FinalizableNativeConstructor back to the code.
(It can be seen in the original PR: microsoft#61)

Any advice?

I see that there are new NativeJSFunction and NativeJSClass, but they seem to serve different purpose: they are native representation of JS code.

[vmoroz]

OK, instead of creating a completely new class FinalizableNativeConstructor, I managed to do just a few small changes to the use of the FinalizableNativeFunction to be able to use it as a constructor.
From the JavaScript point of view it is a much cleaner solution: In JavaScript we can use any custom function as a constructor.
So, I hope this change will be aligned with the expected JS semantics.

I will create a separate PR for this change. So, it will be easier to comment / approve / reject.

[vmoroz]

I just rebased the squashed version of the PR. It has a full set of Node-API tests that are passing.
The code is not 100% complete yet. I still plan to:

• Clean up the code
• Update CMake file to match current static_h style (compile .o files instead of .lib)
• Change tests to work with different JSI implementations

[fbmal7]

@vmoroz I'm worried that this could have unintended consequences, since this could be an observable change in behavior of code that's already using FinalizableNativeFunction. Why did you move away from FinalizableNativeConstructor? What difficulty was there in creating your own this parameter?

[vmoroz]

BTW, as one of the ways to reduce the Hermes changes, I was considering to keep using NativeConstructor where I will pre-create the this object myself before calling user code. I am not sure why this idea did not come to me to start with.
Though, having a true "Finalizable" class would be great to reduce the need to allocated a separate finalizable object as I did it before.

[tmikov]

@vmoroz after @fbmal7 lands his changes, you should use FinalizableNativeConstructor for napi_define_class(). The only detail is that you must ensure that it returns an object if it is invoked as a constructor (if new.target !== undefined) - otherwise the VM will crash.

The functionality of FinalizableNativeConstructor will be as follows:

• When invoked with new it must either return an object or throw an exception. Your code will have to ensure that. This avoids the double allocation problem.
• When invoked normally it works as any other function.
  We will also add a create() method that creates it with a .prototype property.

[vmoroz]

Perfect! Thank you!

[fbmal7]

@vmoroz f027309 has the functionality needed to build this out. Now, FinalizableNativeFunction can be called as a constructor (via new.) When that happens, a this parameter will not be created for it; this should be made and returned by the FinalizableNativeFunction itself. This should allow for maximum flexibility and performance.

[vmoroz]

Thank you, @fbmal7, for the great news! I will start "cooking" the PR update then. :)

[tmikov]

A ton of changes supporting MSVC also landed recently. Not completely done (DLL support is still broken), but the VM, etc, all compile.

[tmikov]

Really looking forward to landing Node-API support!

[vmoroz]

It is great to hear that the new hermes-node with Node-API is coming!
Should I close my Node-API PR as outdated?

[shirakaba]

As exciting as hermes-node is, I think the battle is not over until Node-API is supported in React Native, so I'd prefer Vladimir's PR still be merged!

[vmoroz]

@tmikov , is it worth the effort to have another try to update the Node-API PR since you already have your own implementation?
The change is trivial, but since no one from Meta runs the PR validation I foresee spending quite some time to fix them all again just to hit the wall in the end. It would be nice to know your intent towards the Node-API support.

[vmoroz]

@tmikov , I have updated the Node-API.
There are only a few minimal changes outside of the Node-API code.
The main difference with the code submitted in October is the use of the new FinalizableNativeFunction. Though, I still had to add there missing factory method.