Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: Clarify positioning versus N-API #288

Closed
wants to merge 2 commits into from
Closed

doc: Clarify positioning versus N-API #288

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6dabec1
doc: Clarify positioning versus N-API
mhdawson Jun 19, 2018
f968843
squash: address comments.
mhdawson Jun 21, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 31 additions & 21 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,24 +1,30 @@
# **Node.js API (N-API) Package**

This package contains **header-only C++ wrapper classes** for the
**ABI-stable Node.js API** also known as **N-API**, providing C++ object
model and exception handling semantics with low overhead. It guarantees
backward compatibility when used with older versions of Node.js that do
not have N-API built-in.

N-API is an API for building native addons. It is independent from the
underlying JavaScript runtime (e.g. V8 or ChakraCore) and is maintained as
part of Node.js itself. This API will be Application Binary Interface (ABI)
stable across versions and flavors of Node.js. It is intended to insulate
# **node-addon-api module**
This module contains **header-only C++ wrapper classes** which simplify
the use of the C based [N-API](https://nodejs.org/dist/latest/docs/api/n-api.html)
provided by Node.js when using C++. It provides a C++ object model
and exception handling semantics with low overhead.

N-API is an ABI stale API for building native addons in C++. It is
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you just mean "N-API is a stable API" rather than "N-API is an ABI stale API"

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you should also say N-API is a ABI stable C interface provided by Node.js for building native addons... It is not necessary that such addons be written in C++ and saying in C++ muddies the waters a little bit IMO.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for catching those 2, will update to address

independent from the underlying JavaScript runtime (e.g. V8 or ChakraCore)
and is maintained as part of Node.js itself. It is intended to insulate
native addons from changes in the underlying JavaScript engine and allow
modules compiled for one version to run on later versions of Node.js without
recompilation. N-API guarantees the **API** and **ABI** compatibility across
different versions of Node.js. So if you switched to a different version of
Node.js, you would not need to reinstall or recompile the native addon.

APIs exposed by N-API are generally used to create and manipulate JavaScript
values. Concepts and operations generally map to ideas specified in the
**ECMA262 Language Specification**.
recompilation.

The node-addon-api module preserves the benefits of the N-API as it consists
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add ticks around node-addon-api like node-addon-api.

Recommendation:

The node-addon-api module, which is not a part of Node.js, preserves the benefits of the C N-API by using inline C++ code which only depends on the stable C ABI provided by N-API.

only of inline code that depends only on the stable API provided by N-API.
As such, modules built against one version of Node.js using node-addon-api
should run without having to be rebuilt with newer versions of Node.js.
As new APIs are added to N-API, node-addon-api must be updated to provide
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Start a new paragraph at As new APIs are added to...

wrappers for those new APIs. For this reason node-addon-api provides
methods that allow callers to obtain the underlying N-API handles so
direct calls to N-API and the use of the objects/methods provided by
node-addon-api can be used together. For example, in order to be able
to use an API for which the node-add-api does not yet provide a wrapper.

APIs exposed by node-addon-api are generally used to create and
manipulate JavaScript values. Concepts and operations generally map
to ideas specified in the **ECMA262 Language Specification**.

- **[Setup](#setup)**
- **[API Documentation](#api)**
Expand Down Expand Up @@ -47,6 +53,10 @@ values. Concepts and operations generally map to ideas specified in the
<a name="api"></a>

### **API Documentation**

The following is the documentation for node-addon-api (NOTE:
still a work in progress as its not yet complete).

- [Basic Types](doc/basic_types.md)
- [Array](doc/array.md)
- [Symbol](doc/symbol.md)
Expand Down Expand Up @@ -86,7 +96,7 @@ values. Concepts and operations generally map to ideas specified in the

### **Examples**

Are you new to **N-API**? Take a look at our **[examples](https://github.com/nodejs/abi-stable-node-addon-examples)**
Are you new to **node-addon-api**? Take a look at our **[examples](https://github.com/nodejs/abi-stable-node-addon-examples)**

- **[Hello World](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/1_hello_world/node-addon-api)**
- **[Pass arguments to a function](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/2_function_arguments/node-addon-api)**
Expand All @@ -101,7 +111,7 @@ Are you new to **N-API**? Take a look at our **[examples](https://github.com/nod

### **Tests**

To run the **N-API** tests do:
To run the **node-addon-api** tests do:

```
npm install
Expand Down