Mention emnapi in documentation

[toyobayashi]

Would you mind mentioning emnapi in documentation?

emnapi gives Emscripten users another way to write binding code, and also gives users the ability to port Node.js addons written in Node-API to WebAssembly.

Currently emnapi has a documentation site and has successfully ported most of the official examples in node-addon-examples repository.

I think it is time to let more developers know emnapi. The community can help make it better.

Sorry for my bad English, great appreciate if you approve this.

[sbc100]

Is that - some kind of unicode - ? It looks different to the other ones in this file? Can we stick the to ascii -?

[toyobayashi]

It looks different to the other ones in this file

It was copied from here

emscripten/site/source/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.rst

Lines 769 to 770 in fafcc86

	Binding C++ and JavaScript — WebIDL Binder and Embind
	======================================================

I use Ctrl + F in VSCode, and then find there are many — in this file. I think I should leave them the same.

[sbc100]

I'm not sure it makes sense to list it here. Emnapi is specific set of bindings for node API, right? Not a method of writing new binding?

[toyobayashi]

In my understanding, developers cannot use Node-API to write bindings in emscripten before emnapi exists, in a sense it is a new way to write bindings in emscripten, so it is listed here like embind.

[toyobayashi]

Hi, @sbc100 @kripken

Could you reconsider this PR? With the great help of @RReverser , now emnapi is more and more mature. It is used in lovell/sharp#3522 and TryGhost/node-sqlite3#1674. I have confidence to say now emnapi is the only project which has so complete Node-API implementation for wasm. I believe it is not a toy project and it can make contribution to wasm community.

[sbc100]

Sure, I don't see why we shouldn't mention this in the docs.

I'm not sure the title "Binding C/C++ and JavaScript — Emnapi (Node-API for Emscripten)" makes sense though, at least not to me. This isn't like embind in that sense I don't think. How about "Writing node extensions using emscripten (Node-API)" or "Porting node extensions to emscripten (Node-API)`? Or maybe you can come up with a better one?

[toyobayashi]

If I understand correctly, what embind doing is

void native_function(/* ... */) { /* ... */ }

emscripten::val native_function_binding(/* ... */) {
  // ...
  native_function(/* ... */);
  // ...
}

EMSCRIPTEN_BINDINGS(mod) {
  emscripten::function("nativeFunction", native_function_binding);
}

Then I can use it in JavaScript:

Module.nativeFunction(/* ... */);

---

And what emnapi doing is

void native_function(/* ... */) { /* ... */ }

napi_value native_function_binding(napi_env env, napi_callback_info info) {
  // ...
  native_function(/* ... */);
  // ...
}

#define EXPORT_FUNCTION(env, exports, name, f) \
  do { \
    napi_value f##_fn; \
    napi_create_function((env), NULL, NAPI_AUTO_LENGTH, (f), NULL, &(f##_fn)); \
    napi_set_named_property((env), (exports), (name), (f##_fn)); \
  } while (0)

NAPI_MODULE_INIT() {
  EXPORT_FUNCTION(env, exports, "nativeFunction", native_function_binding);
  return exports;
}

Then I can use it in JavaScript:

const binding = Module.emnapiInit(/* ... */);
binding.nativeFunction(/* ... */);

So what is the difference do you think in binding C/C++ and JavaScript between embind and emnapi? It does give emscripten a new way of writing bindings, at least to me. So I think there is nothing wrong with this title.

Except binding ability, emnapi provide ability of porting Node-API addon to wasm additionally. From this point, "Porting node extensions to emscripten (Node-API)" is also good :)

[toyobayashi]

@sbc100 As I explained above, how about these titles?

• Binding C/C++ and JavaScript - Node-API
• Using Node-API to write binding or port native Node.js addon to Emscripten
• Node-API binding on Emscripten

[sbc100]

I don't really have much insight I'm afraid. Perhaps @RReverser would be better placed to review here?

[RReverser]

Oh, sorry, almost missed this one. I think N-API does make sense in the JS binding section.

While a few of its APIs are Node-specific, most of it was designed as a generic way to interact with JS values from native code - and in that context it doesn't matter whether it's V8, ChakraCore, SpiderMonkey, or something like Emscripten that represents the native side.

[toyobayashi]

Yeah, sorry for my bad English expression, and thanks @RReverser to give us a more clear explanation about Node-API. Now I have updated the title and some content, is there anything else that needs to be changed? Waiting for your approvement.

[kripken]

I think the mention below is ok, but I would remove this one. The main part of this doc is for officially supported things in the emscripten repo. But adding a mention near the end is ok for unofficial stuff (while mentioning it is unofficial, as I see that you do).

[toyobayashi]

Done

[kripken]

Not sure what happened with the other tests, but the docs test passed and this only changed docs...