From 1249bded9f47e5e517aa029038f939f5b2bebc02 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Wed, 26 Aug 2020 10:22:31 -0700 Subject: [PATCH] doc: add inheritance links and other changes * README.md: * Change indentation to reflect class hierarchy. * Link to new doc/hierarchy.md which shows full class hierarchy. * Add single sentence with link to parent class at the top of class doc. * doc/addon.md: * Replace `Addon` with `Addon`. * Show templating in prototypes. * Move `InstanceWrap` method documentation to its own file, because it is shared with `ObjectWRap`, and link to said new file. * doc/array.md: Create the file from the `Array`-related contents of doc/basic_types.md. * Remove doc/basic_types.md, splitting its contents per-class into individual files. * Add doc/hierarchy.md, with full class hierarchy. * Add doc/instance_wrap.md for documenting `InstanceMethod`, `InstanceAccessor`, and `InstanceValue`. * Create doc/name.md from doc/basic_types.md, documenting `Napi::Name`. * doc/object_wrap.md: * Add templating notation `Napi::ObjectWrap`. * Show templating in prototypes. * Wrap file to 80 columns. * Remove methods provided by `InstanceWrap` and link to doc/instance_wrap.md. * doc/value.md: * Merge documentation from doc/basic_types.md. * Add namespacing. * Sort methods alphabetically. Signed-off-by: Gabriel Schulhof --- README.md | 33 +- doc/addon.md | 397 +------------------ doc/array.md | 78 ++++ doc/array_buffer.md | 4 + doc/basic_types.md | 423 -------------------- doc/bigint.md | 4 + doc/boolean.md | 4 + doc/buffer.md | 4 + doc/dataview.md | 4 + doc/date.md | 4 +- doc/error.md | 5 + doc/external.md | 4 + doc/hierarchy.md | 91 +++++ doc/instance_wrap.md | 405 ++++++++++++++++++++ doc/name.md | 29 ++ doc/object.md | 8 +- doc/object_wrap.md | 530 ++++++-------------------- doc/promises.md | 5 + doc/string.md | 4 + doc/symbol.md | 4 + doc/typed_array.md | 4 + doc/typed_array_of.md | 4 + doc/value.md | 270 ++++++++----- doc/working_with_javascript_values.md | 2 +- 24 files changed, 983 insertions(+), 1337 deletions(-) create mode 100644 doc/array.md delete mode 100644 doc/basic_types.md create mode 100644 doc/hierarchy.md create mode 100644 doc/instance_wrap.md create mode 100644 doc/name.md diff --git a/README.md b/README.md index aa06eea67..660a9b1cd 100644 --- a/README.md +++ b/README.md @@ -81,28 +81,29 @@ The oldest Node.js version supported by the current version of node-addon-api is The following is the documentation for node-addon-api. + - [Full Class Hierarchy](doc/hierarchy.md) - [Addon Structure](doc/addon.md) - - [Basic Types](doc/basic_types.md) - - [Array](doc/basic_types.md#array) - - [Symbol](doc/symbol.md) - - [String](doc/string.md) - - [Name](doc/basic_types.md#name) - - [Number](doc/number.md) - - [Date](doc/date.md) - - [BigInt](doc/bigint.md) - - [Boolean](doc/boolean.md) + - Basic Types: - [Env](doc/env.md) - - [Value](doc/value.md) - [CallbackInfo](doc/callbackinfo.md) - [Reference](doc/reference.md) - - [External](doc/external.md) - - [Object](doc/object.md) - - [ObjectReference](doc/object_reference.md) - - [PropertyDescriptor](doc/property_descriptor.md) + - [Value](doc/value.md) + - [Name](doc/basic_types.md#name) + - [Symbol](doc/symbol.md) + - [String](doc/string.md) + - [Number](doc/number.md) + - [Date](doc/date.md) + - [BigInt](doc/bigint.md) + - [Boolean](doc/boolean.md) + - [External](doc/external.md) + - [Object](doc/object.md) + - [Array](doc/basic_types.md#array) + - [ObjectReference](doc/object_reference.md) + - [PropertyDescriptor](doc/property_descriptor.md) - [Error Handling](doc/error_handling.md) - [Error](doc/error.md) - - [TypeError](doc/type_error.md) - - [RangeError](doc/range_error.md) + - [TypeError](doc/type_error.md) + - [RangeError](doc/range_error.md) - [Object Lifetime Management](doc/object_lifetime_management.md) - [HandleScope](doc/handle_scope.md) - [EscapableHandleScope](doc/escapable_handle_scope.md) diff --git a/doc/addon.md b/doc/addon.md index b4c9c9d6b..ee85e7d5e 100644 --- a/doc/addon.md +++ b/doc/addon.md @@ -1,5 +1,7 @@ # Add-on Structure +Class `Napi::Addon` inherits from class [`Napi::InstanceWrap`][]. + Creating add-ons that work correctly when loaded multiple times from the same source package into multiple Node.js threads and/or multiple times into the same Node.js thread requires that all global data they hold be associated with the @@ -8,20 +10,20 @@ variables because doing so does not take into account the fact that an add-on may be loaded into multiple threads nor that an add-on may be loaded multiple times into a single thread. -The `Napi::Addon` class can be used to define an entire add-on. Instances of -`Napi::Addon` subclasses become instances of the add-on, stored safely by +The `Napi::Addon` class can be used to define an entire add-on. Instances of +`Napi::Addon` subclasses become instances of the add-on, stored safely by Node.js on its various threads and into its various contexts. Thus, any data -stored in the instance variables of a `Napi::Addon` subclass instance are stored -safely by Node.js. Functions exposed to JavaScript using -`Napi::Addon::InstanceMethod` and/or `Napi::Addon::DefineAddon` are instance -methods of the `Napi::Addon` subclass and thus have access to data stored inside -the instance. +stored in the instance variables of a `Napi::Addon` subclass instance are +stored safely by Node.js. Functions exposed to JavaScript using +`Napi::Addon::InstanceMethod` and/or `Napi::Addon::DefineAddon` are +instance methods of the `Napi::Addon` subclass and thus have access to data +stored inside the instance. -`Napi::Addon::DefineProperties` may be used to attach `Napi::Addon` subclass -instance methods to objects other than the one that will be returned to Node.js -as the add-on instance. +`Napi::Addon::DefineProperties` may be used to attach `Napi::Addon` +subclass instance methods to objects other than the one that will be returned to +Node.js as the add-on instance. -The `Napi::Addon` class can be used together with the `NODE_API_ADDON()` and +The `Napi::Addon` class can be used together with the `NODE_API_ADDON()` and `NODE_API_NAMED_ADDON()` macros to define add-ons. ## Example @@ -122,7 +124,8 @@ pass it to `DefineAddon()` as its first parameter if it wishes to replace the Defines an add-on instance with functions, accessors, and/or values. ```cpp -void Napi::Addon::DefineAddon(Napi::Object exports, +template +void Napi::Addon::DefineAddon(Napi::Object exports, const std::initializer_list& properties); ``` @@ -138,8 +141,9 @@ Defines function, accessor, and/or value properties on an object using add-on instance methods. ```cpp +template Napi::Object -Napi::Addon::DefineProperties(Napi::Object object, +Napi::Addon::DefineProperties(Napi::Object object, const std::initializer_list& properties); ``` @@ -150,369 +154,4 @@ See: [`Class property and descriptor`](class_property_descriptor.md). Returns `object`. -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(const char* utf8name, - InstanceVoidMethodCallback method, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -void MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(const char* utf8name, - InstanceMethodCallback method, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -Napi::Value MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(Napi::Symbol name, - InstanceVoidMethodCallback method, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] name`: JavaScript symbol that represents the name of the method provided -by the add-on. -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -void MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(Napi::Symbol name, - InstanceMethodCallback method, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] name`: JavaScript symbol that represents the name of the method provided -by the add-on. -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -Napi::Value MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(const char* utf8name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -void MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(const char* utf8name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -Napi::Value MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(Napi::Symbol name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -instance method for the class. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -void MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceMethod - -Creates a property descriptor that represents a method provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceMethod(Napi::Symbol name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] method`: The native function that represents a method provided by the -add-on. -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -instance method for the class. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the method when it is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents a method provided -by the add-on. The method must be of the form - -```cpp -Napi::Value MethodName(const Napi::CallbackInfo& info); -``` - -### InstanceAccessor - -Creates a property descriptor that represents an instance accessor property -provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceAccessor(const char* utf8name, - InstanceGetterCallback getter, - InstanceSetterCallback setter, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] getter`: The native function to call when a get access to the property -is performed. -- `[in] setter`: The native function to call when a set access to the property -is performed. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the getter or the setter when it -is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents an instance accessor -property provided by the add-on. - -### InstanceAccessor - -Creates a property descriptor that represents an instance accessor property -provided by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceAccessor(Symbol name, - InstanceGetterCallback getter, - InstanceSetterCallback setter, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -instance accessor. -- `[in] getter`: The native function to call when a get access to the property of -a JavaScript class is performed. -- `[in] setter`: The native function to call when a set access to the property of -a JavaScript class is performed. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the getter or the setter when it -is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents an instance accessor -property provided by the add-on. - -### InstanceAccessor - -Creates a property descriptor that represents an instance accessor property -provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceAccessor(const char* utf8name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] getter`: The native function to call when a get access to the property of -a JavaScript class is performed. -- `[in] setter`: The native function to call when a set access to the property of -a JavaScript class is performed. -- `[in] utf8name`: Null-terminated string that represents the name of the method -provided by the add-on. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the getter or the setter when it -is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents an instance accessor -property provided by the add-on. - -### InstanceAccessor - -Creates a property descriptor that represents an instance accessor property -provided by the add-on. - -```cpp -template -static Napi::PropertyDescriptor -Napi::Addon::InstanceAccessor(Symbol name, - napi_property_attributes attributes = napi_default, - void* data = nullptr); -``` - -- `[in] getter`: The native function to call when a get access to the property of -a JavaScript class is performed. -- `[in] setter`: The native function to call when a set access to the property of -a JavaScript class is performed. -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -instance accessor. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. -- `[in] data`: User-provided data passed into the getter or the setter when it -is invoked. - -Returns a `Napi::PropertyDescriptor` object that represents an instance accessor -property provided by the add-on. - -### InstanceValue - -Creates property descriptor that represents an instance value property provided -by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceValue(const char* utf8name, - Napi::Value value, - napi_property_attributes attributes = napi_default); -``` - -- `[in] utf8name`: Null-terminated string that represents the name of the property. -- `[in] value`: The value that's retrieved by a get access of the property. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. - -Returns a `Napi::PropertyDescriptor` object that represents an instance value -property of an add-on. - -### InstanceValue - -Creates property descriptor that represents an instance value property provided -by the add-on. - -```cpp -static Napi::PropertyDescriptor -Napi::Addon::InstanceValue(Symbol name, - Napi::Value value, - napi_property_attributes attributes = napi_default); -``` - -- `[in] name`: The `Napi::Symbol` object whose value is used to identify the -name of the property. -- `[in] value`: The value that's retrieved by a get access of the property. -- `[in] attributes`: The attributes associated with the property. One or more of -`napi_property_attributes`. - -Returns a `Napi::PropertyDescriptor` object that represents an instance value -property of an add-on. +[`Napi::InstanceWrap`]: ./instance_wrap.md diff --git a/doc/array.md b/doc/array.md new file mode 100644 index 000000000..c6f75c5b8 --- /dev/null +++ b/doc/array.md @@ -0,0 +1,78 @@ +# Array + +Class [`Napi::Array`][] inherits from class [`Napi::Object`][]. + +Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper +around `napi_value` representing a JavaScript Array. + +[`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data +types such as [`Int32Array`][] and [`ArrayBuffer`][], respectively, that can be +used for transferring large amounts of data from JavaScript to the native side. +An example illustrating the use of a JavaScript-provided `ArrayBuffer` in native +code is available [here](https://github.com/nodejs/node-addon-examples/tree/master/array_buffer_to_native/node-addon-api). + +## Constructor +```cpp +Napi::Array::Array(); +``` + +Returns an empty array. + +If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +```cpp +Napi::Array::Array(napi_env env, napi_value value); +``` +- `[in] env` - The environment in which to create the array. +- `[in] value` - The primitive to wrap. + +Returns a `Napi::Array` wrapping a `napi_value`. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +## Methods + +### New +```cpp +static Napi::Array Napi::Array::New(napi_env env); +``` +- `[in] env` - The environment in which to create the array. + +Returns a new `Napi::Array`. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +### New + +```cpp +static Napi::Array Napi::Array::New(napi_env env, size_t length); +``` +- `[in] env` - The environment in which to create the array. +- `[in] length` - The length of the array. + +Returns a new `Napi::Array` with the given length. + +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +### Length +```cpp +uint32_t Napi::Array::Length() const; +``` + +Returns the length of the array. + +Note: +This can execute JavaScript code implicitly according to JavaScript semantics. +If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not +being used, callers should check the result of `Env::IsExceptionPending` before +attempting to use the returned value. + +[`Napi::Object`]: ./object.md diff --git a/doc/array_buffer.md b/doc/array_buffer.md index ca9d45c00..988a839a4 100644 --- a/doc/array_buffer.md +++ b/doc/array_buffer.md @@ -1,5 +1,7 @@ # ArrayBuffer +Class `Napi::ArrayBuffer` inherits from class [`Napi::Object`][]. + The `Napi::ArrayBuffer` class corresponds to the [JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) class. @@ -127,3 +129,5 @@ void* Napi::ArrayBuffer::Data() const; ``` Returns a pointer the wrapped data. + +[`Napi::Object`]: ./object.md diff --git a/doc/basic_types.md b/doc/basic_types.md deleted file mode 100644 index 03ec14b4b..000000000 --- a/doc/basic_types.md +++ /dev/null @@ -1,423 +0,0 @@ -# Basic Types - -Node Addon API consists of a few fundamental data types. These allow a user of -the API to create, convert and introspect fundamental JavaScript types, and -interoperate with their C++ counterparts. - -## Value - -`Napi::Value` is the base class of Node Addon API's fundamental object type hierarchy. -It represents a JavaScript value of an unknown type. It is a thin wrapper around -the N-API datatype `napi_value`. Methods on this class can be used to check -the JavaScript type of the underlying N-API `napi_value` and also to convert to -C++ types. - -### Constructor - -```cpp -Napi::Value::Value(); -``` - -Used to create a Node Addon API `Napi::Value` that represents an **empty** value. - -```cpp -Napi::Value::Value(napi_env env, napi_value value); -``` - -- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` -object. -- `[in] value` - The underlying JavaScript value that the `Napi::Value` instance -represents. - -Returns a Node.js Addon API `Napi::Value` that represents the `napi_value` passed -in. - -### Operators - -#### operator napi_value - -```cpp -Napi::Value::operator napi_value() const; -``` - -Returns the underlying N-API `napi_value`. If the instance is _empty_, this -returns `nullptr`. - -#### operator == - -```cpp -bool Napi::Value::operator ==(const Value& other) const; -``` - -Returns `true` if this value strictly equals another value, or `false` otherwise. - -#### operator != - -```cpp -bool Napi::Value::operator !=(const Value& other) const; -``` - -Returns `false` if this value strictly equals another value, or `true` otherwise. - -### Methods - -#### From -```cpp -template -static Napi::Value Napi::Value::From(napi_env env, const T& value); -``` - -- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` object. -- `[in] value` - The C++ type to represent in JavaScript. - -Returns a `Napi::Value` representing the input C++ type in JavaScript. - -This method is used to convert from a C++ type to a JavaScript value. -Here, `value` may be any of: -- `bool` - returns a `Napi::Boolean`. -- Any integer type - returns a `Napi::Number`. -- Any floating point type - returns a `Napi::Number`. -- `const char*` (encoded using UTF-8, null-terminated) - returns a `Napi::String`. -- `const char16_t*` (encoded using UTF-16-LE, null-terminated) - returns a `Napi::String`. -- `std::string` (encoded using UTF-8) - returns a `Napi::String`. -- `std::u16string` - returns a `Napi::String`. -- `napi::Value` - returns a `Napi::Value`. -- `napi_value` - returns a `Napi::Value`. - -#### As -```cpp -template T Napi::Value::As() const; -``` - -Returns the `Napi::Value` cast to a desired C++ type. - -Use this when the actual type is known or assumed. - -Note: -This conversion does NOT coerce the type. Calling any methods inappropriate for -the actual value type will throw `Napi::Error`. - -#### StrictEquals -```cpp -bool Napi::Value::StrictEquals(const Value& other) const; -``` - -- `[in] other` - The value to compare against. - -Returns true if the other `Napi::Value` is strictly equal to this one. - -#### Env -```cpp -Napi::Env Napi::Value::Env() const; -``` - -Returns the environment that the value is associated with. See -[`Napi::Env`](env.md) for more details about environments. - -#### IsEmpty -```cpp -bool Napi::Value::IsEmpty() const; -``` - -Returns `true` if the value is uninitialized. - -An empty value is invalid, and most attempts to perform an operation on an -empty value will result in an exception. An empty value is distinct from -JavaScript `null` or `undefined`, which are valid values. - -When C++ exceptions are disabled at compile time, a method with a `Napi::Value` -return type may return an empty value to indicate a pending exception. If C++ -exceptions are not being used, callers should check the result of -`Env::IsExceptionPending` before attempting to use the value. - -#### Type -```cpp -napi_valuetype Napi::Value::Type() const; -``` - -Returns the underlying N-API `napi_valuetype` of the value. - -#### IsUndefined -```cpp -bool Napi::Value::IsUndefined() const; -``` - -Returns `true` if the underlying value is a JavaScript `undefined` or `false` -otherwise. - -#### IsNull -```cpp -bool Napi::Value::IsNull() const; -``` - -Returns `true` if the underlying value is a JavaScript `null` or `false` -otherwise. - -#### IsBoolean -```cpp -bool Napi::Value::IsBoolean() const; -``` - -Returns `true` if the underlying value is a JavaScript `true` or JavaScript -`false`, or `false` if the value is not a `Napi::Boolean` value in JavaScript. - -#### IsNumber -```cpp -bool Napi::Value::IsNumber() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false` -otherwise. - -#### IsString -```cpp -bool Napi::Value::IsString() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::String` or `false` -otherwise. - -#### IsSymbol -```cpp -bool Napi::Value::IsSymbol() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false` -otherwise. - -#### IsArray -```cpp -bool Napi::Value::IsArray() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false` -otherwise. - -#### IsArrayBuffer -```cpp -bool Napi::Value::IsArrayBuffer() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or `false` -otherwise. - -#### IsTypedArray -```cpp -bool Napi::Value::IsTypedArray() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or `false` -otherwise. - -#### IsObject -```cpp -bool Napi::Value::IsObject() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false` -otherwise. - -#### IsFunction -```cpp -bool Napi::Value::IsFunction() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Function` or `false` -otherwise. - -#### IsPromise -```cpp -bool Napi::Value::IsPromise() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::Promise` or `false` -otherwise. - -#### IsDataView -```cpp -bool Napi::Value::IsDataView() const; -``` - -Returns `true` if the underlying value is a JavaScript `Napi::DataView` or `false` -otherwise. - -#### IsBuffer -```cpp -bool Napi::Value::IsBuffer() const; -``` - -Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false` -otherwise. - -#### IsExternal -```cpp -bool Napi::Value::IsExternal() const; -``` - -Returns `true` if the underlying value is a N-API external object or `false` -otherwise. - -#### IsDate -```cpp -bool Napi::Value::IsDate() const; -``` - -Returns `true` if the underlying value is a JavaScript `Date` or `false` -otherwise. - -#### ToBoolean -```cpp -Napi::Boolean Napi::Value::ToBoolean() const; -``` - -Returns a `Napi::Boolean` representing the `Napi::Value`. - -This is a wrapper around `napi_coerce_to_boolean`. This will throw a JavaScript -exception if the coercion fails. If C++ exceptions are not being used, callers -should check the result of `Env::IsExceptionPending` before attempting to use -the returned value. - -#### ToNumber -```cpp -Napi::Number Napi::Value::ToNumber() const; -``` - -Returns a `Napi::Number` representing the `Napi::Value`. - -Note: -This can cause script code to be executed according to JavaScript semantics. -This is a wrapper around `napi_coerce_to_number`. This will throw a JavaScript -exception if the coercion fails. If C++ exceptions are not being used, callers -should check the result of `Env::IsExceptionPending` before attempting to use -the returned value. - -#### ToString -```cpp -Napi::String Napi::Value::ToString() const; -``` - -Returns a `Napi::String` representing the `Napi::Value`. - -Note that this can cause script code to be executed according to JavaScript -semantics. This is a wrapper around `napi_coerce_to_string`. This will throw a -JavaScript exception if the coercion fails. If C++ exceptions are not being -used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -#### ToObject -```cpp -Napi::Object Napi::Value::ToObject() const; -``` - -Returns a `Napi::Object` representing the `Napi::Value`. - -This is a wrapper around `napi_coerce_to_object`. This will throw a JavaScript -exception if the coercion fails. If C++ exceptions are not being used, callers -should check the result of `Env::IsExceptionPending` before attempting to use -the returned value. - -## Name - -Names are JavaScript values that can be used as a property name. There are two -specialized types of names supported in Node.js Addon API [`Napi::String`](string.md) -and [`Napi::Symbol`](symbol.md). - -### Methods - -#### Constructor -```cpp -Napi::Name::Name(); -``` - -Returns an empty `Napi::Name`. - -```cpp -Napi::Name::Name(napi_env env, napi_value value); -``` -- `[in] env` - The environment in which to create the array. -- `[in] value` - The primitive to wrap. - -Returns a `Napi::Name` created from the JavaScript primitive. - -Note: -The value is not coerced to a string. - -## Array - -Arrays are native representations of JavaScript Arrays. `Napi::Array` is a wrapper -around `napi_value` representing a JavaScript Array. - -[`Napi::TypedArray`][] and [`Napi::ArrayBuffer`][] correspond to JavaScript data -types such as [`Int32Array`][] and [`ArrayBuffer`][], respectively, that can be -used for transferring large amounts of data from JavaScript to the native side. -An example illustrating the use of a JavaScript-provided `ArrayBuffer` in native -code is available [here](https://github.com/nodejs/node-addon-examples/tree/master/array_buffer_to_native/node-addon-api). - -### Constructor -```cpp -Napi::Array::Array(); -``` - -Returns an empty array. - -If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -```cpp -Napi::Array::Array(napi_env env, napi_value value); -``` -- `[in] env` - The environment in which to create the array. -- `[in] value` - The primitive to wrap. - -Returns a `Napi::Array` wrapping a `napi_value`. - -If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -### Methods - -#### New -```cpp -static Napi::Array Napi::Array::New(napi_env env); -``` -- `[in] env` - The environment in which to create the array. - -Returns a new `Napi::Array`. - -If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -#### New - -```cpp -static Napi::Array Napi::Array::New(napi_env env, size_t length); -``` -- `[in] env` - The environment in which to create the array. -- `[in] length` - The length of the array. - -Returns a new `Napi::Array` with the given length. - -If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -#### Length -```cpp -uint32_t Napi::Array::Length() const; -``` - -Returns the length of the array. - -Note: -This can execute JavaScript code implicitly according to JavaScript semantics. -If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before -attempting to use the returned value. - -[`Napi::TypedArray`]: ./typed_array.md -[`Napi::ArrayBuffer`]: ./array_buffer.md -[`Int32Array`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Int32Array -[`ArrayBuffer`]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer diff --git a/doc/bigint.md b/doc/bigint.md index 33ada43b3..d6f2ea68e 100644 --- a/doc/bigint.md +++ b/doc/bigint.md @@ -1,5 +1,7 @@ # BigInt +Class `Napi::Bigint` inherits from class [`Napi::Value`][]. + A JavaScript BigInt value. ## Methods @@ -91,3 +93,5 @@ void Napi::BigInt::ToWords(int* sign_bit, size_t* word_count, uint64_t* words); Returns a single `BigInt` value into a sign bit, 64-bit little-endian array, and the number of elements in the array. + +[`Napi::Value`]: ./value.md diff --git a/doc/boolean.md b/doc/boolean.md index 01b6a4c0a..d07daa210 100644 --- a/doc/boolean.md +++ b/doc/boolean.md @@ -1,5 +1,7 @@ # Boolean +Class `Napi::Boolean` inherits from class [`Napi::Value`][]. + `Napi::Boolean` class is a representation of the JavaScript `Boolean` object. The `Napi::Boolean` class inherits its behavior from the `Napi::Value` class (for more info see: [`Napi::Value`](value.md)). @@ -62,3 +64,5 @@ Napi::Boolean::operator bool() const; ``` Returns the boolean primitive type of the corresponding `Napi::Boolean` object. + +[`Napi::Value`]: ./value.md diff --git a/doc/buffer.md b/doc/buffer.md index 8f76b200d..97ed48a5a 100644 --- a/doc/buffer.md +++ b/doc/buffer.md @@ -1,5 +1,7 @@ # Buffer +Class `Napi::Buffer` inherits from class [`Napi::Uint8Array`][]. + The `Napi::Buffer` class creates a projection of raw data that can be consumed by script. @@ -138,3 +140,5 @@ size_t Napi::Buffer::Length() const; ``` Returns the number of `T` elements in the external data. + +[`Napi::Uint8Array`]: ./typed_array_of.md diff --git a/doc/dataview.md b/doc/dataview.md index 64b865b1c..66fb28919 100644 --- a/doc/dataview.md +++ b/doc/dataview.md @@ -1,5 +1,7 @@ # DataView +Class `Napi::DataView` inherits from class [`Napi::Object`][]. + The `Napi::DataView` class corresponds to the [JavaScript `DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView) class. @@ -242,3 +244,5 @@ void Napi::DataView::SetUint32(size_t byteOffset, uint32_t value) const; - `[in] byteOffset`: The offset, in byte, from the start of the view where to read the data. - `[in] value`: The value to set. + +[`Napi::Object`]: ./object.md diff --git a/doc/date.md b/doc/date.md index 959b4b9a6..4c5fefa5e 100644 --- a/doc/date.md +++ b/doc/date.md @@ -1,8 +1,8 @@ # Date `Napi::Date` class is a representation of the JavaScript `Date` object. The -`Napi::Date` class inherits its behavior from `Napi::Value` class -(for more info see [`Napi::Value`](value.md)) +`Napi::Date` class inherits its behavior from the `Napi::Value` class +(for more info see [`Napi::Value`](value.md)). ## Methods diff --git a/doc/error.md b/doc/error.md index 1526bddf0..7530262d7 100644 --- a/doc/error.md +++ b/doc/error.md @@ -1,5 +1,7 @@ # Error +Class `Napi::Error` inherits from class [`Napi::ObjectReference`][] and class [`std::exception`][]. + The `Napi::Error` class is a representation of the JavaScript `Error` object that is thrown when runtime errors occur. The Error object can also be used as a base object for user-defined exceptions. @@ -113,3 +115,6 @@ const char* Napi::Error::what() const NAPI_NOEXCEPT override; Returns a pointer to a null-terminated string that is used to identify the exception. This method can be used only if the exception mechanism is enabled. + +[`Napi::ObjectReference`]: ./object_reference.md +[`std::exception`]: http://cplusplus.com/reference/exception/exception/ diff --git a/doc/external.md b/doc/external.md index 4022b61dd..814eb037c 100644 --- a/doc/external.md +++ b/doc/external.md @@ -1,5 +1,7 @@ # External (template) +Class `Napi::External` inherits from class [`Napi::Value`][]. + The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data. `Napi::External` objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your `Napi::External` object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function. @@ -57,3 +59,5 @@ T* Napi::External::Data() const; ``` Returns a pointer to the arbitrary C++ data held by the `Napi::External` object. + +[`Napi::Value`]: ./value.md diff --git a/doc/hierarchy.md b/doc/hierarchy.md new file mode 100644 index 000000000..e40a65ff9 --- /dev/null +++ b/doc/hierarchy.md @@ -0,0 +1,91 @@ +# Full Class Hierarchy + +| Class | Parent Class(es) | +|---|---| +| [`Napi::Addon`][] | [`Napi::InstanceWrap`][] | +| [`Napi::Array`][] | [`Napi::Object`][] | +| [`Napi::ArrayBuffer`][] | [`Napi::Object`][] | +| [`Napi::AsyncContext`][] | | +| [`Napi::AsyncProgressQueueWorker`][] | `Napi::AsyncProgressWorkerBase` | +| [`Napi::AsyncProgressWorker`][] | `Napi::AsyncProgressWorkerBase` | +| [`Napi::AsyncWorker`][] | | +| [`Napi::BigInt`][] | [`Napi::Value`][] | +| [`Napi::Boolean`][] | [`Napi::Value`][] | +| [`Napi::Buffer`][] | [`Napi::Uint8Array`][] | +| [`Napi::CallbackInfo`][] | | +| [`Napi::CallbackScope`][] | | +| [`Napi::ClassPropertyDescriptor`][] | | +| [`Napi::DataView`][] | [`Napi::Object`][] | +| [`Napi::Date`][] | [`Napi::Value`][] | +| [`Napi::Env`][] | | +| [`Napi::Error`][] | [`Napi::ObjectReference`][], [`std::exception`][] | +| [`Napi::EscapableHandleScope`][] | | +| [`Napi::External`][] | [`Napi::Value`][] | +| [`Napi::Function`][] | [`Napi::Object`][] | +| [`Napi::FunctionReference`][] | [`Napi::Reference`][] | +| [`Napi::HandleScope`][] | | +| [`Napi::InstanceWrap`][] | | +| [`Napi::MemoryManagement`][] | | +| [`Napi::Name`][] | [`Napi::Value`][] | +| [`Napi::Number`][] | [`Napi::Value`][] | +| [`Napi::Object`][] | [`Napi::Value`][] | +| [`Napi::ObjectReference`][] | [`Napi::Reference`][] | +| [`Napi::ObjectWrap`][] | [`Napi::InstanceWrap`][], [`Napi::Reference`][] | +| [`Napi::Promise`][] | [`Napi::Object`][] | +| [`Napi::PropertyDescriptor`][] | | +| [`Napi::RangeError`][] | [`Napi::Error`][] | +| [`Napi::Reference`] | | +| [`Napi::String`][] | [`Napi::Name`][] | +| [`Napi::Symbol`][] | [`Napi::Name`][] | +| [`Napi::ThreadSafeFunction`][] | | +| [`Napi::TypeError`][] | [`Napi::Error`][] | +| [`Napi::TypedArray`][] | [`Napi::Object`][] | +| [`Napi::TypedArrayOf`][] | [`Napi::TypedArray`][] | +| [`Napi::Value`][] | | +| [`Napi::VersionManagement`][] | | + +[`Napi::Addon`]: ./addon.md +[`Napi::Array`]: ./array.md +[`Napi::ArrayBuffer`]: ./array_buffer.md +[`Napi::AsyncContext`]: ./async_context.md +[`Napi::AsyncProgressQueueWorker`]: ./async_worker_variants.md#asyncprogressqueueworker +[`Napi::AsyncProgressWorker`]: ./async_worker_variants.md#asyncprogressworker +[`Napi::AsyncWorker`]: ./async_worker.md +[`Napi::BigInt`]: ./bigint.md +[`Napi::Boolean`]: ./boolean.md +[`Napi::Buffer`]: ./buffer.md +[`Napi::CallbackInfo`]: ./callbackinfo.md +[`Napi::CallbackScope`]: ./callback_scope.md +[`Napi::ClassPropertyDescriptor`]: ./class_property_descriptor.md +[`Napi::DataView`]: ./dataview.md +[`Napi::Date`]: ./date.md +[`Napi::Env`]: ./env.md +[`Napi::Error`]: ./error.md +[`Napi::EscapableHandleScope`]: ./escapable_handle_scope.md +[`Napi::External`]: ./external.md +[`Napi::Function`]: ./function.md +[`Napi::FunctionReference`]: ./function_reference.md +[`Napi::HandleScope`]: ./handle_scope.md +[`Napi::InstanceWrap`]: ./instance_wrap.md +[`Napi::MemoryManagement`]: ./memory_management.md +[`Napi::Name`]: ./name.md +[`Napi::Number`]: ./number.md +[`Napi::Object`]: ./object.md +[`Napi::ObjectReference`]: ./object_reference.md +[`Napi::ObjectWrap`]: ./object_wrap.md +[`Napi::Promise`]: ./promise.md +[`Napi::PropertyDescriptor`]: ./property_descriptor.md +[`Napi::RangeError`]: ./range_error.md +[`Napi::Reference`]: ./reference.md +[`Napi::Reference`]: ./reference.md +[`Napi::Reference`]: ./reference.md +[`Napi::String`]: ./string.md +[`Napi::Symbol`]: ./symbol.md +[`Napi::ThreadSafeFunction`]: ./thread_safe_function.md +[`Napi::TypeError`]: ./type_error.md +[`Napi::TypedArray`]: ./typed_array.md +[`Napi::TypedArrayOf`]: ./typed_array_of.md +[`Napi::Uint8Array`]: ./typed_array_of.md +[`Napi::Value`]: ./value.md +[`Napi::VersionManagement`]: ./version_management.md +[`std::exception`]: http://cplusplus.com/reference/exception/exception/ diff --git a/doc/instance_wrap.md b/doc/instance_wrap.md new file mode 100644 index 000000000..b20d664f1 --- /dev/null +++ b/doc/instance_wrap.md @@ -0,0 +1,405 @@ +# InstanceWrap + +This class serves as the base class for [`Napi::ObjectWrap`][] and +[`Napi::Addon`][]. + +In the case of [`Napi::Addon`][] it provides the +methods for exposing functions to JavaScript on instances of an add-on. + +As a base class for [`Napi::ObjectWrap`][] it provides the methods for +exposing instance methods of JavaScript objects instantiated from the JavaScript +class corresponding to the subclass of [`Napi::ObjectWrap`][]. + +## Methods + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +template +static Napi::ClassPropertyDescriptor +Napi::InstanceWrap::InstanceMethod(const char* utf8name, + InstanceVoidMethodCallback method, + napi_property_attributes attributes = napi_default, + void* data = nullptr); +``` + +- `[in] utf8name`: Null-terminated string that represents the name of the method +provided by instances of the class. +- `[in] method`: The native function that represents a method provided by the +add-on. +- `[in] attributes`: The attributes associated with the property. One or more of +`napi_property_attributes`. +- `[in] data`: User-provided data passed into the method when it is invoked. + +Returns a `Napi::ClassPropertyDescriptor` object that represents a method +provided by instances of the class. The method must be of the form + +```cpp +void MethodName(const Napi::CallbackInfo& info); +``` + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +template +static Napi::ClassPropertyDescriptor +Napi::InstanceWrap::InstanceMethod(const char* utf8name, + InstanceMethodCallback method, + napi_property_attributes attributes = napi_default, + void* data = nullptr); +``` + +- `[in] utf8name`: Null-terminated string that represents the name of the method +provided by instances of the class. +- `[in] method`: The native function that represents a method provided by the +add-on. +- `[in] attributes`: The attributes associated with the property. One or more of +`napi_property_attributes`. +- `[in] data`: User-provided data passed into the method when it is invoked. + +Returns a `Napi::ClassPropertyDescriptor` object that represents a method +provided by instances of the class. The method must be of the form + +```cpp +Napi::Value MethodName(const Napi::CallbackInfo& info); +``` + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +template +static Napi::ClassPropertyDescriptor +Napi::InstanceWrap::InstanceMethod(Napi::Symbol name, + InstanceVoidMethodCallback method, + napi_property_attributes attributes = napi_default, + void* data = nullptr); +``` + +- `[in] name`: JavaScript symbol that represents the name of the method provided +by instances of the class. +- `[in] method`: The native function that represents a method provided by the +add-on. +- `[in] attributes`: The attributes associated with the property. One or more of +`napi_property_attributes`. +- `[in] data`: User-provided data passed into the method when it is invoked. + +Returns a `Napi::ClassPropertyDescriptor` object that represents a method +provided by instances of the class. The method must be of the form + +```cpp +void MethodName(const Napi::CallbackInfo& info); +``` + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +template +static Napi::ClassPropertyDescriptor +Napi::InstanceWrap::InstanceMethod(Napi::Symbol name, + InstanceMethodCallback method, + napi_property_attributes attributes = napi_default, + void* data = nullptr); +``` + +- `[in] name`: JavaScript symbol that represents the name of the method provided +by instances of the class. +- `[in] method`: The native function that represents a method provided by the +add-on. +- `[in] attributes`: The attributes associated with the property. One or more of +`napi_property_attributes`. +- `[in] data`: User-provided data passed into the method when it is invoked. + +Returns a `Napi::ClassPropertyDescriptor` object that represents a method +provided by instances of the class. The method must be of the form + +```cpp +Napi::Value MethodName(const Napi::CallbackInfo& info); +``` + +### InstanceMethod + +Creates a property descriptor that represents a method exposed on JavaScript +instances of this class. + +```cpp +