node-addon-api
Advanced tools
Comparing version 1.6.3 to 1.7.0
# node-addon-api Changelog | ||
## 2019-07-23 Version 1.7.0, @NickNaso | ||
### Notable changes: | ||
#### API | ||
- Added `Napi::ThreadSafeFunction` api. | ||
- Added `Napi::AsyncWorker::GetResult()` method to `Napi::AsyncWorker`. | ||
- Added `Napi::AsyncWorker::Destroy()()` method to `Napi::AsyncWorker`. | ||
- Use full namespace on macros that create the errors. | ||
#### Documentation | ||
- Added documentation about contribution philosophy. | ||
- Added documentation for `Napi::ThreadSafeFunction`. | ||
- Some minor corrections all over the documentation. | ||
#### TEST | ||
- Added test case for bool operator. | ||
- Fixed test case for `Napi::ObjectWrap`. | ||
### Commmits | ||
* [[`717c9ab163`](https://github.com/nodejs/node-addon-api/commit/717c9ab163)] - **AsyncWorker**: add GetResult() method (Kevin Eady) [#512](https://github.com/nodejs/node-addon-api/pull/512) | ||
* [[`d9d991bbc9`](https://github.com/nodejs/node-addon-api/commit/d9d991bbc9)] - **doc**: add ThreadSafeFunction to main README (#513) (Kevin Eady) [#513](https://github.com/nodejs/node-addon-api/pull/513) | ||
* [[`ac6000d0fd`](https://github.com/nodejs/node-addon-api/commit/ac6000d0fd)] - **doc**: fix minor typo (Yohei Kishimoto) [#510](https://github.com/nodejs/node-addon-api/pull/510) | ||
* [[`e9fa1eaa86`](https://github.com/nodejs/node-addon-api/commit/e9fa1eaa86)] - **doc**: document ThreadSafeFunction (#494) (Kevin Eady) [#494](https://github.com/nodejs/node-addon-api/pull/494) | ||
* [[`cab3b1e2a2`](https://github.com/nodejs/node-addon-api/commit/cab3b1e2a2)] - **doc**: ClassPropertyDescriptor example (Ross Weir) [#507](https://github.com/nodejs/node-addon-api/pull/507) | ||
* [[`c32d7dbdcf`](https://github.com/nodejs/node-addon-api/commit/c32d7dbdcf)] - **macros**: create errors fully namespaced (Gabriel Schulhof) [#506](https://github.com/nodejs/node-addon-api/pull/506) | ||
* [[`0a90df2fcb`](https://github.com/nodejs/node-addon-api/commit/0a90df2fcb)] - Implement ThreadSafeFunction class (Jinho Bang) | ||
* [[`1fb540eeb5`](https://github.com/nodejs/node-addon-api/commit/1fb540eeb5)] - Use curly brackets to include node\_api.h (NickNaso) [#493](https://github.com/nodejs/node-addon-api/pull/493) | ||
* [[`b2b08122ea`](https://github.com/nodejs/node-addon-api/commit/b2b08122ea)] - **AsyncWorker**: make callback optional (Kevin Eady) [#489](https://github.com/nodejs/node-addon-api/pull/489) | ||
* [[`a0cac77c82`](https://github.com/nodejs/node-addon-api/commit/a0cac77c82)] - Added test for bool operator (NickNaso) [#490](https://github.com/nodejs/node-addon-api/pull/490) | ||
* [[`ab7d8fcc48`](https://github.com/nodejs/node-addon-api/commit/ab7d8fcc48)] - **src**: fix objectwrap test case (Michael Dawson) [#495](https://github.com/nodejs/node-addon-api/pull/495) | ||
* [[`3b6b9eb88a`](https://github.com/nodejs/node-addon-api/commit/3b6b9eb88a)] - **AsyncWorker**: introduce Destroy() method (Gabriel Schulhof) [#488](https://github.com/nodejs/node-addon-api/pull/488) | ||
* [[`f633fbd95d`](https://github.com/nodejs/node-addon-api/commit/f633fbd95d)] - string.md: Document existing New(env, value, length) APIs (Tux3) [#486](https://github.com/nodejs/node-addon-api/pull/486) | ||
* [[`aaea55eda9`](https://github.com/nodejs/node-addon-api/commit/aaea55eda9)] - Little fix on code example (Nicola Del Gobbo) [#470](https://github.com/nodejs/node-addon-api/pull/470) | ||
* [[`e1cf9a35a1`](https://github.com/nodejs/node-addon-api/commit/e1cf9a35a1)] - Use `Value::IsEmpty` to check for empty value (NickNaso) [#478](https://github.com/nodejs/node-addon-api/pull/478) | ||
* [[`3ad5dfc7d9`](https://github.com/nodejs/node-addon-api/commit/3ad5dfc7d9)] - Fix link (Alba Mendez) [#481](https://github.com/nodejs/node-addon-api/pull/481) | ||
* [[`a3b4d99c45`](https://github.com/nodejs/node-addon-api/commit/a3b4d99c45)] - **doc**: Add contribution philosophy doc (Hitesh Kanwathirtha) | ||
* [[`36863f087b`](https://github.com/nodejs/node-addon-api/commit/36863f087b)] - **doc**: refer to TypedArray and ArrayBuffer from Array (Gabriel "_|Nix|_" Schulhof) [#465](https://github.com/nodejs/node-addon-api/pull/465) | ||
## 2019-04-03 Version 1.6.3, @NickNaso | ||
@@ -17,3 +60,3 @@ | ||
- Some minor corrections all over the documentation | ||
- Some minor corrections all over the documentation. | ||
@@ -20,0 +63,0 @@ ### Commmits |
@@ -82,3 +82,3 @@ # AsyncWorker | ||
an error message will cause the `Napi::AsyncWorker::OnError` method to be | ||
invoked instead of `Napi::AsyncWorker::OnOKOnOK` once the | ||
invoked instead of `Napi::AsyncWorker::OnOK` once the | ||
`Napi::AsyncWorker::Execute` method completes. | ||
@@ -109,5 +109,6 @@ | ||
This method is invoked when the computation in the `Excecute` method ends. | ||
The default implementation runs the Callback provided when the AsyncWorker class | ||
was created. | ||
This method is invoked when the computation in the `Execute` method ends. | ||
The default implementation runs the Callback optionally provided when the AsyncWorker class | ||
was created. The callback will by default receive no arguments. To provide arguments, | ||
override the `GetResult()` method. | ||
@@ -117,6 +118,15 @@ ```cpp | ||
``` | ||
### GetResult | ||
This method returns the arguments passed to the Callback invoked by the default | ||
`OnOK()` implementation. The default implementation returns an empty vector, | ||
providing no arguments to the Callback. | ||
```cpp | ||
virtual std::vector<napi_value> Napi::AsyncWorker::GetResult(Napi::Env env); | ||
``` | ||
### OnError | ||
This method is invoked afer `Napi::AsyncWorker::Execute` completes if an error | ||
This method is invoked after `Napi::AsyncWorker::Execute` completes if an error | ||
occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are | ||
@@ -131,2 +141,15 @@ enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`. | ||
### Destroy | ||
This method is invoked when the instance must be deallocated. If | ||
`SuppressDestruct()` was not called then this method will be called after either | ||
`OnError()` or `OnOK()` complete. The default implementation of this method | ||
causes the instance to delete itself using the `delete` operator. The method is | ||
provided so as to ensure that instances allocated by means other than the `new` | ||
operator can be deallocated upon work completion. | ||
```cpp | ||
virtual void Napi::AsyncWorker::Destroy(); | ||
``` | ||
### Constructor | ||
@@ -143,3 +166,3 @@ | ||
Returns a`Napi::AsyncWork` instance which can later be queued for execution by calling | ||
Returns a `Napi::AsyncWorker` instance which can later be queued for execution by calling | ||
`Queue`. | ||
@@ -161,3 +184,3 @@ | ||
Returns a `Napi::AsyncWork` instance which can later be queued for execution by | ||
Returns a `Napi::AsyncWorker` instance which can later be queued for execution by | ||
calling `Napi::AsyncWork::Queue`. | ||
@@ -181,3 +204,3 @@ | ||
Returns a `Napi::AsyncWork` instance which can later be queued for execution by | ||
Returns a `Napi::AsyncWorker` instance which can later be queued for execution by | ||
calling `Napi::AsyncWork::Queue`. | ||
@@ -197,3 +220,3 @@ | ||
Returns a `Napi::AsyncWork` instance which can later be queued for execution by | ||
Returns a `Napi::AsyncWorker` instance which can later be queued for execution by | ||
calling `Napi::AsyncWork::Queue`. | ||
@@ -206,3 +229,3 @@ | ||
```cpp | ||
explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback,const char* resource_name); | ||
explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name); | ||
``` | ||
@@ -240,2 +263,50 @@ | ||
### Constructor | ||
Creates a new `Napi::AsyncWorker`. | ||
```cpp | ||
explicit Napi::AsyncWorker(Napi::Env env); | ||
``` | ||
- `[in] env`: The environment in which to create the `Napi::AsyncWorker`. | ||
Returns an `Napi::AsyncWorker` instance which can later be queued for execution by calling | ||
`Napi::AsyncWorker::Queue`. | ||
### Constructor | ||
Creates a new `Napi::AsyncWorker`. | ||
```cpp | ||
explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name); | ||
``` | ||
- `[in] env`: The environment in which to create the `Napi::AsyncWorker`. | ||
- `[in] resource_name`: Null-terminated strings that represents the | ||
identifier for the kind of resource that is being provided for diagnostic | ||
information exposed by the async_hooks API. | ||
Returns a `Napi::AsyncWorker` instance which can later be queued for execution by | ||
calling `Napi::AsyncWorker::Queue`. | ||
### Constructor | ||
Creates a new `Napi::AsyncWorker`. | ||
```cpp | ||
explicit Napi::AsyncWorker(Napi::Env env, const char* resource_name, const Napi::Object& resource); | ||
``` | ||
- `[in] env`: The environment in which to create the `Napi::AsyncWorker`. | ||
- `[in] resource_name`: Null-terminated strings that represents the | ||
identifier for the kind of resource that is being provided for diagnostic | ||
information exposed by the async_hooks API. | ||
- `[in] resource`: Object associated with the asynchronous operation that | ||
will be passed to possible async_hooks. | ||
Returns a `Napi::AsyncWorker` instance which can later be queued for execution by | ||
calling `Napi::AsyncWorker::Queue`. | ||
### Destructor | ||
@@ -313,3 +384,3 @@ | ||
The following code shows an example on how to create and and use an `Napi::AsyncWorker` | ||
The following code shows an example on how to create and use an `Napi::AsyncWorker` | ||
@@ -316,0 +387,0 @@ ```cpp |
@@ -342,2 +342,8 @@ # Basic Types | ||
[`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data | ||
types such as [`Int32Array`][] and [`ArrayBuffer`][], respectively, that can be | ||
used for transferring large amounts of data from JavaScript to the native side. | ||
An example illustrating the use of a JavaScript-provided `ArrayBuffer` in native | ||
code is available [here](https://github.com/nodejs/node-addon-examples/tree/master/array_buffer_to_native/node-addon-api). | ||
### Constructor | ||
@@ -406,1 +412,6 @@ ```cpp | ||
attempting to use the returned value. | ||
[`Napi::TypedArray`]: ./typed_array.md | ||
[`Napi::ArrayBuffer`]: ./array_buffer.md | ||
[`Int32Array`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int32Array | ||
[`ArrayBuffer`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer |
@@ -1,2 +0,2 @@ | ||
# Class propertry and descriptor | ||
# Class property and descriptor | ||
@@ -9,2 +9,84 @@ Property descriptor for use with `Napi::ObjectWrap::DefineClass()`. | ||
## Example | ||
```cpp | ||
#include <napi.h> | ||
class Example : public Napi::ObjectWrap<Example> { | ||
public: | ||
static Napi::Object Init(Napi::Env env, Napi::Object exports); | ||
Example(const Napi::CallbackInfo &info); | ||
private: | ||
static Napi::FunctionReference constructor; | ||
double _value; | ||
Napi::Value GetValue(const Napi::CallbackInfo &info); | ||
Napi::Value SetValue(const Napi::CallbackInfo &info); | ||
}; | ||
Napi::Object Example::Init(Napi::Env env, Napi::Object exports) { | ||
Napi::Function func = DefineClass(env, "Example", { | ||
// Register a class instance accessor with getter and setter functions. | ||
InstanceAccessor("value", &Example::GetValue, &Example::SetValue), | ||
// We can also register a readonly accessor by passing nullptr as the setter. | ||
InstanceAccessor("readOnlyProp", &Example::GetValue, nullptr) | ||
}); | ||
constructor = Napi::Persistent(func); | ||
constructor.SuppressDestruct(); | ||
exports.Set("Example", func); | ||
return exports; | ||
} | ||
Example::Example(const Napi::CallbackInfo &info) : Napi::ObjectWrap<Example>(info) { | ||
Napi::Env env = info.Env(); | ||
// ... | ||
Napi::Number value = info[0].As<Napi::Number>(); | ||
this->_value = value.DoubleValue(); | ||
} | ||
Napi::FunctionReference Example::constructor; | ||
Napi::Value Example::GetValue(const Napi::CallbackInfo &info) { | ||
Napi::Env env = info.Env(); | ||
return Napi::Number::New(env, this->_value); | ||
} | ||
Napi::Value Example::SetValue(const Napi::CallbackInfo &info, const Napi::Value &value) { | ||
Napi::Env env = info.Env(); | ||
// ... | ||
Napi::Number arg = value.As<Napi::Number>(); | ||
this->_value = arg.DoubleValue(); | ||
return this->GetValue(info); | ||
} | ||
// Initialize native add-on | ||
Napi::Object Init (Napi::Env env, Napi::Object exports) { | ||
Example::Init(env, exports); | ||
return exports; | ||
} | ||
// Register and initialize native add-on | ||
NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) | ||
``` | ||
The above code can be used from JavaScript as follows: | ||
```js | ||
'use strict'; | ||
const { Example } = require('bindings')('addon'); | ||
const example = new Example(11); | ||
console.log(example.value); | ||
// It prints 11 | ||
example.value = 19; | ||
console.log(example.value); | ||
// It prints 19 | ||
example.readOnlyProp = 500; | ||
console.log(example.readOnlyProp); | ||
// Unchanged. It prints 19 | ||
``` | ||
## Methods | ||
@@ -11,0 +93,0 @@ |
@@ -81,3 +81,3 @@ # Object Wrap | ||
// Regisgter and initialize native add-on | ||
// Register and initialize native add-on | ||
NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) | ||
@@ -84,0 +84,0 @@ ``` |
@@ -26,3 +26,3 @@ # Object | ||
obj.Set("hello", "world"); | ||
obj.Set(42, "The Answer to Life, the Universe, and Everything"); | ||
obj.Set(uint32_t(42), "The Answer to Life, the Universe, and Everything"); | ||
obj.Set("Douglas Adams", true); | ||
@@ -32,3 +32,3 @@ | ||
Value val1 = obj.Get("hello"); | ||
Value val2 = obj.Get(42); | ||
Value val2 = obj.Get(uint32_t(42)); | ||
Value val3 = obj.Get("Douglas Adams"); | ||
@@ -35,0 +35,0 @@ |
@@ -5,3 +5,3 @@ # Prebuild tools | ||
In order to install a native add-on it's important to have all the necessary | ||
dependencies installed and well configured (see the [setup](doc/setum.md) section). | ||
dependencies installed and well configured (see the [setup](setup.md) section). | ||
The end-user will need to compile the add-on when they will do an `npm install` | ||
@@ -8,0 +8,0 @@ and in some cases this could create problems. To avoid the compilation process it's |
@@ -59,2 +59,4 @@ # String | ||
Napi::String::New(napi_env env, const char16_t* value); | ||
Napi::String::New(napi_env env, const char* value, size_t length); | ||
Napi::String::New(napi_env env, const char16_t* value, size_t length); | ||
``` | ||
@@ -68,2 +70,3 @@ | ||
- `const char16_t*` - represents a UTF16-LE string. | ||
- `[in] length`: The length of the string (not necessarily null-terminated) in code units. | ||
@@ -70,0 +73,0 @@ Returns a new `Napi::String` that represents the passed in C++ string. |
@@ -7,2 +7,3 @@ { | ||
"Abhishek Kumar Singh (https://github.com/abhi11210646)", | ||
"Alba Mendez (https://github.com/jmendeth)", | ||
"Andrew Petersen (https://github.com/kirbysayshi)", | ||
@@ -30,2 +31,3 @@ "Anisha Rohra (https://github.com/anisha-rohra)", | ||
"joshgarde (https://github.com/joshgarde)", | ||
"Kevin Eady (https://github.com/KevinEady)", | ||
"Konstantin Tarkus (https://github.com/koistya)", | ||
@@ -42,2 +44,3 @@ "Kyle Farnung (https://github.com/kfarnung)", | ||
"Rolf Timmermans (https://github.com/rolftimmermans)", | ||
"Ross Weir (https://github.com/ross-weir)", | ||
"Ryuichi Okumura (https://github.com/okuryu)", | ||
@@ -47,3 +50,5 @@ "Sampson Gao (https://github.com/sampsongao)", | ||
"Taylor Woll (https://github.com/boingoing)", | ||
"Thomas Gentilhomme (https://github.com/fraxken)" | ||
"Thomas Gentilhomme (https://github.com/fraxken)", | ||
"Tux3 (https://github.com/tux3)", | ||
"Yohei Kishimoto (https://github.com/morokosi)" | ||
], | ||
@@ -76,3 +81,3 @@ "dependencies": {}, | ||
}, | ||
"version": "1.6.3" | ||
"version": "1.7.0" | ||
} |
@@ -49,3 +49,3 @@ # **node-addon-api module** | ||
## **Current version: 1.6.3** | ||
## **Current version: 1.7.0** | ||
@@ -110,2 +110,3 @@ (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog) | ||
- [AsyncContext](doc/async_context.md) | ||
- [Thread-safe Functions](doc/threadsafe_function.md) | ||
- [Promises](doc/promises.md) | ||
@@ -164,2 +165,7 @@ - [Version management](doc/version_management.md) | ||
## **Contributing** | ||
We love contributions from the community to **node-addon-api**. | ||
See [CONTRIBUTING.md](CONTRIBUTING.md) for more details on our philosophy around extending this module. | ||
### **More resource and info about native Addons** | ||
@@ -166,0 +172,0 @@ - **[C++ Addons](https://nodejs.org/dist/latest/docs/api/addons.html)** |
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
753921
74
201