node-addon-api
Advanced tools
Comparing version 1.0.0 to 1.1.0
25
index.js
@@ -20,21 +20,24 @@ var path = require('path'); | ||
// So far it looks like even version 9 will need the flag. We need to adjust | ||
// this for the version where the flag is dropped whenever that version lands. | ||
var needsFlag = (versionArray[0] >= 8); | ||
// The flag is not needed when the Node version is not 8, nor if the API is | ||
// built-in, because we removed the flag at the same time as creating the final | ||
// incarnation of the built-in API. | ||
var needsFlag = (!isNodeApiBuiltin && versionArray[0] == 8); | ||
var include = path.join(__dirname, 'src'); | ||
var include = [__dirname]; | ||
var gyp = path.join(__dirname, 'src', 'node_api.gyp'); | ||
if (isNodeApiBuiltin) { | ||
gyp += ':nothing'; | ||
gyp += ':nothing'; | ||
} else { | ||
gyp += ':node-api'; | ||
include = path.join(__dirname, 'external-napi'); | ||
gyp += ':node-api'; | ||
include.unshift(path.join(__dirname, 'external-napi')); | ||
} | ||
module.exports = { | ||
include: [ '"' + include + '"', '"' + __dirname + '"' ].join(' '), | ||
gyp: gyp, | ||
isNodeApiBuiltin: isNodeApiBuiltin, | ||
needsFlag: needsFlag | ||
include: include.map(function(item) { | ||
return '"' + item + '"'; | ||
}).join(' '), | ||
gyp: gyp, | ||
isNodeApiBuiltin: isNodeApiBuiltin, | ||
needsFlag: needsFlag | ||
}; |
@@ -6,9 +6,18 @@ { | ||
"contributors": [ | ||
"Andrew Petersen (https://github.com/kirbysayshi)", | ||
"Anisha Rohra (https://github.com/anisha-rohra)", | ||
"Anna Henningsen (https://github.com/addaleax)", | ||
"Arunesh Chandra (https://github.com/aruneshchandra)", | ||
"Benjamin Byholm (https://github.com/kkoopa)", | ||
"David Halls (https://github.com/davedoesdev)", | ||
"Gabriel Schulhof (https://github.com/gabrielschulhof)", | ||
"Hitesh Kanwathirtha (https://github.com/digitalinfinity)", | ||
"Jason Ginchereau (https://github.com/jasongin)", | ||
"Jinho Bang (https://github.com/romandev)", | ||
"Konstantin Tarkus (https://github.com/koistya)", | ||
"Kyle Farnung (https://github.com/kfarnung)", | ||
"Matteo Collina (https://github.com/mcollina)", | ||
"Michael Dawson (https://github.com/mhdawson)", | ||
"Nicola Del Gobbo (https://github.com/NickNaso)", | ||
"Rolf Timmermans (https://github.com/rolftimmermans)", | ||
"Sampson Gao (https://github.com/sampsongao)", | ||
@@ -38,3 +47,3 @@ "Taylor Woll (https://github.com/boingoing)" | ||
}, | ||
"version": "1.0.0" | ||
"version": "1.1.0" | ||
} |
166
README.md
@@ -1,84 +0,104 @@ | ||
# Node.js API (N-API) Package | ||
# **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. | ||
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. | ||
### API Documentation | ||
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. | ||
- [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) | ||
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. | ||
### Getting Started | ||
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**. | ||
To use N-API in a native module: | ||
1. Add a dependency on this package to `package.json`: | ||
```json | ||
"dependencies": { | ||
"node-addon-api": "0.3.3", | ||
} | ||
``` | ||
- **[Setup](#setup)** | ||
- **[API Documentation](#api)** | ||
- **[Examples](#examples)** | ||
- **[Tests](#tests)** | ||
- **[More resource and info about native Addons](#resources)** | ||
- **[Contributors](#contributors)** | ||
- **[License](#license)** | ||
2. Reference this package's include directory and gyp file in `binding.gyp`: | ||
```gyp | ||
'include_dirs': ["<!@(node -p \"require('node-addon-api').include\")"], | ||
'dependencies': ["<!(node -p \"require('node-addon-api').gyp\")"], | ||
``` | ||
## **Current version: 1.0.0** | ||
3. Decide whether the package will enable C++ exceptions in the N-API wrapper. | ||
The base ABI-stable C APIs do not throw or handle C++ exceptions, but the | ||
N-API C++ wrapper classes may _optionally_ | ||
[integrate C++ and JavaScript exception-handling | ||
](https://nodejs.github.io/node-addon-api/class_napi_1_1_error.html). | ||
To enable that capability, C++ exceptions must be enabled in `binding.gyp`: | ||
```gyp | ||
'cflags!': [ '-fno-exceptions' ], | ||
'cflags_cc!': [ '-fno-exceptions' ], | ||
'xcode_settings': { | ||
'GCC_ENABLE_CPP_EXCEPTIONS': 'YES', | ||
'CLANG_CXX_LIBRARY': 'libc++', | ||
'MACOSX_DEPLOYMENT_TARGET': '10.7', | ||
}, | ||
'msvs_settings': { | ||
'VCCLCompilerTool': { 'ExceptionHandling': 1 }, | ||
}, | ||
``` | ||
Alternatively, disable use of C++ exceptions in N-API: | ||
```gyp | ||
'defines': [ 'NAPI_DISABLE_CPP_EXCEPTIONS' ], | ||
``` | ||
(See [CHANHELOG.md](CHANGELOG.md) for complete Changelog) | ||
4. Include `napi.h` in the native module code. | ||
To ensure only ABI-stable APIs are used, DO NOT include | ||
`node.h`, `nan.h`, or `v8.h`. | ||
```C++ | ||
#include "napi.h" | ||
``` | ||
[![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/) | ||
At build time, the N-API back-compat library code will be used only when the | ||
targeted node version *does not* have N-API built-in. | ||
<a name="setup"></a> | ||
## 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. | ||
## 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) | ||
<a name="api"></a> | ||
<a name="collaborators"></a> | ||
### **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) | ||
<a name="examples"></a> | ||
### **Examples** | ||
//TODO References to examples | ||
<a name="tests"></a> | ||
### **Tests** | ||
//TODO References to tests | ||
<a name="resources"></a> | ||
### **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)** | ||
<a name="contributors"></a> | ||
### WG Members / Collaborators | ||
@@ -96,1 +116,5 @@ | Name | GitHub link | | ||
| Taylor Woll | [boingoing](https://github.com/boingoing) | | ||
<a name="license"></a> | ||
Licensed under [MIT](./LICENSE.md) |
@@ -19,7 +19,12 @@ #! /usr/bin/env node | ||
'package.json': [ | ||
[ /"nan": *"[^"]+"/g, '"node-addon-api": "' + NodeApiVersion + '"' ] | ||
[ /([ ]*)"dependencies": {/g, '$1"dependencies": {\n$1 "node-addon-api": "' + NodeApiVersion + '",'], | ||
[ /[ ]*"nan": *"[^"]+"(,|)[\n\r]/g, '' ] | ||
], | ||
'binding.gyp': [ | ||
[ /\(node -e \\("|')require\(("|')nan("|')\)\\("|')\)/g, '@(node -p \\$1require(\$2node-addon-api\$3).include\\$4)' ], | ||
[ /("|')target_name("|'): ("|')(.+?)("|'),/g, '$1target_name$2: $3$4$5,\n $1cflags!$1: [ $1-fno-exceptions$1 ],\n $1cflags_cc!$1: [ $1-fno-exceptions$1 ],' ], | ||
[ /([ ]*)'include_dirs': \[/g, '$1\'include_dirs\': [\n$1 \'<!@(node -p "require(\\\'node-addon-api\\\').include")\',' ], | ||
[ /([ ]*)"include_dirs": \[/g, '$1"include_dirs": [\n$1 "<!@(node -p \'require(\\\"node-addon-api\\\").include\')",' ], | ||
[ /([ ]*)'dependencies': \[/g, '$1\'dependencies\': [\n$1 \'<!(node -p "require(\\\'node-addon-api\\\').gyp")\','], | ||
[ /([ ]*)"dependencies": \[/g, '$1"dependencies": [\n$1 "<!(node -p \'require(\\\"node-addon-api\\\").gyp\')",'], | ||
[ /[ ]*("|')<!\(node -e ("|'|\\"|\\')require\(("|'|\\"|\\')nan("|'|\\"|\\')\)("|'|\\"|\\')\)("|')(,|)[\r\n]/g, '' ], | ||
[ /([ ]*)("|')target_name("|'): ("|')(.+?)("|'),/g, '$2target_name$3: $4$5$6,\n$1 $2cflags!$2: [ $1-fno-exceptions$2 ],\n$1 $1cflags_cc!$2: [ $2-fno-exceptions$2 ],' ], | ||
] | ||
@@ -46,8 +51,8 @@ }; | ||
[ /Nan::SetPrototypeMethod\(\w+, "(\w+)", (\w+)\);/g, ' InstanceMethod("$1", &$2),' ], | ||
[ /(?:\w+\.Reset\(\w+\);\s+)?\(target\)\.Set\("(\w+)",\s*Nan::GetFunction\((\w+)\)\);/gm, | ||
[ /([ ]*)Nan::SetPrototypeMethod\(\w+, "(\w+)", (\w+)\);/g, '$1InstanceMethod("$2", &$3),' ], | ||
[ /([ ]*)(?:\w+\.Reset\(\w+\);\s+)?\(target\)\.Set\("(\w+)",\s*Nan::GetFunction\((\w+)\)\);/gm, | ||
'});\n\n' + | ||
' constructor = Napi::Persistent($2);\n' + | ||
' constructor.SuppressDestruct();\n' + | ||
' target.Set("$1", $2);' ], | ||
'$1constructor = Napi::Persistent($3);\n' + | ||
'$1constructor.SuppressDestruct();\n' + | ||
'$1target.Set("$2", $3);' ], | ||
@@ -152,3 +157,3 @@ | ||
// Nan::ThrowError(error) to Napi::Error::New(env, error).ThrowAsJavaScriptException() | ||
[ /return Nan::Throw(\w*?)Error\((.+?)\);/g, 'Napi::$1Error::New(env, $2).ThrowAsJavaScriptException();\n return env.Null();' ], | ||
[ /([ ]*)return Nan::Throw(\w*?)Error\((.+?)\);/g, '$1Napi::$2Error::New(env, $3).ThrowAsJavaScriptException();\n$1return env.Null();' ], | ||
[ /Nan::Throw(\w*?)Error\((.+?)\);\n(\s*)return;/g, 'Napi::$1Error::New(env, $2).ThrowAsJavaScriptException();\n$3return env.Null();' ], | ||
@@ -194,3 +199,3 @@ [ /Nan::Throw(\w*?)Error\((.+?)\);/g, 'Napi::$1Error::New(env, $2).ThrowAsJavaScriptException();\n' ], | ||
[ /Nan::FunctionCallbackInfo<(v8::)*Value>\s*&\s*info\)\s*{/g, 'Napi::CallbackInfo& info) {\n Napi::Env env = info.Env();' ], | ||
[ /Nan::FunctionCallbackInfo<(v8::)?Value>[ ]*& [ ]*info\)[ ]*{\n*([ ]*)/gm, 'Napi::CallbackInfo& info) {\n$2Napi::Env env = info.Env();\n$2' ], | ||
[ /Nan::FunctionCallbackInfo<(v8::)*Value>\s*&\s*info\);/g, 'Napi::CallbackInfo& info);' ], | ||
@@ -211,3 +216,3 @@ | ||
// Declare an env in helper functions that take a Napi::Value | ||
[ /(\w+)\(Napi::Value (\w+)(,\s*[^\()]+)?\)\s*{/g, '$1(Napi::Value $2$3) {\n Napi::Env env = $2.Env();' ], | ||
[ /(\w+)\(Napi::Value (\w+)(,\s*[^\()]+)?\)\s*{\n*([ ]*)/gm, '$1(Napi::Value $2$3) {\n$4Napi::Env env = $2.Env();\n$4' ], | ||
@@ -214,0 +219,0 @@ // delete #include <node.h> and/or <v8.h> |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
450379
59
262
120