[RRFC] Add package.json support to require a minimum Node.js N-API version

[cjbj]

Motivation ("The Why")

Node.js binary add-ons that depend on the N-API interface are coded to an N-API version. There is no good way to prevent npm installing on an incompatible Node.js version. The package.json engines specification can be seen as a partial solution, but isn't ideal.

Example

npm install mymodule should fail to install into Node.js if the N-API required by mymodule is not supported by the Node.js engine.

How

Desired Behaviour

Add package.json syntax to allow installation of a Node.js add-on only for a given (or greater) N-API ABI version, and to gracefully fail otherwise.

[mhdawson]

As mentioned engines does not really cover the use case as that means the author has to map an Node-API version back to several release lines, it would be much easier if they could just say "must support Node-API version X or higher".

For example if you look at the table here:

https://nodejs.org/dist/latest-v15.x/docs/api/n-api.html#n_api_node_api_version_matrix

Saying that you want Node-API 6 or later means you would need to configure engines for >v10.20.0<V11.x, >v12.17.0< v13.0, >v14.0.0

It would be much easier to be able to say Node-API Version >=6 (also much clearer as well what you intend)

[mhdawson]

process.versions includes the 'napi' field that provides the version of node-api that is supported by the node runtime and could be used for this check.

[arcanis]

Coincidentally, this use case is covered by the following RFC: yarnpkg/berry#2751 (doesn't prevent to also make napi an engine field as short-term solution though).

[cjbj]

@arcanis Thanks for referencing that RFC. I can see (rare?) potential to require a different N-API version for different architectures, but the matrix example makes me wonder if there is a misunderstanding about N-API versioning? Why would 4 need to be specified if 6 is also given? What did I miss?

[arcanis]

@arcanis Thanks for referencing that RFC. I can see (rare?) potential to require a different N-API version for different architectures, but the matrix example makes me wonder if there is a misunderstanding about N-API versioning? Why would 4 need to be specified if 6 is also given? What did I miss?

Because packages may be prebuilt against multiple versions of the napi (so as to support a wider range of Node versions), even if compiled from the same sources.

[cjbj]

@arcanis Adding that kind of 'why' comment to the RFC would be beneficial!

I hope your RFC is accepted - what are your expectations for its acceptance, and any timeline?