diff --git a/.gitignore b/.gitignore index c10f4dffc..c5b8bc871 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ /build /benchmark/build /benchmark/src +/test/addon_build/addons diff --git a/CHANGELOG.md b/CHANGELOG.md index e2ef3d432..8ef37c9b0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,50 @@ # node-addon-api Changelog +## 2020-09-18 Version 3.0.2, @NickNaso + +### Notable changes: + +#### API + +- Introduced `include_dir` for use with **gyp** in a scalar context. +- Added `Napi::Addon` to help handle the loading of a native add-on into +multiple threads and or multiple times in the same thread. +- Concentrate callbacks provided to core N-API. +- Make sure wrapcallback is used. + +#### Documentation + +- Added documentation for `Napi::Addon`. +- Added documentation that reports the full class hierarchy. +- Added link to N-API tutorial website. +- Some minor corrections all over the documentation. + +#### TEST + +- Added tests to check the build process. +- Refactored test for threasfafe function using async/await. +- Converted tests that gc into async functions that await 10 ticks after +each gc. +- Some minor corrections all over the test suite. + +### Commits + +* [[`51e25f7c39`](https://github.com/nodejs/node-addon-api/commit/51e25f7c39)] - **doc**: remove a file (#815) (Gabriel Schulhof) +* [[`8c9f1809a2`](https://github.com/nodejs/node-addon-api/commit/8c9f1809a2)] - **doc**: add inheritance links and other changes (Gabriel Schulhof) [#798](https://github.com/nodejs/node-addon-api/pull/798) +* [[`6562e6b0ab`](https://github.com/nodejs/node-addon-api/commit/6562e6b0ab)] - **test**: added tests to check the build process (NickNaso) [#808](https://github.com/nodejs/node-addon-api/pull/808) +* [[`a13b36c96e`](https://github.com/nodejs/node-addon-api/commit/a13b36c96e)] - **test**: fix the threasfafe function test (NickNaso) [#807](https://github.com/nodejs/node-addon-api/pull/807) +* [[`f27623ff61`](https://github.com/nodejs/node-addon-api/commit/f27623ff61)] - **build**: introduce include\_dir (Lovell Fuller) [#766](https://github.com/nodejs/node-addon-api/pull/766) +* [[`9aceea71fc`](https://github.com/nodejs/node-addon-api/commit/9aceea71fc)] - **src**: concentrate callbacks provided to core N-API (Gabriel Schulhof) [#786](https://github.com/nodejs/node-addon-api/pull/786) +* [[`2bc45bbffd`](https://github.com/nodejs/node-addon-api/commit/2bc45bbffd)] - **test**: refactor test to use async/await (Velmisov) [#787](https://github.com/nodejs/node-addon-api/pull/787) +* [[`518cfdcdc1`](https://github.com/nodejs/node-addon-api/commit/518cfdcdc1)] - **test**: test ObjectWrap destructor - no HandleScope (David Halls) [#729](https://github.com/nodejs/node-addon-api/pull/729) +* [[`c2cbbd9191`](https://github.com/nodejs/node-addon-api/commit/c2cbbd9191)] - **doc**: add link to n-api tutorial website (#794) (Jim Schlight) [#794](https://github.com/nodejs/node-addon-api/pull/794) +* [[`1c2a8d59b5`](https://github.com/nodejs/node-addon-api/commit/1c2a8d59b5)] - **doc**: Added required return to example (#793) (pacop) [#793](https://github.com/nodejs/node-addon-api/pull/793) +* [[`cec2c76941`](https://github.com/nodejs/node-addon-api/commit/cec2c76941)] - **src**: wrap finalizer callback (Gabriel Schulhof) [#762](https://github.com/nodejs/node-addon-api/pull/762) +* [[`4ce40d22a6`](https://github.com/nodejs/node-addon-api/commit/4ce40d22a6)] - **test**: use assert.strictEqual() (Koki Nishihara) [#777](https://github.com/nodejs/node-addon-api/pull/777) +* [[`461e3640c6`](https://github.com/nodejs/node-addon-api/commit/461e3640c6)] - **test**: string tests together (Gabriel Schulhof) [#773](https://github.com/nodejs/node-addon-api/pull/773) +* [[`5af645f649`](https://github.com/nodejs/node-addon-api/commit/5af645f649)] - **src**: add Addon\ class (Gabriel Schulhof) [#749](https://github.com/nodejs/node-addon-api/pull/749) +* [[`6148fb4bcc`](https://github.com/nodejs/node-addon-api/commit/6148fb4bcc)] - Synchronise Node.js versions in Appveyor Windows CI with Travis (#768) (Lovell Fuller) + ## 2020-07-13 Version 3.0.1, @NickNaso ### Notable changes: diff --git a/README.md b/README.md index 2c96cd3fb..ff4319553 100644 --- a/README.md +++ b/README.md @@ -37,6 +37,10 @@ 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**. +The [N-API Resource](http://nodejs.github.io/node-addon-examples/) offers an +excellent orientation and tips for developers just getting started with N-API +and node-addon-api. + - **[Setup](#setup)** - **[API Documentation](#api)** - **[Examples](#examples)** @@ -47,7 +51,7 @@ to ideas specified in the **ECMA262 Language Specification**. - **[Contributors](#contributors)** - **[License](#license)** -## **Current version: 3.0.1** +## **Current version: 3.0.2** (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog) @@ -77,32 +81,25 @@ The oldest Node.js version supported by the current version of node-addon-api is The following is the documentation for node-addon-api. + - [Full Class Hierarchy](doc/hierarchy.md) - [Addon Structure](doc/addon.md) - - [Basic Types](doc/basic_types.md) - - [Array](doc/basic_types.md#array) - - [Symbol](doc/symbol.md) - - [String](doc/string.md) - - [Name](doc/basic_types.md#name) - - [Number](doc/number.md) - - [Date](doc/date.md) - - [BigInt](doc/bigint.md) - - [Boolean](doc/boolean.md) + - Data Types: - [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) - - [TypeError](doc/type_error.md) - - [RangeError](doc/range_error.md) - - [Object Lifetime 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) + - [Value](doc/value.md) + - [Name](doc/name.md) + - [Symbol](doc/symbol.md) + - [String](doc/string.md) + - [Number](doc/number.md) + - [Date](doc/date.md) + - [BigInt](doc/bigint.md) + - [Boolean](doc/boolean.md) + - [External](doc/external.md) + - [Object](doc/object.md) + - [Array](doc/array.md) + - [ObjectReference](doc/object_reference.md) + - [PropertyDescriptor](doc/property_descriptor.md) - [Function](doc/function.md) - [FunctionReference](doc/function_reference.md) - [ObjectWrap](doc/object_wrap.md) @@ -112,6 +109,13 @@ The following is the documentation for node-addon-api. - [TypedArray](doc/typed_array.md) - [TypedArrayOf](doc/typed_array_of.md) - [DataView](doc/dataview.md) + - [Error Handling](doc/error_handling.md) + - [Error](doc/error.md) + - [TypeError](doc/type_error.md) + - [RangeError](doc/range_error.md) + - [Object Lifetime Management](doc/object_lifetime_management.md) + - [HandleScope](doc/handle_scope.md) + - [EscapableHandleScope](doc/escapable_handle_scope.md) - [Memory Management](doc/memory_management.md) - [Async Operations](doc/async_operations.md) - [AsyncWorker](doc/async_worker.md) diff --git a/doc/addon.md b/doc/addon.md index b4c9c9d6b..96dae718d 100644 --- a/doc/addon.md +++ b/doc/addon.md @@ -1,5 +1,7 @@ # Add-on Structure +Class `Napi::Addon` inherits from class [`Napi::InstanceWrap`][]. + Creating add-ons that work correctly when loaded multiple times from the same source package into multiple Node.js threads and/or multiple times into the same Node.js thread requires that all global data they hold be associated with the @@ -8,20 +10,20 @@ variables because doing so does not take into account the fact that an add-on may be loaded into multiple threads nor that an add-on may be loaded multiple times into a single thread. -The `Napi::Addon` class can be used to define an entire add-on. Instances of -`Napi::Addon` subclasses become instances of the add-on, stored safely by +The `Napi::Addon` class can be used to define an entire add-on. Instances of +`Napi::Addon` subclasses become instances of the add-on, stored safely by Node.js on its various threads and into its various contexts. Thus, any data -stored in the instance variables of a `Napi::Addon` subclass instance are stored -safely by Node.js. Functions exposed to JavaScript using -`Napi::Addon::InstanceMethod` and/or `Napi::Addon::DefineAddon` are instance -methods of the `Napi::Addon` subclass and thus have access to data stored inside -the instance. +stored in the instance variables of a `Napi::Addon` subclass instance are +stored safely by Node.js. Functions exposed to JavaScript using +`Napi::Addon::InstanceMethod` and/or `Napi::Addon::DefineAddon` are +instance methods of the `Napi::Addon` subclass and thus have access to data +stored inside the instance. -`Napi::Addon::DefineProperties` may be used to attach `Napi::Addon` subclass -instance methods to objects other than the one that will be returned to Node.js -as the add-on instance. +`Napi::Addon::DefineProperties` may be used to attach `Napi::Addon` +subclass instance methods to objects other than the one that will be returned to +Node.js as the add-on instance. -The `Napi::Addon` class can be used together with the `NODE_API_ADDON()` and +The `Napi::Addon` class can be used together with the `NODE_API_ADDON()` and `NODE_API_NAMED_ADDON()` macros to define add-ons. ## Example @@ -32,16 +34,16 @@ The `Napi::Addon` class can be used together with the `NODE_API_ADDON()` and class ExampleAddon : public Napi::Addon { public: ExampleAddon(Napi::Env env, Napi::Object exports) { - // In the constructor we declare the functions the add-on makes avaialable + // In the constructor we declare the functions the add-on makes available // to JavaScript. DefineAddon(exports, { InstanceMethod("increment", &ExampleAddon::Increment), // We can also attach plain objects to `exports`, and instance methods as // properties of those sub-objects. - InstanceValue("subObject", DefineProperties(Napi::Object::New(), { - InstanceMethod("decrement", &ExampleAddon::Decrement - })), napi_enumerable) + InstanceValue("subObject", DefineProperties(Napi::Object::New(env), { + InstanceMethod("decrement", &ExampleAddon::Decrement) + }), napi_enumerable) }); } private: @@ -78,7 +80,7 @@ The above code can be used from JavaScript as follows: const exampleAddon = require('bindings')('example_addon'); console.log(exampleAddon.increment()); // prints 43 console.log(exampleAddon.increment()); // prints 44 -consnole.log(exampleAddon.subObject.decrement()); // prints 43 +console.log(exampleAddon.subObject.decrement()); // prints 43 ``` When Node.js loads an instance of the add-on, a new instance of the class is @@ -122,7 +124,8 @@ pass it to `DefineAddon()` as its first parameter if it wishes to replace the Defines an add-on instance with functions, accessors, and/or values. ```cpp -void Napi::Addon::DefineAddon(Napi::Object exports, +template +void Napi::Addon::DefineAddon(Napi::Object exports, const std::initializer_list& properties); ``` @@ -138,8 +141,9 @@ Defines function, accessor, and/or value properties on an object using add-on instance methods. ```cpp +template Napi::Object -Napi::Addon::DefineProperties(Napi::Object object, +Napi::Addon::DefineProperties(Napi::Object object, const std::initializer_list& properties); ``` @@ -150,369 +154,4 @@ See: [`Class property and descriptor`](class_property_descriptor.md). Returns `object`. -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(const char* utf8name, - InstanceVoidMethodCallback method, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -void MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(const char* utf8name, - InstanceMethodCallback method, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -Napi::Value MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(Napi::Symbol name, - InstanceVoidMethodCallback method, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] name`: JavaScript symbol that represents the name of the method provided -by the add-on. -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -void MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(Napi::Symbol name, - InstanceMethodCallback method, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] name`: JavaScript symbol that represents the name of the method provided -by the add-on. -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -Napi::Value MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(const char* utf8name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -void MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(const char* utf8name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -Napi::Value MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(Napi::Symbol name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -instance method for the class. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -void MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(Napi::Symbol name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -instance method for the class. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -Napi::Value MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceAccessor - -Creates a property descriptor that represents an instance accessor property -provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceAccessor(const char* utf8name, - InstanceGetterCallback getter, - InstanceSetterCallback setter, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] getter`: The native function to call when a get access to the property -is performed. -- `[in] setter`: The native function to call when a set access to the property -is performed. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the getter or the setter when it -is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents an instance accessor -property provided by the add-on. - -### InstanceAccessor - -Creates a property descriptor that represents an instance accessor property -provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceAccessor(Symbol name, - InstanceGetterCallback getter, - InstanceSetterCallback setter, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -instance accessor. -- `[in] getter`: The native function to call when a get access to the property of -a JavaScript class is performed. -- `[in] setter`: The native function to call when a set access to the property of -a JavaScript class is performed. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the getter or the setter when it -is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents an instance accessor -property provided by the add-on. - -### InstanceAccessor - -Creates a property descriptor that represents an instance accessor property -provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceAccessor(const char* utf8name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] getter`: The native function to call when a get access to the property of -a JavaScript class is performed. -- `[in] setter`: The native function to call when a set access to the property of -a JavaScript class is performed. -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the getter or the setter when it -is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents an instance accessor -property provided by the add-on. - -### InstanceAccessor - -Creates a property descriptor that represents an instance accessor property -provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceAccessor(Symbol name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] getter`: The native function to call when a get access to the property of -a JavaScript class is performed. -- `[in] setter`: The native function to call when a set access to the property of -a JavaScript class is performed. -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -instance accessor. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the getter or the setter when it -is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents an instance accessor -property provided by the add-on. - -### InstanceValue - -Creates property descriptor that represents an instance value property provided -by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceValue(const char* utf8name, - Napi::Value value, - napi_property_attributes attributes = napi_default); -``` - -- `[in] utf8name`: Null-terminated string that represents the name of the property. -- `[in] value`: The value that's retrieved by a get access of the property. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. - -Returns a `Napi::PropertyDescriptor` object that represents an instance value -property of an add-on. - -### InstanceValue - -Creates property descriptor that represents an instance value property provided -by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceValue(Symbol name, - Napi::Value value, - napi_property_attributes attributes = napi_default); -``` - -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -name of the property. -- `[in] value`: The value that's retrieved by a get access of the property. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. - -Returns a `Napi::PropertyDescriptor` object that represents an instance value -property of an add-on. +[`Napi::InstanceWrap`]: ./instance_wrap.md diff --git a/doc/array.md b/doc/array.md new file mode 100644 index 000000000..a12e92daf --- /dev/null +++ b/doc/array.md @@ -0,0 +1,81 @@ +# Array + +Class [`Napi::Array`][] inherits from class [`Napi::Object`][]. + +Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper +around `napi_value` representing a JavaScript Array. + +[`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data +types such as [`Napi::Int32Array`][] and [`Napi::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 +```cpp +Napi::Array::Array(); +``` + +Returns an empty array. + +If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +```cpp +Napi::Array::Array(napi_env env, napi_value value); +``` +- `[in] env` - The environment in which to create the array. +- `[in] value` - The primitive to wrap. + +Returns a `Napi::Array` wrapping a `napi_value`. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +## Methods + +### New +```cpp +static Napi::Array Napi::Array::New(napi_env env); +``` +- `[in] env` - The environment in which to create the array. + +Returns a new `Napi::Array`. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +### New + +```cpp +static Napi::Array Napi::Array::New(napi_env env, size_t length); +``` +- `[in] env` - The environment in which to create the array. +- `[in] length` - The length of the array. + +Returns a new `Napi::Array` with the given length. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +### Length +```cpp +uint32_t Napi::Array::Length() const; +``` + +Returns the length of the array. + +Note: +This can execute JavaScript code implicitly according to JavaScript semantics. +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +[`Napi::ArrayBuffer`]: ./array_buffer.md +[`Napi::Int32Array`]: ./typed_array_of.md +[`Napi::Object`]: ./object.md +[`Napi::TypedArray`]: ./typed_array.md diff --git a/doc/array_buffer.md b/doc/array_buffer.md index ca9d45c00..988a839a4 100644 --- a/doc/array_buffer.md +++ b/doc/array_buffer.md @@ -1,5 +1,7 @@ # ArrayBuffer +Class `Napi::ArrayBuffer` inherits from class [`Napi::Object`][]. + The `Napi::ArrayBuffer` class corresponds to the [JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) class. @@ -127,3 +129,5 @@ void* Napi::ArrayBuffer::Data() const; ``` Returns a pointer the wrapped data. + +[`Napi::Object`]: ./object.md diff --git a/doc/async_context.md b/doc/async_context.md index 8e1f481c5..b217d336a 100644 --- a/doc/async_context.md +++ b/doc/async_context.md @@ -73,7 +73,7 @@ void MakeCallbackWithAsyncContext(const Napi::CallbackInfo& info) { Napi::Function callback = info[0].As(); Napi::Object resource = info[1].As(); - // Creat a new async context instance. + // Create a new async context instance. Napi::AsyncContext context(info.Env(), "async_context_test", resource); // Invoke the callback with the async context instance. diff --git a/doc/async_worker.md b/doc/async_worker.md index d7753ac8c..b6bb0cd67 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -395,7 +395,7 @@ class EchoWorker : public AsyncWorker { }; ``` -The `EchoWorker`'s contructor calls the base class' constructor to pass in the +The `EchoWorker`'s constructor calls the base class' constructor to pass in the callback that the `Napi::AsyncWorker` base class will store persistently. When the work on the `Napi::AsyncWorker::Execute` method is done the `Napi::AsyncWorker::OnOk` method is called and the results return back to diff --git a/doc/basic_types.md b/doc/basic_types.md deleted file mode 100644 index 03ec14b4b..000000000 --- a/doc/basic_types.md +++ /dev/null @@ -1,423 +0,0 @@ -# Basic Types - -Node Addon API consists of a few fundamental data types. These allow a user of -the API to create, convert and introspect fundamental JavaScript types, and -interoperate with their C++ counterparts. - -## Value - -`Napi::Value` is the base class of Node Addon API's fundamental object type hierarchy. -It represents a JavaScript value of an unknown type. It is a thin wrapper around -the N-API datatype `napi_value`. Methods on this class can be used to check -the JavaScript type of the underlying N-API `napi_value` and also to convert to -C++ types. - -### Constructor - -```cpp -Napi::Value::Value(); -``` - -Used to create a Node Addon API `Napi::Value` that represents an **empty** value. - -```cpp -Napi::Value::Value(napi_env env, napi_value value); -``` - -- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` -object. -- `[in] value` - The underlying JavaScript value that the `Napi::Value` instance -represents. - -Returns a Node.js Addon API `Napi::Value` that represents the `napi_value` passed -in. - -### Operators - -#### operator napi_value - -```cpp -Napi::Value::operator napi_value() const; -``` - -Returns the underlying N-API `napi_value`. If the instance is _empty_, this -returns `nullptr`. - -#### operator == - -```cpp -bool Napi::Value::operator ==(const Value& other) const; -``` - -Returns `true` if this value strictly equals another value, or `false` otherwise. - -#### operator != - -```cpp -bool Napi::Value::operator !=(const Value& other) const; -``` - -Returns `false` if this value strictly equals another value, or `true` otherwise. - -### Methods - -#### From -```cpp -template -static Napi::Value Napi::Value::From(napi_env env, const T& value); -``` - -- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` object. -- `[in] value` - The C++ type to represent in JavaScript. - -Returns a `Napi::Value` representing the input C++ type in JavaScript. - -This method is used to convert from a C++ type to a JavaScript value. -Here, `value` may be any of: -- `bool` - returns a `Napi::Boolean`. -- Any integer type - returns a `Napi::Number`. -- Any floating point type - returns a `Napi::Number`. -- `const char*` (encoded using UTF-8, null-terminated) - returns a `Napi::String`. -- `const char16_t*` (encoded using UTF-16-LE, null-terminated) - returns a `Napi::String`. -- `std::string` (encoded using UTF-8) - returns a `Napi::String`. -- `std::u16string` - returns a `Napi::String`. -- `napi::Value` - returns a `Napi::Value`. -- `napi_value` - returns a `Napi::Value`. - -#### As -```cpp -template T Napi::Value::As() const; -``` - -Returns the `Napi::Value` cast to a desired C++ type. - -Use this when the actual type is known or assumed. - -Note: -This conversion does NOT coerce the type. Calling any methods inappropriate for -the actual value type will throw `Napi::Error`. - -#### StrictEquals -```cpp -bool Napi::Value::StrictEquals(const Value& other) const; -``` - -- `[in] other` - The value to compare against. - -Returns true if the other `Napi::Value` is strictly equal to this one. - -#### Env -```cpp -Napi::Env Napi::Value::Env() const; -``` - -Returns the environment that the value is associated with. See -[`Napi::Env`](env.md) for more details about environments. - -#### IsEmpty -```cpp -bool Napi::Value::IsEmpty() const; -``` - -Returns `true` if the value is uninitialized. - -An empty value is invalid, and most attempts to perform an operation on an -empty value will result in an exception. An empty value is distinct from -JavaScript `null` or `undefined`, which are valid values. - -When C++ exceptions are disabled at compile time, a method with a `Napi::Value` -return type may return an empty value to indicate a pending exception. If C++ -exceptions are not being used, callers should check the result of -`Env::IsExceptionPending` before attempting to use the value. - -#### Type -```cpp -napi_valuetype Napi::Value::Type() const; -``` - -Returns the underlying N-API `napi_valuetype` of the value. - -#### IsUndefined -```cpp -bool Napi::Value::IsUndefined() const; -``` - -Returns `true` if the underlying value is a JavaScript `undefined` or `false` -otherwise. - -#### IsNull -```cpp -bool Napi::Value::IsNull() const; -``` - -Returns `true` if the underlying value is a JavaScript `null` or `false` -otherwise. - -#### IsBoolean -```cpp -bool Napi::Value::IsBoolean() const; -``` - -Returns `true` if the underlying value is a JavaScript `true` or JavaScript -`false`, or `false` if the value is not a `Napi::Boolean` value in JavaScript. - -#### IsNumber -```cpp -bool Napi::Value::IsNumber() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false` -otherwise. - -#### IsString -```cpp -bool Napi::Value::IsString() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::String` or `false` -otherwise. - -#### IsSymbol -```cpp -bool Napi::Value::IsSymbol() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false` -otherwise. - -#### IsArray -```cpp -bool Napi::Value::IsArray() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false` -otherwise. - -#### IsArrayBuffer -```cpp -bool Napi::Value::IsArrayBuffer() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or `false` -otherwise. - -#### IsTypedArray -```cpp -bool Napi::Value::IsTypedArray() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or `false` -otherwise. - -#### IsObject -```cpp -bool Napi::Value::IsObject() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false` -otherwise. - -#### IsFunction -```cpp -bool Napi::Value::IsFunction() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Function` or `false` -otherwise. - -#### IsPromise -```cpp -bool Napi::Value::IsPromise() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Promise` or `false` -otherwise. - -#### IsDataView -```cpp -bool Napi::Value::IsDataView() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::DataView` or `false` -otherwise. - -#### IsBuffer -```cpp -bool Napi::Value::IsBuffer() const; -``` - -Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false` -otherwise. - -#### IsExternal -```cpp -bool Napi::Value::IsExternal() const; -``` - -Returns `true` if the underlying value is a N-API external object or `false` -otherwise. - -#### IsDate -```cpp -bool Napi::Value::IsDate() const; -``` - -Returns `true` if the underlying value is a JavaScript `Date` or `false` -otherwise. - -#### ToBoolean -```cpp -Napi::Boolean Napi::Value::ToBoolean() const; -``` - -Returns a `Napi::Boolean` representing the `Napi::Value`. - -This is a wrapper around `napi_coerce_to_boolean`. This will throw a JavaScript -exception if the coercion fails. If C++ exceptions are not being used, callers -should check the result of `Env::IsExceptionPending` before attempting to use -the returned value. - -#### ToNumber -```cpp -Napi::Number Napi::Value::ToNumber() const; -``` - -Returns a `Napi::Number` representing the `Napi::Value`. - -Note: -This can cause script code to be executed according to JavaScript semantics. -This is a wrapper around `napi_coerce_to_number`. This will throw a JavaScript -exception if the coercion fails. If C++ exceptions are not being used, callers -should check the result of `Env::IsExceptionPending` before attempting to use -the returned value. - -#### ToString -```cpp -Napi::String Napi::Value::ToString() const; -``` - -Returns a `Napi::String` representing the `Napi::Value`. - -Note that this can cause script code to be executed according to JavaScript -semantics. This is a wrapper around `napi_coerce_to_string`. This will throw a -JavaScript exception if the coercion fails. If C++ exceptions are not being -used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -#### ToObject -```cpp -Napi::Object Napi::Value::ToObject() const; -``` - -Returns a `Napi::Object` representing the `Napi::Value`. - -This is a wrapper around `napi_coerce_to_object`. This will throw a JavaScript -exception if the coercion fails. If C++ exceptions are not being used, callers -should check the result of `Env::IsExceptionPending` before attempting to use -the returned value. - -## Name - -Names are JavaScript values that can be used as a property name. There are two -specialized types of names supported in Node.js Addon API [`Napi::String`](string.md) -and [`Napi::Symbol`](symbol.md). - -### Methods - -#### Constructor -```cpp -Napi::Name::Name(); -``` - -Returns an empty `Napi::Name`. - -```cpp -Napi::Name::Name(napi_env env, napi_value value); -``` -- `[in] env` - The environment in which to create the array. -- `[in] value` - The primitive to wrap. - -Returns a `Napi::Name` created from the JavaScript primitive. - -Note: -The value is not coerced to a string. - -## Array - -Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper -around `napi_value` representing a JavaScript Array. - -[`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 -```cpp -Napi::Array::Array(); -``` - -Returns an empty array. - -If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -```cpp -Napi::Array::Array(napi_env env, napi_value value); -``` -- `[in] env` - The environment in which to create the array. -- `[in] value` - The primitive to wrap. - -Returns a `Napi::Array` wrapping a `napi_value`. - -If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -### Methods - -#### New -```cpp -static Napi::Array Napi::Array::New(napi_env env); -``` -- `[in] env` - The environment in which to create the array. - -Returns a new `Napi::Array`. - -If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -#### New - -```cpp -static Napi::Array Napi::Array::New(napi_env env, size_t length); -``` -- `[in] env` - The environment in which to create the array. -- `[in] length` - The length of the array. - -Returns a new `Napi::Array` with the given length. - -If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -#### Length -```cpp -uint32_t Napi::Array::Length() const; -``` - -Returns the length of the array. - -Note: -This can execute JavaScript code implicitly according to JavaScript semantics. -If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -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 diff --git a/doc/bigint.md b/doc/bigint.md index 33ada43b3..d6f2ea68e 100644 --- a/doc/bigint.md +++ b/doc/bigint.md @@ -1,5 +1,7 @@ # BigInt +Class `Napi::Bigint` inherits from class [`Napi::Value`][]. + A JavaScript BigInt value. ## Methods @@ -91,3 +93,5 @@ void Napi::BigInt::ToWords(int* sign_bit, size_t* word_count, uint64_t* words); Returns a single `BigInt` value into a sign bit, 64-bit little-endian array, and the number of elements in the array. + +[`Napi::Value`]: ./value.md diff --git a/doc/boolean.md b/doc/boolean.md index 01b6a4c0a..6a8ec3f98 100644 --- a/doc/boolean.md +++ b/doc/boolean.md @@ -1,5 +1,7 @@ # Boolean +Class `Napi::Boolean` inherits from class [`Napi::Value`][]. + `Napi::Boolean` class is a representation of the JavaScript `Boolean` object. The `Napi::Boolean` class inherits its behavior from the `Napi::Value` class (for more info see: [`Napi::Value`](value.md)). @@ -16,7 +18,7 @@ Napi::Boolean::Boolean(); Returns a new _empty_ `Napi::Boolean` object. -### Contructor +### Constructor Creates a new instance of the `Napi::Boolean` object. @@ -62,3 +64,5 @@ Napi::Boolean::operator bool() const; ``` Returns the boolean primitive type of the corresponding `Napi::Boolean` object. + +[`Napi::Value`]: ./value.md diff --git a/doc/buffer.md b/doc/buffer.md index 8f76b200d..97ed48a5a 100644 --- a/doc/buffer.md +++ b/doc/buffer.md @@ -1,5 +1,7 @@ # Buffer +Class `Napi::Buffer` inherits from class [`Napi::Uint8Array`][]. + The `Napi::Buffer` class creates a projection of raw data that can be consumed by script. @@ -138,3 +140,5 @@ size_t Napi::Buffer::Length() const; ``` Returns the number of `T` elements in the external data. + +[`Napi::Uint8Array`]: ./typed_array_of.md diff --git a/doc/checker-tool.md b/doc/checker-tool.md index 499d3ab9d..135f13fd7 100644 --- a/doc/checker-tool.md +++ b/doc/checker-tool.md @@ -26,7 +26,7 @@ indicating for each addon whether it is an N-API addon. ``` The tool accepts the root directory from which to start checking for Node.js -native addons as a single optional command line parameter. If ommitted it will +native addons as a single optional command line parameter. If omitted it will start checking from the current directory (`.`). [checker tool]: ../tools/check-napi.js diff --git a/doc/creating_a_release.md b/doc/creating_a_release.md index beb67d287..5c8f8b025 100644 --- a/doc/creating_a_release.md +++ b/doc/creating_a_release.md @@ -36,7 +36,7 @@ the route folder of the repo launch the following command: ```bash > changelog-maker ``` -* Use the output generated by **changelog maker** to pdate the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/master/CHANGELOG.md) +* Use the output generated by **changelog maker** to update the [CHANGELOG.md](https://github.com/nodejs/node-addon-api/blob/master/CHANGELOG.md) following the style used in publishing the previous release. * Add any new contributors to the "contributors" section in the package.json diff --git a/doc/dataview.md b/doc/dataview.md index 64b865b1c..66fb28919 100644 --- a/doc/dataview.md +++ b/doc/dataview.md @@ -1,5 +1,7 @@ # DataView +Class `Napi::DataView` inherits from class [`Napi::Object`][]. + The `Napi::DataView` class corresponds to the [JavaScript `DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) class. @@ -242,3 +244,5 @@ void Napi::DataView::SetUint32(size_t byteOffset, uint32_t value) const; - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. + +[`Napi::Object`]: ./object.md diff --git a/doc/date.md b/doc/date.md index 959b4b9a6..4c5fefa5e 100644 --- a/doc/date.md +++ b/doc/date.md @@ -1,8 +1,8 @@ # Date `Napi::Date` class is a representation of the JavaScript `Date` object. The -`Napi::Date` class inherits its behavior from `Napi::Value` class -(for more info see [`Napi::Value`](value.md)) +`Napi::Date` class inherits its behavior from the `Napi::Value` class +(for more info see [`Napi::Value`](value.md)). ## Methods diff --git a/doc/error.md b/doc/error.md index 1526bddf0..7530262d7 100644 --- a/doc/error.md +++ b/doc/error.md @@ -1,5 +1,7 @@ # Error +Class `Napi::Error` inherits from class [`Napi::ObjectReference`][] and class [`std::exception`][]. + The `Napi::Error` class is a representation of the JavaScript `Error` object that is thrown when runtime errors occur. The Error object can also be used as a base object for user-defined exceptions. @@ -113,3 +115,6 @@ const char* Napi::Error::what() const NAPI_NOEXCEPT override; Returns a pointer to a null-terminated string that is used to identify the exception. This method can be used only if the exception mechanism is enabled. + +[`Napi::ObjectReference`]: ./object_reference.md +[`std::exception`]: http://cplusplus.com/reference/exception/exception/ diff --git a/doc/escapable_handle_scope.md b/doc/escapable_handle_scope.md index 978aab354..4f3e2d062 100644 --- a/doc/escapable_handle_scope.md +++ b/doc/escapable_handle_scope.md @@ -59,7 +59,7 @@ Napi::EscapableHandleScope::~EscapableHandleScope(); Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created in the scope to be collected by the garbage collector. There is no -guarantee as to when the gargbage collector will do this. +guarantee as to when the garbage collector will do this. ### Escape diff --git a/doc/external.md b/doc/external.md index 4022b61dd..814eb037c 100644 --- a/doc/external.md +++ b/doc/external.md @@ -1,5 +1,7 @@ # External (template) +Class `Napi::External` inherits from class [`Napi::Value`][]. + The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data. `Napi::External` objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your `Napi::External` object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function. @@ -57,3 +59,5 @@ T* Napi::External::Data() const; ``` Returns a pointer to the arbitrary C++ data held by the `Napi::External` object. + +[`Napi::Value`]: ./value.md diff --git a/doc/function.md b/doc/function.md index c1b0fc9fb..ddc089cf7 100644 --- a/doc/function.md +++ b/doc/function.md @@ -30,6 +30,7 @@ Value Fn(const CallbackInfo& info) { Object Init(Env env, Object exports) { exports.Set(String::New(env, "fn"), Function::New(env)); + return exports; } NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) @@ -217,7 +218,7 @@ Napi::Object Napi::Function::New(const std::initializer_list& args) ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing -the arguments of the contructor function. +the arguments of the constructor function. Returns a new JavaScript object. @@ -244,7 +245,7 @@ object. Napi::Object Napi::Function::New(size_t argc, const napi_value* args) const; ``` -- `[in] argc`: The number of the arguments passed to the contructor function. +- `[in] argc`: The number of the arguments passed to the constructor function. - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the constructor function. diff --git a/doc/function_reference.md b/doc/function_reference.md index 7b299b9bb..fa21830b8 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -73,7 +73,7 @@ Napi::Object Napi::FunctionReference::New(const std::initializer_list`][] | +| [`Napi::HandleScope`][] | | +| [`Napi::InstanceWrap`][] | | +| [`Napi::MemoryManagement`][] | | +| [`Napi::Name`][] | [`Napi::Value`][] | +| [`Napi::Number`][] | [`Napi::Value`][] | +| [`Napi::Object`][] | [`Napi::Value`][] | +| [`Napi::ObjectReference`][] | [`Napi::Reference`][] | +| [`Napi::ObjectWrap`][] | [`Napi::InstanceWrap`][], [`Napi::Reference`][] | +| [`Napi::Promise`][] | [`Napi::Object`][] | +| [`Napi::PropertyDescriptor`][] | | +| [`Napi::RangeError`][] | [`Napi::Error`][] | +| [`Napi::Reference`] | | +| [`Napi::String`][] | [`Napi::Name`][] | +| [`Napi::Symbol`][] | [`Napi::Name`][] | +| [`Napi::ThreadSafeFunction`][] | | +| [`Napi::TypeError`][] | [`Napi::Error`][] | +| [`Napi::TypedArray`][] | [`Napi::Object`][] | +| [`Napi::TypedArrayOf`][] | [`Napi::TypedArray`][] | +| [`Napi::Value`][] | | +| [`Napi::VersionManagement`][] | | + +[`Napi::Addon`]: ./addon.md +[`Napi::Array`]: ./array.md +[`Napi::ArrayBuffer`]: ./array_buffer.md +[`Napi::AsyncContext`]: ./async_context.md +[`Napi::AsyncProgressQueueWorker`]: ./async_worker_variants.md#asyncprogressqueueworker +[`Napi::AsyncProgressWorker`]: ./async_worker_variants.md#asyncprogressworker +[`Napi::AsyncWorker`]: ./async_worker.md +[`Napi::BigInt`]: ./bigint.md +[`Napi::Boolean`]: ./boolean.md +[`Napi::Buffer`]: ./buffer.md +[`Napi::CallbackInfo`]: ./callbackinfo.md +[`Napi::CallbackScope`]: ./callback_scope.md +[`Napi::ClassPropertyDescriptor`]: ./class_property_descriptor.md +[`Napi::DataView`]: ./dataview.md +[`Napi::Date`]: ./date.md +[`Napi::Env`]: ./env.md +[`Napi::Error`]: ./error.md +[`Napi::EscapableHandleScope`]: ./escapable_handle_scope.md +[`Napi::External`]: ./external.md +[`Napi::Function`]: ./function.md +[`Napi::FunctionReference`]: ./function_reference.md +[`Napi::HandleScope`]: ./handle_scope.md +[`Napi::InstanceWrap`]: ./instance_wrap.md +[`Napi::MemoryManagement`]: ./memory_management.md +[`Napi::Name`]: ./name.md +[`Napi::Number`]: ./number.md +[`Napi::Object`]: ./object.md +[`Napi::ObjectReference`]: ./object_reference.md +[`Napi::ObjectWrap`]: ./object_wrap.md +[`Napi::Promise`]: ./promise.md +[`Napi::PropertyDescriptor`]: ./property_descriptor.md +[`Napi::RangeError`]: ./range_error.md +[`Napi::Reference`]: ./reference.md +[`Napi::Reference`]: ./reference.md +[`Napi::Reference`]: ./reference.md +[`Napi::String`]: ./string.md +[`Napi::Symbol`]: ./symbol.md +[`Napi::ThreadSafeFunction`]: ./thread_safe_function.md +[`Napi::TypeError`]: ./type_error.md +[`Napi::TypedArray`]: ./typed_array.md +[`Napi::TypedArrayOf`]: ./typed_array_of.md +[`Napi::Uint8Array`]: ./typed_array_of.md +[`Napi::Value`]: ./value.md +[`Napi::VersionManagement`]: ./version_management.md +[`std::exception`]: http://cplusplus.com/reference/exception/exception/ diff --git a/doc/instance_wrap.md b/doc/instance_wrap.md new file mode 100644 index 000000000..1238e7e29 --- /dev/null +++ b/doc/instance_wrap.md @@ -0,0 +1,408 @@ +# InstanceWrap + +This class serves as the base class for [`Napi::ObjectWrap`][] and +[`Napi::Addon`][]. + +In the case of [`Napi::Addon`][] it provides the +methods for exposing functions to JavaScript on instances of an add-on. + +As a base class for [`Napi::ObjectWrap`][] it provides the methods for +exposing instance methods of JavaScript objects instantiated from the JavaScript +class corresponding to the subclass of [`Napi::ObjectWrap`][]. + +## Methods + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +template +static Napi::ClassPropertyDescriptor +Napi::InstanceWrap::InstanceMethod(const char* utf8name, + InstanceVoidMethodCallback method, + napi_property_attributes attributes = napi_default, + void* data = nullptr); +``` + +- `[in] utf8name`: Null-terminated string that represents the name of the method +provided by instances of the class. +- `[in] method`: The native function that represents a method provided by the +add-on. +- `[in] attributes`: The attributes associated with the property. One or more of +`napi_property_attributes`. +- `[in] data`: User-provided data passed into the method when it is invoked. + +Returns a `Napi::ClassPropertyDescriptor` object that represents a method +provided by instances of the class. The method must be of the form + +```cpp +void MethodName(const Napi::CallbackInfo& info); +``` + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +template +static Napi::ClassPropertyDescriptor +Napi::InstanceWrap::InstanceMethod(const char* utf8name, + InstanceMethodCallback method, + napi_property_attributes attributes = napi_default, + void* data = nullptr); +``` + +- `[in] utf8name`: Null-terminated string that represents the name of the method +provided by instances of the class. +- `[in] method`: The native function that represents a method provided by the +add-on. +- `[in] attributes`: The attributes associated with the property. One or more of +`napi_property_attributes`. +- `[in] data`: User-provided data passed into the method when it is invoked. + +Returns a `Napi::ClassPropertyDescriptor` object that represents a method +provided by instances of the class. The method must be of the form + +```cpp +Napi::Value MethodName(const Napi::CallbackInfo& info); +``` + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +template +static Napi::ClassPropertyDescriptor +Napi::InstanceWrap::InstanceMethod(Napi::Symbol name, + InstanceVoidMethodCallback method, + napi_property_attributes attributes = napi_default, + void* data = nullptr); +``` + +- `[in] name`: JavaScript symbol that represents the name of the method provided +by instances of the class. +- `[in] method`: The native function that represents a method provided by the +add-on. +- `[in] attributes`: The attributes associated with the property. One or more of +`napi_property_attributes`. +- `[in] data`: User-provided data passed into the method when it is invoked. + +Returns a `Napi::ClassPropertyDescriptor` object that represents a method +provided by instances of the class. The method must be of the form + +```cpp +void MethodName(const Napi::CallbackInfo& info); +``` + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +template +static Napi::ClassPropertyDescriptor +Napi::InstanceWrap::InstanceMethod(Napi::Symbol name, + InstanceMethodCallback method, + napi_property_attributes attributes = napi_default, + void* data = nullptr); +``` + +- `[in] name`: JavaScript symbol that represents the name of the method provided +by instances of the class. +- `[in] method`: The native function that represents a method provided by the +add-on. +- `[in] attributes`: The attributes associated with the property. One or more of +`napi_property_attributes`. +- `[in] data`: User-provided data passed into the method when it is invoked. + +Returns a `Napi::ClassPropertyDescriptor` object that represents a method +provided by instances of the class. The method must be of the form + +```cpp +Napi::Value MethodName(const Napi::CallbackInfo& info); +``` + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +