@@ -34,13 +34,51 @@ properties: |
34 | 34 | handling section [Error Handling][]. |
35 | 35 |
|
36 | 36 | The N-API is a C API that ensures ABI stability across Node.js versions |
37 | | -and different compiler levels. However, we also understand that a C++ |
38 | | -API can be easier to use in many cases. To support these cases we expect |
39 | | -there to be one or more C++ wrapper modules that provide an inlineable C++ |
40 | | -API. Binaries built with these wrapper modules will depend on the symbols |
41 | | -for the N-API C based functions exported by Node.js. These wrappers are not |
42 | | -part of N-API, nor will they be maintained as part of Node.js. One such |
43 | | -example is: [node-addon-api](https://github.com/nodejs/node-addon-api). |
| 37 | +and different compiler levels. A C++ API can be easier to use. |
| 38 | +To support using C++, the project maintains a |
| 39 | +C++ wrapper module called |
| 40 | +[node-addon-api](https://github.com/nodejs/node-addon-api). |
| 41 | +This wrapper provides an inlineable C++ API. Binaries built |
| 42 | +with `node-addon-api` will depend on the symbols for the N-API C-based |
| 43 | +functions exported by Node.js. `node-addon-api` is a more |
| 44 | +efficient way to write code that calls N-API. Take, for example, the |
| 45 | +following `node-addon-api` code. The first section shows the |
| 46 | +`node-addon-api` code and the second section shows what actually gets |
| 47 | +used in the addon. |
| 48 | + |
| 49 | +```C++ |
| 50 | +Object obj = Object::New(env); |
| 51 | +obj["foo"] = String::New(env, "bar"); |
| 52 | +``` |
| 53 | + |
| 54 | +```C++ |
| 55 | +napi_status status; |
| 56 | +napi_value object, string; |
| 57 | +status = napi_create_object(env, &object); |
| 58 | +if (status != napi_ok) { |
| 59 | + napi_throw_error(env, ...); |
| 60 | + return; |
| 61 | +} |
| 62 | + |
| 63 | +status = napi_crate_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string); |
| 64 | +if (status != napi_ok) { |
| 65 | + napi_throw_error(env, ...); |
| 66 | + return; |
| 67 | +} |
| 68 | + |
| 69 | +status = napi_set_named_property(env, object, "foo", string); |
| 70 | +if (status != napi_ok) { |
| 71 | + napi_throw_error(env, ...); |
| 72 | + return; |
| 73 | +} |
| 74 | +``` |
| 75 | + |
| 76 | +The end result is that the addon only uses the exported C APIs. As a result, |
| 77 | +it still gets the benefits of the ABI stability provided by the C API. |
| 78 | + |
| 79 | +When using `node-addon-api` instead of the C APIs, start with the API |
| 80 | +[docs](https://github.com/nodejs/node-addon-api#api-documentation) |
| 81 | +for `node-addon-api`. |
44 | 82 |
|
45 | 83 | ## Implications of ABI Stability |
46 | 84 |
|
|