diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..7c2819b --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ +# Node.js API (N-API) Package Changelog \ No newline at end of file diff --git a/README.md b/README.md index 259f593..83663ec 100644 --- a/README.md +++ b/README.md @@ -1,86 +1,106 @@ -# Node.js API (N-API) Package - -This package contains header-only C++ wrapper classes for the ABI-stable -Node.js API (N-API), along with library code that enables -backward-compatibility with use with older versions of Node.js that do -not have N-API built-in. - -### API Documentation - - - [ABI-Stable C APIs in Node.js](https://nodejs.org/api/n-api.html) - - [C++ APIs in this package](https://nodejs.github.io/node-addon-api/namespace_napi.html) - -### Getting Started - -To use N-API in a native module: - 1. Add a dependency on this package to `package.json`: -```json - "dependencies": { - "node-addon-api": "1.0.0", - } -``` - - 2. Reference this package's include directory and gyp file in `binding.gyp`: -```gyp - 'include_dirs': [" +# **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 with +use with older versions of Node.js that do not have N-API built-in. + +Node.js API guarentees the **API** and **ABI** compatibility across different +version of Node.js. So if you switch to a +different version of Node.js you must not reinstall and maybe recompile the +Addon. + +N-API is an API for building native Addons. It is independent from the underlying +JavaScript runtime (ex V8) and is maintained as part of Node.js itself. This API +will be Application Binary Interface (ABI) stable across versions of Node.js. It +is intended to insulate 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. + +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**. + +- **[Setup](#setup)** +- **[API Documentation](#api)** +- **[Examples](#examples)** +- **[Tests](#tests)** +- **[More resource and info about native Addons](#resources)** +- **[Contributors](#contributors)** +- **[License](#license)** + +## **Current version: 1.0.0** + +(See [CHANHELOG.md](CHANGELOG.md) for complete Changelog) + +[![NPM](https://nodei.co/npm/node-addon-api.png?downloads=true&downloadRank=true)](https://nodei.co/npm/dode-addon-api/) [![NPM](https://nodei.co/npm-dl/node-addon-api.png?months=6&height=1)](https://nodei.co/npm/dode-addon-api/) + + + +## Setup + - [Installation and usage](doc/setup.md) + - [node-gyp](doc/node-gyp.md) + - [cmake-js](doc/cmake-js.md) + - [Conversion tool](doc/conversion-tool.md) + - [Generator](doc/generator.md) + + + +### **API Documentation** + - [Basic Types](doc/basic_types.md) + - [Array](doc/array.md) + - [Symbol](doc/symbol.md) + - [String](doc/string.md) + - [Name](doc/name.md) + - [Number](doc/number.md) + - [Boolean](doc/boolean.md) + - [Env](doc/env.md) + - [Value](doc/value.md) + - [CallbackInfo](doc/callbackinfo.md) + - [Reference](doc/reference.md) + - [External](doc/external.md) + - [Object](doc/object.md) + - [ObjectReference](doc/object_reference.md) + - [PropertyDescriptor](doc/property_descriptor.md) + - [Error Handling](doc/error_handling.md) + - [Error](doc/error.md) + - [Object Lifettime Management](doc/object_lifetime_management.md) + - [HandleScope](doc/handle_scope.md) + - [EscapableHandleScope](doc/escapable_handle_scope.md) + - [Working with JavaScript Values](doc/working_with_javascript_values.md) + - [Function](doc/function.md) + - [FunctionReference](doc/function_reference.md) + - [ObjectWrap](doc/object_wrap.md) + - [ClassPropertyDescriptor](doc/class_property_descriptor.md) + - [Buffer](doc/buffer.md) + - [ArrayBuffer](doc/array_buffer.md) + - [TypedArray](doc/typed_array.md) + - [TypedArrayOf](doc/typed_array_of.md) + - [Async Operations](doc/async_operations.md) + - [AsyncWorker](async_worker.md) + - [Promises](doc/promises.md) + + + +### **Examples** + +//TODO References to examples + + + +### **Tests** + +//TODO References to tests + + + +### **More resource and info about native Addons** +- **[C++ Addons](https://nodejs.org/dist/latest/docs/api/addons.html)** +- **[N-API](https://nodejs.org/dist/latest/docs/api/n-api.html)** +- **[N-API - Next Generation Node API for Native Modules](https://youtu.be/-Oniup60Afs)** + + + ### WG Members / Collaborators | Name | GitHub link | | ------------------- | ----------------------------------------------------- | @@ -93,3 +113,7 @@ module's tests. | Michael Dawson | [mhdawson](https://github.com/mhdawson) | | Sampson Gao | [sampsongao](https://github.com/sampsongao) | | Taylor Woll | [boingoing](https://github.com/boingoing) | + + + +Licensed under [MIT](./LICENSE.md) diff --git a/doc/array.md b/doc/array.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/array_buffer.md b/doc/array_buffer.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/async_operations.md b/doc/async_operations.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/async_worker.md b/doc/async_worker.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/basic_types.md b/doc/basic_types.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/boolean.md b/doc/boolean.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/buffer.md b/doc/buffer.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/callbackinfo.md b/doc/callbackinfo.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/class_property_descriptor.md b/doc/class_property_descriptor.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/cmake-js.md b/doc/cmake-js.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/conversion-tool.md b/doc/conversion-tool.md new file mode 100644 index 0000000..d0e05dc --- /dev/null +++ b/doc/conversion-tool.md @@ -0,0 +1,28 @@ +## Conversion Tool + +To make the migration to node-addon-api easier, we have provided a script to help +complete the steps listed above. To use the conversion script: + + 1. Go to your module directory + +``` +cd [module_path] +``` + + 2. Install node-addon-api module + +``` +npm install node-addon-api +``` + + 3. Run node-addon-api conversion script + +``` +node ./node_modules/node-addon-api/tools/conversion.js ./ +``` + + 4. While this script makes conversion easier, it still cannot fully convert + +the module. The next step is to try to build the module and complete the +remaining conversions necessary to allow it to compile and pass all of the +module's tests. \ No newline at end of file diff --git a/doc/env.md b/doc/env.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/error.md b/doc/error.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/error_handling.md b/doc/error_handling.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/escapable_handle_sope.md b/doc/escapable_handle_sope.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/external.md b/doc/external.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/function.md b/doc/function.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/function_reference.md b/doc/function_reference.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/generator.md b/doc/generator.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/handle_scope.md b/doc/handle_scope.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/name.md b/doc/name.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/node-gyp.md b/doc/node-gyp.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/number.md b/doc/number.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/object.md b/doc/object.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/object_reference.md b/doc/object_reference.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/object_wrap.md b/doc/object_wrap.md new file mode 100644 index 0000000..fc79dbf --- /dev/null +++ b/doc/object_wrap.md @@ -0,0 +1,9 @@ +## Object Wrap + +The ```ObjectWrap``` class can be used to expose C++ code to JavaScript. To do +this you need to extend the ObjectWrap class that contain all the plumbing to connect +JavaScript code to a C++ object. +Classes extending ```ObjectWrap``` can be instantiated from JavaScript using the +**new** operator, and their methods can be directly invoked from JavaScript. +The **wrap** word refers to a way to group methods and state of your class because it +will be your responsibility write custom code to bridge each of your C++ class methods. \ No newline at end of file diff --git a/doc/onject_lifetime_management.md b/doc/onject_lifetime_management.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/promises.md b/doc/promises.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/property_descriptor.md b/doc/property_descriptor.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/reference.md b/doc/reference.md new file mode 100644 index 0000000..e69de29 diff --git a/doc/setup.md b/doc/setup.md new file mode 100644 index 0000000..f8136fc --- /dev/null +++ b/doc/setup.md @@ -0,0 +1,55 @@ +## Setup + +To use N-API in a native module: + + 1. Add a dependency on this package to `package.json`: + +```json + "dependencies": { + "node-addon-api": "1.0.0", + } +``` + + 2. Reference this package's include directory and gyp file in `binding.gyp`: + +```gyp + 'include_dirs': ["