node-api: clarify enum value ABI stability

[legendecas]

Codify the ABI stability guarantees on Node-API enum types.

In summary, we should distinguish enums used as an in-parameter, and used as a return value or an out-parameter:

• For enum in in-parameters, unknown values are undefined behavior (the Node-API function should return napi_invalid_arg in general practice). New values will be introduced with an NAPI_VERSION guard.
• For enum in return values and out-parameters, addons should handle unknown values.

Unless explicitly documented, an enum type does not work with bit operators.

Refs: #58879

[nodejs-github-bot]

Review requested:

• @nodejs/node-api

[NickNaso]

I left some comments tryong to improve the doc.

[vmoroz]

To me creating such rule today makes it ABI incompatible with the previous code compiled against Node-API.
We never stated such rules and limitations before. Any code that is currently implemented without abiding to these rules may start to fail. Should we rather implement it starting with some specific Node-API version?

E.g. previously we added the new status such as napi_cannot_run_js, but we never return it to the Node-API modules with versions < 10. This new status code is only visible to modules that use newer Node-API versions.

I believe we must carefully discuss such new rule about freely adding new enum values to output and return values. IMHO, it may break the ABI compatibility. E.g. see this StackOverflow discussion.

[vmoroz]

I am concerned about freely adding new output and return enum values. Let's discuss it first.

[legendecas]

E.g. previously we added the new status such as napi_cannot_run_js, but we never return it to the Node-API modules with versions < 10. This new status code is only visible to modules that use newer Node-API versions.

For reference, #45181 added napi_no_external_buffers_allowed and it must be respected in all Node-API versions otherwise the runtime has no choice other than abort.

[vmoroz]

@legendecas , let's discuss it in more details tomorrow in Node-API meeting.
IMHO, the simple Node-API version does not cover the full range of various JavaScript features that can be added with time to V8 or other JS engines. A much better approach would be to go with the C++ language approach where they have a way to probe for various features besides the overall language version.

This way we could add new features to the Node-API while allowing different implementations to say if they are available or not.
E.g. the Float16Arrays are added to V8 starting from a specific V8 version. Node-API version on its own cannot guarantee that Float16Arrays will be available to all users of Node-API version X. It depends on the V8 version. A similar story could be with other JS engines like JSC or Hermes.
A better approach would be to say that Node-API version X supports Float16Arrays, but whether it is available or not depends on the current JS runtime.
This way we can promote new Node-API versions even to the oldest supported Node.js runtimes.
Then, we can even decide if it OK to add new features to the previous Node-API versions.

For reference, #45181 added napi_no_external_buffers_allowed and it must be respected in all Node-API versions otherwise the runtime has no choice other than abort.

I believe that time we had to do something quick to address a serious issue. Due to V8 changes some of Node-API functions simply stopped to work. It would be nice to also think through the scenarios where the underlying JS engine not only adds features, but also removes or disables them. We must keep the ABI stability, but it seems like we do not have the full control over the overall API behavior. It maybe also worth to document it.

[nodejs-github-bot]

Landed in 1d7bea7