diff --git a/README.md b/README.md index 9a27d6c4d..8a22b123d 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,19 @@ -# **node-addon-api module** +# **node-addon-api module** This module contains **header-only C++ wrapper classes** which simplify the use of the C based [N-API](https://nodejs.org/dist/latest/docs/api/n-api.html) provided by Node.js when using C++. It provides a C++ object model and exception handling semantics with low overhead. -N-API is an ABI stable C interface provided by Node.js for building native +N-API is an ABI stable C interface provided by Node.js for building native addons. It is independent from the underlying JavaScript runtime (e.g. V8 or ChakraCore) -and is maintained as part of Node.js itself. It is intended to insulate -native addons from changes in the underlying JavaScript engine and allow -modules compiled for one version to run on later versions of Node.js without +and is maintained as part of Node.js itself. It is intended to insulate +native addons from changes in the underlying JavaScript engine and allow +modules compiled for one version to run on later versions of Node.js without recompilation. The `node-addon-api` module, which is not part of Node.js, preserves the benefits of the N-API as it consists only of inline code that depends only on the stable API -provided by N-API. As such, modules built against one version of Node.js +provided by N-API. As such, modules built against one version of Node.js using node-addon-api should run without having to be rebuilt with newer versions of Node.js. @@ -63,8 +63,7 @@ to ideas specified in the **ECMA262 Language Specification**. ### **API Documentation** -The following is the documentation for node-addon-api (NOTE: -still a work in progress as its not yet complete). +The following is the documentation for node-addon-api. - [Basic Types](doc/basic_types.md) - [Array](doc/basic_types.md#array) diff --git a/doc/array_buffer.md b/doc/array_buffer.md index 754983686..e7217d73a 100644 --- a/doc/array_buffer.md +++ b/doc/array_buffer.md @@ -1,6 +1,6 @@ # 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) class. @@ -8,114 +8,114 @@ class. ### New -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 -static ArrayBuffer New(napi_env env, +static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength, Finalizer finalizeCallback); ``` -- `[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. ```cpp template -static ArrayBuffer New(napi_env env, +static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength, Finalizer finalizeCallback, Hint* finalizeHint); ``` -- `[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 `externalData` pointer) and `Hint*`, and return `void`. - `[in] finalizeHint`: The hint to be passed as the second parameter of the finalize callback. -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(); ``` ### Constructor -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. ### ByteLength ```cpp -size_t ByteLength() const; +size_t Napi::ArrayBuffer::ByteLength() const; ``` Returns the length of the wrapped data, in bytes. @@ -123,7 +123,7 @@ Returns the length of the wrapped data, in bytes. ### Data ```cpp -T* Data() const; +T* Napi::ArrayBuffer::Data() const; ``` Returns a pointer the wrapped data. diff --git a/doc/async_operations.md b/doc/async_operations.md index b8dec37cf..ee445dd3f 100644 --- a/doc/async_operations.md +++ b/doc/async_operations.md @@ -17,7 +17,7 @@ Node Addon API provides an interface to support functions that cover the most common asynchronous use cases. There is an abstract classes to implement 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**. diff --git a/doc/async_worker.md b/doc/async_worker.md index 0d78c1b62..a71b29d9f 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -1,17 +1,19 @@ # 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. ## Methods @@ -20,7 +22,7 @@ subclass. Requests the environment in which the async worker has been initially created. ```cpp -Env Env() const; +Napi::Env Napi::AsyncWorker::Env() const; ``` Returns the environment in which the async worker has been created. @@ -30,7 +32,7 @@ Returns the environment in which the async worker has been created. Requests that the work be queued for execution. ```cpp -void Queue(); +void Napi::AsyncWorker::Queue(); ``` ### Cancel @@ -40,13 +42,13 @@ executing, it cannot be cancelled. If cancelled successfully neither `OnOK` nor `OnError` will be called. ```cpp -void Cancel(); +void Napi::AsyncWorker::Cancel(); ``` ### Receiver ```cpp -ObjectReference& Receiver(); +Napi::ObjectReference& Napi::AsyncWorker::Receiver(); ``` Returns the persistent object reference of the receiver object set when the async @@ -55,22 +57,24 @@ worker was created. ### Callback ```cpp -FunctionReference& Callback(); +Napi::FunctionReference& Napi::AsyncWorker::Callback(); ``` Returns the persistent function reference of the callback set when the async 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. ### 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); ``` - `[in] error`: The reference to the string that represent the message of the error. @@ -81,13 +85,13 @@ This method is used to execute some tasks out of the **event loop** on a libuv worker thread. Subclasses must implement this method and the method is run on a thread other than that running the main event loop. As the method is not 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; ``` ### OnOK @@ -97,41 +101,41 @@ The default implementation runs the Callback provided when the AsyncWorker class was created. ```cpp -virtual void OnOK(); +virtual void Napi::AsyncWorker::OnOK(); ``` ### OnError -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); ``` ### Constructor -Creates a new `AsyncWorker`. +Creates a new `Napi::AsyncWorker`. ```cpp -explicit AsyncWorker(const Function& callback); +explicit Napi::AsyncWorker(const Napi::Function& callback); ``` - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. -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`. ### Constructor -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); ``` - `[in] callback`: The function which will be called when an asynchronous @@ -140,16 +144,15 @@ operations ends. The given function is called from the main event loop thread. identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. -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); ``` - `[in] callback`: The function which will be called when an asynchronous @@ -160,31 +163,30 @@ information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. -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); ``` - `[in] receiver`: The `this` object passed to the called function. - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. -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); ``` - `[in] receiver`: The `this` object passed to the called function. @@ -194,16 +196,15 @@ operations ends. The given function is called from the main event loop thread. identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. -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); ``` - `[in] receiver`: The `this` object passed to the called function. @@ -215,42 +216,44 @@ information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. -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`. ### Destructor Deletes the created work object that is used to execute logic asynchronously. ```cpp -virtual ~AsyncWorker(); +virtual Napi::AsyncWorker::~AsyncWorker(); ``` ## Operator ```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: ```cpp #include @@ -283,13 +286,21 @@ class EchoWorker : public AsyncWorker { ``` 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 + +// Include EchoWorker class +// .. + +use namespace Napi; + Value Echo(const CallbackInfo& info) { // You need to check the input data here Function cb = info[1].As(); @@ -299,8 +310,8 @@ Value Echo(const CallbackInfo& info) { return info.Env().Undefined(); ``` -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. diff --git a/doc/basic_types.md b/doc/basic_types.md index 43b041dc8..7e65ead1b 100644 --- a/doc/basic_types.md +++ b/doc/basic_types.md @@ -6,7 +6,7 @@ interoperate with their C++ counterparts. ## Value -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 the N-API datatype `napi_value`. Methods on this class can be used to check the JavaScript type of the underlying N-API `napi_value` and also to convert to @@ -15,21 +15,21 @@ C++ types. ### Constructor ```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. ### Operators @@ -37,7 +37,7 @@ in. #### operator napi_value ```cpp -operator napi_value() const; +Napi::Value::operator napi_value() const; ``` Returns the underlying N-API `napi_value`. If the instance is _empty_, this @@ -46,7 +46,7 @@ returns `nullptr`. #### operator == ```cpp -bool operator ==(const Value& other) const; +bool Napi::Value::operator ==(const Value& other) const; ``` Returns `true` if this value strictly equals another value, or `false` otherwise. @@ -54,7 +54,7 @@ Returns `true` if this value strictly equals another value, or `false` otherwise #### operator != ```cpp -bool operator !=(const Value& other) const; +bool Napi::Value::operator !=(const Value& other) const; ``` Returns `false` if this value strictly equals another value, or `true` otherwise. @@ -64,10 +64,10 @@ Returns `false` if this value strictly equals another value, or `true` otherwise #### From ```cpp template -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. Returns a `Napi::Value` representing the input C++ type in JavaScript. @@ -86,7 +86,7 @@ Here, `value` may be any of: #### As ```cpp -template T As() const; +template T Napi::Value::As() const; ``` Returns the `Napi::Value` cast to a desired C++ type. @@ -99,7 +99,7 @@ the actual value type will throw `Napi::Error`. #### StrictEquals ```cpp -bool StrictEquals(const Value& other) const; +bool Napi::Value::StrictEquals(const Value& other) const; ``` - `[in] other` - The value to compare against. @@ -108,7 +108,7 @@ Returns true if the other `Napi::Value` is strictly equal to this one. #### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::Value::Env() const; ``` Returns the environment that the value is associated with. See @@ -116,7 +116,7 @@ Returns the environment that the value is associated with. See #### IsEmpty ```cpp -bool IsEmpty() const; +bool Napi::Value::IsEmpty() const; ``` Returns `true` if the value is uninitialized. @@ -125,21 +125,21 @@ An empty value is invalid, and most attempts to perform an operation on an empty value will result in an exception. An empty value is distinct from JavaScript `null` or `undefined`, which are valid values. -When C++ exceptions are disabled at compile time, a method with a `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++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the value. #### Type ```cpp -napi_valuetype Type() const; +napi_valuetype Napi::Value::Type() const; ``` Returns the underlying N-API `napi_valuetype` of the value. #### IsUndefined ```cpp -bool IsUndefined() const; +bool Napi::Value::IsUndefined() const; ``` Returns `true` if the underlying value is a JavaScript `undefined` or `false` @@ -147,7 +147,7 @@ otherwise. #### IsNull ```cpp -bool IsNull() const; +bool Napi::Value::IsNull() const; ``` Returns `true` if the underlying value is a JavaScript `null` or `false` @@ -155,103 +155,103 @@ otherwise. #### IsBoolean ```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. #### IsString ```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. #### IsSymbol ```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. #### IsArray ```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. #### IsArrayBuffer ```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. #### IsTypedArray ```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. #### IsObject ```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. #### IsFunction ```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. #### IsPromise ```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. #### IsDataView ```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. #### IsBuffer ```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. #### IsExternal ```cpp -bool IsExternal() const; +bool Napi::Value::IsExternal() const; ``` Returns `true` if the underlying value is a N-API external object or `false` @@ -259,7 +259,7 @@ otherwise. #### ToBoolean ```cpp -Boolean ToBoolean() const; +Napi::Boolean Napi::Value::ToBoolean() const; ``` Returns a `Napi::Boolean` representing the `Napi::Value`. @@ -269,10 +269,9 @@ exception if the coercion fails. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - #### ToNumber ```cpp -Number ToNumber() const; +Napi::Number Napi::Value::ToNumber() const; ``` Returns a `Napi::Number` representing the `Napi::Value`. @@ -284,10 +283,9 @@ exception if the coercion fails. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - #### ToString ```cpp -String ToString() const; +Napi::String Napi::Value::ToString() const; ``` Returns a `Napi::String` representing the `Napi::Value`. @@ -298,10 +296,9 @@ JavaScript exception if the coercion fails. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - #### ToObject ```cpp -Object ToObject() const; +Napi::Object Napi::Value::ToObject() const; ``` Returns a `Napi::Object` representing the `Napi::Value`. @@ -311,29 +308,28 @@ exception if the coercion fails. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - ## Name Names are JavaScript values that can be used as a property name. There are two -specialized types of names supported in Node.js Addon API- [`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). ### Methods #### Constructor ```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); ``` - `[in] env` - The environment in which to create the array. - `[in] value` - The primitive to wrap. -Returns a Name created from the JavaScript primitive. +Returns a `Napi::Name` created from the JavaScript primitive. Note: The value is not coerced to a string. @@ -345,7 +341,7 @@ around `napi_value` representing a JavaScript Array. ### Constructor ```cpp -Array(); +Napi::Array::Array(); ``` Returns an empty array. @@ -354,9 +350,8 @@ If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - ```cpp -Array(napi_env env, napi_value value); +Napi::Array::Array(napi_env env, napi_value value); ``` - `[in] env` - The environment in which to create the array. - `[in] value` - The primitive to wrap. @@ -371,7 +366,7 @@ attempting to use the returned value. #### New ```cpp -static Array New(napi_env env); +static Napi::Array Napi::Array::New(napi_env env); ``` - `[in] env` - The environment in which to create the array. @@ -384,7 +379,7 @@ attempting to use the returned value. #### New ```cpp -static Array New(napi_env env, size_t length); +static Napi::Array Napi::Array::New(napi_env env, size_t length); ``` - `[in] env` - The environment in which to create the array. - `[in] length` - The length of the array. @@ -395,9 +390,9 @@ If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. -#### New +#### Length ```cpp -uint32_t Length() const; +uint32_t Napi::Array::Length() const; ``` Returns the length of the array. diff --git a/doc/boolean.md b/doc/boolean.md index 070f21e1f..2886b1d0c 100644 --- a/doc/boolean.md +++ b/doc/boolean.md @@ -1,9 +1,5 @@ # 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/) - # Methods ### Constructor @@ -15,19 +11,19 @@ Napi::Boolean::New(Napi::Env env, bool value); - `[in] value`: The Javascript boolean value ```cpp -Napi::Boolean(); +Napi::Boolean::Boolean(); ``` returns a new empty Javascript Boolean value type. ### operator bool -Converts a Boolean value to a boolean primitive. +Converts a `Napi::Boolean` value to a boolean primitive. ```cpp -operator bool() const; +Napi::Boolean::operator bool() const; ``` ### Value -Converts a Boolean value to a boolean primitive. +Converts a `Napi::Boolean` value to a boolean primitive. ```cpp -bool Value() const; -``` \ No newline at end of file +bool Napi::Boolean::Value() const; +``` diff --git a/doc/buffer.md b/doc/buffer.md index e37f7d980..8f76b200d 100644 --- a/doc/buffer.md +++ b/doc/buffer.md @@ -1,132 +1,132 @@ # 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. ## Methods ### New -Allocates a new `Buffer` object with a given length. +Allocates a new `Napi::Buffer` object with a given length. ```cpp -static Buffer New(napi_env env, size_t length); +static Napi::Buffer 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 needs to be freed. ```cpp -static Buffer New(napi_env env, T* data, size_t length); +static Napi::Buffer 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 -static Buffer New(napi_env env, +static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length, Finalizer finalizeCallback); ``` -- `[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 -static Buffer New(napi_env env, +static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length, Finalizer finalizeCallback, Hint* finalizeHint); ``` -- `[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 `Hint*`, and return `void`. - `[in] finalizeHint`: The hint to be passed as the second parameter of the finalize callback. -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 Copy(napi_env env, const T* data, size_t length); +static Napi::Buffer 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(); ``` ### Constructor -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. ### Data ```cpp -T* Data() const; +T* Napi::Buffer::Data() const; ``` Returns a pointer the external data. @@ -134,7 +134,7 @@ Returns a pointer the external data. ### Length ```cpp -size_t Length() const; +size_t Napi::Buffer::Length() const; ``` Returns the number of `T` elements in the external data. diff --git a/doc/callbackinfo.md b/doc/callbackinfo.md index add1ea00e..0bf4e1ad1 100644 --- a/doc/callbackinfo.md +++ b/doc/callbackinfo.md @@ -1,30 +1,28 @@ -**WORK IN PROGRESS, NOT YET COMPLETE** - # CallbackInfo The object representing the components of the JavaScript request being made. -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. ## Methods ### Constructor ```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. ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::CallbackInfo::Env() const; ``` Returns the `Env` object in which the request is being made. @@ -32,42 +30,41 @@ Returns the `Env` object in which the request is being made. ### NewTarget ```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. ### 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. ### operator [] ```cpp -const Value operator [](size_t index) const; +const Napi::Value operator [](size_t index) const; ``` - `[in] index`: The zero-based index of the requested argument. -Returns a `Value` object containing the requested argument. +Returns a `Napi::Value` object containing the requested argument. ### This ```cpp -Value This() const; +Napi::Value Napi::CallbackInfo::This() const; ``` Returns the JavaScript `this` value for the call @@ -75,7 +72,7 @@ Returns the JavaScript `this` value for the call ### Data ```cpp -void* Data() const; +void* Napi::CallbackInfo::Data() const; ``` Returns the data pointer for the callback. @@ -83,18 +80,18 @@ Returns the data pointer for the callback. ### SetData ```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. Returns `void`. ### Not documented here ```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; ``` diff --git a/doc/env.md b/doc/env.md index 344b8be24..9bde741ca 100644 --- a/doc/env.md +++ b/doc/env.md @@ -1,5 +1,3 @@ -**WORK IN PROGRESS, NOT YET COMPLETE** - # Env The opaque data structure containing the environment in which the request is being run. @@ -11,10 +9,10 @@ The Env object is usually created and passed by the Node.js runtime or node-addo ### Constructor ```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. ### napi_env @@ -27,31 +25,31 @@ Returns the `napi_env` opaque data structure representing the environment. ### Global ```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. ### 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. ### 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. ### IsExceptionPending ```cpp -bool IsExceptionPending() const; +bool Napi::Env::IsExceptionPending() const; ``` Returns a `bool` indicating if an exception is pending in the environment. @@ -59,7 +57,7 @@ Returns a `bool` indicating if an exception is pending in the environment. ### GetAndClearPendingException ```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. diff --git a/doc/error.md b/doc/error.md index dc5e7ea07..1526bddf0 100644 --- a/doc/error.md +++ b/doc/error.md @@ -1,14 +1,14 @@ # 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. For more details about error handling refer to the section titled [Error handling](error_handling.md). @@ -17,41 +17,41 @@ For more details about error handling refer to the section titled [Error handlin ### New -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. ### Fatal @@ -59,38 +59,38 @@ In case of an unrecoverable error in a native module, a fatal error can be throw to immediately terminate the process. ```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); ``` The function call does not return, the process will be terminated. ### Constructor -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. ### Message ```cpp -std::string& Message() const NAPI_NOEXCEPT; +std::string& Napi::Error::Message() const NAPI_NOEXCEPT; ``` Returns the reference to the string that represent the message of the error. @@ -100,7 +100,7 @@ Returns the reference to the string that represent the message of the error. Throw the error as JavaScript exception. ```cpp -void ThrowAsJavaScriptException() const; +void Napi::Error::ThrowAsJavaScriptException() const; ``` Throws the error as a JavaScript exception. @@ -108,7 +108,7 @@ Throws the error as a JavaScript exception. ### what ```cpp -const char* what() const NAPI_NOEXCEPT override; +const char* Napi::Error::what() const NAPI_NOEXCEPT override; ``` Returns a pointer to a null-terminated string that is used to identify the diff --git a/doc/error_handling.md b/doc/error_handling.md index d56281575..d5df55450 100644 --- a/doc/error_handling.md +++ b/doc/error_handling.md @@ -6,12 +6,12 @@ have to handle and dispatch it correctly. **node-addon-api** uses return values JavaScript exceptions for error handling. You can choose return values or exception handling based on the mechanism that works best for your add-on. -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++ 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. The following sections explain the approach for each case: @@ -34,14 +34,14 @@ returning from a native method. If a node-addon-api call fails without executing any JavaScript code (for example due to 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. On return from a native method, node-addon-api will automatically convert a pending C++ @@ -57,35 +57,35 @@ returning from a native method. ```cpp Env env = ... -throw Error::New(env, "Example exception"); +throw Napi::Error::New(env, "Example exception"); // other C++ statements // ... ``` 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 when returning to JavaScript. ### Propagating a N-API C++ exception ```cpp -Function jsFunctionThatThrows = someObj.As(); -Value result = jsFunctionThatThrows({ arg1, arg2 }); +Napi::Function jsFunctionThatThrows = someObj.As(); +Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); // other C++ statements // ... ``` 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 a JavaScript exception when returning to JavaScript. ### Handling a N-API C++ exception ```cpp -Function jsFunctionThatThrows = someObj.As(); -Value result; +Napi::Function jsFunctionThatThrows = someObj.As(); +Napi::Value result; try { result = jsFunctionThatThrows({ arg1, arg2 }); } catch (const Error& e) { @@ -101,22 +101,22 @@ exception. ## Handling Errors Without C++ Exceptions 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. ## Examples with C++ exceptions disabled ### Throwing a JS exception ```cpp -Env env = ... -Error::New(env, "Example exception").ThrowAsJavaScriptException(); +Napi::Env env = ... +Napi::Error::New(env, "Example exception").ThrowAsJavaScriptException(); return; ``` @@ -126,28 +126,27 @@ immediately from the native callback, after performing any necessary cleanup. ### Propagating a N-API JS exception ```cpp -Env env = ... -Function jsFunctionThatThrows = someObj.As(); -Value result = jsFunctionThatThrows({ arg1, arg2 }); +Napi::Env env = ... +Napi::Function jsFunctionThatThrows = someObj.As(); +Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); if (env.IsExceptionPending()) { Error e = env.GetAndClearPendingException(); return e.Value(); } ``` -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. ### Handling a N-API JS exception ```cpp -Env env = ... -Function jsFunctionThatThrows = someObj.As(); -Value result = jsFunctionThatThrows({ arg1, arg2 }); +Napi::Env env = ... +Napi::Function jsFunctionThatThrows = someObj.As(); +Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); if (env.IsExceptionPending()) { - Error e = env.GetAndClearPendingException(); + Napi::Error e = env.GetAndClearPendingException(); cerr << "Caught JavaScript exception: " + e.Message(); } ``` diff --git a/doc/escapable_handle_scope.md b/doc/escapable_handle_scope.md index 4ebd107f4..978aab354 100644 --- a/doc/escapable_handle_scope.md +++ b/doc/escapable_handle_scope.md @@ -1,17 +1,17 @@ # 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 keep an object alive in the heap in order to ensure that the objects are not collected by the garbage collector while native code is using them. A handle may be created when any new node-addon-api Value or one of its subclasses is created or returned. -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). ## Methods @@ -20,63 +20,63 @@ For more details refer to the section titled Creates a new escapable handle scope. ```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` ### Constructor Creates a new escapable handle scope. ```cpp -EscapableHandleScope EscapableHandleScope::New(napi_env env, napi_handle_scope scope); +Napi::EscapableHandleScope Napi::EscapableHandleScope::New(napi_env env, napi_handle_scope scope); ``` - `[in] env`: napi_env in which the scope passed in was created. - `[in] scope`: pre-existing napi_handle_scope. -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 to mix usage of the C N-API and node-addon-api. operator EscapableHandleScope::napi_escapable_handle_scope ```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 the class to be used be converted to a napi_escapable_handle_scope. ### Destructor ```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 guarantee as to when the gargbage collector will do this. ### Escape ```cpp -napi::Value EscapableHandleScope::Escape(napi_value escapee); +napi::Value Napi::EscapableHandleScope::Escape(napi_value escapee); ``` - `[in] escapee`: Napi::Value or napi_env to promote to the outer scope -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. ### Env ```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`. diff --git a/doc/external.md b/doc/external.md index 3bcda8fda..4022b61dd 100644 --- a/doc/external.md +++ b/doc/external.md @@ -1,10 +1,8 @@ -**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. ## Methods @@ -12,50 +10,50 @@ External objects can be created with an optional Finalizer function and optional ```cpp template -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` object. +Returns the created `Napi::External` object. ### New ```cpp template -static External New(napi_env env, +static Napi::External Napi::External::New(napi_env env, T* data, 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` object. +Returns the created `Napi::External` object. ### New ```cpp template -static External New(napi_env env, +static Napi::External Napi::External::New(napi_env env, T* data, Finalizer finalizeCallback, Hint* finalizeHint); ``` -- `[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` object. +Returns the created `Napi::External` object. ### 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. diff --git a/doc/function.md b/doc/function.md index ca85ef05a..3e8351ba3 100644 --- a/doc/function.md +++ b/doc/function.md @@ -5,7 +5,7 @@ native code that can later be called from JavaScript. The created function is no 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 `Function` class also provides methods that can be used to call +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 @@ -54,7 +54,7 @@ on the stack (for example when running a native method called from JavaScript). Creates a new empty instance of `Napi::Function`. ```cpp -Function(); +Napi::Function::Function(); ``` ### Constructor @@ -62,7 +62,7 @@ Function(); Creates a new instance of the `Napi::Function` object. ```cpp -Function(napi_env env, napi_value value); +Napi::Function::Function(napi_env env, napi_value value); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. @@ -76,7 +76,7 @@ Creates an instance of a `Napi::Function` object. ```cpp template -static Function New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr); +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. @@ -91,7 +91,7 @@ Returns an instance of a `Napi::Function` object. ```cpp template -static Function New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr); +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. @@ -108,7 +108,7 @@ Creates a new JavaScript value from one that represents the constructor for the object. ```cpp -Napi::Object New(const std::initializer_list& args) const; +Napi::Object Napi::Function::New(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing @@ -122,7 +122,7 @@ Creates a new JavaScript value from one that represents the constructor for the object. ```cpp -Napi::Object New(const std::vector& args) const; +Napi::Object Napi::Function::New(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the @@ -136,7 +136,7 @@ Creates a new JavaScript value from one that represents the constructor for the object. ```cpp -Napi::Object New(size_t argc, const napi_value* args) const; +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. @@ -150,7 +150,7 @@ Returns a new JavaScript object. Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(const std::initializer_list& args) const; +Napi::Value Napi::Function::Call(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing @@ -163,7 +163,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a JavaScript function from a native add-on. ```cpp -Napi::Value Call(const std::vector& args) const; +Napi::Value Napi::Function::Call(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the @@ -176,7 +176,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(size_t argc, const napi_value* args) const; +Napi::Value Napi::Function::Call(size_t argc, const napi_value* args) const; ``` - `[in] argc`: The number of the arguments passed to the function. @@ -190,7 +190,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::initializer_list& args) const; +Napi::Value Napi::Function::Call(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -204,7 +204,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::vector& args) const; +Napi::Value Napi::Function::Call(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -218,7 +218,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, size_t argc, const napi_value* args) const; +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. @@ -233,7 +233,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -247,7 +247,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; +Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -261,7 +261,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Napi::Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; +Napi::Value Napi::Function::MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -274,7 +274,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi ## Operator ```cpp -Napi::Value operator ()(const std::initializer_list& args) const; +Napi::Value Napi::Function::operator ()(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value`. diff --git a/doc/function_reference.md b/doc/function_reference.md index 356fe1d93..a18a9b898 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -23,7 +23,7 @@ Creates a "weak" reference to the value, in that the initial reference count is set to 0. ```cpp -static FunctionReference Weak(const Function& value); +static Napi::FunctionReference Napi::FunctionReference::Weak(const Napi::Function& value); ``` - `[in] value`: The value which is to be referenced. @@ -36,7 +36,7 @@ Creates a "persistent" reference to the value, in that the initial reference count is set to 1. ```cpp -static FunctionReference Persistent(const Function& value); +static Napi::FunctionReference Napi::FunctionReference::Persistent(const Napi::Function& value); ``` - `[in] value`: The value which is to be referenced. @@ -48,7 +48,7 @@ Returns the newly created reference. Creates a new empty instance of `Napi::FunctionReference`. ```cpp -FunctionReference(); +Napi::FunctionReference::FunctionReference(); ``` ### Constructor @@ -56,7 +56,7 @@ FunctionReference(); Creates a new instance of the `Napi::FunctionReference`. ```cpp -FunctionReference(napi_env env, napi_ref ref); +Napi::FunctionReference::FunctionReference(napi_env env, napi_ref ref); ``` - `[in] env`: The environment in which to construct the `Napi::FunctionReference` object. @@ -69,7 +69,7 @@ Returns a newly created `Napi::FunctionReference` object. Constructs a new instance by calling the constructor held by this reference. ```cpp -Napi::Object New(const std::initializer_list& args) const; +Napi::Object Napi::FunctionReference::New(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing @@ -82,7 +82,7 @@ Returns a new JavaScript object. Constructs a new instance by calling the constructor held by this reference. ```cpp -Napi::Object New(const std::vector& args) const; +Napi::Object Napi::FunctionReference::New(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the @@ -95,7 +95,7 @@ Returns a new JavaScript object. Calls a referenced Javascript function from a native add-on. ```cpp -Napi::Value Call(const std::initializer_list& args) const; +Napi::Value Napi::FunctionReference::Call(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing @@ -106,10 +106,10 @@ function. ### Call -Calls a referenced Javascript function from a native add-on. +Calls a referenced JavaScript function from a native add-on. ```cpp -Napi::Value Call(const std::vector& args) const; +Napi::Value Napi::FunctionReference::Call(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the @@ -120,10 +120,10 @@ function. ### Call -Calls a referenced Javascript function from a native add-on. +Calls a referenced JavaScript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::initializer_list& args) const; +Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. @@ -135,10 +135,10 @@ function. ### Call -Calls a referenced Javascript function from a native add-on. +Calls a referenced JavaScript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::vector& args) const; +Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. @@ -167,11 +167,11 @@ function. ### MakeCallback -Calls a referenced Javascript function from a native add-on after an asynchronous +Calls a referenced JavaScript function from a native add-on after an asynchronous operation. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. @@ -183,11 +183,11 @@ function. ### MakeCallback -Calls a referenced Javascript function from a native add-on after an asynchronous +Calls a referenced JavaScript function from a native add-on after an asynchronous operation. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; +Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. diff --git a/doc/handle_scope.md b/doc/handle_scope.md index 81a63fa28..9b34fcf2f 100644 --- a/doc/handle_scope.md +++ b/doc/handle_scope.md @@ -6,7 +6,7 @@ keep an object alive in the heap in order to ensure that the objects are not collected while native code is using them. A handle may be created when any new node-addon-api Value or one 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). ## Methods @@ -15,52 +15,51 @@ the section titled (Object lifetime management)[object_lifetime_management]. Creates a new handle scope on the stack. ```cpp -HandleScope(Napi:Env env); +Napi::HandleScope::HandleScope(Napi::Env env); ``` -- `[in] env`: The environment in which to construct the HandleScope object. - -Returns a new HandleScope +- `[in] env`: The environment in which to construct the `Napi::HandleScope` object. +Returns a new `Napi::HandleScope` ### Constructor Creates a new handle scope on the stack. ```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 and node-addon-api. operator HandleScope::napi_handle_scope ```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 the class to be used be converted to a napi_handle_scope. ### Destructor ```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 guarantee as to when the gargbage collector will do this. ### Env ```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`. diff --git a/doc/memory_management.md b/doc/memory_management.md index 2cabd57ca..afa622550 100644 --- a/doc/memory_management.md +++ b/doc/memory_management.md @@ -1,6 +1,6 @@ # 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 JavaScript objects. @@ -17,7 +17,7 @@ more often than it would otherwise in an attempt to garbage collect the JavaScri objects that keep the externally allocated memory alive. ```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); ``` - `[in] env`: The environment in which the API is invoked under. diff --git a/doc/number.md b/doc/number.md index a08b0abc4..d1bee4810 100644 --- a/doc/number.md +++ b/doc/number.md @@ -3,7 +3,6 @@ A Javascript number value. ## Methods - ### Constructor ```cpp @@ -13,21 +12,21 @@ Napi::Number::New(Napi::Env env, double value); - `[in] value`: The value the Javascript Number will contain ```cpp -Napi::Number(); +Napi::Number::Number(); ``` returns a new empty Javascript Number You can easily cast a Javascript number to one of: - - int32_t - - uint32_t - - int64_t - - float - - double + - `int32_t` + - `uint32_t` + - `int64_t` + - `float` + - `double` The following shows an example of casting a number to an uint32_t value. ```cpp -uint32_t operatorVal = Number::New(Env(), 10.0); // Number to unsigned 32 bit integer +uint32_t operatorVal = Napi::Number::New(Env(), 10.0); // Number to unsigned 32 bit integer // or -auto instanceVal = info[0].As().Uint32Value(); +auto instanceVal = info[0].As().Uint32Value(); ``` diff --git a/doc/object.md b/doc/object.md index 38895a10b..3e32fa4e9 100644 --- a/doc/object.md +++ b/doc/object.md @@ -1,12 +1,12 @@ # Object -The Object class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types: +The `Napi::Object` class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types: -- [Value](value.md) and extends [Array](array.md) -- [ArrayBuffer](array_buffer.md) -- [Buffer](buffer.md) -- [Function](function.md) -- [TypedArray](typed_array.md). +- [`Napi::Value`](value.md) and extends [`Napi::Array`](array.md) +- [`Napi::ArrayBuffer`](array_buffer.md) +- [`Napi::Buffer`](buffer.md) +- [`Napi::Function`](function.md) +- [`Napi::TypedArray`](typed_array.md). This class provides a number of convenience methods, most of which are used to set or get properties on a JavaScript object. For example, Set() and Get(). @@ -62,19 +62,19 @@ Napi::Object::Object(napi_env env, napi_value value); - const char16_t* (encoded using UTF-16-LE, null-terminated) - std::string (encoded using UTF-8) - std::u16string - - napi::Value + - Napi::Value - napi_value -Creates a non-empty Object instance. +Creates a non-empty `Napi::Object` instance. ### New() ```cpp -Object Napi::Object::New(napi_env env); +Napi::Object Napi::Object::New(napi_env env); ``` -- `[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. -Creates a new Object value. +Creates a new `Napi::Object` value. ### Set() @@ -88,14 +88,14 @@ Add a property with the specified key with the specified value to the object. The key can be any of the following types: - `napi_value` -- [Value](value.md) +- [`Napi::Value`](value.md) - `const char*` - `const std::string&` - `uint32_t` While the value must be any of the following types: - `napi_value` -- [Value](value.md) +- [`Napi::Value`](value.md) - `const char*` - `std::string&` - `bool` @@ -104,15 +104,15 @@ While the value must be any of the following types: ### Get() ```cpp -Value Napi::Object::Get(____ key); +Napi::Value Napi::Object::Get(____ key); ``` - `[in] key`: The name of the property to return the value for. -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. The `key` can be any of the following types: - `napi_value` -- [Value](value.md) +- [`Napi::Value`](value.md) - `const char *` - `const std::string &` - `uint32_t` @@ -131,18 +131,18 @@ Returns a `bool` that is *true* if the object has a property named `key` and *fa ```cpp bool Napi::Object::InstanceOf (const Function& constructor) const ``` -- `[in] constructor`: The constructor [Function](function.md) of the value that is being compared with the object. +- `[in] constructor`: The constructor [`Napi::Function`](function.md) of the value that is being compared with the object. -Returns a `bool` that is true if the Object is an instance created by the `constructor` and false otherwise. +Returns a `bool` that is true if the `Napi::Object` is an instance created by the `constructor` and false otherwise. Note: This is equivalent to the JavaScript instanceof operator. ### DefineProperty() ```cpp -void Napi::Object::DefineProperty (const PropertyDescriptor& property); +void Napi::Object::DefineProperty (const Napi::PropertyDescriptor& property); ``` -- `[in] property`: A [PropertyDescriptor](propertydescriptor.md). +- `[in] property`: A [`Napi::PropertyDescriptor`](propertydescriptor.md). Define a property on the object. @@ -151,52 +151,52 @@ Define a property on the object. ```cpp void Napi::Object::DefineProperties (____ properties) ``` -- `[in] properties`: A list of [PropertyDescriptor](propertydescriptor.md). Can be one of the following types: - - const std::initializer_list& - - const std::vector& +- `[in] properties`: A list of [`Napi::PropertyDescriptor`](propertydescriptor.md). Can be one of the following types: + - const std::initializer_list& + - const std::vector& Defines properties on the object. ### Operator[]() ```cpp -PropertyLValue Napi::Object::operator[] (const char* utf8name); +Napi::PropertyLValue Napi::Object::operator[] (const char* utf8name); ``` - `[in] utf8name`: UTF-8 encoded null-terminated property name. -Returns a [PropertyLValue](propertylvalue.md) as the named property or sets the named property. +Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property. ```cpp -PropertyLValue Napi::Object::operator[] (const std::string& utf8name); +Napi::PropertyLValue Napi::Object::operator[] (const std::string& utf8name); ``` - `[in] utf8name`: UTF-8 encoded property name. -Returns a [PropertyLValue](propertylvalue.md) as the named property or sets the named property. +Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property. ```cpp -PropertyLValue Napi::Object::operator[] (uint32_t index); +Napi::PropertyLValue Napi::Object::operator[] (uint32_t index); ``` - `[in] index`: Element index. -Returns a [PropertyLValue](propertylvalue.md) or sets an indexed property or array element. +Returns a [`Napi::PropertyLValue`](propertylvalue.md) or sets an indexed property or array element. ```cpp -Value Napi::Object::operator[] (const char* utf8name) const; +Napi::Value Napi::Object::operator[] (const char* utf8name) const; ``` - `[in] utf8name`: UTF-8 encoded null-terminated property name. -Returns the named property as a [Value](value.md). +Returns the named property as a [`Napi::Value`](value.md). ```cpp -Value Napi::Object::operator[] (const std::string& utf8name) const; +Napi::Value Napi::Object::operator[] (const std::string& utf8name) const; ``` - `[in] utf8name`: UTF-8 encoded property name. -Returns the named property as a [Value](value.md). +Returns the named property as a [`Napi::Value`](value.md). ```cpp -Value Napi::Object::operator[] (uint32_t index) const; +Napi::Value Napi::Object::operator[] (uint32_t index) const; ``` - `[in] index`: Element index. -Returns an indexed property or array element as a [Value](value.md). +Returns an indexed property or array element as a [`Napi::Value`](value.md). diff --git a/doc/object_lifetime_management.md b/doc/object_lifetime_management.md index 5c7a66c28..4ab19ecd1 100644 --- a/doc/object_lifetime_management.md +++ b/doc/object_lifetime_management.md @@ -34,7 +34,7 @@ with each of the values, one at a time: ```C++ for (int i = 0; i < LOOP_MAX; i++) { 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 }; ``` @@ -47,8 +47,8 @@ values would also be kept alive since they all share the same scope. To handle this case, node-addon-api provides the ability to establish a new 'scope' to which newly created handles will be associated. Once those 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. node-addon-api only supports a single nested hierarchy of scopes. There is @@ -56,28 +56,28 @@ only one active scope at any time, and all new handles will be associated with that scope while it is active. Scopes must be deleted in the reverse order from which they are opened. In addition, all scopes created within 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 execution of the loop: ```C 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 }; ``` When nesting scopes, there are cases where a handle from an 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`. diff --git a/doc/object_reference.md b/doc/object_reference.md index da826f109..4c20f16f8 100644 --- a/doc/object_reference.md +++ b/doc/object_reference.md @@ -1,8 +1,8 @@ # Object Reference -ObjectReference is a subclass of [Reference](reference.md), and is equivalent to an instance of `Reference`. 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`. 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). ## Example ```cpp @@ -30,17 +30,17 @@ void Init(Env env) { ### Initialization ```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. * `[in] initialRefcount`: The initial reference count. Returns the newly created reference. ```cpp -static ObjectReference Weak(const Object& value); +static Napi::ObjectReference Napi::ObjectReference::Weak(const Napi::Object& value); ``` Creates a "weak" reference to the value, in that the initial count of number of references is set to 0. @@ -50,7 +50,7 @@ Creates a "weak" reference to the value, in that the initial count of number of Returns the newly created reference. ```cpp -static ObjectReference Persistent(const Object& value); +static Napi::ObjectReference Napi::ObjectReference::Persistent(const Napi::Object& value); ``` Creates a "persistent" reference to the value, in that the initial count of number of references is set to 1. @@ -62,26 +62,26 @@ Returns the newly created reference. ### Empty Constructor ```cpp -ObjectReference(); +Napi::ObjectReference::ObjectReference(); ``` -Returns a new _empty_ ObjectReference instance. +Returns a new _empty_ `Napi::ObjectReference` instance. ### 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`. Returns the newly created reference. ### Set ```cpp -void Set(___ key, ___ value); +void Napi::ObjectReference::Set(___ key, ___ value); ``` * `[in] key`: The name for the property being assigned. @@ -103,12 +103,12 @@ The `value` can be any of the following types: ### Get ```cpp -Value Get(___ key); +Napi::Value Napi::ObjectReference::Get(___ key); ``` * `[in] key`: The name of the property to return the value for. -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. The `key` can be any of the following types: - `const char*` diff --git a/doc/promises.md b/doc/promises.md index e67483bbb..62529006b 100644 --- a/doc/promises.md +++ b/doc/promises.md @@ -1,23 +1,19 @@ -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/) - # Promise -The Promise class, along with its Promise::Deferred class, implement the ability to create, resolve, and reject Promise objects. +The `Napi::Promise` class, along with its `Napi::Promise::Deferred` class, implement the ability to create, resolve, and reject Promise objects. -The basic approach is to create a Promise::Deferred object and return to your caller the value returned by the Promise::Deferred::Promise method. For example: +The basic approach is to create a `Napi::Promise::Deferred` object and return to your caller the value returned by the `Napi::Promise::Deferred::Promise` method. For example: ```cpp -Value YourFunction(const CallbackInfo& info) { +Napi::Value YourFunction(const Napi::CallbackInfo& info) { // your code goes here... - Promise::Deferred deferred = Promise::Deferred::New(info.Env()); + Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(info.Env()); // deferred needs to survive this call... return deferred.Promise(); } ``` -Later, when the asynchronous process completes, call either the `Resolve` or `Reject` method on the Promise::Deferred object created earlier: +Later, when the asynchronous process completes, call either the `Resolve` or `Reject` method on the `Napi::Promise::Deferred` object created earlier: ```cpp deferred.Resolve(String::New(info.Env(), "OK")); @@ -28,51 +24,51 @@ Later, when the asynchronous process completes, call either the `Resolve` or `Re ### Factory Method ```cpp -static Promise::Deferred Promise::Deferred::New(napi_env env); +static Napi::Promise::Deferred Napi::Promise::Deferred::New(napi_env env); ``` -* `[in] env`: The `napi_env` environment in which to create the Deferred object. +* `[in] env`: The `napi_env` environment in which to create the `Napi::Promise::Deferred` object. ### Constructor ```cpp -Promise::Deferred(napi_env env); +Napi::Promise::Deferred(napi_env env); ``` -* `[in] env`: The `napi_env` environment in which to construct the Deferred object. +* `[in] env`: The `napi_env` environment in which to construct the `Napi::Promise::Deferred` object. ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::Promise::Deferred::Env() const; ``` -Returns the Env environment this Promise::Deferred object is associated with. +Returns the Env environment this `Napi::Promise::Deferred` object is associated with. ### Promise ```cpp -Promise Promise::Deferred::Promise() const; +Napi::Promise Napi::Promise::Deferred::Promise() const; ``` -Returns the Promise object held by the Promise::Deferred object. +Returns the `Napi::Promise` object held by the `Napi::Promise::Deferred` object. ### Resolve ```cpp -void Promise::Deferred::Resolve(napi_value value) const; +void Napi::Promise::Deferred::Resolve(napi_value value) const; ``` -Resolves the Promise object held by the Promise::Deferred object. +Resolves the `Napi::Promise` object held by the `Napi::Promise::Deferred` object. -* `[in] value`: The N-API primitive value with which to resolve the Promise. +* `[in] value`: The N-API primitive value with which to resolve the `Napi::Promise`. ### Reject ```cpp -void Promise::Deferred::Reject(napi_value value) const; +void Napi::Promise::Deferred::Reject(napi_value value) const; ``` -Rejects the Promise object held by the Promise::Deferred object. +Rejects the Promise object held by the `Napi::Promise::Deferred` object. -* `[in] value`: The N-API primitive value with which to reject the Promise. +* `[in] value`: The N-API primitive value with which to reject the `Napi::Promise`. diff --git a/doc/property_descriptor.md b/doc/property_descriptor.md index 02c022fcb..2c0fa6fac 100644 --- a/doc/property_descriptor.md +++ b/doc/property_descriptor.md @@ -1,6 +1,6 @@ # Property Descriptor -An [Object](object.md) can be assigned properites via its [DefineProperty](object.md#defineproperty) and [DefineProperties](object.md#defineproperties) function, which take PropertyDescrptor(s) as their parameters. The PropertyDescriptor can contain either values or functions, which are then assigned to the Object. Note that a single instance of a PropertyDescriptor class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [Accessor](#accessor), [Function](#function), or [Value](#value), each of which return a new static instance of a PropertyDescriptor. +A [`Napi::Object`](object.md) can be assigned properites via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) functions, which take PropertyDescrptor(s) as their parameters. The `Napi::PropertyDescriptor` can contain either values or functions, which are then assigned to the `Napi::Object`. Note that a single instance of a `Napi::PropertyDescriptor` class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [`Accessor`](#accessor), [`Function`](#function), or [`Value`](#value), each of which return a new static instance of a `Napi::PropertyDescriptor`. ## Example @@ -52,7 +52,7 @@ Napi::PropertyDescriptor::PropertyDescriptor (napi_property_descriptor desc); ### Accessor ```cpp -static PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, +static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, Getter getter, napi_property_attributes attributes = napi_default, void *data = nullptr); @@ -69,10 +69,10 @@ The name of the property can be any of the following types: - `const char*` - `const std::string &` - `napi_value value` -- `Name` +- `Napi::Name` ```cpp -static PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, +static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, Getter getter, Setter setter, napi_property_attributes attributes = napi_default, @@ -85,18 +85,18 @@ static PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, * `[in] attributes`: Potential attributes for the getter function. * `[in] data`: A pointer to data of any type, default is a null pointer. -Returns a PropertyDescriptor that contains a Getter and Setter function. +Returns a `Napi::PropertyDescriptor` that contains a `Getter` and `Setter` function. The name of the property can be any of the following types: - `const char*` - `const std::string &` - `napi_value value` -- `Name` +- `Napi::Name` ### Function ```cpp -static PropertyDescriptor Napi::PropertyDescriptor::Function (___ name, +static Napi::PropertyDescriptor Napi::PropertyDescriptor::Function (___ name, Callable cb, napi_property_attributes attributes = napi_default, void *data = nullptr); @@ -107,18 +107,18 @@ static PropertyDescriptor Napi::PropertyDescriptor::Function (___ name, * `[in] attributes`: Potential attributes for the getter function. * `[in] data`: A pointer to data of any type, default is a null pointer. -Returns a PropertyDescriptor that contains a callable Function. +Returns a `Napi::PropertyDescriptor` that contains a callable `Napi::Function`. The name of the property can be any of the following types: - `const char*` - `const std::string &` - `napi_value value` -- `Name` +- `Napi::Name` ### Value ```cpp -static PropertyDescriptor Napi::PropertyDescriptor::Value (___ name, +static Napi::PropertyDescriptor Napi::PropertyDescriptor::Value (___ name, napi_value value, napi_property_attributes attributes = napi_default); ``` @@ -127,7 +127,7 @@ The name of the property can be any of the following types: - `const char*` - `const std::string &` - `napi_value value` -- `Name` +- `Napi::Name` ## Related Information diff --git a/doc/range_error.md b/doc/range_error.md index e0bd14d30..e134a4098 100644 --- a/doc/range_error.md +++ b/doc/range_error.md @@ -1,11 +1,11 @@ # RangeError -The **RangeError** class is a representation of the JavaScript RangeError that is +The `Napi::RangeError` class is a representation of the JavaScript `RangeError` that is thrown when trying to pass a value as an argument to a function that does not allow a range that includes the value. -The **RangeError** class inherits its behaviors from the **Error** class (for -more info see: [Error](error.md)). +The `Napi::RangeError` class inherits its behaviors from the `Napi::Error` class (for +more info see: [`Napi::Error`](error.md)). For more details about error handling refer to the section titled [Error handling](error_handling.md). @@ -13,47 +13,47 @@ For more details about error handling refer to the section titled [Error handlin ### New -Creates a new instance of a `RangeError` object. +Creates a new instance of a `Napi::RangeError` object. ```cpp -RangeError::New(Napi:Env env, const char* message); +Napi::RangeError::New(Napi::Env env, const char* message); ``` -- `[in] Env`: The environment in which to construct the `RangeError` object. -- `[in] message`: Null-terminated string to be used as the message for the `RangeError`. +- `[in] Env`: The environment in which to construct the `Napi::RangeError` object. +- `[in] message`: Null-terminated string to be used as the message for the `Napi::RangeError`. -Returns an instance of a `RangeError` object. +Returns an instance of a `Napi::RangeError` object. ### New -Creates a new instance of a `RangeError` object. +Creates a new instance of a `Napi::RangeError` object. ```cpp -RangeError::New(Napi:Env env, const std::string& message); +Napi::RangeError::New(Napi::Env env, const std::string& message); ``` -- `[in] Env`: The environment in which to construct the `RangeError` object. -- `[in] message`: Reference string to be used as the message for the `RangeError`. +- `[in] Env`: The environment in which to construct the `Napi::RangeError` object. +- `[in] message`: Reference string to be used as the message for the `Napi::RangeError`. -Returns an instance of a `RangeError` object. +Returns an instance of a `Napi::RangeError` object. ### Constructor -Creates a new empty instance of a `RangeError`. +Creates a new empty instance of a `Napi::RangeError`. ```cpp -RangeError(); +Napi::RangeError::RangeError(); ``` ### Constructor -Initializes a `RangeError` instance from an existing Javascript error object. +Initializes a `Napi::RangeError` instance from an existing Javascript error object. ```cpp -RangeError(napi_env env, napi_value value); +Napi::RangeError::RangeError(napi_env env, napi_value value); ``` -- `[in] Env`: The environment in which to construct the `RangeError` object. -- `[in] value`: The `Error` reference to wrap. +- `[in] Env`: The environment in which to construct the `Napi::RangeError` object. +- `[in] value`: The `Napi::Error` reference to wrap. -Returns an instance of a `RangeError` object. \ No newline at end of file +Returns an instance of a `Napi::RangeError` object. diff --git a/doc/reference.md b/doc/reference.md index c25f98d8e..108c009bb 100644 --- a/doc/reference.md +++ b/doc/reference.md @@ -1,27 +1,23 @@ -You are reading a draft of the next documentation and it's in continuos update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) - # Reference (template) -Holds a counted reference to a [Value](value.md) object; initially a weak reference unless otherwise specified, may be changed to/from a strong reference by adjusting the refcount. +Holds a counted reference to a [`Napi::Value`](value.md) object; initially a weak reference unless otherwise specified, may be changed to/from a strong reference by adjusting the refcount. -The referenced Value is not immediately destroyed when the reference count is zero; it is merely then eligible for garbage-collection if there are no other references to the Value. +The referenced `Napi::Value` is not immediately destroyed when the reference count is zero; it is merely then eligible for garbage-collection if there are no other references to the `Napi::Value`. -Reference objects allocated in static space, such as a global static instance, must call the `SuppressDestruct` method to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. +`Napi::Reference` objects allocated in static space, such as a global static instance, must call the `SuppressDestruct` method to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. -The following classes inherit, either directly or indirectly, from Reference: +The following classes inherit, either directly or indirectly, from `Napi::Reference`: -* [ObjectWrap](object_wrap.md) -* [ObjectReference](object_reference.md) -* [FunctionReference](function_reference.md) +* [`Napi::ObjectWrap`](object_wrap.md) +* [`Napi::ObjectReference`](object_reference.md) +* [`Napi::FunctionReference`](function_reference.md) ## Methods ### Factory Method ```cpp -static Reference New(const T& value, uint32_t initialRefcount = 0); +static Napi::Reference Napi::Reference::New(const T& value, uint32_t initialRefcount = 0); ``` * `[in] value`: The value which is to be referenced. @@ -31,85 +27,85 @@ static Reference New(const T& value, uint32_t initialRefcount = 0); ### Empty Constructor ```cpp -Reference(); +Napi::Reference::Reference(); ``` -Creates a new _empty_ Reference instance. +Creates a new _empty_ `Napi::Reference` instance. ### Constructor ```cpp -Reference(napi_env env, napi_value value); +Napi::Reference::Reference(napi_env env, napi_value value); ``` -* `[in] env`: The `napi_env` environment in which to construct the Reference object. +* `[in] env`: The `napi_env` environment in which to construct the `Napi::Reference` object. -* `[in] value`: The N-API primitive value to be held by the Reference. +* `[in] value`: The N-API primitive value to be held by the `Napi::Reference`. ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::Reference::Env() const; ``` -Returns the `Env` value in which the Reference was instantiated. +Returns the `Napi::Env` value in which the `Napi::Reference` was instantiated. ### IsEmpty ```cpp -bool IsEmpty() const; +bool Napi::Reference::IsEmpty() const; ``` -Determines whether the value held by the Reference is empty. +Determines whether the value held by the `Napi::Reference` is empty. ### Value ```cpp -T Value() const; +T Napi::Reference::Value() const; ``` -Returns the value held by the Reference. +Returns the value held by the `Napi::Reference`. ### Ref ```cpp -uint32_t Ref(); +uint32_t Napi::Reference::Ref(); ``` -Increments the reference count for the Reference and returns the resulting reference count. Throws an error if the increment fails. +Increments the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the increment fails. ### Unref ```cpp -uint32_t Unref(); +uint32_t Napi::Reference::Unref(); ``` -Decrements the reference count for the Reference and returns the resulting reference count. Throws an error if the decrement fails. +Decrements the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the decrement fails. ### Reset (Empty) ```cpp -void Reset(); +void Napi::Reference::Reset(); ``` -Sets the value held by the Reference to be empty. +Sets the value held by the `Napi::Reference` to be empty. ### Reset ```cpp -void Reset(const T& value, uint32_t refcount = 0); +void Napi::Reference::Reset(const T& value, uint32_t refcount = 0); ``` * `[in] value`: The value which is to be referenced. * `[in] initialRefcount`: The initial reference count. -Sets the value held by the Reference. +Sets the value held by the `Napi::Reference`. ### SuppressDestruct ```cpp -void SuppressDestruct(); +void Napi::Reference::SuppressDestruct(); ``` -Call this method on a Reference that is declared as static data to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. +Call this method on a `Napi::Reference` that is declared as static data to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. diff --git a/doc/setup.md b/doc/setup.md index 176815a96..542729a69 100644 --- a/doc/setup.md +++ b/doc/setup.md @@ -19,7 +19,7 @@ To use **N-API** in a native module: ```json "dependencies": { - "node-addon-api": "1.2.0", + "node-addon-api": "*", } ``` diff --git a/doc/string.md b/doc/string.md index faa308a2d..21ce8f8cb 100644 --- a/doc/string.md +++ b/doc/string.md @@ -3,17 +3,17 @@ ## Constructor ```cpp -String(); +Napi::String::String(); ``` -Returns a new **empty** String instance. +Returns a new **empty** `Napi::String` instance. If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. ```cpp -String(napi_env env, napi_value value); ///< Wraps a N-API value primitive. +Napi::String::String(napi_env env, napi_value value); ///< Wraps a N-API value primitive. ``` - `[in] env` - The environment in which to create the string. - `[in] value` - The primitive to wrap. @@ -29,14 +29,14 @@ attempting to use the returned value. ### operator std::string ```cpp -operator std::string() const; +Napi::String::operator std::string() const; ``` Returns a UTF-8 encoded C++ string. ### operator std::u16string ```cpp -operator std::u16string() const; +Napi::String::operator std::u16string() const; ``` Returns a UTF-16 encoded C++ string. @@ -45,21 +45,21 @@ Returns a UTF-16 encoded C++ string. ### New ```cpp -String::New(); +Napi::String::New(); ``` -Returns a new empty String +Returns a new empty `Napi::String`. ### New ```cpp -String::New(napi_env env, const std::string& value); -String::New(napi_env env, const std::u16string& value); -String::New(napi_env env, const char* value); -String::New(napi_env env, const char16_t* value); +Napi::String::New(napi_env env, const std::string& value); +Napi::String::New(napi_env env, const std::u16::string& value); +Napi::String::New(napi_env env, const char* value); +Napi::String::New(napi_env env, const char16_t* value); ``` -- `[in] env`: The `napi_env` environment in which to construct the Value object. -- `[in] value`: The C++ primitive from which to instantiate the Value. `value` may be any of: +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object. +- `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of: - `std::string&` - represents an ANSI string. - `std::u16string&` - represents a UTF16-LE string. - `const char*` - represents a UTF8 string. @@ -73,14 +73,14 @@ attempting to use the returned value. ### Utf8Value ```cpp -std::string Utf8Value() const; +std::string Napi::String::Utf8Value() const; ``` Returns a UTF-8 encoded C++ string. ### Utf16Value ```cpp -std::u16string Utf16Value() const; +std::u16string Napi::String::Utf16Value() const; ``` Returns a UTF-16 encoded C++ string. diff --git a/doc/symbol.md b/doc/symbol.md index fe7ee9c03..13abe3e20 100644 --- a/doc/symbol.md +++ b/doc/symbol.md @@ -4,24 +4,24 @@ ### Constructor -Instantiates a new `Symbol` value +Instantiates a new `Napi::Symbol` value. ```cpp -Symbol(); +Napi::Symbol::Symbol(); ``` -Returns a new empty Symbol. +Returns a new empty `Napi::Symbol`. ### New ```cpp -Symbol::New(napi_env env, const std::string& description); -Symbol::New(napi_env env, const char* description); -Symbol::New(napi_env env, String description); -Symbol::New(napi_env env, napi_value description); +Napi::Symbol::New(napi_env env, const std::string& description); +Napi::Symbol::New(napi_env env, const char* description); +Napi::Symbol::New(napi_env env, Napi::String description); +Napi::Symbol::New(napi_env env, napi_value description); ``` -- `[in] env`: The `napi_env` environment in which to construct the Symbol object. -- `[in] value`: The C++ primitive which represents the description hint for the Symbol. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object. +- `[in] value`: The C++ primitive which represents the description hint for the `Napi::Symbol`. `description` may be any of: - `std::string&` - ANSI string description. - `const char*` - represents a UTF8 string description. @@ -29,16 +29,16 @@ Symbol::New(napi_env env, napi_value description); - `napi_value` - N-API `napi_value` description. If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before +being used, callers should check the result of `Napi::Env::IsExceptionPending` before attempting to use the returned value. ### Utf8Value ```cpp -static Symbol WellKnown(napi_env env, const std::string& name); +static Napi::Symbol Napi::Symbol::WellKnown(napi_env env, const std::string& name); ``` -- `[in] env`: The `napi_env` environment in which to construct the Symbol object. -- `[in] name`: The C++ string representing the `Symbol` to retrieve. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object. +- `[in] name`: The C++ string representing the `Napi::Symbol` to retrieve. -Returns a `Napi::Symbol` representing a well-known Symbol from the -Symbol registry. +Returns a `Napi::Symbol` representing a well-known `Symbol` from the +`Symbol` registry. diff --git a/doc/type_error.md b/doc/type_error.md index 7cfb9d1bf..24bbf8eda 100644 --- a/doc/type_error.md +++ b/doc/type_error.md @@ -1,11 +1,11 @@ # TypeError -The **TypeError** class is a representation of the JavaScript `TypeError` that is +The `Napi::TypeError` class is a representation of the JavaScript `TypeError` that is thrown when an operand or argument passed to a function is incompatible with the type expected by the operator or function. -The **TypeError** class inherits its behaviors from the **Error** class (for more info -see: [Error](error.md)). +The `Napi::TypeError` class inherits its behaviors from the `Napi::Error` class (for more info +see: [`Napi::Error`](error.md)). For more details about error handling refer to the section titled [Error handling](error_handling.md). @@ -13,47 +13,47 @@ For more details about error handling refer to the section titled [Error handlin ### New -Creates a new instance of the `TypeError` object. +Creates a new instance of the `Napi::TypeError` object. ```cpp -TypeError::New(Napi:Env env, const char* message); +Napi::TypeError::New(Napi:Env env, const char* message); ``` -- `[in] Env`: The environment in which to construct the `TypeError` object. -- `[in] message`: Null-terminated string to be used as the message for the `TypeError`. +- `[in] Env`: The environment in which to construct the `Napi::TypeError` object. +- `[in] message`: Null-terminated string to be used as the message for the `Napi::TypeError`. -Returns an instance of a `TypeError` object. +Returns an instance of a `Napi::TypeError` object. ### New -Creates a new instance of a `TypeError` object. +Creates a new instance of a `Napi::TypeError` object. ```cpp -TypeError::New(Napi:Env env, const std::string& message); +Napi::TypeError::New(Napi:Env env, const std::string& message); ``` -- `[in] Env`: The environment in which to construct the `TypeError` object. -- `[in] message`: Reference string to be used as the message for the `TypeError`. +- `[in] Env`: The environment in which to construct the `Napi::TypeError` object. +- `[in] message`: Reference string to be used as the message for the `Napi::TypeError`. -Returns an instance of a `TypeError` object. +Returns an instance of a `Napi::TypeError` object. ### Constructor -Creates a new empty instance of a `TypeError`. +Creates a new empty instance of a `Napi::TypeError`. ```cpp -TypeError(); +Napi::TypeError::TypeError(); ``` ### Constructor -Initializes a ```TypeError``` instance from an existing JavaScript error object. +Initializes a `Napi::TypeError` instance from an existing JavaScript error object. ```cpp -TypeError(napi_env env, napi_value value); +Napi::TypeError::TypeError(napi_env env, napi_value value); ``` -- `[in] Env`: The environment in which to construct the `TypeError` object. -- `[in] value`: The `Error` reference to wrap. +- `[in] Env`: The environment in which to construct the `Napi::TypeError` object. +- `[in] value`: The `Napi::Error` reference to wrap. -Returns an instance of a `TypeError` object. \ No newline at end of file +Returns an instance of a `Napi::TypeError` object. diff --git a/doc/typed_array.md b/doc/typed_array.md index f96d36499..ced67d8e4 100644 --- a/doc/typed_array.md +++ b/doc/typed_array.md @@ -1,6 +1,6 @@ # TypedArray -The `TypedArray` class corresponds to the +The `Napi::TypedArray` class corresponds to the [JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) class. @@ -8,27 +8,27 @@ class. ### Constructor -Initializes an empty instance of the `TypedArray` class. +Initializes an empty instance of the `Napi::TypedArray` class. ```cpp -TypedArray(); +Napi::TypedArray::TypedArray(); ``` ### Constructor -Initializes a wrapper instance of an existing `TypedArray` instance. +Initializes a wrapper instance of an existing `Napi::TypedArray` instance. ```cpp -TypedArray(napi_env env, napi_value value); +Napi::TypedArray::TypedArray(napi_env env, napi_value value); ``` -- `[in] env`: The environment in which to create the `TypedArray` instance. -- `[in] value`: The `TypedArray` reference to wrap. +- `[in] env`: The environment in which to create the `Napi::TypedArray` instance. +- `[in] value`: The `Napi::TypedArray` reference to wrap. ### TypedArrayType ```cpp -napi_typedarray_type TypedArrayType() const; +napi_typedarray_type Napi::TypedArray::TypedArrayType() const; ``` Returns the type of this instance. @@ -36,7 +36,7 @@ Returns the type of this instance. ### ArrayBuffer ```cpp -Napi::ArrayBuffer ArrayBuffer() const; +Napi::ArrayBuffer Napi::TypedArray::ArrayBuffer() const; ``` Returns the backing array buffer. @@ -44,7 +44,7 @@ Returns the backing array buffer. ### ElementSize ```cpp -uint8_t ElementSize() const; +uint8_t Napi::TypedArray::ElementSize() const; ``` Returns the size of one element, in bytes. @@ -52,7 +52,7 @@ Returns the size of one element, in bytes. ### ElementLength ```cpp -size_t ElementLength() const; +size_t Napi::TypedArray::ElementLength() const; ``` Returns the number of elements. @@ -60,15 +60,15 @@ Returns the number of elements. ### ByteOffset ```cpp -size_t ByteOffset() const; +size_t Napi::TypedArray::ByteOffset() const; ``` -Returns the offset into the `ArrayBuffer` where the array starts, in bytes. +Returns the offset into the `Napi::ArrayBuffer` where the array starts, in bytes. ### ByteLength ```cpp -size_t ByteLength() const; +size_t Napi::TypedArray::ByteLength() const; ``` Returns the length of the array, in bytes. diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md index 868e5ec44..fc30218c1 100644 --- a/doc/typed_array_of.md +++ b/doc/typed_array_of.md @@ -1,6 +1,6 @@ # TypedArrayOf -The `TypedArrayOf` class corresponds to the various +The `Napi::TypedArrayOf` class corresponds to the various [JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) classes. @@ -9,14 +9,14 @@ classes. The common JavaScript `TypedArray` types are pre-defined for each of use: ```cpp -typedef TypedArrayOf Int8Array; -typedef TypedArrayOf Uint8Array; -typedef TypedArrayOf Int16Array; -typedef TypedArrayOf Uint16Array; -typedef TypedArrayOf Int32Array; -typedef TypedArrayOf Uint32Array; -typedef TypedArrayOf Float32Array; -typedef TypedArrayOf Float64Array; +typedef Napi::TypedArrayOf Int8Array; +typedef Napi::TypedArrayOf Uint8Array; +typedef Napi::TypedArrayOf Int16Array; +typedef Napi::TypedArrayOf Uint16Array; +typedef Napi::TypedArrayOf Int32Array; +typedef Napi::TypedArrayOf Uint32Array; +typedef Napi::TypedArrayOf Float32Array; +typedef Napi::TypedArrayOf Float64Array; ``` The one exception is the `Uint8ClampedArray` which requires explicit @@ -33,71 +33,71 @@ behavior is only applied in JavaScript. ### New -Allocates a new `TypedArray` instance with a given length. The underlying -`ArrayBuffer` is allocated automatically to the desired number of elements. +Allocates a new `Napi::TypedArray` instance with a given length. The underlying +`Napi::ArrayBuffer` is allocated automatically to the desired number of elements. The array type parameter can normally be omitted (because it is inferred from the template parameter T), except when creating a "clamped" array. ```cpp -static TypedArrayOf New(napi_env env, +static Napi::TypedArrayOf Napi::TypedArrayOf::New(napi_env env, size_t elementLength, napi_typedarray_type type); ``` -- `[in] env`: The environment in which to create the `TypedArrayOf` instance. +- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` instance. - `[in] elementLength`: The length to be allocated, in elements. - `[in] type`: The type of array to allocate (optional). -Returns a new `TypedArrayOf` instance. +Returns a new `Napi::TypedArrayOf` instance. ### New -Wraps the provided `ArrayBuffer` into a new `TypedArray` instance. +Wraps the provided `Napi::ArrayBuffer` into a new `Napi::TypedArray` instance. The array `type` parameter can normally be omitted (because it is inferred from the template parameter `T`), except when creating a "clamped" array. ```cpp -static TypedArrayOf New(napi_env env, +static Napi::TypedArrayOf Napi::TypedArrayOf::New(napi_env env, size_t elementLength, Napi::ArrayBuffer arrayBuffer, size_t bufferOffset, napi_typedarray_type type); ``` -- `[in] env`: The environment in which to create the `TypedArrayOf` instance. +- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` instance. - `[in] elementLength`: The length to array, in elements. -- `[in] arrayBuffer`: The backing `ArrayBuffer` instance. -- `[in] bufferOffset`: The offset into the `ArrayBuffer` where the array starts, +- `[in] arrayBuffer`: The backing `Napi::ArrayBuffer` instance. +- `[in] bufferOffset`: The offset into the `Napi::ArrayBuffer` where the array starts, in bytes. - `[in] type`: The type of array to allocate (optional). -Returns a new `TypedArrayOf` instance. +Returns a new `Napi::TypedArrayOf` instance. ### Constructor -Initializes an empty instance of the `TypedArrayOf` class. +Initializes an empty instance of the `Napi::TypedArrayOf` class. ```cpp -TypedArrayOf(); +Napi::TypedArrayOf::TypedArrayOf(); ``` ### Constructor -Initializes a wrapper instance of an existing `TypedArrayOf` object. +Initializes a wrapper instance of an existing `Napi::TypedArrayOf` object. ```cpp -TypedArrayOf(napi_env env, napi_value value); +Napi::TypedArrayOf::TypedArrayOf(napi_env env, napi_value value); ``` -- `[in] env`: The environment in which to create the `TypedArrayOf` object. -- `[in] value`: The `TypedArrayOf` reference to wrap. +- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` object. +- `[in] value`: The `Napi::TypedArrayOf` reference to wrap. ### operator [] ```cpp -T& operator [](size_t index); +T& Napi::TypedArrayOf::operator [](size_t index); ``` - `[in] index: The element index into the array. @@ -107,7 +107,7 @@ Returns the element found at the given index. ### operator [] ```cpp -const T& operator [](size_t index) const; +const T& Napi::TypedArrayOf::operator [](size_t index) const; ``` - `[in] index: The element index into the array. @@ -117,17 +117,17 @@ Returns the element found at the given index. ### Data ```cpp -T* Data() const; +T* Napi::TypedArrayOf::Data() const; ``` -Returns a pointer into the backing `ArrayBuffer` which is offset to point to the +Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the start of the array. ### Data ```cpp -const T* Data() const +const T* Napi::TypedArrayOf::Data() const ``` -Returns a pointer into the backing `ArrayBuffer` which is offset to point to the +Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the start of the array. diff --git a/doc/value.md b/doc/value.md index 5e79d352e..e9f9f8a7f 100644 --- a/doc/value.md +++ b/doc/value.md @@ -1,67 +1,65 @@ -**WORK IN PROGRESS, NOT YET COMPLETE** - # Value -Value is the C++ manifestation of a JavaScript value. +`Napi::Value` is the C++ manifestation of a JavaScript value. Value is a the base class upon which other JavaScript values such as Number, Boolean, String, and Object are based. -The following classes inherit, either directly or indirectly, from Value: - -- [Array](array.md) -- [ArrayBuffer](array_buffer.md) -- [Boolean](boolean.md) -- [Buffer](buffer.md) -- [External](external.md) -- [Function](function.md) -- [Name](name.md) -- [Number](number.md) -- [Object](object.md) -- [String](string.md) -- [Symbol](symbol.md) -- [TypedArray](typed_array.md) -- [TypedArrayOf](typed_array_of.md) +The following classes inherit, either directly or indirectly, from `Napi::Value`: + +- [`Napi::Array`](array.md) +- [`Napi::ArrayBuffer`](array_buffer.md) +- [`Napi::Boolean`](boolean.md) +- [`Napi::Buffer`](buffer.md) +- [`Napi::External`](external.md) +- [`Napi::Function`](function.md) +- [`Napi::Name`](name.md) +- [`Napi::Number`](number.md) +- [`Napi::Object`](object.md) +- [`Napi::String`](string.md) +- [`Napi::Symbol`](symbol.md) +- [`Napi::TypedArray`](typed_array.md) +- [`Napi::TypedArrayOf`](typed_array_of.md) ## Methods ### Empty Constructor ```cpp -Value(); +Napi::Value::Value(); ``` -Creates a new *empty* Value instance. +Creates a new *empty* `Napi::Value` instance. ### Constructor ```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 object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object. -- `[in] value`: The C++ primitive from which to instantiate the Value. `value` may be any of: - - bool +- `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of: + - `bool` - Any integer type - Any floating point type - - const char* (encoded using UTF-8, null-terminated) - - const char16_t* (encoded using UTF-16-LE, null-terminated) - - std::string (encoded using UTF-8) - - std::u16string - - napi::Value - - napi_value + - `const char*` (encoded using UTF-8, null-terminated) + - `const char16_t*` (encoded using UTF-16-LE, null-terminated) + - `std::string` (encoded using UTF-8) + - `std::u16string` + - `Napi::Value` + - `napi_value` ### From ```cpp -template static Value From(napi_env env, const T& value); +template static Napi::Value Napi::Value::From(napi_env env, const T& value); ``` -- `[in] env`: The `napi_env` environment in which to create the Value object. +- `[in] env`: The `napi_env` environment in which to create the `Napi::Value` object. -- `[in] value`: The N-API primitive value from which to create the Value object. +- `[in] value`: The N-API primitive value from which to create the `Napi::Value` object. -Returns a Value object from an N-API primitive value. +Returns a `Napi::Value` object from an N-API primitive value. ### operator napi_value @@ -71,165 +69,167 @@ operator napi_value() const; Returns this Value's N-API value primitive. -Returns `nullptr` if this Value is *empty*. +Returns `nullptr` if this `Napi::Value` is *empty*. ### operator == ```cpp -bool operator ==(const Value& other) const; + +bool Napi::Value::operator ==(const Napi::Value& other) const; ``` -- `[in] other`: The Value object to be compared. +- `[in] other`: The `Napi::Value` object to be compared. -Returns a `bool` indicating if this Value strictly equals another Value. +Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi::Value`. ### operator != ```cpp -bool operator !=(const Value& other) const; +bool Napi::Value::operator !=(const Napi::Value& other) const; ``` -- `[in] other`: The Value object to be compared. +- `[in] other`: The `Napi::Value` object to be compared. -Returns a `bool` indicating if this Value does not strictly equal another Value. +Returns a `bool` indicating if this `Napi::Value` does not strictly equal another `Napi::Value`. ### StrictEquals ```cpp -bool StrictEquals(const Value& other) const; +bool Napi::Value::StrictEquals(const Napi::Value& other) const; ``` -- `[in] other`: The Value object to be compared. +- `[in] other`: The `Napi::Value` object to be compared. -Returns a `bool` indicating if this Value strictly equals another Value. +Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi::Value`. ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::Value::Env() const; ``` -Returns the `Env` environment this value is associated with. +Returns the `Napi::Env` environment this value is associated with. ### IsEmpty ```cpp -bool IsEmpty() const; +bool Napi::Value::IsEmpty() const; ``` -Returns a `bool` indicating if this Value is *empty* (uninitialized). +Returns a `bool` indicating if this `Napi::Value` is *empty* (uninitialized). -An empty Value is invalid, and most attempts to perform an operation on an empty Value will result in an exception. Note an empty Value is distinct from JavaScript `null` or `undefined`, which are valid values. +An empty `Napi::Value` is invalid, and most attempts to perform an operation on an empty Value will result in an exception. +Note an empty `Napi::Value` is distinct from JavaScript `null` or `undefined`, which are valid values. -When C++ exceptions are disabled at compile time, a method with a `Value` return type may return an empty Value to indicate a pending exception. So when not using C++ exceptions, callers should check whether this Value is empty before attempting to use it. +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. So when not using C++ exceptions, callers should check whether this `Napi::Value` is empty before attempting to use it. ### Type ```cpp -napi_valuetype Type() const; +napi_valuetype Napi::Value::Type() const; ``` -Returns the `napi_valuetype` type of the Value. +Returns the `napi_valuetype` type of the `Napi::Value`. ### IsUndefined ```cpp -bool IsUndefined() const; +bool Napi::Value::IsUndefined() const; ``` -Returns a `bool` indicating if this Value is an undefined JavaScript value. +Returns a `bool` indicating if this `Napi::Value` is an undefined JavaScript value. ### IsNull ```cpp -bool IsNull() const; +bool Napi::Value::IsNull() const; ``` -Returns a `bool` indicating if this Value is a null JavaScript value. +Returns a `bool` indicating if this `Napi::Value` is a null JavaScript value. ### IsBoolean ```cpp -bool IsBoolean() const; +bool Napi::Value::IsBoolean() const; ``` -Returns a `bool` indicating if this Value is a JavaScript boolean. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript boolean. ### IsNumber ```cpp -bool IsNumber() const; +bool Napi::Value::IsNumber() const; ``` -Returns a `bool` indicating if this Value is a JavaScript number. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript number. ### IsString ```cpp -bool IsString() const; +bool Napi::Value::IsString() const; ``` -Returns a `bool` indicating if this Value is a JavaScript string. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript string. ### IsSymbol ```cpp -bool IsSymbol() const; +bool Napi::Value::IsSymbol() const; ``` -Returns a `bool` indicating if this Value is a JavaScript symbol. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript symbol. ### IsArray ```cpp -bool IsArray() const; +bool Napi::Value::IsArray() const; ``` -Returns a `bool` indicating if this Value is a JavaScript array. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript array. ### IsArrayBuffer ```cpp -bool IsArrayBuffer() const; +bool Napi::Value::IsArrayBuffer() const; ``` -Returns a `bool` indicating if this Value is a JavaScript array buffer. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript array buffer. ### IsTypedArray ```cpp -bool IsTypedArray() const; +bool Napi::Value::IsTypedArray() const; ``` -Returns a `bool` indicating if this Value is a JavaScript typed array. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript typed array. ### IsObject ```cpp -bool IsObject() const; +bool Napi::Value::IsObject() const; ``` -Returns a `bool` indicating if this Value is JavaScript object. +Returns a `bool` indicating if this `Napi::Value` is JavaScript object. ### IsFunction ```cpp -bool IsFunction() const; +bool Napi::Value::IsFunction() const; ``` -Returns a `bool` indicating if this Value is a JavaScript function. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript function. ### IsBuffer ```cpp -bool IsBuffer() const; +bool Napi::Value::IsBuffer() const; ``` -Returns a `bool` indicating if this Value is a Node buffer. +Returns a `bool` indicating if this `Napi::Value` is a Node buffer. ### As ```cpp -template T As() const; +template T Napi::Value::As() const; ``` Casts to another type of `Napi::Value`, when the actual type is known or assumed. @@ -239,31 +239,31 @@ This conversion does not coerce the type. Calling any methods inappropriate for ### ToBoolean ```cpp -Boolean ToBoolean() const; +Napi::Boolean Napi::Value::ToBoolean() const; ``` -Returns the Value coerced to a JavaScript boolean. +Returns the `Napi::Value` coerced to a JavaScript boolean. ### ToNumber ```cpp -Number ToNumber() const; +Napi::Number Napi::Value::ToNumber() const; ``` -Returns the Value coerced to a JavaScript number. +Returns the `Napi::Value` coerced to a JavaScript number. ### ToString ```cpp -String ToString() const; +Napi::String Napi::Value::ToString() const; ``` -Returns the Value coerced to a JavaScript string. +Returns the `Napi::Value` coerced to a JavaScript string. ### ToObject ```cpp -Object ToObject() const; +Napi::Object Napi::Value::ToObject() const; ``` -Returns the Value coerced to a JavaScript object. +Returns the `Napi::Value` coerced to a JavaScript object. diff --git a/doc/working_with_javascript_values.md b/doc/working_with_javascript_values.md index 0c5cbe2ee..fc208f10f 100644 --- a/doc/working_with_javascript_values.md +++ b/doc/working_with_javascript_values.md @@ -1,5 +1,13 @@ # Working with JavaScript Values -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/) +`node-addon-api` provides a set of classes that allow to create and manage +JavaScript object: + +- [Function](doc/function.md) + - [FunctionReference](doc/function_reference.md) +- [ObjectWrap](doc/object_wrap.md) + - [ClassPropertyDescriptor](doc/class_property_descriptor.md) +- [Buffer](doc/buffer.md) +- [ArrayBuffer](doc/array_buffer.md) +- [TypedArray](doc/typed_array.md) + - [TypedArrayOf](doc/typed_array_of.md)