node-api: include experimental feature flags in add-on version reported at runtime
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 122k
- Forks
- 37.3k
- Avg merge
- 4d 2h
- Merged PRs (30d)
- 283
Description
This only applies to features that change the behaviour of existing APIs.
We currently have two flags for each experimental behaviour-changing API:
- A feature flag indicating that it is available within the
NAPI_EXPERIMENTALportion of the API. - An opt-out flag indicating that, although the add-on chose to use
NAPI_EXPERIMENTALit does not wish to use this particular feature of the experimental bundle.
In order to avoid going down the experimental code path when running an add-on that chose to opt out of an experimental feature, we need to encode that choice in the version reported to the add-on loader.
If NAPI_EXPERIMENTAL is defined, all experimental features are turned on, unless, for any given feature, its opt-out flag is given.
We can include experimental flags in the version number reported at runtime as follows:
| highest 16 bits | lowest 16 bits | |||
| feature 1 | feature 2 | ... | feature 16 | NAPI_VERSION (latest released, i.e. 8, 9, 10, etc.) |
| or | ||||
|---|---|---|---|---|
| NAPI_VERSION_EXPERIMENTAL (2147483647) All experimental features are requested | ||||
This value ends up on napi_env. At runtime we can check against the bits of this value to decide on the code path. We should probably create a family of macros for making decisions based on the feature flags.
At our Node-API meeting we concluded that we should introduce behaviour-changing features extremely sparingly, because, in order to ensure we do not break our users, even those that have opted into NAPI_EXPERIMENTAL, the testing complexity doubles with each feature we introduce.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
No implementation files or tests are named. Start by tracing how the Node-API version reaches napi_env and how experimental features are represented at runtime; done means encoding opt-out choices in the reported version and providing the proposed feature-flag checks without changing released-version behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js
- Domain
- api
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100