Socket
Socket
Sign inDemoInstall

node-addon-api

Package Overview
Dependencies
0
Maintainers
5
Versions
44
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

Comparing version 1.4.0 to 1.5.0

doc/async_context.md

69

CHANGELOG.md
# node-addon-api Changelog
## 2018-07-19 Version 1.4.0 (Current), @NickNasso
## 2018-10-03 Version 1.5.0 (Current), @NickNasso

@@ -9,2 +9,67 @@ ### Notable changes:

- Completed the documentation to cover all the API surface.
- Numerous fixes to make documentation more consistent in all of its parts.
#### API
- Add `Napi::AsyncContext` class to handle asynchronous operation.
- Add B`Napi::igInt` class to work with BigInt type.
- Add `Napi::VersionManagement` class to retrieve the versions of Node.js and N-API.
- Fix potential memory leaks.
- DataView feature is enabled by default
- Add descriptor for Symbols
- Add new methods on `Napi::FunctionReference`.
- Add the possibility to retrieve the environment on `Napi::Promise::Deferred`
#### TOOL
- Add tool to check if a native add-on is built using N-API
#### TEST
- Start to increase the test coverage
- Fix in the test suite to better handle the experimental features that are not
yet backported in the previous Node.js version.
### Commits
* [[`2009c019af`](https://github.com/nodejs/node-addon-api/commit/2009c019af)] - Merge pull request #292 from devsnek/feature/bigint (Gus Caplan)
* [[`e44aca985e`](https://github.com/nodejs/node-addon-api/commit/e44aca985e)] - add bigint class (Gus Caplan)
* [[`a3951ab973`](https://github.com/nodejs/node-addon-api/commit/a3951ab973)] - Add documentation for Env(). (Rolf Timmermans) [#318](https://github.com/nodejs/node-addon-api/pull/318)
* [[`a6f7a6ad51`](https://github.com/nodejs/node-addon-api/commit/a6f7a6ad51)] - Add Env() to Promise::Deferred. (Rolf Timmermans)
* [[`0097e96b92`](https://github.com/nodejs/node-addon-api/commit/0097e96b92)] - Fixed broken links for Symbol and String (NickNaso)
* [[`b0ecd38d76`](https://github.com/nodejs/node-addon-api/commit/b0ecd38d76)] - Fix Code of conduct link properly (#323) (Jake Yoon) [#323](https://github.com/nodejs/node-addon-api/pull/323)
* [[`223474900f`](https://github.com/nodejs/node-addon-api/commit/223474900f)] - **doc**: update Version management (Dongjin Na) [#360](https://github.com/nodejs/node-addon-api/pull/360)
* [[`4f76262a10`](https://github.com/nodejs/node-addon-api/commit/4f76262a10)] - **doc**: some fix on `Napi::Boolean` documentation (NickNaso) [#354](https://github.com/nodejs/node-addon-api/pull/354)
* [[`78374f72d2`](https://github.com/nodejs/node-addon-api/commit/78374f72d2)] - **doc**: number documentation (NickNaso) [#356](https://github.com/nodejs/node-addon-api/pull/356)
* [[`51ffe453f8`](https://github.com/nodejs/node-addon-api/commit/51ffe453f8)] - **doc**: doc cleanup (NickNaso) [#353](https://github.com/nodejs/node-addon-api/pull/353)
* [[`fc11c944b2`](https://github.com/nodejs/node-addon-api/commit/fc11c944b2)] - **doc**: major doc cleanup (NickNaso) [#335](https://github.com/nodejs/node-addon-api/pull/335)
* [[`100d0a7cb2`](https://github.com/nodejs/node-addon-api/commit/100d0a7cb2)] - **doc**: first pass on objectwrap documentation (NickNaso) [#321](https://github.com/nodejs/node-addon-api/pull/321)
* [[`c7d54180ff`](https://github.com/nodejs/node-addon-api/commit/c7d54180ff)] - **doc**: the Napi::ObjectWrap example does not compile (Arnaud Botella) [#339](https://github.com/nodejs/node-addon-api/pull/339)
* [[`7cdd78726a`](https://github.com/nodejs/node-addon-api/commit/7cdd78726a)] - **doc**: added cpp highlight for string.md (Jaeseok Yoon) [#329](https://github.com/nodejs/node-addon-api/pull/329)
* [[`8ed29f547c`](https://github.com/nodejs/node-addon-api/commit/8ed29f547c)] - **doc**: add blurb about ABI stability (Gabriel Schulhof) [#326](https://github.com/nodejs/node-addon-api/pull/326)
* [[`757eb1f5a3`](https://github.com/nodejs/node-addon-api/commit/757eb1f5a3)] - **doc**: add function and function reference doc (NickNaso) [#299](https://github.com/nodejs/node-addon-api/pull/299)
* [[`2885c18591`](https://github.com/nodejs/node-addon-api/commit/2885c18591)] - **doc**: Create changelog for release 1.4.0 (Nicola Del Gobbo)
* [[`917bd60baa`](https://github.com/nodejs/node-addon-api/commit/917bd60baa)] - **src**: remove TODOs by fixing memory leaks (Gabriel Schulhof) [#343](https://github.com/nodejs/node-addon-api/pull/343)
* [[`dfcb93945f`](https://github.com/nodejs/node-addon-api/commit/dfcb93945f)] - **src**: implement AsyncContext class (Jinho Bang) [#252](https://github.com/nodejs/node-addon-api/pull/252)
* [[`211ed38d0d`](https://github.com/nodejs/node-addon-api/commit/211ed38d0d)] - **src**: make 'nothing' target a static library (Gabriel Schulhof) [#348](https://github.com/nodejs/node-addon-api/pull/348)
* [[`97c4ab5cf2`](https://github.com/nodejs/node-addon-api/commit/97c4ab5cf2)] - **src**: add Call and MakeCallback that accept cargs (NickNaso) [#344](https://github.com/nodejs/node-addon-api/pull/344)
* [[`b6e2d92c09`](https://github.com/nodejs/node-addon-api/commit/b6e2d92c09)] - **src**: enable DataView feature by default (Jinho) [#331](https://github.com/nodejs/node-addon-api/pull/331)
* [[`0a00e7c97b`](https://github.com/nodejs/node-addon-api/commit/0a00e7c97b)] - **src**: implement missing descriptor defs for symbols (Philipp Renoth) [#280](https://github.com/nodejs/node-addon-api/pull/280)
* [[`38e01b7e3b`](https://github.com/nodejs/node-addon-api/commit/38e01b7e3b)] - **src**: first pass on adding version management apis (NickNaso) [#325](https://github.com/nodejs/node-addon-api/pull/325)
* [[`79ee8381d2`](https://github.com/nodejs/node-addon-api/commit/79ee8381d2)] - **src**: fix compile failure in test (Michael Dawson) [#345](https://github.com/nodejs/node-addon-api/pull/345)
* [[`4d92a6066f`](https://github.com/nodejs/node-addon-api/commit/4d92a6066f)] - **src**: Add ObjectReference test case (Anisha Rohra) [#212](https://github.com/nodejs/node-addon-api/pull/212)
* [[`779560f397`](https://github.com/nodejs/node-addon-api/commit/779560f397)] - **test**: add operator overloading tests in Number (Your Name) [#355](https://github.com/nodejs/node-addon-api/pull/355)
* [[`73fed84ceb`](https://github.com/nodejs/node-addon-api/commit/73fed84ceb)] - **test**: add ability to control experimental tests (Michael Dawson) [#350](https://github.com/nodejs/node-addon-api/pull/350)
* [[`14c69abd46`](https://github.com/nodejs/node-addon-api/commit/14c69abd46)] - **test**: write tests for Boolean class (Jaeseok Yoon) [#328](https://github.com/nodejs/node-addon-api/pull/328)
* [[`2ad47a83b1`](https://github.com/nodejs/node-addon-api/commit/2ad47a83b1)] - **test**: explicitly cast to uint32\_t in test (Gabriel Schulhof) [#341](https://github.com/nodejs/node-addon-api/pull/341)
* [[`622ffaea76`](https://github.com/nodejs/node-addon-api/commit/622ffaea76)] - **test**: Tighten up compiler warnings (Mikhail Cheshkov) [#315](https://github.com/nodejs/node-addon-api/pull/315)
* [[`fd3c37b0f2`](https://github.com/nodejs/node-addon-api/commit/fd3c37b0f2)] - **tools**: add tool to check for N-API modules (Gabriel Schulhof) [#346](https://github.com/nodejs/node-addon-api/pull/346)
## 2018-07-19 Version 1.4.0, @NickNasso
### Notable changes:
#### Documentation
- Numerous additions to the documentation, filling out coverage

@@ -65,3 +130,3 @@ of API surface

#### Tests
- Fix test failures on linuxOne and AIX
- Fix test failures on linuxOne and AIX
- Added basic tests for Scopes

@@ -68,0 +133,0 @@ - Fix MSVC warning C4244 in tests

2

CODE_OF_CONDUCT.md
# Code of Conduct
The Node.js Code of Conduct, which applies to this project, can be found at
https://github.com/nodejs/TSC/blob/master/CODE_OF_CONDUCT.md.
https://github.com/nodejs/admin/blob/master/CODE_OF_CONDUCT.md.
# ArrayBuffer
The `ArrayBuffer` class corresponds to the
The `Napi::ArrayBuffer` class corresponds to the
[JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)

@@ -11,44 +11,44 @@ class.

Allocates a new `ArrayBuffer` instance with a given length.
Allocates a new `Napi::ArrayBuffer` instance with a given length.
```cpp
static ArrayBuffer New(napi_env env, size_t byteLength);
static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, size_t byteLength);
```
- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
- `[in] byteLength`: The length to be allocated, in bytes.
Returns a new `ArrayBuffer` instance.
Returns a new `Napi::ArrayBuffer` instance.
### New
Wraps the provided external data into a new `ArrayBuffer` instance.
Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
The `ArrayBuffer` instance does not assume ownership for the data and expects it
to be valid for the lifetime of the instance. Since the `ArrayBuffer` is subject
to garbage collection this overload is only suitable for data which is static
and never needs to be freed.
The `Napi::ArrayBuffer` instance does not assume ownership for the data and
expects it to be valid for the lifetime of the instance. Since the
`Napi::ArrayBuffer` is subject to garbage collection this overload is only
suitable for data which is static and never needs to be freed.
```cpp
static ArrayBuffer New(napi_env env, void* externalData, size_t byteLength);
static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength);
```
- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
- `[in] externalData`: The pointer to the external data to wrap.
- `[in] byteLength`: The length of the `externalData`, in bytes.
Returns a new `ArrayBuffer` instance.
Returns a new `Napi::ArrayBuffer` instance.
### New
Wraps the provided external data into a new `ArrayBuffer` instance.
Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
The `ArrayBuffer` instance does not assume ownership for the data and expects it
to be valid for the lifetime of the instance. The data can only be freed once
the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
released.
The `Napi::ArrayBuffer` instance does not assume ownership for the data and
expects it to be valid for the lifetime of the instance. The data can only be
freed once the `finalizeCallback` is invoked to indicate that the
`Napi::ArrayBuffer` has been released.
```cpp
template <typename Finalizer>
static ArrayBuffer New(napi_env env,
static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
void* externalData,

@@ -59,18 +59,18 @@ size_t byteLength,

- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
- `[in] externalData`: The pointer to the external data to wrap.
- `[in] byteLength`: The length of the `externalData`, in bytes.
- `[in] finalizeCallback`: A function to be called when the `ArrayBuffer` is
- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()`, accept a `void*` (which is the
`externalData` pointer), and return `void`.
Returns a new `ArrayBuffer` instance.
Returns a new `Napi::ArrayBuffer` instance.
### New
Wraps the provided external data into a new `ArrayBuffer` instance.
Wraps the provided external data into a new `Napi::ArrayBuffer` instance.
The `ArrayBuffer` instance does not assume ownership for the data and expects it
The `Napi::ArrayBuffer` instance does not assume ownership for the data and expects it
to be valid for the lifetime of the instance. The data can only be freed once
the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been
the `finalizeCallback` is invoked to indicate that the `Napi::ArrayBuffer` has been
released.

@@ -80,3 +80,3 @@

template <typename Finalizer, typename Hint>
static ArrayBuffer New(napi_env env,
static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env,
void* externalData,

@@ -88,6 +88,6 @@ size_t byteLength,

- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
- `[in] externalData`: The pointer to the external data to wrap.
- `[in] byteLength`: The length of the `externalData`, in bytes.
- `[in] finalizeCallback`: The function to be called when the `ArrayBuffer` is
- `[in] finalizeCallback`: The function to be called when the `Napi::ArrayBuffer` is
destroyed. It must implement `operator()`, accept a `void*` (which is the

@@ -98,10 +98,10 @@ `externalData` pointer) and `Hint*`, and return `void`.

Returns a new `ArrayBuffer` instance.
Returns a new `Napi::ArrayBuffer` instance.
### Constructor
Initializes an empty instance of the `ArrayBuffer` class.
Initializes an empty instance of the `Napi::ArrayBuffer` class.
```cpp
ArrayBuffer();
Napi::ArrayBuffer::ArrayBuffer();
```

@@ -111,10 +111,10 @@

Initializes a wrapper instance of an existing `ArrayBuffer` object.
Initializes a wrapper instance of an existing `Napi::ArrayBuffer` object.
```cpp
ArrayBuffer(napi_env env, napi_value value);
Napi::ArrayBuffer::ArrayBuffer(napi_env env, napi_value value);
```
- `[in] env`: The environment in which to create the `ArrayBuffer` instance.
- `[in] value`: The `ArrayBuffer` reference to wrap.
- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance.
- `[in] value`: The `Napi::ArrayBuffer` reference to wrap.

@@ -124,3 +124,3 @@ ### ByteLength

```cpp
size_t ByteLength() const;
size_t Napi::ArrayBuffer::ByteLength() const;
```

@@ -133,5 +133,5 @@

```cpp
T* Data() const;
T* Napi::ArrayBuffer::Data() const;
```
Returns a pointer the wrapped data.

@@ -20,5 +20,11 @@ # Asynchronous operations

- **[AsyncWorker](async_worker.md)**
- **[`Napi::AsyncWorker`](async_worker.md)**
These class helps manage asynchronous operations through an abstraction
of the concept of moving data between the **event loop** and **worker threads**.
Also, the above class may not be appropriate for every scenario. When using any
other asynchronous mechanism, the following API is necessary to ensure an
asynchronous operation is properly tracked by the runtime:
- **[AsyncContext](async_context.md)**
# AsyncWorker
`AsyncWorker` is an abstract class that you can subclass to remove many of the
tedious tasks of moving data between the event loop and worker threads. This
`Napi::AsyncWorker` is an abstract class that you can subclass to remove many of
the tedious tasks of moving data between the event loop and worker threads. This
class internally handles all the details of creating and executing an asynchronous
operation.
Once created, execution is requested by calling `Queue`. When a thread is
available for execution the `Execute` method will be invoked. Once `Execute`
complets either `OnOK` or `OnError` will be invoked. Once the `OnOK` or
`OnError` methods are complete the AsyncWorker instance is destructed.
Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When
a thread is available for execution the `Napi::AsyncWorker::Execute` method will
be invoked. Once `Napi::AsyncWorker::Execute` completes either
`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once
the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are
complete the `Napi::AsyncWorker` instance is destructed.
For the most basic use, only the `Execute` method must be implemented in a
subclass.
For the most basic use, only the `Napi::AsyncWorker::Execute` method must be
implemented in a subclass.

@@ -23,3 +25,3 @@ ## Methods

```cpp
Env Env() const;
Napi::Env Napi::AsyncWorker::Env() const;
```

@@ -34,3 +36,3 @@

```cpp
void Queue();
void Napi::AsyncWorker::Queue();
```

@@ -45,3 +47,3 @@

```cpp
void Cancel();
void Napi::AsyncWorker::Cancel();
```

@@ -52,3 +54,3 @@

```cpp
ObjectReference& Receiver();
Napi::ObjectReference& Napi::AsyncWorker::Receiver();
```

@@ -62,3 +64,3 @@

```cpp
FunctionReference& Callback();
Napi::FunctionReference& Napi::AsyncWorker::Callback();
```

@@ -68,4 +70,5 @@

worker was created. The returned function reference will receive the results of
the computation that happened in the `Execute` method, unless the default
implementation of `OnOK` or `OnError` is overridden.
the computation that happened in the `Napi::AsyncWorker::Execute` method, unless
the default implementation of `Napi::AsyncWorker::OnOK` or
`Napi::AsyncWorker::OnError` is overridden.

@@ -75,7 +78,8 @@ ### SetError

Sets the error message for the error that happened during the execution. Setting
an error message will cause the `OnError` method to be invoked instead of `OnOK`
once the `Execute` method completes.
an error message will cause the `Napi::AsyncWorker::OnError` method to be
invoked instead of `Napi::AsyncWorker::OnOKOnOK` once the
`Napi::AsyncWorker::Execute` method completes.
```cpp
void SetError(const std::string& error);
void Napi::AsyncWorker::SetError(const std::string& error);
```

@@ -91,9 +95,9 @@

running on the main event loop, it must avoid calling any methods from node-addon-api
or running any code that might invoke JavaScript. Instead once this method is
or running any code that might invoke JavaScript. Instead, once this method is
complete any interaction through node-addon-api with JavaScript should be implemented
in the `OnOK` method which runs on the main thread and is invoked when the `Execute`
method completes.
in the `Napi::AsyncWorker::OnOK` method which runs on the main thread and is
invoked when the `Napi::AsyncWorker::Execute` method completes.
```cpp
virtual void Execute() = 0;
virtual void Napi::AsyncWorker::Execute() = 0;
```

@@ -108,3 +112,3 @@

```cpp
virtual void OnOK();
virtual void Napi::AsyncWorker::OnOK();
```

@@ -114,10 +118,10 @@

This method is invoked afer Execute() completes if an error occurs
while `Execute` is running and C++ exceptions are enabled or if an
error was set through a call to `SetError`. The default implementation
calls the callback provided when the AsyncWorker class was created, passing
in the error as the first parameter.
This method is invoked afer `Napi::AsyncWorker::Execute` completes if an error
occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are
enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`.
The default implementation calls the callback provided when the `Napi::AsyncWorker`
class was created, passing in the error as the first parameter.
```cpp
virtual void OnError(const Error& e);
virtual void Napi::AsyncWorker::OnError(const Napi::Error& e);
```

@@ -127,6 +131,6 @@

Creates a new `AsyncWorker`.
Creates a new `Napi::AsyncWorker`.
```cpp
explicit AsyncWorker(const Function& callback);
explicit Napi::AsyncWorker(const Napi::Function& callback);
```

@@ -137,3 +141,3 @@

Returns an AsyncWork instance which can later be queued for execution by calling
Returns a`Napi::AsyncWork` instance which can later be queued for execution by calling
`Queue`.

@@ -143,6 +147,6 @@

Creates a new `AsyncWorker`.
Creates a new `Napi::AsyncWorker`.
```cpp
explicit AsyncWorker(const Function& callback, const char* resource_name);
explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_name);
```

@@ -156,12 +160,11 @@

Returns an AsyncWork instance which can later be queued for execution by calling
`Queue`.
Returns a `Napi::AsyncWork` instance which can later be queued for execution by
calling `Napi::AsyncWork::Queue`.
### Constructor
Creates a new `AsyncWorker`.
Creates a new `Napi::AsyncWorker`.
```cpp
explicit AsyncWorker(const Function& callback, const char* resource_name, const Object& resource);
explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_name, const Napi::Object& resource);
```

@@ -177,11 +180,11 @@

Returns an AsyncWork instance which can later be queued for execution by calling
`Queue`.
Returns a `Napi::AsyncWork` instance which can later be queued for execution by
calling `Napi::AsyncWork::Queue`.
### Constructor
Creates a new `AsyncWorker`.
Creates a new `Napi::AsyncWorker`.
```cpp
explicit AsyncWorker(const Object& receiver, const Function& callback);
explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback);
```

@@ -193,12 +196,11 @@

Returns an AsyncWork instance which can later be queued for execution by calling
`Queue`.
Returns a `Napi::AsyncWork` instance which can later be queued for execution by
calling `Napi::AsyncWork::Queue`.
### Constructor
Creates a new `AsyncWorker`.
Creates a new `Napi::AsyncWorker`.
```cpp
explicit AsyncWorker(const Object& receiver, const Function& callback,const char* resource_name);
explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback,const char* resource_name);
```

@@ -213,12 +215,11 @@

Returns an AsyncWork instance which can later be queued for execution by calling
`Queue`.
Returns a `Napi::AsyncWork` instance which can later be queued for execution by
calling `Napi::AsyncWork::Queue`.
### Constructor
Creates a new `AsyncWorker`.
Creates a new `Napi::AsyncWorker`.
```cpp
explicit AsyncWorker(const Object& receiver, const Function& callback, const char* resource_name, const Object& resource);
explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name, const Napi::Object& resource);
```

@@ -235,4 +236,4 @@

Returns an AsyncWork instance which can later be queued for execution by calling
`Queue`.
Returns a `Napi::AsyncWork` instance which can later be queued for execution by
calling `Napi::AsyncWork::Queue`.

@@ -244,3 +245,3 @@ ### Destructor

```cpp
virtual ~AsyncWorker();
virtual Napi::AsyncWorker::~AsyncWorker();
```

@@ -251,24 +252,26 @@

```cpp
operator napi_async_work() const;
Napi::AsyncWorker::operator napi_async_work() const;
```
Returns the N-API napi_async_work wrapped by the AsyncWorker object. This can be
used to mix usage of the C N-API and node-addon-api.
Returns the N-API napi_async_work wrapped by the `Napi::AsyncWorker` object. This
can be used to mix usage of the C N-API and node-addon-api.
## Example
The first step to use the `AsyncWorker` class is to create a new class that inherit
from it and implement the `Execute` abstract method. Typically input to your
worker will be saved within class' fields generally passed in through its
constructor.
The first step to use the `Napi::AsyncWorker` class is to create a new class that
inherits from it and implement the `Napi::AsyncWorker::Execute` abstract method.
Typically input to your worker will be saved within class' fields generally
passed in through its constructor.
When the `Execute` method completes without errors the `OnOK` function callback
will be invoked. In this function the results of the computation will be
reassembled and returned back to the initial JavaScript context.
When the `Napi::AsyncWorker::Execute` method completes without errors the
`Napi::AsyncWorker::OnOK` function callback will be invoked. In this function the
results of the computation will be reassembled and returned back to the initial
JavaScript context.
`AsyncWorker` ensures that all the code in the `Execute` function runs in the
background out of the **event loop** thread and at the end the `OnOK` or `OnError`
function will be called and are executed as part of the event loop.
`Napi::AsyncWorker` ensures that all the code in the `Napi::AsyncWorker::Execute`
function runs in the background out of the **event loop** thread and at the end
the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` function will be
called and are executed as part of the event loop.
The code below show a basic example of `AsyncWorker` the implementation:
The code below show a basic example of `Napi::AsyncWorker` the implementation:

@@ -306,9 +309,17 @@ ```cpp

The `EchoWorker`'s contructor calls the base class' constructor to pass in the
callback that the `AsyncWorker` base class will store persistently. When the work
on the `Execute` method is done the `OnOk` method is called and the results return
back to JavaScript invoking the stored callback with its associated environment.
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
JavaScript invoking the stored callback with its associated environment.
The following code shows an example on how to create and and use an `AsyncWorker`
The following code shows an example on how to create and and use an `Napi::AsyncWorker`
```cpp
#include<napi.h>
// Include EchoWorker class
// ..
use namespace Napi;
Value Echo(const CallbackInfo& info) {

@@ -323,6 +334,6 @@ // You need to check the input data here

Using the implementation of an `AsyncWorker` is straight forward. You need only create
a new instance and pass to its constructor the callback you want to execute when
your asynchronous task ends and other data you need for your computation. Once created the
only other action you have to do is to call the `Queue` method that will that will
queue the created worker for execution.
Using the implementation of a `Napi::AsyncWorker` is straight forward. You only
need to create a new instance and pass to its constructor the callback you want to
execute when your asynchronous task ends and other data you need for your
computation. Once created the only other action you have to do is to call the
`Napi::AsyncWorker::Queue` method that will queue the created worker for execution.

@@ -9,3 +9,3 @@ # Basic Types

Value is the base class of Node Addon API's fundamental object type hierarchy.
`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

@@ -19,17 +19,17 @@ the N-API datatype `napi_value`. Methods on this class can be used to check

```cpp
Value();
Napi::Value::Value();
```
Used to create a Node Addon API `Value` that represents an **empty** value.
Used to create a Node Addon API `Napi::Value` that represents an **empty** value.
```cpp
Value(napi_env env, napi_value value);
Napi::Value::Value(napi_env env, napi_value value);
```
- `[in] env` - The `napi_env` environment in which to construct the Value
- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value`
object.
- `[in] value` - The underlying JavaScript value that the `Value` instance
- `[in] value` - The underlying JavaScript value that the `Napi::Value` instance
represents.
Returns a Node.js Addon API `Value` that represents the `napi_value` passed
Returns a Node.js Addon API `Napi::Value` that represents the `napi_value` passed
in.

@@ -42,3 +42,3 @@

```cpp
operator napi_value() const;
Napi::Value::operator napi_value() const;
```

@@ -52,3 +52,3 @@

```cpp
bool operator ==(const Value& other) const;
bool Napi::Value::operator ==(const Value& other) const;
```

@@ -61,3 +61,3 @@

```cpp
bool operator !=(const Value& other) const;
bool Napi::Value::operator !=(const Value& other) const;
```

@@ -72,6 +72,6 @@

template <typename T>
static Value From(napi_env env, const T& value);
static Napi::Value Napi::Value::From(napi_env env, const T& value);
```
- `[in] env` - The `napi_env` environment in which to construct the Value object.
- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` object.
- `[in] value` - The C++ type to represent in JavaScript.

@@ -95,3 +95,3 @@

```cpp
template <typename T> T As() const;
template <typename T> T Napi::Value::As() const;
```

@@ -109,3 +109,3 @@

```cpp
bool StrictEquals(const Value& other) const;
bool Napi::Value::StrictEquals(const Value& other) const;
```

@@ -119,3 +119,3 @@

```cpp
Napi::Env Env() const;
Napi::Env Napi::Value::Env() const;
```

@@ -128,3 +128,3 @@

```cpp
bool IsEmpty() const;
bool Napi::Value::IsEmpty() const;
```

@@ -138,3 +138,3 @@

When C++ exceptions are disabled at compile time, a method with a `Value`
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++

@@ -146,3 +146,3 @@ exceptions are not being used, callers should check the result of

```cpp
napi_valuetype Type() const;
napi_valuetype Napi::Value::Type() const;
```

@@ -154,3 +154,3 @@

```cpp
bool IsUndefined() const;
bool Napi::Value::IsUndefined() const;
```

@@ -163,3 +163,3 @@

```cpp
bool IsNull() const;
bool Napi::Value::IsNull() const;
```

@@ -172,14 +172,14 @@

```cpp
bool IsBoolean() const;
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 Boolean value in JavaScript.
`false`, or `false` if the value is not a `Napi::Boolean` value in JavaScript.
#### IsNumber
```cpp
bool IsNumber() const;
bool Napi::Value::IsNumber() const;
```
Returns `true` if the underlying value is a JavaScript `Number` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false`
otherwise.

@@ -189,6 +189,6 @@

```cpp
bool IsString() const;
bool Napi::Value::IsString() const;
```
Returns `true` if the underlying value is a JavaScript `String` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::String` or `false`
otherwise.

@@ -198,6 +198,6 @@

```cpp
bool IsSymbol() const;
bool Napi::Value::IsSymbol() const;
```
Returns `true` if the underlying value is a JavaScript `Symbol` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false`
otherwise.

@@ -207,6 +207,6 @@

```cpp
bool IsArray() const;
bool Napi::Value::IsArray() const;
```
Returns `true` if the underlying value is a JavaScript `Array` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false`
otherwise.

@@ -216,6 +216,6 @@

```cpp
bool IsArrayBuffer() const;
bool Napi::Value::IsArrayBuffer() const;
```
Returns `true` if the underlying value is a JavaScript `ArrayBuffer` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or `false`
otherwise.

@@ -225,6 +225,6 @@

```cpp
bool IsTypedArray() const;
bool Napi::Value::IsTypedArray() const;
```
Returns `true` if the underlying value is a JavaScript `TypedArray` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or `false`
otherwise.

@@ -234,6 +234,6 @@

```cpp
bool IsObject() const;
bool Napi::Value::IsObject() const;
```
Returns `true` if the underlying value is a JavaScript `Object` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false`
otherwise.

@@ -243,6 +243,6 @@

```cpp
bool IsFunction() const;
bool Napi::Value::IsFunction() const;
```
Returns `true` if the underlying value is a JavaScript `Function` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::Function` or `false`
otherwise.

@@ -252,6 +252,6 @@

```cpp
bool IsPromise() const;
bool Napi::Value::IsPromise() const;
```
Returns `true` if the underlying value is a JavaScript `Promise` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::Promise` or `false`
otherwise.

@@ -261,6 +261,6 @@

```cpp
bool IsDataView() const;
bool Napi::Value::IsDataView() const;
```
Returns `true` if the underlying value is a JavaScript `DataView` or `false`
Returns `true` if the underlying value is a JavaScript `Napi::DataView` or `false`
otherwise.

@@ -270,6 +270,6 @@

```cpp
bool IsBuffer() const;
bool Napi::Value::IsBuffer() const;
```
Returns `true` if the underlying value is a Node.js `Buffer` or `false`
Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false`
otherwise.

@@ -279,3 +279,3 @@

```cpp
bool IsExternal() const;
bool Napi::Value::IsExternal() const;
```

@@ -288,3 +288,3 @@

```cpp
Boolean ToBoolean() const;
Napi::Boolean Napi::Value::ToBoolean() const;
```

@@ -299,6 +299,5 @@

#### ToNumber
```cpp
Number ToNumber() const;
Napi::Number Napi::Value::ToNumber() const;
```

@@ -315,6 +314,5 @@

#### ToString
```cpp
String ToString() const;
Napi::String Napi::Value::ToString() const;
```

@@ -330,6 +328,5 @@

#### ToObject
```cpp
Object ToObject() const;
Napi::Object Napi::Value::ToObject() const;
```

@@ -344,8 +341,7 @@

## 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- [`String`](String.md)
and [`Symbol`](Symbol.md).
specialized types of names supported in Node.js Addon API [`Napi::String`](string.md)
and [`Napi::Symbol`](symbol.md).

@@ -356,9 +352,9 @@ ### Methods

```cpp
Name();
Napi::Name::Name();
```
Returns an empty `Name`.
Returns an empty `Napi::Name`.
```cpp
Name(napi_env env, napi_value value);
Napi::Name::Name(napi_env env, napi_value value);
```

@@ -368,3 +364,3 @@ - `[in] env` - The environment in which to create the array.

Returns a Name created from the JavaScript primitive.
Returns a `Napi::Name` created from the JavaScript primitive.

@@ -381,3 +377,3 @@ Note:

```cpp
Array();
Napi::Array::Array();
```

@@ -391,5 +387,4 @@

```cpp
Array(napi_env env, napi_value value);
Napi::Array::Array(napi_env env, napi_value value);
```

@@ -409,3 +404,3 @@ - `[in] env` - The environment in which to create the array.

```cpp
static Array New(napi_env env);
static Napi::Array Napi::Array::New(napi_env env);
```

@@ -423,3 +418,3 @@ - `[in] env` - The environment in which to create the array.

```cpp
static Array New(napi_env env, size_t length);
static Napi::Array Napi::Array::New(napi_env env, size_t length);
```

@@ -435,5 +430,5 @@ - `[in] env` - The environment in which to create the array.

#### New
#### Length
```cpp
uint32_t Length() const;
uint32_t Napi::Array::Length() const;
```

@@ -440,0 +435,0 @@

# Boolean
You are reading a draft of the next documentation and it's in continuous 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/)
`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)).
# Methods
## Methods
### Constructor
Creates a new empty instance of an `Napi::Boolean` object.
```cpp
Napi::Boolean::New(Napi::Env env, bool value);
Napi::Boolean::Boolean();
```
- `[in] env`: The `napi_env` Environment
- `[in] value`: The Javascript boolean value
Returns a new _empty_ `Napi::Boolean` object.
### Contructor
Creates a new instance of the `Napi::Boolean` object.
```cpp
Napi::Boolean();
Napi::Boolean(napi_env env, napi_value value);
```
returns a new empty Javascript Boolean value type.
### operator bool
Converts a Boolean value to a boolean primitive.
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Boolean` object.
- `[in] value`: The `napi_value` which is a handle for a JavaScript `Boolean`.
Returns a non-empty `Napi::Boolean` object.
### New
Initializes a new instance of the `Napi::Boolean` object.
```cpp
operator bool() const;
Napi::Boolean Napi::Boolean::New(napi_env env, bool value);
```
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Boolean` object.
- `[in] value`: The primitive boolean value (`true` or `false`).
Returns a new instance of the `Napi::Boolean` object.
### Value
Converts a Boolean value to a boolean primitive.
Converts a `Napi::Boolean` value to a boolean primitive.
```cpp
bool Value() const;
```
bool Napi::Boolean::Value() const;
```
Returns the boolean primitive type of the corresponding `Napi::Boolean` object.
## Operators
### operator bool
Converts a `Napi::Boolean` value to a boolean primitive.
```cpp
Napi::Boolean::operator bool() const;
```
Returns the boolean primitive type of the corresponding `Napi::Boolean` object.
# Buffer
The `Buffer` class creates a projection of raw data that can be consumed by
The `Napi::Buffer` class creates a projection of raw data that can be consumed by
script.

@@ -10,19 +10,19 @@

Allocates a new `Buffer` object with a given length.
Allocates a new `Napi::Buffer` object with a given length.
```cpp
static Buffer<T> New(napi_env env, size_t length);
static Napi::Buffer<T> Napi::Buffer::New(napi_env env, size_t length);
```
- `[in] env`: The environment in which to create the `Buffer` object.
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] length`: The number of `T` elements to allocate.
Returns a new `Buffer` object.
Returns a new `Napi::Buffer` object.
### New
Wraps the provided external data into a new `Buffer` object.
Wraps the provided external data into a new `Napi::Buffer` object.
The `Buffer` object does not assume ownership for the data and expects it to be
valid for the lifetime of the object. Since the `Buffer` is subject to garbage
The `Napi::Buffer` object does not assume ownership for the data and expects it to be
valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage
collection this overload is only suitable for data which is static and never

@@ -32,22 +32,22 @@ needs to be freed.

```cpp
static Buffer<T> New(napi_env env, T* data, size_t length);
static Napi::Buffer<T> Napi::Buffer::New(napi_env env, T* data, size_t length);
```
- `[in] env`: The environment in which to create the `Buffer` object.
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
Returns a new `Buffer` object.
Returns a new `Napi::Buffer` object.
### New
Wraps the provided external data into a new `Buffer` object.
Wraps the provided external data into a new `Napi::Buffer` object.
The `Buffer` object does not assume ownership for the data and expects it
The `Napi::Buffer` object does not assume ownership for the data and expects it
to be valid for the lifetime of the object. The data can only be freed once the
`finalizeCallback` is invoked to indicate that the `Buffer` has been released.
`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
```cpp
template <typename Finalizer>
static Buffer<T> New(napi_env env,
static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
T* data,

@@ -58,22 +58,22 @@ size_t length,

- `[in] env`: The environment in which to create the `Buffer` object.
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
- `[in] finalizeCallback`: The function to be called when the `Buffer` is
- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
destroyed. It must implement `operator()`, accept a `T*` (which is the
external data pointer), and return `void`.
Returns a new `Buffer` object.
Returns a new `Napi::Buffer` object.
### New
Wraps the provided external data into a new `Buffer` object.
Wraps the provided external data into a new `Napi::Buffer` object.
The `Buffer` object does not assume ownership for the data and expects it to be
The `Napi::Buffer` object does not assume ownership for the data and expects it to be
valid for the lifetime of the object. The data can only be freed once the
`finalizeCallback` is invoked to indicate that the `Buffer` has been released.
`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released.
```cpp
template <typename Finalizer, typename Hint>
static Buffer<T> New(napi_env env,
static Napi::Buffer<T> Napi::Buffer::New(napi_env env,
T* data,

@@ -85,6 +85,6 @@ size_t length,

- `[in] env`: The environment in which to create the `Buffer` object.
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to expose.
- `[in] length`: The number of `T` elements in the external data.
- `[in] finalizeCallback`: The function to be called when the `Buffer` is
- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is
destroyed. It must implement `operator()`, accept a `T*` (which is the

@@ -95,24 +95,24 @@ external data pointer) and `Hint*`, and return `void`.

Returns a new `Buffer` object.
Returns a new `Napi::Buffer` object.
### Copy
Allocates a new `Buffer` object and copies the provided external data into it.
Allocates a new `Napi::Buffer` object and copies the provided external data into it.
```cpp
static Buffer<T> Copy(napi_env env, const T* data, size_t length);
static Napi::Buffer<T> Napi::Buffer::Copy(napi_env env, const T* data, size_t length);
```
- `[in] env`: The environment in which to create the `Buffer` object.
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] data`: The pointer to the external data to copy.
- `[in] length`: The number of `T` elements in the external data.
Returns a new `Buffer` object containing a copy of the data.
Returns a new `Napi::Buffer` object containing a copy of the data.
### Constructor
Initializes an empty instance of the `Buffer` class.
Initializes an empty instance of the `Napi::Buffer` class.
```cpp
Buffer();
Napi::Buffer::Buffer();
```

@@ -122,9 +122,9 @@

Initializes the `Buffer` object using an existing Uint8Array.
Initializes the `Napi::Buffer` object using an existing Uint8Array.
```cpp
Buffer(napi_env env, napi_value value);
Napi::Buffer::Buffer(napi_env env, napi_value value);
```
- `[in] env`: The environment in which to create the `Buffer` object.
- `[in] env`: The environment in which to create the `Napi::Buffer` object.
- `[in] value`: The Uint8Array reference to wrap.

@@ -135,3 +135,3 @@

```cpp
T* Data() const;
T* Napi::Buffer::Data() const;
```

@@ -144,5 +144,5 @@

```cpp
size_t Length() const;
size_t Napi::Buffer::Length() const;
```
Returns the number of `T` elements in the external data.

@@ -1,3 +0,1 @@

**WORK IN PROGRESS, NOT YET COMPLETE**
# CallbackInfo

@@ -7,7 +5,7 @@

The CallbackInfo object is usually created and passed by the Node.js runtime or node-addon-api infrastructure.
The `Napi::CallbackInfo` object is usually created and passed by the Node.js runtime or node-addon-api infrastructure.
The CallbackInfo object contains the arguments passed by the caller. The number of arguments is returned by the `Length` method. Each individual argument can be accessed using the `operator[]` method.
The `Napi::CallbackInfo` object contains the arguments passed by the caller. The number of arguments is returned by the `Length` method. Each individual argument can be accessed using the `operator[]` method.
The `SetData` and `Data` methods are used to set and retrieve the data pointer contained in the CallbackInfo object.
The `SetData` and `Data` methods are used to set and retrieve the data pointer contained in the `Napi::CallbackInfo` object.

@@ -19,7 +17,7 @@ ## Methods

```cpp
CallbackInfo(napi_env env, napi_callback_info info);
Napi::CallbackInfo::CallbackInfo(napi_env env, napi_callback_info info);
```
- `[in] env`: The `napi_env` environment in which to construct the `CallbackInfo` object.
- `[in] info`: The `napi_callback_info` data structure from which to construct the `CallbackInfo` object.
- `[in] env`: The `napi_env` environment in which to construct the `Napi::CallbackInfo` object.
- `[in] info`: The `napi_callback_info` data structure from which to construct the `Napi::CallbackInfo` object.

@@ -29,3 +27,3 @@ ### Env

```cpp
Napi::Env Env() const;
Napi::Env Napi::CallbackInfo::Env() const;
```

@@ -38,6 +36,6 @@

```cpp
Value NewTarget() const;
Napi::Value Napi::CallbackInfo::NewTarget() const;
```
Returns the `new.target` value of the constructor call. If the function that was invoked (and for which the CallbackInfo was passed) is not a constructor call, a call to `IsEmpty()` on the returned value returns true.
Returns the `new.target` value of the constructor call. If the function that was invoked (and for which the `Napi::NCallbackInfo` was passed) is not a constructor call, a call to `IsEmpty()` on the returned value returns true.

@@ -47,15 +45,14 @@ ### IsConstructCall

```cpp
bool IsConstructCall() const;
bool Napi::CallbackInfo::IsConstructCall() const;
```
Returns a `bool` indicating if the function that was invoked (and for which the CallbackInfo was passed) is a constructor call.
Returns a `bool` indicating if the function that was invoked (and for which the `Napi::CallbackInfo` was passed) is a constructor call.
### Length
```cpp
size_t Length() const;
size_t Napi::CallbackInfo::Length() const;
```
Returns the number of arguments passed in the CallbackInfo object.
Returns the number of arguments passed in the `Napi::CallbackInfo` object.

@@ -65,3 +62,3 @@ ### operator []

```cpp
const Value operator [](size_t index) const;
const Napi::Value operator [](size_t index) const;
```

@@ -71,3 +68,3 @@

Returns a `Value` object containing the requested argument.
Returns a `Napi::Value` object containing the requested argument.

@@ -77,3 +74,3 @@ ### This

```cpp
Value This() const;
Napi::Value Napi::CallbackInfo::This() const;
```

@@ -86,3 +83,3 @@

```cpp
void* Data() const;
void* Napi::CallbackInfo::Data() const;
```

@@ -95,6 +92,6 @@

```cpp
void SetData(void* data);
void Napi::CallbackInfo::SetData(void* data);
```
- `[in] data`: The new data pointer to associate with this CallbackInfo object.
- `[in] data`: The new data pointer to associate with this `Napi::CallbackInfo` object.

@@ -106,6 +103,6 @@ Returns `void`.

```cpp
~CallbackInfo();
Napi::CallbackInfo::~CallbackInfo();
// Disallow copying to prevent multiple free of _dynamicArgs
CallbackInfo(CallbackInfo const &) = delete;
void operator=(CallbackInfo const &) = delete;
Napi::CallbackInfo::CallbackInfo(CallbackInfo const &) = delete;
void Napi::CallbackInfo::operator=(CallbackInfo const &) = delete;
```

@@ -1,5 +0,36 @@

# Class propertry and descriptior
# Class propertry and descriptor
You are reading a draft of the next documentation and it's in continuous 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/)
Property descriptor for use with `Napi::ObjectWrap::DefineClass()`.
This is different from the standalone `Napi::PropertyDescriptor` because it is
specific to each `Napi::ObjectWrap<T>` subclass.
This prevents using descriptors from a different class when defining a new class
(preventing the callbacks from having incorrect `this` pointers).
## Methods
### Contructor
Creates new instance of `Napi::ClassPropertyDescriptor` descriptor object.
```cpp
Napi::ClassPropertyDescriptor(napi_property_descriptor desc) : _desc(desc) {}
```
- `[in] desc`: The `napi_property_descriptor`
Returns new instance of `Napi::ClassPropertyDescriptor` that is used as property descriptor
inside the `Napi::ObjectWrap<T>` class.
### Operator
```cpp
operator napi_property_descriptor&() { return _desc; }
```
Returns the original N-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor`
```cpp
operator const napi_property_descriptor&() const { return _desc; }
```
Returns the original N-API `napi_property_descriptor` wrapped inside the `Napi::ClassPropertyDescriptor`

@@ -1,3 +0,1 @@

**WORK IN PROGRESS, NOT YET COMPLETE**
# Env

@@ -14,6 +12,6 @@

```cpp
Env(napi_env env);
Napi::Env::Env(napi_env env);
```
- `[in] env`: The `napi_env` environment from which to construct the `Env` object.
- `[in] env`: The `napi_env` environment from which to construct the `Napi::Env` object.

@@ -31,6 +29,6 @@ ### napi_env

```cpp
Object Global() const;
Napi::Object Napi::Env::Global() const;
```
Returns the `Object` representing the environment's JavaScript Global Object.
Returns the `Napi::Object` representing the environment's JavaScript Global Object.

@@ -40,6 +38,6 @@ ### Undefined

```cpp
Value Undefined() const;
Napi::Value Napi::Env::Undefined() const;
```
Returns the `Value` representing the environment's JavaScript Undefined Object.
Returns the `Napi::Value` representing the environment's JavaScript Undefined Object.

@@ -49,6 +47,6 @@ ### Null

```cpp
Value Null() const;
Napi::Value Napi::Env::Null() const;
```
Returns the `Value` representing the environment's JavaScript Null Object.
Returns the `Napi::Value` representing the environment's JavaScript Null Object.

@@ -58,3 +56,3 @@ ### IsExceptionPending

```cpp
bool IsExceptionPending() const;
bool Napi::Env::IsExceptionPending() const;
```

@@ -67,5 +65,5 @@

```cpp
Error GetAndClearPendingException();
Napi::Error Napi::Env::GetAndClearPendingException();
```
Returns an `Error` object representing the environment's pending exception, if any.
Returns an `Napi::Error` object representing the environment's pending exception, if any.

@@ -9,3 +9,3 @@ # Error handling

The **Error** is a persistent reference (for more info see: [Object reference](object_reference.md))
The `Napi::Error` is a persistent reference (for more info see: [`Napi::ObjectReference`](object_reference.md))
to a JavaScript error object. Use of this class depends on whether C++

@@ -15,3 +15,3 @@ exceptions are enabled at compile time.

If C++ exceptions are enabled (for more info see: [Setup](setup.md)), then the
**Error** class extends `std::exception` and enables integrated
`Napi::Error` class extends `std::exception` and enables integrated
error-handling for C++ exceptions and JavaScript exceptions.

@@ -39,10 +39,10 @@

an invalid argument), then node-addon-api automatically converts and throws
the error as a C++ exception of type **Error**.
the error as a C++ exception of type `Napi::Error`.
If a JavaScript function called by C++ code via node-addon-api throws a JavaScript
exception, then node-addon-api automatically converts and throws it as a C++
exception of type **Error** on return from the JavaScript code to the native
exception of type `Napi:Error` on return from the JavaScript code to the native
method.
If a C++ exception of type **Error** escapes from a N-API C++ callback, then
If a C++ exception of type `Napi::Error` escapes from a N-API C++ callback, then
the N-API wrapper automatically converts and throws it as a JavaScript exception.

@@ -63,3 +63,3 @@

Env env = ...
throw Error::New(env, "Example exception");
throw Napi::Error::New(env, "Example exception");
// other C++ statements

@@ -70,3 +70,3 @@ // ...

The statements following the throw statement will not be executed. The exception
will bubble up as a C++ exception of type **Error**, until it is either caught
will bubble up as a C++ exception of type `Napi::Error`, until it is either caught
while still in C++, or else automatically propagated as a JavaScript exception

@@ -78,4 +78,4 @@ when returning to JavaScript.

```cpp
Function jsFunctionThatThrows = someObj.As<Function>();
Value result = jsFunctionThatThrows({ arg1, arg2 });
Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
// other C++ statements

@@ -86,3 +86,3 @@ // ...

The C++ statements following the call to the JavaScript function will not be
executed. The exception will bubble up as a C++ exception of type **Error**,
executed. The exception will bubble up as a C++ exception of type `Napi::Error`,
until it is either caught while still in C++, or else automatically propagated as

@@ -94,4 +94,4 @@ a JavaScript exception when returning to JavaScript.

```cpp
Function jsFunctionThatThrows = someObj.As<Function>();
Value result;
Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
Napi::Value result;
try {

@@ -112,10 +112,10 @@ result = jsFunctionThatThrows({ arg1, arg2 });

If C++ exceptions are disabled (for more info see: [Setup](setup.md)), then the
**Error** class does not extend `std::exception`. This means that any calls to
`Napi::Error` class does not extend `std::exception`. This means that any calls to
node-addon-api function do not throw a C++ exceptions. Instead, it raises
_pending_ JavaScript exceptions and returns an _empty_ **Value**.
_pending_ JavaScript exceptions and returns an _empty_ `Napi::Value`.
The calling code should check `env.IsExceptionPending()` before attempting to use a
returned value, and may use methods on the **Env** class
returned value, and may use methods on the `Napi::Env` class
to check for, get, and clear a pending JavaScript exception (for more info see: [Env](env.md)).
If the pending exception is not cleared, it will be thrown when the native code
returns to JavaScript.
returns to JavaScript.

@@ -127,4 +127,4 @@ ## Examples with C++ exceptions disabled

```cpp
Env env = ...
Error::New(env, "Example exception").ThrowAsJavaScriptException();
Napi::Env env = ...
Napi::Error::New(env, "Example exception").ThrowAsJavaScriptException();
return;

@@ -139,5 +139,5 @@ ```

```cpp
Env env = ...
Function jsFunctionThatThrows = someObj.As<Function>();
Value result = jsFunctionThatThrows({ arg1, arg2 });
Napi::Env env = ...
Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
if (env.IsExceptionPending()) {

@@ -149,6 +149,5 @@ Error e = env.GetAndClearPendingException();

If env.IsExceptionPending() is returns true a
JavaScript exception is pending. To let the exception propagate, the code should
generally return immediately from the native callback, after performing any
necessary cleanup.
If env.IsExceptionPending() returns true a JavaScript exception is pending. To
let the exception propagate, the code should generally return immediately from
the native callback, after performing any necessary cleanup.

@@ -158,7 +157,7 @@ ### Handling a N-API JS exception

```cpp
Env env = ...
Function jsFunctionThatThrows = someObj.As<Function>();
Value result = jsFunctionThatThrows({ arg1, arg2 });
Napi::Env env = ...
Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
if (env.IsExceptionPending()) {
Error e = env.GetAndClearPendingException();
Napi::Error e = env.GetAndClearPendingException();
cerr << "Caught JavaScript exception: " + e.Message();

@@ -165,0 +164,0 @@ }

# Error
The **Error** class is a representation of the JavaScript Error object that is thrown
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.
The **Error** class is a persistent reference to a JavaScript error object thus
inherits its behavior from the `ObjectReference` class (for more info see: [ObjectReference](object_reference.md)).
The `Napi::Error` class is a persistent reference to a JavaScript error object thus
inherits its behavior from the `Napi::ObjectReference` class (for more info see: [`Napi::ObjectReference`](object_reference.md)).
If C++ exceptions are enabled (for more info see: [Setup](setup.md)), then the
**Error** class extends `std::exception` and enables integrated
`Napi::Error` class extends `std::exception` and enables integrated
error-handling for C++ exceptions and JavaScript exceptions.

@@ -20,37 +20,37 @@

Creates empty instance of an `Error` object for the specified environment.
Creates empty instance of an `Napi::Error` object for the specified environment.
```cpp
Error::New(Napi:Env env);
Napi::Error::New(Napi::Env env);
```
- `[in] Env`: The environment in which to construct the Error object.
- `[in] env`: The environment in which to construct the `Napi::Error` object.
Returns an instance of `Error` object.
Returns an instance of `Napi::Error` object.
### New
Creates instance of an `Error` object.
Creates instance of an `Napi::Error` object.
```cpp
Error::New(Napi:Env env, const char* message);
Napi::Error::New(Napi::Env env, const char* message);
```
- `[in] Env`: The environment in which to construct the Error object.
- `[in] message`: Null-terminated string to be used as the message for the Error.
- `[in] env`: The environment in which to construct the `Napi::Error` object.
- `[in] message`: Null-terminated string to be used as the message for the `Napi::Error`.
Returns instance of an `Error` object.
Returns instance of an `Napi::Error` object.
### New
Creates instance of an `Error` object
Creates instance of an `Napi::Error` object
```cpp
Error::New(Napi:Env env, const std::string& message);
Napi::Error::New(Napi::Env env, const std::string& message);
```
- `[in] Env`: The environment in which to construct the `Error` object.
- `[in] message`: Reference string to be used as the message for the `Error`.
- `[in] env`: The environment in which to construct the `Napi::Error` object.
- `[in] message`: Reference string to be used as the message for the `Napi::Error`.
Returns instance of an `Error` object.
Returns instance of an `Napi::Error` object.

@@ -63,3 +63,3 @@ ### Fatal

```cpp
static NAPI_NO_RETURN void Fatal(const char* location, const char* message);
static NAPI_NO_RETURN void Napi::Error::Fatal(const char* location, const char* message);
```

@@ -71,22 +71,22 @@

Creates empty instance of an `Error`.
Creates empty instance of an `Napi::Error`.
```cpp
Error();
Napi::Error::Error();
```
Returns an instance of `Error` object.
Returns an instance of `Napi::Error` object.
### Constructor
Initializes an `Error` instance from an existing JavaScript error object.
Initializes an `Napi::Error` instance from an existing JavaScript error object.
```cpp
Error(napi_env env, napi_value value);
Napi::Error::Error(napi_env env, napi_value value);
```
- `[in] Env`: The environment in which to construct the Error object.
- `[in] value`: The `Error` reference to wrap.
- `[in] env`: The environment in which to construct the error object.
- `[in] value`: The `Napi::Error` reference to wrap.
Returns instance of an `Error` object.
Returns instance of an `Napi::Error` object.

@@ -96,3 +96,3 @@ ### Message

```cpp
std::string& Message() const NAPI_NOEXCEPT;
std::string& Napi::Error::Message() const NAPI_NOEXCEPT;
```

@@ -107,3 +107,3 @@

```cpp
void ThrowAsJavaScriptException() const;
void Napi::Error::ThrowAsJavaScriptException() const;
```

@@ -116,3 +116,3 @@

```cpp
const char* what() const NAPI_NOEXCEPT override;
const char* Napi::Error::what() const NAPI_NOEXCEPT override;
```

@@ -119,0 +119,0 @@

# EscapableHandleScope
The EscapableHandleScope class is used to manage the lifetime of object handles
The `Napi::EscapableHandleScope` class is used to manage the lifetime of object handles
which are created through the use of node-addon-api. These handles

@@ -10,7 +10,7 @@ keep an object alive in the heap in order to ensure that the objects

An EscapableHandleScope is a special type of HandleScope
The `Napi::EscapableHandleScope` is a special type of `Napi::HandleScope`
which allows a single handle to be "promoted" to an outer scope.
For more details refer to the section titled
(Object lifetime management)[object_lifetime_management].
[Object lifetime management](object_lifetime_management.md).

@@ -24,8 +24,8 @@ ## Methods

```cpp
EscapableHandleScope EscapableHandleScope::New(Napi:Env env);
Napi::EscapableHandleScope Napi::EscapableHandleScope::New(Napi:Env env);
```
- `[in] Env`: The environment in which to construct the EscapableHandleScope object.
- `[in] Env`: The environment in which to construct the `Napi::EscapableHandleScope` object.
Returns a new EscapableHandleScope
Returns a new `Napi::EscapableHandleScope`

@@ -37,3 +37,3 @@ ### Constructor

```cpp
EscapableHandleScope EscapableHandleScope::New(napi_env env, napi_handle_scope scope);
Napi::EscapableHandleScope Napi::EscapableHandleScope::New(napi_env env, napi_handle_scope scope);
```

@@ -44,3 +44,3 @@

Returns a new EscapableHandleScope instance which wraps the
Returns a new `Napi::EscapableHandleScope` instance which wraps the
napi_escapable_handle_scope handle passed in. This can be used

@@ -52,6 +52,6 @@ to mix usage of the C N-API and node-addon-api.

```cpp
operator EscapableHandleScope::napi_escapable_handle_scope() const
operator Napi::EscapableHandleScope::napi_escapable_handle_scope() const
```
Returns the N-API napi_escapable_handle_scope wrapped by the EscapableHandleScope object.
Returns the N-API napi_escapable_handle_scope wrapped by the `Napi::EscapableHandleScope` object.
This can be used to mix usage of the C N-API and node-addon-api by allowing

@@ -62,6 +62,6 @@ the class to be used be converted to a napi_escapable_handle_scope.

```cpp
~EscapableHandleScope();
Napi::EscapableHandleScope::~EscapableHandleScope();
```
Deletes the EscapableHandleScope instance and allows any objects/handles created
Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created
in the scope to be collected by the garbage collector. There is no

@@ -73,3 +73,3 @@ guarantee as to when the gargbage collector will do this.

```cpp
napi::Value EscapableHandleScope::Escape(napi_value escapee);
napi::Value Napi::EscapableHandleScope::Escape(napi_value escapee);
```

@@ -79,4 +79,4 @@

Returns Napi:Value which can be used in the outer scope. This method can
be called at most once on a given EscapableHandleScope. If it is called
Returns `Napi::Value` which can be used in the outer scope. This method can
be called at most once on a given `Napi::EscapableHandleScope`. If it is called
more than once an exception will be thrown.

@@ -87,5 +87,5 @@

```cpp
Napi::Env Env() const;
Napi::Env Napi::EscapableHandleScope::Env() const;
```
Returns the Napi:Env associated with the EscapableHandleScope.
Returns the `Napi::Env` associated with the `Napi::EscapableHandleScope`.

@@ -1,8 +0,6 @@

**WORK IN PROGRESS, NOT YET COMPLETE**
# External (template)
The External template class implements the ability to create a Value object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data.
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.
External objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your 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.
`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.

@@ -15,9 +13,9 @@ ## Methods

template <typename T>
static External New(napi_env env, T* data);
static Napi::External Napi::External::New(napi_env env, T* data);
```
- `[in] env`: The `napi_env` environment in which to construct the External object.
- `[in] data`: The arbitrary C++ data to be held by the External object.
- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
Returns the created `External<T>` object.
Returns the created `Napi::External<T>` object.

@@ -28,3 +26,3 @@ ### New

template <typename T>
static External New(napi_env env,
static Napi::External Napi::External::New(napi_env env,
T* data,

@@ -34,7 +32,7 @@ Finalizer finalizeCallback);

- `[in] env`: The `napi_env` environment in which to construct the External object.
- `[in] data`: The arbitrary C++ data to be held by the External object.
- `[in] finalizeCallback`: A function called when the External object is released by the garbage collector accepting a T* and returning void.
- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting a T* and returning void.
Returns the created `External<T>` object.
Returns the created `Napi::External<T>` object.

@@ -45,3 +43,3 @@ ### New

template <typename T>
static External New(napi_env env,
static Napi::External Napi::External::New(napi_env env,
T* data,

@@ -52,8 +50,8 @@ Finalizer finalizeCallback,

- `[in] env`: The `napi_env` environment in which to construct the External object.
- `[in] data`: The arbitrary C++ data to be held by the External object.
- `[in] finalizeCallback`: A function called when the External object is released by the garbage collector accepting T* and Hint* parameters and returning void.
- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object.
- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object.
- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting T* and Hint* parameters and returning void.
- `[in] finalizeHint`: A hint value passed to the `finalizeCallback` function.
Returns the created `External<T>` object.
Returns the created `Napi::External<T>` object.

@@ -63,5 +61,5 @@ ### Data

```cpp
T* Data() const;
T* Napi::External::Data() const;
```
Returns a pointer to the arbitrary C++ data held by the External object.
Returns a pointer to the arbitrary C++ data held by the `Napi::External` object.

@@ -1,5 +0,238 @@

# Function reference
# FunctionReference
You are reading a draft of the next documentation and it's in continuous 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/)
`Napi::FunctionReference` is a subclass of [`Napi::Reference`](reference.md), and
is equivalent to an instance of `Napi::Reference<Napi::Function>`. This means
that a `Napi::FunctionReference` holds a [`Napi::Function`](function.md), and a
count of the number of references to that `Napi::Function`. When the count is
greater than 0, a `Napi::FunctionReference` is not eligible for garbage collection.
This ensures that the `Function` will remain accessible, even if the original
reference to it is no longer available.
`Napi::FunctionReference` allows the referenced JavaScript function object to be
called from a native add-on with two different methods: `Call` and `MakeCallback`.
See the documentation for [`Napi::Function`](function.md) for when `Call` should
be used instead of `MakeCallback` and vice-versa.
The `Napi::FunctionReference` class inherits its behavior from the `Napi::Reference`
class (for more info see: [`Napi::Reference`](reference.md)).
## Methods
### Weak
Creates a "weak" reference to the value, in that the initial reference count is
set to 0.
```cpp
static Napi::FunctionReference Napi::FunctionReference::Weak(const Napi::Function& value);
```
- `[in] value`: The value which is to be referenced.
Returns the newly created reference.
### Persistent
Creates a "persistent" reference to the value, in that the initial reference
count is set to 1.
```cpp
static Napi::FunctionReference Napi::FunctionReference::Persistent(const Napi::Function& value);
```
- `[in] value`: The value which is to be referenced.
Returns the newly created reference.
### Constructor
Creates a new empty instance of `Napi::FunctionReference`.
```cpp
Napi::FunctionReference::FunctionReference();
```
### Constructor
Creates a new instance of the `Napi::FunctionReference`.
```cpp
Napi::FunctionReference::FunctionReference(napi_env env, napi_ref ref);
```
- `[in] env`: The environment in which to construct the `Napi::FunctionReference` object.
- `[in] ref`: The N-API reference to be held by the `Napi::FunctionReference`.
Returns a newly created `Napi::FunctionReference` object.
### New
Constructs a new instance by calling the constructor held by this reference.
```cpp
Napi::Object Napi::FunctionReference::New(const std::initializer_list<napi_value>& args) const;
```
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
the arguments of the contructor function.
Returns a new JavaScript object.
### New
Constructs a new instance by calling the constructor held by this reference.
```cpp
Napi::Object Napi::FunctionReference::New(const std::vector<napi_value>& args) const;
```
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
arguments of the constructor function.
Returns a new JavaScript object.
### Call
Calls a referenced Javascript function from a native add-on.
```cpp
Napi::Value Napi::FunctionReference::Call(const std::initializer_list<napi_value>& args) const;
```
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
the arguments of the referenced function.
Returns a `Napi::Value` representing the JavaScript object returned by the referenced
function.
### Call
Calls a referenced JavaScript function from a native add-on.
```cpp
Napi::Value Napi::FunctionReference::Call(const std::vector<napi_value>& args) const;
```
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
arguments of the referenced function.
Returns a `Napi::Value` representing the JavaScript object returned by the referenced
function.
### Call
Calls a referenced JavaScript function from a native add-on.
```cpp
Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::initializer_list<napi_value>& args) const;
```
- `[in] recv`: The `this` object passed to the referenced function when it's called.
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
the arguments of the referenced function.
Returns a `Napi::Value` representing the JavaScript object returned by the referenced
function.
### Call
Calls a referenced JavaScript function from a native add-on.
```cpp
Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::vector<napi_value>& args) const;
```
- `[in] recv`: The `this` object passed to the referenced function when it's called.
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
arguments of the referenced function.
Returns a `Napi::Value` representing the JavaScript object returned by the referenced
function.
### Call
Calls a referenced JavaScript function from a native add-on.
```cpp
Napi::Value Napi::FunctionReference::Call(napi_value recv, size_t argc, const napi_value* args) const;
```
- `[in] recv`: The `this` object passed to the referenced function when it's called.
- `[in] argc`: The number of arguments passed to the referenced function.
- `[in] args`: Array of JavaScript values as `napi_value` representing the
arguments of the referenced function.
Returns a `Napi::Value` representing the JavaScript object returned by the referenced
function.
### MakeCallback
Calls a referenced JavaScript function from a native add-on after an asynchronous
operation.
```cpp
Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::initializer_list<napi_value>& args, napi_async_context = nullptr) const;
```
- `[in] recv`: The `this` object passed to the referenced function when it's called.
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
the arguments of the referenced function.
- `[in] context`: Context for the async operation that is invoking the callback.
This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
However `nullptr` is also allowed, which indicates the current async context
(if any) is to be used for the callback.
Returns a `Napi::Value` representing the JavaScript object returned by the referenced
function.
### MakeCallback
Calls a referenced JavaScript function from a native add-on after an asynchronous
operation.
```cpp
Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::vector<napi_value>& args, napi_async_context context = nullptr) const;
```
- `[in] recv`: The `this` object passed to the referenced function when it's called.
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
arguments of the referenced function.
- `[in] context`: Context for the async operation that is invoking the callback.
This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
However `nullptr` is also allowed, which indicates the current async context
(if any) is to be used for the callback.
Returns a `Napi::Value` representing the JavaScript object returned by the referenced
function.
### MakeCallback
Calls a referenced JavaScript function from a native add-on after an asynchronous
operation.
```cpp
Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, size_t argc, const napi_value* args, napi_async_context context = nullptr) const;
```
- `[in] recv`: The `this` object passed to the referenced function when it's called.
- `[in] argc`: The number of arguments passed to the referenced function.
- `[in] args`: Array of JavaScript values as `napi_value` representing the
arguments of the referenced function.
- `[in] context`: Context for the async operation that is invoking the callback.
This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
However `nullptr` is also allowed, which indicates the current async context
(if any) is to be used for the callback.
Returns a `Napi::Value` representing the JavaScript object returned by the referenced
function.
## Operator
```cpp
Napi::Value operator ()(const std::initializer_list<napi_value>& args) const;
```
- `[in] args`: Initializer list of reference to JavaScript values as `napi_value`
Returns a `Napi::Value` representing the JavaScript value returned by the referenced
function.
# Function
You are reading a draft of the next documentation and it's in continuous 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/)
The `Napi::Function` class provides a set of methods for creating a function object in
native code that can later be called from JavaScript. The created function is not
automatically visible from JavaScript. Instead it needs to be part of the add-on's
module exports or be returned by one of the module's exported functions.
In addition the `Napi::Function` class also provides methods that can be used to call
functions that were created in JavaScript and passed to the native add-on.
The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info
see: [`Napi::Object`](object.md)).
## Example
```cpp
#include <napi.h>
using namespace Napi;
Value Fn(const CallbackInfo& info) {
Env env = info.Env();
// ...
return String::New(env, "Hello World");
}
Object Init(Env env, Object exports) {
exports.Set(String::New(env, "fn"), Function::New(env, Fn));
}
NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init)
```
The above code can be used from JavaScript as follows:
```js
const addon = require('./addon');
addon.fn();
```
With the `Napi::Function` class it is possible to call a JavaScript function object
from a native add-on with two different methods: `Call` and `MakeCallback`.
The API of these two methods is very similar, but they are used in different
contexts. The `MakeCallback` method is used to call from native code back into
JavaScript after returning from an [asynchronous operation](async_operations.md)
and in general in situations which don't have an existing JavaScript function on
the stack. The `Call` method is used when there is already a JavaScript function
on the stack (for example when running a native method called from JavaScript).
## Methods
### Constructor
Creates a new empty instance of `Napi::Function`.
```cpp
Napi::Function::Function();
```
### Constructor
Creates a new instance of the `Napi::Function` object.
```cpp
Napi::Function::Function(napi_env env, napi_value value);
```
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
- `[in] value`: The `napi_value` which is a handle for a JavaScript function.
Returns a non-empty `Napi::Function` instance.
### New
Creates an instance of a `Napi::Function` object.
```cpp
template <typename Callable>
static Napi::Function Napi::Function::New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr);
```
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
- `[in] cb`: Object that implements `Callable`.
- `[in] utf8name`: Null-terminated string to be used as the name of the function.
- `[in] data`: User-provided data context. This will be passed back into the
function when invoked later.
Returns an instance of a `Napi::Function` object.
### New
```cpp
template <typename Callable>
static Napi::Function Napi::Function::New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr);
```
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object.
- `[in] cb`: Object that implements `Callable`.
- `[in] utf8name`: String to be used as the name of the function.
- `[in] data`: User-provided data context. This will be passed back into the
function when invoked later.
Returns an instance of a `Napi::Function` object.
### New
Creates a new JavaScript value from one that represents the constructor for the
object.
```cpp
Napi::Object Napi::Function::New(const std::initializer_list<napi_value>& args) const;
```
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
the arguments of the contructor function.
Returns a new JavaScript object.
### New
Creates a new JavaScript value from one that represents the constructor for the
object.
```cpp
Napi::Object Napi::Function::New(const std::vector<napi_value>& args) const;
```
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
arguments of the constructor function.
Returns a new JavaScript object.
### New
Creates a new JavaScript value from one that represents the constructor for the
object.
```cpp
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] args`: Array of JavaScript values as `napi_value` representing the
arguments of the constructor function.
Returns a new JavaScript object.
### Call
Calls a Javascript function from a native add-on.
```cpp
Napi::Value Napi::Function::Call(const std::initializer_list<napi_value>& args) const;
```
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
the arguments of the function.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
### Call
Calls a JavaScript function from a native add-on.
```cpp
Napi::Value Napi::Function::Call(const std::vector<napi_value>& args) const;
```
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
arguments of the function.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
### Call
Calls a Javascript function from a native add-on.
```cpp
Napi::Value Napi::Function::Call(size_t argc, const napi_value* args) const;
```
- `[in] argc`: The number of the arguments passed to the function.
- `[in] args`: Array of JavaScript values as `napi_value` representing the
arguments of the function.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
### Call
Calls a Javascript function from a native add-on.
```cpp
Napi::Value Napi::Function::Call(napi_value recv, const std::initializer_list<napi_value>& args) const;
```
- `[in] recv`: The `this` object passed to the called function.
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
the arguments of the function.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
### Call
Calls a Javascript function from a native add-on.
```cpp
Napi::Value Napi::Function::Call(napi_value recv, const std::vector<napi_value>& args) const;
```
- `[in] recv`: The `this` object passed to the called function.
- `[in] args`: Vector of JavaScript values as `napi_value` representing the
arguments of the function.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
### Call
Calls a Javascript function from a native add-on.
```cpp
Napi::Value Napi::Function::Call(napi_value recv, size_t argc, const napi_value* args) const;
```
- `[in] recv`: The `this` object passed to the called function.
- `[in] argc`: The number of the arguments passed to the function.
- `[in] args`: Array of JavaScript values as `napi_value` representing the
arguments of the function.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
### MakeCallback
Calls a Javascript function from a native add-on after an asynchronous operation.
```cpp
Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::initializer_list<napi_value>& args, napi_async_context context = nullptr) const;
```
- `[in] recv`: The `this` object passed to the called function.
- `[in] args`: Initializer list of JavaScript values as `napi_value` representing
the arguments of the function.
- `[in] context`: Context for the async operation that is invoking the callback.
This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
However `nullptr` is also allowed, which indicates the current async context
(if any) is to be used for the callback.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
### MakeCallback
Calls a Javascript function from a native add-on after an asynchronous operation.
```cpp
Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::vector<napi_value>& args, napi_async_context context = nullptr) const;
```
- `[in] recv`: The `this` object passed to the called function.
- `[in] args`: List of JavaScript values as `napi_value` representing the
arguments of the function.
- `[in] context`: Context for the async operation that is invoking the callback.
This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
However `nullptr` is also allowed, which indicates the current async context
(if any) is to be used for the callback.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
### MakeCallback
Calls a Javascript function from a native add-on after an asynchronous operation.
```cpp
Napi::Value Napi::Function::MakeCallback(napi_value recv, size_t argc, const napi_value* args, napi_async_context context = nullptr) const;
```
- `[in] recv`: The `this` object passed to the called function.
- `[in] argc`: The number of the arguments passed to the function.
- `[in] args`: Array of JavaScript values as `napi_value` representing the
arguments of the function.
- `[in] context`: Context for the async operation that is invoking the callback.
This should normally be a value previously obtained from [Napi::AsyncContext](async_context.md).
However `nullptr` is also allowed, which indicates the current async context
(if any) is to be used for the callback.
Returns a `Napi::Value` representing the JavaScript value returned by the function.
## Operator
```cpp
Napi::Value Napi::Function::operator ()(const std::initializer_list<napi_value>& args) const;
```
- `[in] args`: Initializer list of JavaScript values as `napi_value`.
Returns a `Napi::Value` representing the JavaScript value returned by the function.

@@ -9,3 +9,3 @@ # HandleScope

of its subclasses is created or returned. For more details refer to
the section titled (Object lifetime management)[object_lifetime_management].
the section titled [Object lifetime management](object_lifetime_management.md).

@@ -19,10 +19,9 @@ ## Methods

```cpp
HandleScope(Napi:Env env);
Napi::HandleScope::HandleScope(Napi::Env env);
```
- `[in] env`: The environment in which to construct the HandleScope object.
- `[in] env`: The environment in which to construct the `Napi::HandleScope` object.
Returns a new HandleScope
Returns a new `Napi::HandleScope`
### Constructor

@@ -33,9 +32,9 @@

```cpp
HandleScope(Napi::Env env, Napi::HandleScope scope);
Napi::HandleScope::HandleScope(Napi::Env env, Napi::HandleScope scope);
```
- `[in] env`: Napi::Env in which the scope passed in was created.
- `[in] scope`: pre-existing Napi::HandleScope.
- `[in] env`: `Napi::Env` in which the scope passed in was created.
- `[in] scope`: pre-existing `Napi::HandleScope`.
Returns a new HandleScope instance which wraps the napi_handle_scope
Returns a new `Napi::HandleScope` instance which wraps the napi_handle_scope
handle passed in. This can be used to mix usage of the C N-API

@@ -47,6 +46,6 @@ and node-addon-api.

```cpp
operator napi_handle_scope() const
operator Napi::HandleScope::napi_handle_scope() const
```
Returns the N-API napi_handle_scope wrapped by the EscapableHandleScope object.
Returns the N-API napi_handle_scope wrapped by the `Napi::EscapableHandleScope` object.
This can be used to mix usage of the C N-API and node-addon-api by allowing

@@ -57,6 +56,6 @@ the class to be used be converted to a napi_handle_scope.

```cpp
~HandleScope();
Napi::HandleScope::~HandleScope();
```
Deletes the HandleScope instance and allows any objects/handles created
Deletes the `Napi::HandleScope` instance and allows any objects/handles created
in the scope to be collected by the garbage collector. There is no

@@ -68,5 +67,5 @@ guarantee as to when the gargbage collector will do this.

```cpp
Napi::Env Env() const;
Napi::Env Napi::HandleScope::Env() const;
```
Returns the Napi:Env associated with the HandleScope.
Returns the `Napi::Env` associated with the `Napi::HandleScope`.
# MemoryManagement
The `MemoryManagement` class contains functions that give the JavaScript engine
The `Napi::MemoryManagement` class contains functions that give the JavaScript engine
an indication of the amount of externally allocated memory that is kept alive by

@@ -20,3 +20,3 @@ JavaScript objects.

```cpp
static int64_t MemoryManagement::AdjustExternalMemory(Env env, int64_t change_in_bytes);
static int64_t Napi::MemoryManagement::AdjustExternalMemory(Napi::Env env, int64_t change_in_bytes);
```

@@ -23,0 +23,0 @@

# Number
A Javascript number value.
`Napi::Number` class is a representation of the JavaScript `Number` object. The
`Napi::Number` class inherits its behavior from `Napi::Value` class
(for more info see [`Napi::Value`](value.md))
## Methods
### Constructor
Creates a new _empty_ instance of a `Napi::Number` object.
```cpp
Napi::Number::New(Napi::Env env, double value);
Napi::Number();
```
- `[in] env`: The `napi_env` Environment
- `[in] value`: The value the Javascript Number will contain
Returns a new _empty_ `Napi::Number` object.
### Contructor
Creates a new instance of a `Napi::Number` object.
```cpp
Napi::Number();
Napi::Number(napi_env env, napi_value value);
```
returns a new empty Javascript Number
You can easily cast a Javascript number to one of:
- int32_t
- uint32_t
- int64_t
- float
- double
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Nuber` object.
- `[in] value`: The `napi_value` which is a handle for a JavaScript `Number`.
The following shows an example of casting a number to an uint32_t value.
Returns a non-empty `Napi::Number` object.
### New
Creates a new instance of a `Napi::Number` object.
```cpp
uint32_t operatorVal = Number::New(Env(), 10.0); // Number to unsigned 32 bit integer
Napi::Number Napi::Number::New(napi_env env, double value);
```
- `[in] env`: The `napi_env` environment in which to construct the `Napi::Nuber` object.
- `[in] value`: The `napi_value` which is a handle for a JavaScript `Number`.
Creates a new instance of a `Napi::Number` object.
### Int32Value
Converts a `Napi::Number` value to a `uint32_t` primitive type.
```cpp
Napi::Number::Int32Value() const;
```
Returns the `int32_t` primitive type of the corresponding `Napi::Number` object.
### Uint32Value
Converts a `Napi::Number` value to a `uint32_t` primitive type.
```cpp
Napi::Number::Uint32Value() const;
```
Returns the `uint32_t` primitive type of the corresponding `Napi::Number` object.
### Int64Value
Converts a `Napi::Number` value to a `int64_t` primitive type.
```cpp
Napi::Number::Int64Value() const;
```
Returns the `int64_t` primitive type of the corresponding `Napi::Number` object.
### FloatValue
Converts a `Napi::Number` value to a `float` primitive type.
```cpp
Napi::Number::FloatValue() const;
```
Returns the `float` primitive type of the corresponding `Napi::Number` object.
### DoubleValue
Converts a `Napi::Number` value to a `double` primitive type.
```cpp
Napi::Number::DoubleValue() const;
```
Returns the `double` primitive type of the corresponding `Napi::Number` object.
## Operators
The `Napi::Number` class contains a set of operators to easily cast JavaScript
`Number` object to one of the following primitive types:
- `int32_t`
- `uint32_t`
- `int64_t`
- `float`
- `double`
### operator int32_t
Converts a `Napi::Number` value to a `int32_t` primitive.
```cpp
Napi::Number::operator int32_t() const;
```
Returns the `int32_t` primitive type of the corresponding `Napi::Number` object.
### operator uint32_t
Converts a `Napi::Number` value to a `uint32_t` primitive type.
```cpp
Napi::Number::operator uint32_t() const;
```
Returns the `uint32_t` primitive type of the corresponding `Napi::Number` object.
### operator int64_t
Converts a `Napi::Number` value to a `int64_t` primitive type.
```cpp
Napi::Number::operator int64_t() const;
```
Returns the `int64_t` primitive type of the corresponding `Napi::Number` object.
### operator float
Converts a `Napi::Number` value to a `float` primitive type.
```cpp
Napi::Number::operator float() const;
```
Returns the `float` primitive type of the corresponding `Napi::Number` object.
### operator double
Converts a `Napi::Number` value to a `double` primitive type.
```cpp
Napi::Number::operator double() const;
```
Returns the `double` primitive type of the corresponding `Napi::Number` object.
### Example
The following shows an example of casting a number to an `uint32_t` value.
```cpp
uint32_t operatorVal = Napi::Number::New(Env(), 10.0); // Number to unsigned 32 bit integer
// or
auto instanceVal = info[0].As<Number>().Uint32Value();
auto instanceVal = info[0].As<Napi::Number>().Uint32Value();
```

@@ -37,3 +37,3 @@ # Object lifetime management

std::string name = std::string("inner-scope") + std::to_string(i);
Value newValue = String::New(info.Env(), name.c_str());
Napi::Value newValue = Napi::String::New(info.Env(), name.c_str());
// do something with newValue

@@ -51,4 +51,4 @@ };

handles are no longer required, the scope can be deleted and any handles
associated with the scope are invalidated. The `HandleScope`
and `EscapableHandleScope` classes are provided by node-addon-api for
associated with the scope are invalidated. The `Napi::HandleScope`
and `Napi::EscapableHandleScope` classes are provided by node-addon-api for
creating additional scopes.

@@ -61,7 +61,7 @@

a native method must be deleted before returning from that method. Since
HandleScopes are typically stack allocated the compiler will take care of
`Napi::HandleScopes` are typically stack allocated the compiler will take care of
deletion, however, care must be taken to create the scope in the right
place such that you achieve the desired lifetime.
Taking the earlier example, creating a HandleScope in the innner loop
Taking the earlier example, creating a `Napi::HandleScope` in the innner loop
would ensure that at most a single new value is held alive throughout the

@@ -72,5 +72,5 @@ execution of the loop:

for (int i = 0; i < LOOP_MAX; i++) {
HandleScope scope(info.Env());
Napi::HandleScope scope(info.Env());
std::string name = std::string("inner-scope") + std::to_string(i);
Value newValue = String::New(info.Env(), name.c_str());
Napi::Value newValue = Napi::String::New(info.Env(), name.c_str());
// do something with neValue

@@ -82,7 +82,7 @@ };

inner scope needs to live beyond the lifespan of that scope. node-addon-api
provides the `EscapableHandleScope` with the Escape method
provides the `Napi::EscapableHandleScope` with the `Escape` method
in order to support this case. An escapable scope
allows one object to be 'promoted' so that it 'escapes' the
current scope and the lifespan of the handle changes from the current
scope to that of the outer scope. The Escape method can only be called
once for a given EscapableHandleScope.
scope to that of the outer scope. The `Escape` method can only be called
once for a given `Napi::EscapableHandleScope`.
# Object Reference
ObjectReference is a subclass of [Reference](reference.md), and is equivalent to an instance of `Reference<Object>`. This means that an ObjectReference holds an [Object](object.md), and a count of the number of references to that Object. When the count is greater than 0, an ObjectReference is not eligible for garbage collection. This ensures that the Object being held as a value of the ObjectReference will remain accessible, even if the original Object no longer is. However, ObjectReference is unique from a Reference since properties can be set and get to the Object itself that can be accessed through the ObjectReference.
`Napi::ObjectReference` is a subclass of [`Napi::Reference`](reference.md), and is equivalent to an instance of `Napi::Reference<Object>`. This means that a `Napi::ObjectReference` holds a [`Napi::Object`](object.md), and a count of the number of references to that Object. When the count is greater than 0, an ObjectReference is not eligible for garbage collection. This ensures that the Object being held as a value of the ObjectReference will remain accessible, even if the original Object no longer is. However, ObjectReference is unique from a Reference since properties can be set and get to the Object itself that can be accessed through the ObjectReference.
For more general information on references, please consult [Reference](referenc.md).
For more general information on references, please consult [`Napi::Reference`](referenc.md).

@@ -33,6 +33,6 @@ ## Example

```cpp
static ObjectReference New(const Object& value, uint32_t initialRefcount = 0);
static Napi::ObjectReference Napi::ObjectReference::New(const Napi::Object& value, uint32_t initialRefcount = 0);
```
* `[in] value`: The Object which is to be referenced.
* `[in] value`: The `Napi::Object` which is to be referenced.

@@ -44,3 +44,3 @@ * `[in] initialRefcount`: The initial reference count.

```cpp
static ObjectReference Weak(const Object& value);
static Napi::ObjectReference Napi::ObjectReference::Weak(const Napi::Object& value);
```

@@ -55,3 +55,3 @@

```cpp
static ObjectReference Persistent(const Object& value);
static Napi::ObjectReference Napi::ObjectReference::Persistent(const Napi::Object& value);
```

@@ -68,6 +68,6 @@

```cpp
ObjectReference();
Napi::ObjectReference::ObjectReference();
```
Returns a new _empty_ ObjectReference instance.
Returns a new _empty_ `Napi::ObjectReference` instance.

@@ -77,8 +77,8 @@ ### Constructor

```cpp
ObjectReference(napi_env env, napi_value value);
Napi::ObjectReference::ObjectReference(napi_env env, napi_value value);
```
* `[in] env`: The `napi_env` environment in which to construct the ObjectReference object.
* `[in] env`: The `napi_env` environment in which to construct the `Napi::ObjectReference` object.
* `[in] value`: The N-API primitive value to be held by the ObjectReference.
* `[in] value`: The N-API primitive value to be held by the `Napi::ObjectReference`.

@@ -89,3 +89,3 @@ Returns the newly created reference.

```cpp
void Set(___ key, ___ value);
void Napi::ObjectReference::Set(___ key, ___ value);
```

@@ -112,3 +112,3 @@

```cpp
Value Get(___ key);
Napi::Value Napi::ObjectReference::Get(___ key);
```

@@ -118,3 +118,3 @@

Returns the [Value](value.md) associated with the key property. Returns NULL if no such key exists.
Returns the [`Napi::Value`](value.md) associated with the key property. Returns NULL if no such key exists.

@@ -121,0 +121,0 @@ The `key` can be any of the following types:

@@ -1,13 +0,546 @@

## Object Wrap
# Object Wrap
The ```ObjectWrap``` class can be used to expose C++ code to JavaScript. To do
this you need to extend the ObjectWrap class that contain all the plumbing to connect
JavaScript code to a C++ object.
Classes extending ```ObjectWrap``` can be instantiated from JavaScript using the
**new** operator, and their methods can be directly invoked from JavaScript.
The **wrap** word refers to a way to group methods and state of your class because it
will be your responsibility write custom code to bridge each of your C++ class methods.
The `Napi::ObjectWrap` class is used to bind the lifetime of C++ code to a
JavaScript object. Once bound, each time an instance of the JavaScript object
is created, an instance of the C++ class will also be created. When a method
is called on the JavaScript object which is defined as an InstanceMethod, the
corresponding C++ method on the wrapped C++ class will be invoked.
You are reading a draft of the next documentation and it's in continuous 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/)
In order to create a wrapper it's necessary to extend the
`Napi::ObjectWrap`class which contains all the plumbing to connect JavaScript code
with a C++ object. Classes extending `Napi::ObjectWrap` can be instantiated from
JavaScript using the **new** operator, and their methods can be directly invoked
from JavaScript. The **wrap** word refers to a way of grouping methods and state
of the class because it will be necessary write custom code to bridge each of
your C++ class methods.
## 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) {
// This method is used to hook the accessor and method callbacks
Napi::Function func = DefineClass(env, "Example", {
InstanceMethod("GetValue", &Example::GetValue),
InstanceMethod("SetValue", &Example::SetValue)
});
// Create a peristent reference to the class constructor. This will allow
// a function called on a class prototype and a function
// called on instance of a class to be distinguished from each other.
constructor = Napi::Persistent(func);
// Call the SuppressDestruct() method on the static data prevent the calling
// to this destructor to reset the reference when the environment is no longer
// available.
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){
Napi::Env env = info.Env();
// ...
Napi::Number value = info[0].As<Napi::Number>();
this->_value = value.DoubleValue();
return this->GetValue(info);
}
// Initialize native add-on
Napi::Object Init (Napi::Env env, Napi::Object exports) {
Example::Init(env, exports);
return exports;
}
// Regisgter 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.GetValue())
// It prints 11
example.SetValue(19)
console.log(example.GetValue());
// It prints 19
```
At initialization time, the `Napi::ObjectWrap::DefineClass()` method must be used
to hook up the accessor and method callbacks. It takes a list of property
descriptors, which can be constructed via the various static methods on the base
class.
When JavaScript code invokes the constructor, the constructor callback will create
a new C++ instance and "wrap" it into the newly created JavaScript object.
When JavaScript code invokes a method or a property accessor on the class the
corresponding C++ callback function will be executed.
For a wrapped object it could be difficult to distinguish between a function called
on a class prototype and a function called on instance of a class. Therefore it is
good practice to save a persistent reference to the class constructor. This allows
the two cases to be distinguished from each other by checking the this object
against the class constructor.
## Methods
### Contructor
Creates a new instance of a JavaScript object that wraps native instance.
```cpp
Napi::ObjectWrap(const Napi::CallbackInfo& callbackInfo);
```
- `[in] callbackInfo`: The object representing the components of the JavaScript
request being made.
### Unwrap
Retrieves a native instance wrapped in a JavaScript object.
```cpp
static T* Napi::ObjectWrap::Unwrap(Napi::Object wrapper);
```
* `[in] wrapper`: The JavaScript object that wraps the native instance.
Returns a native instace wrapped in a JavaScript object. Given the
Napi:Object, this allows a method to get a pointer to the wrapped
C++ object and then reference fields, call methods, etc. within that class.
In many cases calling Unwrap is not required, as methods can
use the `this` field for ObjectWrap when running in a method on a
class that extends ObjectWrap.
### DefineClass
Defnines a JavaScript class with constructor, static and instance properties and
methods.
```cpp
static Napi::Function Napi::ObjectWrap::DefineClass(Napi::Env env,
const char* utf8name,
const std::initializer_list<PropertyDescriptor>& properties,
void* data = nullptr);
```
* `[in] env`: The environment in which to construct a JavaScript class.
* `[in] utf8name`: Null-terminated string that represents the name of the
JavaScript constructor function.
* `[in] properties`: Initializer list of class property descriptor describing
static and instance properties and methods of the class.
See: [`Class propertry and descriptor`](class_property_descriptor.md).
* `[in] data`: User-provided data passed to the constructor callback as `data`
property of the `Napi::CallbackInfo`.
Returns a `Napi::Function` representing the constructor function for the class.
### DefineClass
Defnines a JavaScript class with constructor, static and instance properties and
methods.
```cpp
static Napi::Function Napi::ObjectWrap::DefineClass(Napi::Env env,
const char* utf8name,
const std::vector<PropertyDescriptor>& properties,
void* data = nullptr);
```
* `[in] env`: The environment in which to construct a JavaScript class.
* `[in] utf8name`: Null-terminated string that represents the name of the
JavaScript constructor function.
* `[in] properties`: Vector of class property descriptor describing static and
instance properties and methods of the class.
See: [`Class propertry and descriptor`](class_property_descriptor.md).
* `[in] data`: User-provided data passed to the constructor callback as `data`
property of the `Napi::CallbackInfo`.
Returns a `Napi::Function` representing the constructor function for the class.
### StaticMethod
Creates property descriptor that represents a static method of a JavaScript class.
```cpp
static Napi::PropertyDescriptor Napi::ObjectWrap::StaticMethod(const char* utf8name,
StaticVoidMethodCallback method,
napi_property_attributes attributes = napi_default,
void* data = nullptr);
```
- `[in] utf8name`: Null-terminated string that represents the name of a static
method for the class.
- `[in] method`: The native function that represents a static method of a
JavaScript class.
- `[in] attributes`: The attributes associated with a particular property.
One or more of `napi_property_attributes`.
- `[in] data`: User-provided data passed into method when it is invoked.
Returns `Napi::PropertyDescriptor` object that represents the static method of a
JavaScript class.
### StaticMethod
Creates property descriptor that represents a static method of a JavaScript class.
```cpp
static Napi::PropertyDescriptor Napi::ObjectWrap::StaticMethod(const char* utf8name,
StaticMethodCallback method,
napi_property_attributes attributes = napi_default,
void* data = nullptr);
```
- `[in] utf8name`: Null-terminated string that represents the name of a static
method for the class.
- `[in] method`: The native function that represents a static method of a
JavaScript class.
- `[in] attributes`: The attributes associated with a particular property.
One or more of `napi_property_attributes`.
- `[in] data`: User-provided data passed into method when it is invoked.
Returns `Napi::PropertyDescriptor` object that represents a static method of a
JavaScript class.
### StaticMethod
Creates property descriptor that represents a static method of a JavaScript class.
```cpp
static Napi::PropertyDescriptor Napi::ObjectWrap::StaticMethod(Symbol name,
StaticVoidMethodCallback method,
napi_property_attributes attributes = napi_default,
void* data = nullptr);
```
- `[in] name`: Napi:Symbol that represents the name of a static
method for the class.
- `[in] method`: The native function that represents a static method of a
JavaScript class.
- `[in] attributes`: The attributes associated with a particular property.
One or more of `napi_property_attributes`.
- `[in] data`: User-provided data passed into method when it is invoked.
Returns `Napi::PropertyDescriptor` object that represents the static method of a
JavaScript class.
### StaticMethod
Creates property descriptor that represents a static method of a JavaScript class.
```cpp
static Napi::PropertyDescriptor Napi::ObjectWrap::StaticMethod(Symbol name,
StaticMethodCallback method,
napi_property_attributes attributes = napi_default,
void* data = nullptr);
```
method for the class.
- `[in] name`: Napi:Symbol that represents the name of a static.
- `[in] method`: The native function that represents a static method of a
JavaScript class.
- `[in] attributes`: The attributes associated with a particular property.
One or more of `napi_property_attributes`.
- `[in] data`: User-provided data passed into method when it is invoked.
Returns `Napi::PropertyDescriptor` object that represents a static method of a
JavaScript class.
### StaticAccessor
Creates property descriptor that represents a static accessor property of a
JavaScript class.
```cpp
static Napi::PropertyDescriptor Napi::ObjectWrap::StaticAccessor(const char* utf8name,
StaticGetterCallback getter,
StaticSetterCallback setter,
napi_property_attributes attributes = napi_default,
void* data = nullptr);
```
- `[in] utf8name`: Null-terminated string that represents the name of a static
accessor property for the class.
- `[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 a particular property.
One or more of `napi_property_attributes`.
- `[in] data`: User-provided data passed into getter or setter when
is invoked.