renaming n-api to something more appropriate and descriptive

[jasnell]

N-API is a poorly selected name for the ABI-stable API for native addons. While the intent is for the name to be pronounced "En-Ay-Pee-Eye", it is most often colloquially reduced to "nappy", which -- if you're unfamiliar -- is term often used in English as a derogatory way describing the hair of black people. Aside from that, it's just not actually descriptive of what the API is for.

I'd like to propose "Stable ABI" (or S-ABI for short) as an alternative. (@addaleax has suggested C-API as a viable alternative also... based on the fact that, well, "that's exactly what it is" 🤣... that would work also)

I can open a PR to update all of the references in project but wanted to determine the support. I'd rather not spend a ton of time bike-shedding alternative names.

There's been some adoption of the API in other projects so the old name certainly won't disappear entirely overnight, but renaming it here would be a great step in the right direction.

/cc @addaleax @nodejs/tsc

[jasnell]

Let's make it a vote with emoji. 🎉 = S-ABI 🚀 = C-API 👎🏻 = status quo

[Trott]

@nodejs/n-api

[mhdawson]

Will put on agenda of the N-API team for this Friday.

[mhdawson]

@jasnell, the files in src are node_api.h, node_api_types.h and despite being a bit longer it would likely be less confusing/more consistent to rename doc references to node_api or node-api than using C-API or S-API.

[gabrielschulhof]

@mhdawson we have js_native_api.h for non-Node.js-specific APIs, so we could diverge this further into node_api_* and js_api_*.

[mhdawson]

@gabrielschulhof I'm not quite sure I follow. The discussion is around replacing N-API in all of the docs with something else. I'm suggesting we use NODE-API to replace N-API versus the other suggestions based on the names of the include files.

[gengjiawen]

n-api has been Node.js brand for a long time. Search engine, books, library author used it everywhere. It can have two names, but rename it will cost too much for community.

[mhdawson]

From the discussion in the team meeting,

1. @jasnell were you suggesting that it would change all of the API call names (for example napi_create_buffer) as due to the ABI stability promises we cannot remove the existing symbols, they would have to be duplicated. Adding duplicate symbols could double the code space (if we inline common implementation) or slow things down requiring and additional call for every method. The other complication is that methods that used the new symbols would not run on older Node.js versions. This would mean that the new aliases would all have to be added as part of a new node api version.

2. in terms of naming from the discussion if there is a rename we'd prefer node_api overall, and then for the new method names we would use node_api_xxxx for node specific methods and js_api_xxx for the non-node specific methods. That would also avoid duplicates of the existing include files (src/node_api.h, src/node_api_types.h)

3. The team does share the concern about the issue related breaking existing content, blog posts etc. We will continue the discussion in the next meeting based on your answer to question 1).

[jasnell]

No, not suggesting we rename or duplicate symbols, just do better as we go for ward from here. node_api works good as a name.

[mhdawson]

@jasnell it sounds like what we might be able to do is:

• Make sure that when we talk about the API going forward we use NODE-API instead of N-API, do a careful pass through docs and use that where it won't cause broken links for existing references etc.
• Leave all methods, symbols etc as they are, while the goal of the steps from more consistently referring to the API as NODE-API leading to people thinking node api when they see napi or n-api.

@jasnell would that align with how you were thinking we'd address the concern?

[addaleax]

were you suggesting that it would change all of the API call names (for example napi_create_buffer) as due to the ABI stability promises we cannot remove the existing symbols, they would have to be duplicated. Adding duplicate symbols could double the code space (if we inline common implementation) or slow things down requiring and additional call for every method. The other complication is that methods that used the new symbols would not run on older Node.js versions. This would mean that the new aliases would all have to be added as part of a new node api version.

Fwiw, these are all problems that can be easily solved by using #define.

[mhdawson]

@addaleax using define was something that we discussed, from our understanding it can solve the names in the include files etc. but still leaves the symbols with the original names as what is exported by node. It would be another possibility for "partial" replacement but we wanted to understand what/how far @jasnell was suggesting we go before considering the different partial/full steps.

[jasnell]

@mhdawson ... Yes, that sounds good. Using the #define approach for aliases would be ideal, I think.

[jschlight]

@mhdawson Since the N-API team has decided to move forward with this initiative, does it make sense to create a new issue on https://github.com/nodejs/abi-stable-node and organize our work there instead of continuing this issue? We could just rename #417 and pickup from there.

[mhdawson]

If @jasnell is ok with it I can just move this issue over to the abi-stable-node repo ?