node-addon-api
Advanced tools
Comparing version 1.1.0 to 1.2.0
@@ -1,6 +0,8 @@ | ||
## Conversion Tool | ||
# 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: | ||
To make the migration to **node-addon-api** easier, we have provided a script to | ||
help complete some tasks. | ||
## To use the conversion script: | ||
1. Go to your module directory | ||
@@ -17,3 +19,2 @@ | ||
``` | ||
3. Run node-addon-api conversion script | ||
@@ -26,5 +27,4 @@ | ||
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. |
@@ -9,2 +9,6 @@ ## Object Wrap | ||
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. | ||
will be your responsibility write custom code to bridge each of your C++ class methods. | ||
You are reading a draft of the next documentation and it's in continuos update so | ||
if you don't find what you need please refer to: | ||
[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) |
@@ -1,5 +0,18 @@ | ||
## Setup | ||
# Setup | ||
To use N-API in a native module: | ||
## Prerequisites | ||
Before starting to use **N-API** you need to assure you have the following | ||
prerequisites: | ||
* **Node.JS** see: [Installing Node.js](https://nodejs.org/) | ||
* **Node.js native addon build tool** | ||
- **[node-gyp](node-gyp.md)** | ||
## Installation and usage | ||
To use **N-API** in a native module: | ||
1. Add a dependency on this package to `package.json`: | ||
@@ -9,3 +22,3 @@ | ||
"dependencies": { | ||
"node-addon-api": "1.0.0", | ||
"node-addon-api": "1.1.0", | ||
} | ||
@@ -56,2 +69,2 @@ ``` | ||
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. | ||
targeted node version *does not* have N-API built-in. |
@@ -46,3 +46,3 @@ { | ||
}, | ||
"version": "1.1.0" | ||
"version": "1.2.0" | ||
} |
# **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. | ||
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. | ||
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 (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 | ||
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. | ||
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 | ||
@@ -29,10 +28,11 @@ values. Concepts and operations generally map to ideas specified in the | ||
- **[More resource and info about native Addons](#resources)** | ||
- **[Code of Conduct](CODE_OF_CONDUCT.md)** | ||
- **[Contributors](#contributors)** | ||
- **[License](#license)** | ||
## **Current version: 1.0.0** | ||
## **Current version: 1.1.0** | ||
(See [CHANHELOG.md](CHANGELOG.md) for complete Changelog) | ||
(See [CHANGELOG.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/) | ||
[![NPM](https://nodei.co/npm/node-addon-api.png?downloads=true&downloadRank=true)](https://nodei.co/npm/node-addon-api/) [![NPM](https://nodei.co/npm-dl/node-addon-api.png?months=6&height=1)](https://nodei.co/npm/node-addon-api/) | ||
@@ -88,4 +88,13 @@ <a name="setup"></a> | ||
//TODO References to examples | ||
Are you new to **N-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)** | ||
- **[Callbacks](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/3_callbacks/node-addon-api)** | ||
- **[Object factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)** | ||
- **[Function factory](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/4_object_factory/node-addon-api)** | ||
- **[Wrapping C++ Object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/6_object_wrap/node-addon-api)** | ||
- **[Factory of wrapped object](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/7_factory_wrap/node-addon-api)** | ||
- **[Passing wrapped object around](https://github.com/nodejs/abi-stable-node-addon-examples/tree/master/8_passing_wrapped/node-addon-api)** | ||
<a name="tests"></a> | ||
@@ -95,4 +104,11 @@ | ||
//TODO References to tests | ||
To run the **N-API** tests do: | ||
``` | ||
npm install | ||
npm test | ||
``` | ||
Take a look and get inspired by our **[test suite](https://github.com/nodejs/node-addon-api/tree/master/test)** | ||
<a name="resources"></a> | ||
@@ -99,0 +115,0 @@ |
@@ -17,18 +17,38 @@ #! /usr/bin/env node | ||
var ConfigFileOperations = { | ||
'package.json': [ | ||
[ /([ ]*)"dependencies": {/g, '$1"dependencies": {\n$1 "node-addon-api": "' + NodeApiVersion + '",'], | ||
[ /[ ]*"nan": *"[^"]+"(,|)[\n\r]/g, '' ] | ||
], | ||
'binding.gyp': [ | ||
[ /([ ]*)'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 ],' ], | ||
] | ||
}; | ||
const disable = args[1]; | ||
if (disable != "--disable" && dir != "--disable") { | ||
var ConfigFileOperations = { | ||
'package.json': [ | ||
[ /([ ]*)"dependencies": {/g, '$1"dependencies": {\n$1 "node-addon-api": "' + NodeApiVersion + '",'], | ||
[ /[ ]*"nan": *"[^"]+"(,|)[\n\r]/g, '' ] | ||
], | ||
'binding.gyp': [ | ||
[ /([ ]*)'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, '$1$2target_name$2: $4$5$6,\n $2cflags!$2: [ $2-fno-exceptions$2 ],\n $2cflags_cc!$2: [ $2-fno-exceptions$2 ],\n $2xcode_settings$2: { $2GCC_ENABLE_CPP_EXCEPTIONS$2: $2YES$2,\n $2CLANG_CXX_LIBRARY$2: $2libc++$2,\n $2MACOSX_DEPLOYMENT_TARGET$2: $210.7$2,\n },\n $2msvs_settings$2: {\n $2VCCLCompilerTool$2: { $2ExceptionHandling$2: 1 },\n },' ], | ||
] | ||
}; | ||
} else { | ||
var ConfigFileOperations = { | ||
'package.json': [ | ||
[ /([ ]*)"dependencies": {/g, '$1"dependencies": {\n$1 "node-addon-api": "' + NodeApiVersion + '",'], | ||
[ /[ ]*"nan": *"[^"]+"(,|)[\n\r]/g, '' ] | ||
], | ||
'binding.gyp': [ | ||
[ /([ ]*)'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, '$1$2target_name$2: $4$5$6,\n $2cflags!$2: [ $2-fno-exceptions$2 ],\n $2cflags_cc!$2: [ $2-fno-exceptions$2 ],\n $2defines$2: [ $2NAPI_DISABLE_CPP_EXCEPTIONS$2 ],\n $2conditions$2: [\n [\'OS==\"win\"\', { $2defines$2: [ $2_HAS_EXCEPTIONS=1$2 ] }]\n ]' ], | ||
] | ||
}; | ||
} | ||
var SourceFileOperations = [ | ||
[ /Nan::SetMethod\(target,[\s]*\"(.*)\"[\s]*,[\s]*([^)]+)\)/g, 'exports.Set(Napi::String::New(env, \"$1\"), Napi::Function::New(env, $2))' ], | ||
[ /v8::Local<v8::FunctionTemplate>\s+(\w+)\s*=\s*Nan::New<FunctionTemplate>\([\w\d:]+\);(?:\w+->Reset\(\1\))?\s+\1->SetClassName\(Nan::String::New\("(\w+)"\)\);/g, 'Napi::Function $1 = DefineClass(env, "$2", {' ], | ||
@@ -104,3 +124,3 @@ [ /Local<FunctionTemplate>\s+(\w+)\s*=\s*Nan::New<FunctionTemplate>\([\w\d:]+\);\s+(\w+)\.Reset\((\1)\);\s+\1->SetClassName\((Nan::String::New|Nan::New<(v8::)*String>)\("(.+?)"\)\);/g, 'Napi::Function $1 = DefineClass(env, "$6", {'], | ||
[ /(.+?)->BooleanValue\(\)/g, '$1.As<Napi::Boolean>().BooleanValue()' ], | ||
[ /(.+?)->BooleanValue\(\)/g, '$1.As<Napi::Boolean>().Value()' ], | ||
[ /(.+?)->Int32Value\(\)/g, '$1.As<Napi::Number>().Int32Value()' ], | ||
@@ -185,2 +205,5 @@ [ /(.+?)->Uint32Value\(\)/g, '$1.As<Napi::Number>().Uint32Value()' ], | ||
[ /Nan::NAN_METHOD_RETURN_TYPE/g, 'void' ], | ||
[ /NAN_INLINE/g, 'inline' ], | ||
[ /Nan::NAN_METHOD_ARGS_TYPE/g, 'const Napi::CallbackInfo&' ], | ||
@@ -192,6 +215,7 @@ [ /NAN_METHOD\(([\w\d:]+?)\)/g, 'Napi::Value $1(const Napi::CallbackInfo& info)'], | ||
[ /NAN_SETTER\(([\w\d:]+?)\)/g, 'void $1(const Napi::CallbackInfo& info, const Napi::Value& value)' ], | ||
[ /void Init\((v8::)*Local<(v8::)*Object> exports\)/g, 'void Init(Napi::Env env, Napi::Object exports, Napi::Object module)' ], | ||
[ /NAN_MODULE_INIT\(([\w\d:]+?)\);/g, 'void $1(Napi::Env env, Napi::Object exports, Napi::Object module);' ], | ||
[ /NAN_MODULE_INIT\(([\w\d:]+?)\)/g, 'void $1(Napi::Env env, Napi::Object exports, Napi::Object module)' ], | ||
[ /void Init\((v8::)*Local<(v8::)*Object> exports\)/g, 'Napi::Object Init(Napi::Env env, Napi::Object exports)' ], | ||
[ /NAN_MODULE_INIT\(([\w\d:]+?)\);/g, 'Napi::Object $1(Napi::Env env, Napi::Object exports);' ], | ||
[ /NAN_MODULE_INIT\(([\w\d:]+?)\)/g, 'Napi::Object $1(Napi::Env env, Napi::Object exports)' ], | ||
[ /::(Init(?:ialize)?)\(target\)/g, '::$1(env, target, module)' ], | ||
@@ -202,3 +226,6 @@ [ /constructor_template/g, 'constructor' ], | ||
[ /Nan::FunctionCallbackInfo<(v8::)*Value>\s*&\s*info\);/g, 'Napi::CallbackInfo& info);' ], | ||
[ /Nan::FunctionCallbackInfo<(v8::)*Value>\s*&/g, 'Napi::CallbackInfo&' ], | ||
[ /Buffer::HasInstance\(([^)]+)\)/g, '$1.IsBuffer()' ], | ||
[ /info\[(\d+)\]->/g, 'info[$1].' ], | ||
@@ -205,0 +232,0 @@ [ /info\[([\w\d]+)\]->/g, 'info[$1].' ], |
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
479640
60
287
136