Node-API add-on build

[NickNaso]

Node-API is an ABI stable API independent from Node.js version. The build of a native add-on needs only the headers file for Node-API so it's not necessary download all the headers file for a specific Node.js version. We created the package node-api-headers to help in the process of building a native add-on. The first project that I know that adopted the node-api-headers is CMake.js (v7.0.0-2 beta https://github.com/cmake-js/cmake-js/pull/278)as reported in this issue https://github.com/nodejs/node-api-headers/issues/3. Now I have some consideration about the experimental api that I would like to discuss in the next Node-API meeting (see: https://github.com/nodejs/node-api-headers/issues/3#issuecomment-1147396890)

[Julusian]

I'll reply to https://github.com/nodejs/node-api-headers/issues/3#issuecomment-1147396890 over here, as it feels like a better place to continue discussion

Hi @Julusian, I like to hear your feedback. We created node-api-headers to allow the build of native addon without download all the headers for a specific version of Node.js. This is possible because Node-API is an ABI stable API and it's independent from any Node.js version what matters is the version of Node-API.

Node-API has some experimental API that are not part of any version because they are not considered stable. We removed from the headers the features e / o functions that are under NAPI_EXPERIMENTAL so this means that if a developer set the NAPI_EXPERIMENTAL flag he will obtain a compilation error.

I don't know if this could be a problem, but I want to discuss at the next Node-API meeting nodejs/abi-stable-node#meeting. If you have time and want to join us it will be a pleasure to discuss about this together.

My idea is to use the original Node-API's headers (without removing the experimental feature) and add a new section named EXPERIMENTAL in the symbol.js like reported below:

    EXPERIMENTAL: {
        js_native_api_symbols: [
            // List of symbols in js_native_api.h considered experimental.
        ],
        node_api_symbols: [
          // List of symbols in node_api.h considered experimental.
        ]
    }

At this stage, the experimental apis are not something I have thought about, so I dont have any insight on how I think they should be handled. My main focus has been on wrapping native libraries as npm packages (https://www.npmjs.com/package/@julusian/jpeg-turbo, https://www.npmjs.com/package/node-hid, https://www.npmjs.com/package/freetype2), so I've typically been targetting an older node-api version, and have not considered using anything from experimental.

That said, if someone does want to use experimental with cmake-js v7, I will need to do something to allow them to. But that might be best achieved by letting them use the old flow of downloading a specific version of the nodejs headers and building against that. That flow wont be removed anytime soon, as it is still necessary for non node-api projects.

[KevinEady]

We discussed in the 10 Jun Node API meeting to include the experimental APIs under a new EXPERIMENTAL property like @NickNaso suggested in https://github.com/nodejs/abi-stable-node/issues/438#issuecomment-1147731207 . This property will include all of the previous version's symbols as well, since someone using experimental APIs would only target the most recent Node API version. It doesn't make sense to target a previous version and still use experimental APIs, since those APIs would never be included in the previous version.

[mhdawson]

Since the content of EXPERIMENTAL can change there is not guarrantee that any build made with EXPERIMENTAL will work with the latest version (the APIs can be removed or modified while experimental). I think it's safer to not include them in the separate headers but if we do documentation should make it clear that anything that uses that option make break with any future version.

[NickNaso]

Proposal to sue node-api-headers in node-gyp https://github.com/nodejs/node-gyp/issues/2736