Node-API: Fine-grained versioning support based on features

[vmoroz]

Currently Node-API offers a relatively 'coarse-grained' API version support based on version number.
Whenever we want to add or modify functionality we must add a new function.
The new function must be initially be part of experimental version, and then after some time become part of the official version.

What if we need to modify behavior of existing function to fix a bug and existing code depends on the buggy behavior?
What if we want to do broad improvements that may accidently change behavior of several functions?

Currently it is not possible because it changes the ABI contract.
Any broad changes or bug fixes may break ABI contract and thus causing issues for Node-API users.

Many other big systems face similar issues.
For example, the CMake often adds new features and modifies/deprecates old functionality.
C++ evolves as a language and it evolves its standard library.
How are they doing it and keeping their users happy?

These systems use fine-grained feature support in addition to the coarse-grained versions.
What if we implement the same approach in the Node-API?

• Every single bug fix, new function, or changes to existing function must be associated with a Feature ID.
• Developers - users of the Node-API - have a choice to enable or disable any feature per native module.
• We keep the coarse-grained Node-API versioning as before. Each 'coarse-grained' version says which features are 'on' or 'off' by default.
• Some features could be deprecated as time goes, and then can be completely removed in future releases.
• We can back port some features to previous Node-API releases. It can be useful if we need to fix a bug that may affect behavior.
• If a native module targets previous release of Node-API, but wants to use a feature enabled in newer versions, it can check if the feature exists in the current Node-API version and use it if it does. This way the module could evolve by starting using new features while still being compatible with old APIs.

See PR #42463 for how this proposal might work.

[mhdawson]

We have had some recent discussions in the Node-API team meeting on adding an API which would allow you to opt-in to new or modified behavior.

I think

Every single bug fix, new function, or changes to existing function must be associated with a Feature ID.

might be a bit too much, but adding flags you could set through the API to opt-in in specific cases were that made sense might handle most of the specific cases where it needed.

Is an API that accepted a set of flags you could set to opt-in to behavior along the lines of what you had in mind?

[vmoroz]

Having flags per function to tweak its behavior is a great tool too.
But what if there was a bug in implementing those flags?
See the PR #42463 where I propose fixing a wrong flag behavior based on the feature bit.