aboutsummaryrefslogtreecommitdiffstats
path: root/node_modules/node-addon-api/napi.h
diff options
context:
space:
mode:
authorpack <pack@packgekko.xyz>2026-08-09 10:37:07 +0000
committerpack <pack@packgekko.xyz>2026-08-09 10:37:07 +0000
commit55a4f1fc869e41aca748c63d3018f0448b1606e0 (patch)
treed132d1d01772b6d53faee3e63c534dea5706b78a /node_modules/node-addon-api/napi.h
downloadcrud-55a4f1fc869e41aca748c63d3018f0448b1606e0.tar.gz
first commit
Diffstat (limited to '')
-rw-r--r--node_modules/node-addon-api/napi.h3420
1 files changed, 3420 insertions, 0 deletions
diff --git a/node_modules/node-addon-api/napi.h b/node_modules/node-addon-api/napi.h
new file mode 100644
index 0000000..870a5c2
--- /dev/null
+++ b/node_modules/node-addon-api/napi.h
@@ -0,0 +1,3420 @@
+#ifndef SRC_NAPI_H_
+#define SRC_NAPI_H_
+
+#ifndef NAPI_HAS_THREADS
+#if !defined(__wasm__) || (defined(__EMSCRIPTEN_PTHREADS__) || \
+ (defined(__wasi__) && defined(_REENTRANT)))
+#define NAPI_HAS_THREADS 1
+#else
+#define NAPI_HAS_THREADS 0
+#endif
+#endif
+
+#include <node_api.h>
+#include <functional>
+#include <initializer_list>
+#include <memory>
+#if NAPI_HAS_THREADS
+#include <mutex>
+#endif // NAPI_HAS_THREADS
+#include <chrono>
+#include <string>
+#include <string_view>
+#include <vector>
+
+// VS2015 RTM has bugs with constexpr, so require min of VS2015 Update 3 (known
+// good version)
+#if !defined(_MSC_VER) || _MSC_FULL_VER >= 190024210
+#define NAPI_HAS_CONSTEXPR 1
+#endif
+
+// VS2013 does not support char16_t literal strings, so we'll work around it
+// using wchar_t strings and casting them. This is safe as long as the character
+// sizes are the same.
+#if defined(_MSC_VER) && _MSC_VER <= 1800
+static_assert(sizeof(char16_t) == sizeof(wchar_t),
+ "Size mismatch between char16_t and wchar_t");
+#define NAPI_WIDE_TEXT(x) reinterpret_cast<char16_t*>(L##x)
+#else
+#define NAPI_WIDE_TEXT(x) u##x
+#endif
+
+// Backwards-compatibility to handle the rename of this macro definition, in
+// case they are used within userland code.
+#ifdef NAPI_CPP_EXCEPTIONS
+#define NODE_ADDON_API_CPP_EXCEPTIONS
+#endif
+#if defined(NODE_ADDON_API_CPP_EXCEPTIONS) && !defined(NAPI_CPP_EXCEPTIONS)
+#define NAPI_CPP_EXCEPTIONS
+#endif
+#ifdef NAPI_DISABLE_CPP_EXCEPTIONS
+#define NODE_ADDON_API_DISABLE_CPP_EXCEPTIONS
+#endif
+#if defined(NODE_ADDON_API_DISABLE_CPP_EXCEPTIONS) && \
+ !defined(NAPI_DISABLE_CPP_EXCEPTIONS)
+#define NAPI_DISABLE_CPP_EXCEPTIONS
+#endif
+
+// If C++ exceptions are not explicitly enabled or disabled, enable them
+// if exceptions were enabled in the compiler settings.
+#if !defined(NODE_ADDON_API_CPP_EXCEPTIONS) && \
+ !defined(NODE_ADDON_API_DISABLE_CPP_EXCEPTIONS)
+#if defined(_CPPUNWIND) || defined(__EXCEPTIONS)
+#define NODE_ADDON_API_CPP_EXCEPTIONS
+#else
+#error Exception support not detected. \
+ Define either NODE_ADDON_API_CPP_EXCEPTIONS or NODE_ADDON_API_DISABLE_CPP_EXCEPTIONS.
+#endif
+#endif
+
+// If C++ NODE_ADDON_API_CPP_EXCEPTIONS are enabled, NODE_ADDON_API_ENABLE_MAYBE
+// should not be set
+#if defined(NODE_ADDON_API_CPP_EXCEPTIONS) && \
+ defined(NODE_ADDON_API_ENABLE_MAYBE)
+#error NODE_ADDON_API_ENABLE_MAYBE should not be set when \
+ NODE_ADDON_API_CPP_EXCEPTIONS is defined.
+#endif
+
+#ifdef _NOEXCEPT
+#define NAPI_NOEXCEPT _NOEXCEPT
+#else
+#define NAPI_NOEXCEPT noexcept
+#endif
+
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS
+
+// When C++ exceptions are enabled, Errors are thrown directly. There is no need
+// to return anything after the throw statements. The variadic parameter is an
+// optional return value that is ignored.
+// We need _VOID versions of the macros to avoid warnings resulting from
+// leaving the NAPI_THROW_* `...` argument empty.
+
+#define NAPI_THROW(e, ...) throw e
+#define NAPI_THROW_VOID(e) throw e
+
+#define NAPI_THROW_IF_FAILED(env, status, ...) \
+ if ((status) != napi_ok) throw Napi::Error::New(env);
+
+#define NAPI_THROW_IF_FAILED_VOID(env, status) \
+ if ((status) != napi_ok) throw Napi::Error::New(env);
+
+#else // NODE_ADDON_API_CPP_EXCEPTIONS
+
+// When C++ exceptions are disabled, Errors are thrown as JavaScript exceptions,
+// which are pending until the callback returns to JS. The variadic parameter
+// is an optional return value; usually it is an empty result.
+// We need _VOID versions of the macros to avoid warnings resulting from
+// leaving the NAPI_THROW_* `...` argument empty.
+
+#define NAPI_THROW(e, ...) \
+ do { \
+ (e).ThrowAsJavaScriptException(); \
+ return __VA_ARGS__; \
+ } while (0)
+
+#define NAPI_THROW_VOID(e) \
+ do { \
+ (e).ThrowAsJavaScriptException(); \
+ return; \
+ } while (0)
+
+#define NAPI_THROW_IF_FAILED(env, status, ...) \
+ if ((status) != napi_ok) { \
+ Napi::Error::New(env).ThrowAsJavaScriptException(); \
+ return __VA_ARGS__; \
+ }
+
+#define NAPI_THROW_IF_FAILED_VOID(env, status) \
+ if ((status) != napi_ok) { \
+ Napi::Error::New(env).ThrowAsJavaScriptException(); \
+ return; \
+ }
+
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS
+
+#ifdef NODE_ADDON_API_ENABLE_MAYBE
+#define NAPI_MAYBE_THROW_IF_FAILED(env, status, type) \
+ NAPI_THROW_IF_FAILED(env, status, Napi::Nothing<type>())
+
+#define NAPI_RETURN_OR_THROW_IF_FAILED(env, status, result, type) \
+ NAPI_MAYBE_THROW_IF_FAILED(env, status, type); \
+ return Napi::Just<type>(result);
+#else
+#define NAPI_MAYBE_THROW_IF_FAILED(env, status, type) \
+ NAPI_THROW_IF_FAILED(env, status, type())
+
+#define NAPI_RETURN_OR_THROW_IF_FAILED(env, status, result, type) \
+ NAPI_MAYBE_THROW_IF_FAILED(env, status, type); \
+ return result;
+#endif
+
+#define NAPI_DISALLOW_ASSIGN(CLASS) void operator=(const CLASS&) = delete;
+#define NAPI_DISALLOW_COPY(CLASS) CLASS(const CLASS&) = delete;
+
+#define NAPI_DISALLOW_ASSIGN_COPY(CLASS) \
+ NAPI_DISALLOW_ASSIGN(CLASS) \
+ NAPI_DISALLOW_COPY(CLASS)
+
+#define NAPI_CHECK(condition, location, message) \
+ do { \
+ if (!(condition)) { \
+ Napi::Error::Fatal((location), (message)); \
+ } \
+ } while (0)
+
+// Internal check helper. Be careful that the formatted message length should be
+// max 255 size and null terminated.
+#define NAPI_INTERNAL_CHECK(expr, location, ...) \
+ do { \
+ if (!(expr)) { \
+ std::string msg = Napi::details::StringFormat(__VA_ARGS__); \
+ Napi::Error::Fatal(location, msg.c_str()); \
+ } \
+ } while (0)
+
+#define NAPI_INTERNAL_CHECK_EQ(actual, expected, value_format, location) \
+ do { \
+ auto actual_value = (actual); \
+ NAPI_INTERNAL_CHECK(actual_value == (expected), \
+ location, \
+ "Expected " #actual " to be equal to " #expected \
+ ", but got " value_format ".", \
+ actual_value); \
+ } while (0)
+
+#define NAPI_FATAL_IF_FAILED(status, location, message) \
+ NAPI_CHECK((status) == napi_ok, location, message)
+
+////////////////////////////////////////////////////////////////////////////////
+/// Node-API C++ Wrapper Classes
+///
+/// These classes wrap the "Node-API" ABI-stable C APIs for Node.js, providing a
+/// C++ object model and C++ exception-handling semantics with low overhead.
+/// The wrappers are all header-only so that they do not affect the ABI.
+////////////////////////////////////////////////////////////////////////////////
+namespace Napi {
+
+#ifdef NAPI_CPP_CUSTOM_NAMESPACE
+// NAPI_CPP_CUSTOM_NAMESPACE can be #define'd per-addon to avoid symbol
+// conflicts between different instances of node-addon-api
+
+// First dummy definition of the namespace to make sure that Napi::(name) still
+// refers to the right things inside this file.
+namespace NAPI_CPP_CUSTOM_NAMESPACE {}
+using namespace NAPI_CPP_CUSTOM_NAMESPACE;
+
+namespace NAPI_CPP_CUSTOM_NAMESPACE {
+#endif
+
+// Forward declarations
+class Env;
+class Value;
+class Boolean;
+class Number;
+#if NAPI_VERSION > 5
+class BigInt;
+#endif // NAPI_VERSION > 5
+#if (NAPI_VERSION > 4)
+class Date;
+#endif
+class String;
+class Object;
+class Array;
+class ArrayBuffer;
+class Function;
+class Error;
+class PropertyDescriptor;
+class CallbackInfo;
+class TypedArray;
+template <typename T>
+class TypedArrayOf;
+
+using Int8Array =
+ TypedArrayOf<int8_t>; ///< Typed-array of signed 8-bit integers
+using Uint8Array =
+ TypedArrayOf<uint8_t>; ///< Typed-array of unsigned 8-bit integers
+using Int16Array =
+ TypedArrayOf<int16_t>; ///< Typed-array of signed 16-bit integers
+using Uint16Array =
+ TypedArrayOf<uint16_t>; ///< Typed-array of unsigned 16-bit integers
+using Int32Array =
+ TypedArrayOf<int32_t>; ///< Typed-array of signed 32-bit integers
+using Uint32Array =
+ TypedArrayOf<uint32_t>; ///< Typed-array of unsigned 32-bit integers
+using Float32Array =
+ TypedArrayOf<float>; ///< Typed-array of 32-bit floating-point values
+using Float64Array =
+ TypedArrayOf<double>; ///< Typed-array of 64-bit floating-point values
+#if NAPI_VERSION > 5
+using BigInt64Array =
+ TypedArrayOf<int64_t>; ///< Typed array of signed 64-bit integers
+using BigUint64Array =
+ TypedArrayOf<uint64_t>; ///< Typed array of unsigned 64-bit integers
+#endif // NAPI_VERSION > 5
+
+/// Defines the signature of a Node-API C++ module's registration callback
+/// (init) function.
+using ModuleRegisterCallback = Object (*)(Env env, Object exports);
+
+class MemoryManagement;
+
+/// A simple Maybe type, representing an object which may or may not have a
+/// value.
+///
+/// If an API method returns a Maybe<>, the API method can potentially fail
+/// either because an exception is thrown, or because an exception is pending,
+/// e.g. because a previous API call threw an exception that hasn't been
+/// caught yet. In that case, a "Nothing" value is returned.
+template <class T>
+class Maybe {
+ public:
+ bool IsNothing() const;
+ bool IsJust() const;
+
+ /// Short-hand for Unwrap(), which doesn't return a value. Could be used
+ /// where the actual value of the Maybe is not needed like Object::Set.
+ /// If this Maybe is nothing (empty), node-addon-api will crash the
+ /// process.
+ void Check() const;
+
+ /// Return the value of type T contained in the Maybe. If this Maybe is
+ /// nothing (empty), node-addon-api will crash the process.
+ T Unwrap() const;
+
+ /// Return the value of type T contained in the Maybe, or using a default
+ /// value if this Maybe is nothing (empty).
+ T UnwrapOr(const T& default_value) const;
+
+ /// Converts this Maybe to a value of type T in the out. If this Maybe is
+ /// nothing (empty), `false` is returned and `out` is left untouched.
+ bool UnwrapTo(T* out) const;
+
+ bool operator==(const Maybe& other) const;
+ bool operator!=(const Maybe& other) const;
+
+ private:
+ Maybe();
+ explicit Maybe(const T& t);
+
+ bool _has_value;
+ T _value;
+
+ template <class U>
+ friend Maybe<U> Nothing();
+ template <class U>
+ friend Maybe<U> Just(const U& u);
+};
+
+template <class T>
+inline Maybe<T> Nothing();
+
+template <class T>
+inline Maybe<T> Just(const T& t);
+
+#if defined(NODE_ADDON_API_ENABLE_MAYBE)
+template <typename T>
+using MaybeOrValue = Maybe<T>;
+#else
+template <typename T>
+using MaybeOrValue = T;
+#endif
+
+#ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
+using node_addon_api_basic_env = node_api_nogc_env;
+using node_addon_api_basic_finalize = node_api_nogc_finalize;
+#else
+using node_addon_api_basic_env = napi_env;
+using node_addon_api_basic_finalize = napi_finalize;
+#endif
+
+/// Environment for Node-API values and operations.
+///
+/// All Node-API values and operations must be associated with an environment.
+/// An environment instance is always provided to callback functions; that
+/// environment must then be used for any creation of Node-API values or other
+/// Node-API operations within the callback. (Many methods infer the
+/// environment from the `this` instance that the method is called on.)
+///
+/// Multiple environments may co-exist in a single process or a thread.
+///
+/// In the V8 JavaScript engine, a Node-API environment approximately
+/// corresponds to an Isolate.
+class BasicEnv {
+ private:
+ node_addon_api_basic_env _env;
+#if NAPI_VERSION > 5
+ template <typename T>
+ static void DefaultFini(Env, T* data);
+ template <typename DataType, typename HintType>
+ static void DefaultFiniWithHint(Env, DataType* data, HintType* hint);
+#endif // NAPI_VERSION > 5
+ public:
+ BasicEnv(node_addon_api_basic_env env);
+
+ operator node_addon_api_basic_env() const;
+
+ // Without these operator overloads, the error:
+ //
+ // Use of overloaded operator '==' is ambiguous (with operand types
+ // 'Napi::Env' and 'Napi::Env')
+ //
+ // ... occurs when comparing foo.Env() == bar.Env() or foo.Env() == nullptr
+ bool operator==(const BasicEnv& other) const {
+ return _env == other._env;
+ }
+ bool operator==(std::nullptr_t /*other*/) const {
+ return _env == nullptr;
+ }
+
+#if NAPI_VERSION > 2
+ template <typename Hook, typename Arg = void>
+ class CleanupHook;
+
+ template <typename Hook>
+ CleanupHook<Hook> AddCleanupHook(Hook hook);
+
+ template <typename Hook, typename Arg>
+ CleanupHook<Hook, Arg> AddCleanupHook(Hook hook, Arg* arg);
+#endif // NAPI_VERSION > 2
+
+#if NAPI_VERSION > 5
+ template <typename T>
+ T* GetInstanceData() const;
+
+ template <typename T>
+ using Finalizer = void (*)(Env, T*);
+ template <typename T, Finalizer<T> fini = BasicEnv::DefaultFini<T>>
+ void SetInstanceData(T* data) const;
+
+ template <typename DataType, typename HintType>
+ using FinalizerWithHint = void (*)(Env, DataType*, HintType*);
+ template <typename DataType,
+ typename HintType,
+ FinalizerWithHint<DataType, HintType> fini =
+ BasicEnv::DefaultFiniWithHint<DataType, HintType>>
+ void SetInstanceData(DataType* data, HintType* hint) const;
+#endif // NAPI_VERSION > 5
+
+#if NAPI_VERSION > 2
+ template <typename Hook, typename Arg>
+ class CleanupHook {
+ public:
+ CleanupHook();
+ CleanupHook(BasicEnv env, Hook hook, Arg* arg);
+ CleanupHook(BasicEnv env, Hook hook);
+ bool Remove(BasicEnv env);
+ bool IsEmpty() const;
+
+ private:
+ static inline void Wrapper(void* data) NAPI_NOEXCEPT;
+ static inline void WrapperWithArg(void* data) NAPI_NOEXCEPT;
+
+ void (*wrapper)(void* arg);
+ struct CleanupData {
+ Hook hook;
+ Arg* arg;
+ } * data;
+ };
+#endif // NAPI_VERSION > 2
+
+#if NAPI_VERSION > 8
+ const char* GetModuleFileName() const;
+#endif // NAPI_VERSION > 8
+
+#ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
+ template <typename FinalizerType>
+ inline void PostFinalizer(FinalizerType finalizeCallback) const;
+
+ template <typename FinalizerType, typename T>
+ inline void PostFinalizer(FinalizerType finalizeCallback, T* data) const;
+
+ template <typename FinalizerType, typename T, typename Hint>
+ inline void PostFinalizer(FinalizerType finalizeCallback,
+ T* data,
+ Hint* finalizeHint) const;
+#endif // NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
+
+ friend class Env;
+};
+
+class Env : public BasicEnv {
+ public:
+ Env(napi_env env);
+
+ operator napi_env() const;
+
+ Object Global() const;
+ Value Undefined() const;
+ Value Null() const;
+
+ bool IsExceptionPending() const;
+ Error GetAndClearPendingException() const;
+
+ MaybeOrValue<Value> RunScript(const char* utf8script) const;
+ MaybeOrValue<Value> RunScript(const std::string& utf8script) const;
+ MaybeOrValue<Value> RunScript(String script) const;
+};
+
+/// A JavaScript value of unknown type.
+///
+/// For type-specific operations, convert to one of the Value subclasses using a
+/// `To*` or `As()` method. The `To*` methods do type coercion; the `As()`
+/// method does not.
+///
+/// Napi::Value value = ...
+/// if (!value.IsString()) throw Napi::TypeError::New(env, "Invalid
+/// arg..."); Napi::String str = value.As<Napi::String>(); // Cast to a
+/// string value
+///
+/// Napi::Value anotherValue = ...
+/// bool isTruthy = anotherValue.ToBoolean(); // Coerce to a boolean value
+class Value {
+ public:
+ Value(); ///< Creates a new _empty_ Value instance.
+ Value(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ /// Creates a JS value from a C++ primitive.
+ ///
+ /// `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
+ template <typename T>
+ static Value From(napi_env env, const T& value);
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ /// Converts to a Node-API value primitive.
+ ///
+ /// If the instance is _empty_, this returns `nullptr`.
+ operator napi_value() const;
+
+ /// Tests if this value strictly equals another value.
+ bool operator==(const Value& other) const;
+
+ /// Tests if this value does not strictly equal another value.
+ bool operator!=(const Value& other) const;
+
+ /// Tests if this value strictly equals another value.
+ bool StrictEquals(const Value& other) const;
+
+ /// Gets the environment the value is associated with.
+ Napi::Env Env() const;
+
+ /// Checks if the 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.
+ ///
+ /// 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 the value is
+ /// empty before attempting to use it.
+ bool IsEmpty() const;
+
+ napi_valuetype Type() const; ///< Gets the type of the value.
+
+ bool IsUndefined()
+ const; ///< Tests if a value is an undefined JavaScript value.
+ bool IsNull() const; ///< Tests if a value is a null JavaScript value.
+ bool IsBoolean() const; ///< Tests if a value is a JavaScript boolean.
+ bool IsNumber() const; ///< Tests if a value is a JavaScript number.
+#if NAPI_VERSION > 5
+ bool IsBigInt() const; ///< Tests if a value is a JavaScript bigint.
+#endif // NAPI_VERSION > 5
+#if (NAPI_VERSION > 4)
+ bool IsDate() const; ///< Tests if a value is a JavaScript date.
+#endif
+ bool IsString() const; ///< Tests if a value is a JavaScript string.
+ bool IsSymbol() const; ///< Tests if a value is a JavaScript symbol.
+ bool IsArray() const; ///< Tests if a value is a JavaScript array.
+ bool IsArrayBuffer()
+ const; ///< Tests if a value is a JavaScript array buffer.
+ bool IsTypedArray() const; ///< Tests if a value is a JavaScript typed array.
+ bool IsObject() const; ///< Tests if a value is a JavaScript object.
+ bool IsFunction() const; ///< Tests if a value is a JavaScript function.
+ bool IsPromise() const; ///< Tests if a value is a JavaScript promise.
+ bool IsDataView() const; ///< Tests if a value is a JavaScript data view.
+ bool IsBuffer() const; ///< Tests if a value is a Node buffer.
+ bool IsExternal() const; ///< Tests if a value is a pointer to external data.
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+ bool IsSharedArrayBuffer() const;
+#endif
+
+ /// Casts to another type of `Napi::Value`, when the actual type is known or
+ /// assumed.
+ ///
+ /// This conversion does NOT coerce the type. Calling any methods
+ /// inappropriate for the actual value type will throw `Napi::Error`.
+ ///
+ /// If `NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` is defined, this method
+ /// asserts that the actual type is the expected type.
+ template <typename T>
+ T As() const;
+
+ // Unsafe Value::As(), should be avoided.
+ template <typename T>
+ T UnsafeAs() const;
+
+ MaybeOrValue<Boolean> ToBoolean()
+ const; ///< Coerces a value to a JavaScript boolean.
+ MaybeOrValue<Number> ToNumber()
+ const; ///< Coerces a value to a JavaScript number.
+ MaybeOrValue<String> ToString()
+ const; ///< Coerces a value to a JavaScript string.
+ MaybeOrValue<Object> ToObject()
+ const; ///< Coerces a value to a JavaScript object.
+
+ protected:
+ /// !cond INTERNAL
+ napi_env _env;
+ napi_value _value;
+ /// !endcond
+};
+
+/// A JavaScript boolean value.
+class Boolean : public Value {
+ public:
+ static Boolean New(napi_env env, ///< Node-API environment
+ bool value ///< Boolean value
+ );
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Boolean(); ///< Creates a new _empty_ Boolean instance.
+ Boolean(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ operator bool() const; ///< Converts a Boolean value to a boolean primitive.
+ bool Value() const; ///< Converts a Boolean value to a boolean primitive.
+};
+
+/// A JavaScript number value.
+class Number : public Value {
+ public:
+ static Number New(napi_env env, ///< Node-API environment
+ double value ///< Number value
+ );
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Number(); ///< Creates a new _empty_ Number instance.
+ Number(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ operator int32_t()
+ const; ///< Converts a Number value to a 32-bit signed integer value.
+ operator uint32_t()
+ const; ///< Converts a Number value to a 32-bit unsigned integer value.
+ operator int64_t()
+ const; ///< Converts a Number value to a 64-bit signed integer value.
+ operator float()
+ const; ///< Converts a Number value to a 32-bit floating-point value.
+ operator double()
+ const; ///< Converts a Number value to a 64-bit floating-point value.
+
+ int32_t Int32Value()
+ const; ///< Converts a Number value to a 32-bit signed integer value.
+ uint32_t Uint32Value()
+ const; ///< Converts a Number value to a 32-bit unsigned integer value.
+ int64_t Int64Value()
+ const; ///< Converts a Number value to a 64-bit signed integer value.
+ float FloatValue()
+ const; ///< Converts a Number value to a 32-bit floating-point value.
+ double DoubleValue()
+ const; ///< Converts a Number value to a 64-bit floating-point value.
+};
+
+#if NAPI_VERSION > 5
+/// A JavaScript bigint value.
+class BigInt : public Value {
+ public:
+ static BigInt New(napi_env env, ///< Node-API environment
+ int64_t value ///< Number value
+ );
+ static BigInt New(napi_env env, ///< Node-API environment
+ uint64_t value ///< Number value
+ );
+
+ /// Creates a new BigInt object using a specified sign bit and a
+ /// specified list of digits/words.
+ /// The resulting number is calculated as:
+ /// (-1)^sign_bit * (words[0] * (2^64)^0 + words[1] * (2^64)^1 + ...)
+ static BigInt New(napi_env env, ///< Node-API environment
+ int sign_bit, ///< Sign bit. 1 if negative.
+ size_t word_count, ///< Number of words in array
+ const uint64_t* words ///< Array of words
+ );
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ BigInt(); ///< Creates a new _empty_ BigInt instance.
+ BigInt(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ int64_t Int64Value(bool* lossless)
+ const; ///< Converts a BigInt value to a 64-bit signed integer value.
+ uint64_t Uint64Value(bool* lossless)
+ const; ///< Converts a BigInt value to a 64-bit unsigned integer value.
+
+ size_t WordCount() const; ///< The number of 64-bit words needed to store
+ ///< the result of ToWords().
+
+ /// Writes the contents of this BigInt to a specified memory location.
+ /// `sign_bit` must be provided and will be set to 1 if this BigInt is
+ /// negative.
+ /// `*word_count` has to be initialized to the length of the `words` array.
+ /// Upon return, it will be set to the actual number of words that would
+ /// be needed to store this BigInt (i.e. the return value of `WordCount()`).
+ void ToWords(int* sign_bit, size_t* word_count, uint64_t* words);
+};
+#endif // NAPI_VERSION > 5
+
+#if (NAPI_VERSION > 4)
+/// A JavaScript date value.
+class Date : public Value {
+ public:
+ /// Creates a new Date value from a double primitive.
+ static Date New(napi_env env, ///< Node-API environment
+ double value ///< Number value
+ );
+
+ /// Creates a new Date value from a std::chrono::system_clock::time_point.
+ static Date New(
+ napi_env env, ///< Node-API environment
+ std::chrono::system_clock::time_point time_point ///< Time point value
+ );
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Date(); ///< Creates a new _empty_ Date instance.
+ Date(napi_env env, napi_value value); ///< Wraps a Node-API value primitive.
+ operator double() const; ///< Converts a Date value to double primitive
+
+ double ValueOf() const; ///< Converts a Date value to a double primitive.
+};
+#endif
+
+/// A JavaScript string or symbol value (that can be used as a property name).
+class Name : public Value {
+ public:
+ static void CheckCast(napi_env env, napi_value value);
+
+ Name(); ///< Creates a new _empty_ Name instance.
+ Name(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+};
+
+/// A JavaScript string value.
+class String : public Name {
+ public:
+ /// Creates a new String value from a UTF-8 encoded C++ string.
+ static String New(napi_env env, ///< Node-API environment
+ const std::string& value ///< UTF-8 encoded C++ string
+ );
+
+ /// Creates a new String value from a UTF-16 encoded C++ string.
+ static String New(napi_env env, ///< Node-API environment
+ const std::u16string& value ///< UTF-16 encoded C++ string
+ );
+
+ /// Creates a new String value from a UTF-8 encoded C++ string view.
+ static String New(napi_env env, ///< Node-API environment
+ std::string_view value ///< UTF-8 encoded C++ string view
+ );
+
+ /// Creates a new String value from a UTF-8 encoded C string.
+ static String New(
+ napi_env env, ///< Node-API environment
+ const char* value ///< UTF-8 encoded null-terminated C string
+ );
+
+ /// Creates a new String value from a UTF-16 encoded C string.
+ static String New(
+ napi_env env, ///< Node-API environment
+ const char16_t* value ///< UTF-16 encoded null-terminated C string
+ );
+
+ /// Creates a new String value from a UTF-8 encoded C string with specified
+ /// length.
+ static String New(napi_env env, ///< Node-API environment
+ const char* value, ///< UTF-8 encoded C string (not
+ ///< necessarily null-terminated)
+ size_t length ///< length of the string in bytes
+ );
+
+ /// Creates a new String value from a UTF-16 encoded C string with specified
+ /// length.
+ static String New(
+ napi_env env, ///< Node-API environment
+ const char16_t* value, ///< UTF-16 encoded C string (not necessarily
+ ///< null-terminated)
+ size_t length ///< Length of the string in 2-byte code units
+ );
+
+ /// Creates a new String based on the original object's type.
+ ///
+ /// `value` may be any of:
+ /// - 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
+ template <typename T>
+ static String From(napi_env env, const T& value);
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ String(); ///< Creates a new _empty_ String instance.
+ String(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ operator std::string()
+ const; ///< Converts a String value to a UTF-8 encoded C++ string.
+ operator std::u16string()
+ const; ///< Converts a String value to a UTF-16 encoded C++ string.
+ std::string Utf8Value()
+ const; ///< Converts a String value to a UTF-8 encoded C++ string.
+ std::u16string Utf16Value()
+ const; ///< Converts a String value to a UTF-16 encoded C++ string.
+};
+
+/// A JavaScript symbol value.
+class Symbol : public Name {
+ public:
+ /// Creates a new Symbol value with an optional description.
+ static Symbol New(
+ napi_env env, ///< Node-API environment
+ const char* description =
+ nullptr ///< Optional UTF-8 encoded null-terminated C string
+ /// describing the symbol
+ );
+
+ /// Creates a new Symbol value with a description.
+ static Symbol New(
+ napi_env env, ///< Node-API environment
+ const std::string&
+ description ///< UTF-8 encoded C++ string describing the symbol
+ );
+
+ /// Creates a new Symbol value with a description.
+ static Symbol New(
+ napi_env env, ///< Node-API environment
+ std::string_view
+ description ///< UTF-8 encoded C++ string view describing the symbol
+ );
+
+ /// Creates a new Symbol value with a description.
+ static Symbol New(napi_env env, ///< Node-API environment
+ String description ///< String value describing the symbol
+ );
+
+ /// Creates a new Symbol value with a description.
+ static Symbol New(
+ napi_env env, ///< Node-API environment
+ napi_value description ///< String value describing the symbol
+ );
+
+ /// Get a public Symbol (e.g. Symbol.iterator).
+ static MaybeOrValue<Symbol> WellKnown(napi_env, const std::string& name);
+
+ // Create a symbol in the global registry, UTF-8 Encoded cpp string
+ static MaybeOrValue<Symbol> For(napi_env env, const std::string& description);
+
+ // Create a symbol in the global registry, UTF-8 encoded cpp string view
+ static MaybeOrValue<Symbol> For(napi_env env, std::string_view description);
+
+ // Create a symbol in the global registry, C style string (null terminated)
+ static MaybeOrValue<Symbol> For(napi_env env, const char* description);
+
+ // Create a symbol in the global registry, String value describing the symbol
+ static MaybeOrValue<Symbol> For(napi_env env, String description);
+
+ // Create a symbol in the global registry, napi_value describing the symbol
+ static MaybeOrValue<Symbol> For(napi_env env, napi_value description);
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Symbol(); ///< Creates a new _empty_ Symbol instance.
+ Symbol(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+};
+
+class TypeTaggable : public Value {
+ public:
+#if NAPI_VERSION >= 8
+ void TypeTag(const napi_type_tag* type_tag) const;
+ bool CheckTypeTag(const napi_type_tag* type_tag) const;
+#endif // NAPI_VERSION >= 8
+ protected:
+ TypeTaggable();
+ TypeTaggable(napi_env env, napi_value value);
+};
+
+/// A JavaScript object value.
+class Object : public TypeTaggable {
+ public:
+ /// Enables property and element assignments using indexing syntax.
+ ///
+ /// This is a convenient helper to get and set object properties. As
+ /// getting and setting object properties may throw with JavaScript
+ /// exceptions, it is notable that these operations may fail.
+ /// When NODE_ADDON_API_ENABLE_MAYBE is defined, the process will abort
+ /// on JavaScript exceptions.
+ ///
+ /// Example:
+ ///
+ /// Napi::Value propertyValue = object1['A'];
+ /// object2['A'] = propertyValue;
+ /// Napi::Value elementValue = array[0];
+ /// array[1] = elementValue;
+ template <typename Key>
+ class PropertyLValue {
+ public:
+ /// Converts an L-value to a value.
+ operator Value() const;
+
+ /// Assigns a value to the property. The type of value can be
+ /// anything supported by `Object::Set`.
+ template <typename ValueType>
+ PropertyLValue& operator=(ValueType value);
+
+ /// Converts an L-value to a value. For convenience.
+ Value AsValue() const;
+
+ private:
+ PropertyLValue() = delete;
+ PropertyLValue(Object object, Key key);
+ napi_env _env;
+ napi_value _object;
+ Key _key;
+
+ friend class Napi::Object;
+ };
+
+ /// Creates a new Object value.
+ static Object New(napi_env env ///< Node-API environment
+ );
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Object(); ///< Creates a new _empty_ Object instance.
+ Object(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ /// Gets or sets a named property.
+ PropertyLValue<std::string> operator[](
+ const char* utf8name ///< UTF-8 encoded null-terminated property name
+ );
+
+ /// Gets or sets a named property.
+ PropertyLValue<std::string> operator[](
+ const std::string& utf8name ///< UTF-8 encoded property name
+ );
+
+ /// Gets or sets an indexed property or array element.
+ PropertyLValue<uint32_t> operator[](
+ uint32_t index /// Property / element index
+ );
+
+ /// Gets or sets an indexed property or array element.
+ PropertyLValue<Value> operator[](Value index /// Property / element index
+ ) const;
+
+ /// Gets a named property.
+ MaybeOrValue<Value> operator[](
+ const char* utf8name ///< UTF-8 encoded null-terminated property name
+ ) const;
+
+ /// Gets a named property.
+ MaybeOrValue<Value> operator[](
+ const std::string& utf8name ///< UTF-8 encoded property name
+ ) const;
+
+ /// Gets an indexed property or array element.
+ MaybeOrValue<Value> operator[](uint32_t index ///< Property / element index
+ ) const;
+
+ /// Checks whether a property is present.
+ MaybeOrValue<bool> Has(napi_value key ///< Property key primitive
+ ) const;
+
+ /// Checks whether a property is present.
+ MaybeOrValue<bool> Has(Value key ///< Property key
+ ) const;
+
+ /// Checks whether a named property is present.
+ MaybeOrValue<bool> Has(
+ const char* utf8name ///< UTF-8 encoded null-terminated property name
+ ) const;
+
+ /// Checks whether a named property is present.
+ MaybeOrValue<bool> Has(
+ const std::string& utf8name ///< UTF-8 encoded property name
+ ) const;
+
+ /// Checks whether a own property is present.
+ MaybeOrValue<bool> HasOwnProperty(napi_value key ///< Property key primitive
+ ) const;
+
+ /// Checks whether a own property is present.
+ MaybeOrValue<bool> HasOwnProperty(Value key ///< Property key
+ ) const;
+
+ /// Checks whether a own property is present.
+ MaybeOrValue<bool> HasOwnProperty(
+ const char* utf8name ///< UTF-8 encoded null-terminated property name
+ ) const;
+
+ /// Checks whether a own property is present.
+ MaybeOrValue<bool> HasOwnProperty(
+ const std::string& utf8name ///< UTF-8 encoded property name
+ ) const;
+
+ /// Gets a property.
+ MaybeOrValue<Value> Get(napi_value key ///< Property key primitive
+ ) const;
+
+ /// Gets a property.
+ MaybeOrValue<Value> Get(Value key ///< Property key
+ ) const;
+
+ /// Gets a named property.
+ MaybeOrValue<Value> Get(
+ const char* utf8name ///< UTF-8 encoded null-terminated property name
+ ) const;
+
+ /// Gets a named property.
+ MaybeOrValue<Value> Get(
+ const std::string& utf8name ///< UTF-8 encoded property name
+ ) const;
+
+ /// Sets a property.
+ template <typename ValueType>
+ MaybeOrValue<bool> Set(napi_value key, ///< Property key primitive
+ const ValueType& value ///< Property value primitive
+ ) const;
+
+ /// Sets a property.
+ template <typename ValueType>
+ MaybeOrValue<bool> Set(Value key, ///< Property key
+ const ValueType& value ///< Property value
+ ) const;
+
+ /// Sets a named property.
+ template <typename ValueType>
+ MaybeOrValue<bool> Set(
+ const char* utf8name, ///< UTF-8 encoded null-terminated property name
+ const ValueType& value) const;
+
+ /// Sets a named property.
+ template <typename ValueType>
+ MaybeOrValue<bool> Set(
+ const std::string& utf8name, ///< UTF-8 encoded property name
+ const ValueType& value ///< Property value primitive
+ ) const;
+
+ /// Delete property.
+ MaybeOrValue<bool> Delete(napi_value key ///< Property key primitive
+ ) const;
+
+ /// Delete property.
+ MaybeOrValue<bool> Delete(Value key ///< Property key
+ ) const;
+
+ /// Delete property.
+ MaybeOrValue<bool> Delete(
+ const char* utf8name ///< UTF-8 encoded null-terminated property name
+ ) const;
+
+ /// Delete property.
+ MaybeOrValue<bool> Delete(
+ const std::string& utf8name ///< UTF-8 encoded property name
+ ) const;
+
+ /// Checks whether an indexed property is present.
+ MaybeOrValue<bool> Has(uint32_t index ///< Property / element index
+ ) const;
+
+ /// Gets an indexed property or array element.
+ MaybeOrValue<Value> Get(uint32_t index ///< Property / element index
+ ) const;
+
+ /// Sets an indexed property or array element.
+ template <typename ValueType>
+ MaybeOrValue<bool> Set(uint32_t index, ///< Property / element index
+ const ValueType& value ///< Property value primitive
+ ) const;
+
+ /// Deletes an indexed property or array element.
+ MaybeOrValue<bool> Delete(uint32_t index ///< Property / element index
+ ) const;
+
+ /// This operation can fail in case of Proxy.[[OwnPropertyKeys]] and
+ /// Proxy.[[GetOwnProperty]] calling into JavaScript. See:
+ /// -
+ /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-ownpropertykeys
+ /// -
+ /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-getownproperty-p
+ MaybeOrValue<Array> GetPropertyNames() const; ///< Get all property names
+
+ /// Defines a property on the object.
+ ///
+ /// This operation can fail in case of Proxy.[[DefineOwnProperty]] calling
+ /// into JavaScript. See
+ /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-defineownproperty-p-desc
+ MaybeOrValue<bool> DefineProperty(
+ const PropertyDescriptor&
+ property ///< Descriptor for the property to be defined
+ ) const;
+
+ /// Defines properties on the object.
+ ///
+ /// This operation can fail in case of Proxy.[[DefineOwnProperty]] calling
+ /// into JavaScript. See
+ /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-defineownproperty-p-desc
+ MaybeOrValue<bool> DefineProperties(
+ const std::initializer_list<PropertyDescriptor>& properties
+ ///< List of descriptors for the properties to be defined
+ ) const;
+
+ /// Defines properties on the object.
+ ///
+ /// This operation can fail in case of Proxy.[[DefineOwnProperty]] calling
+ /// into JavaScript. See
+ /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-defineownproperty-p-desc
+ MaybeOrValue<bool> DefineProperties(
+ const std::vector<PropertyDescriptor>& properties
+ ///< Vector of descriptors for the properties to be defined
+ ) const;
+
+ /// Checks if an object is an instance created by a constructor function.
+ ///
+ /// This is equivalent to the JavaScript `instanceof` operator.
+ ///
+ /// This operation can fail in case of Proxy.[[GetPrototypeOf]] calling into
+ /// JavaScript.
+ /// See
+ /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-getprototypeof
+ MaybeOrValue<bool> InstanceOf(
+ const Function& constructor ///< Constructor function
+ ) const;
+
+ template <typename Finalizer, typename T>
+ inline void AddFinalizer(Finalizer finalizeCallback, T* data) const;
+
+ template <typename Finalizer, typename T, typename Hint>
+ inline void AddFinalizer(Finalizer finalizeCallback,
+ T* data,
+ Hint* finalizeHint) const;
+
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS
+ class const_iterator;
+
+ inline const_iterator begin() const;
+
+ inline const_iterator end() const;
+
+ class iterator;
+
+ inline iterator begin();
+
+ inline iterator end();
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS
+
+#if NAPI_VERSION >= 8
+ /// This operation can fail in case of Proxy.[[GetPrototypeOf]] calling into
+ /// JavaScript.
+ /// See
+ /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-getprototypeof
+ MaybeOrValue<bool> Freeze() const;
+ /// This operation can fail in case of Proxy.[[GetPrototypeOf]] calling into
+ /// JavaScript.
+ /// See
+ /// https://tc39.es/ecma262/#sec-proxy-object-internal-methods-and-internal-slots-getprototypeof
+ MaybeOrValue<bool> Seal() const;
+#endif // NAPI_VERSION >= 8
+
+ MaybeOrValue<Object> GetPrototype() const;
+
+#ifdef NODE_API_EXPERIMENTAL_HAS_SET_PROTOTYPE
+ MaybeOrValue<bool> SetPrototype(const Object& value) const;
+#endif
+};
+
+template <typename T>
+class External : public TypeTaggable {
+ public:
+ static External New(napi_env env, T* data);
+
+ // Finalizer must implement `void operator()(Env env, T* data)`.
+ template <typename Finalizer>
+ static External New(napi_env env, T* data, Finalizer finalizeCallback);
+ // Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
+ template <typename Finalizer, typename Hint>
+ static External New(napi_env env,
+ T* data,
+ Finalizer finalizeCallback,
+ Hint* finalizeHint);
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ External();
+ External(napi_env env, napi_value value);
+
+ T* Data() const;
+};
+
+class Array : public Object {
+ public:
+ static Array New(napi_env env);
+ static Array New(napi_env env, size_t length);
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Array();
+ Array(napi_env env, napi_value value);
+
+ uint32_t Length() const;
+};
+
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS
+class Object::const_iterator {
+ private:
+ enum class Type { BEGIN, END };
+
+ inline const_iterator(const Object* object, const Type type);
+
+ public:
+ inline const_iterator& operator++();
+
+ inline bool operator==(const const_iterator& other) const;
+
+ inline bool operator!=(const const_iterator& other) const;
+
+ inline const std::pair<Value, Object::PropertyLValue<Value>> operator*()
+ const;
+
+ private:
+ const Napi::Object* _object;
+ Array _keys;
+ uint32_t _index;
+
+ friend class Object;
+};
+
+class Object::iterator {
+ private:
+ enum class Type { BEGIN, END };
+
+ inline iterator(Object* object, const Type type);
+
+ public:
+ inline iterator& operator++();
+
+ inline bool operator==(const iterator& other) const;
+
+ inline bool operator!=(const iterator& other) const;
+
+ inline std::pair<Value, Object::PropertyLValue<Value>> operator*();
+
+ private:
+ Napi::Object* _object;
+ Array _keys;
+ uint32_t _index;
+
+ friend class Object;
+};
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS
+
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+class SharedArrayBuffer : public Object {
+ public:
+ SharedArrayBuffer();
+ SharedArrayBuffer(napi_env env, napi_value value);
+
+ static SharedArrayBuffer New(napi_env env, size_t byteLength);
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ void* Data();
+ size_t ByteLength();
+};
+#endif
+
+/// A JavaScript array buffer value.
+class ArrayBuffer : public Object {
+ public:
+ /// Creates a new ArrayBuffer instance over a new automatically-allocated
+ /// buffer.
+ static ArrayBuffer New(
+ napi_env env, ///< Node-API environment
+ size_t byteLength ///< Length of the buffer to be allocated, in bytes
+ );
+
+#ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
+ /// Creates a new ArrayBuffer instance, using an external buffer with
+ /// specified byte length.
+ static ArrayBuffer New(
+ napi_env env, ///< Node-API environment
+ void* externalData, ///< Pointer to the external buffer to be used by
+ ///< the array
+ size_t byteLength ///< Length of the external buffer to be used by the
+ ///< array, in bytes
+ );
+
+ /// Creates a new ArrayBuffer instance, using an external buffer with
+ /// specified byte length.
+ template <typename Finalizer>
+ static ArrayBuffer New(
+ napi_env env, ///< Node-API environment
+ void* externalData, ///< Pointer to the external buffer to be used by
+ ///< the array
+ size_t byteLength, ///< Length of the external buffer to be used by the
+ ///< array,
+ /// in bytes
+ Finalizer finalizeCallback ///< Function to be called when the array
+ ///< buffer is destroyed;
+ /// must implement `void operator()(Env env,
+ /// void* externalData)`
+ );
+
+ /// Creates a new ArrayBuffer instance, using an external buffer with
+ /// specified byte length.
+ template <typename Finalizer, typename Hint>
+ static ArrayBuffer New(
+ napi_env env, ///< Node-API environment
+ void* externalData, ///< Pointer to the external buffer to be used by
+ ///< the array
+ size_t byteLength, ///< Length of the external buffer to be used by the
+ ///< array,
+ /// in bytes
+ Finalizer finalizeCallback, ///< Function to be called when the array
+ ///< buffer is destroyed;
+ /// must implement `void operator()(Env
+ /// env, void* externalData, Hint* hint)`
+ Hint* finalizeHint ///< Hint (second parameter) to be passed to the
+ ///< finalize callback
+ );
+#endif // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ ArrayBuffer(); ///< Creates a new _empty_ ArrayBuffer instance.
+ ArrayBuffer(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ void* Data(); ///< Gets a pointer to the data buffer.
+ size_t ByteLength(); ///< Gets the length of the array buffer in bytes.
+
+#if NAPI_VERSION >= 7
+ bool IsDetached() const;
+ void Detach();
+#endif // NAPI_VERSION >= 7
+};
+
+/// A JavaScript typed-array value with unknown array type.
+///
+/// For type-specific operations, cast to a `TypedArrayOf<T>` instance using the
+/// `As()` method:
+///
+/// Napi::TypedArray array = ...
+/// if (t.TypedArrayType() == napi_int32_array) {
+/// Napi::Int32Array int32Array = t.As<Napi::Int32Array>();
+/// }
+class TypedArray : public Object {
+ public:
+ static void CheckCast(napi_env env, napi_value value);
+
+ TypedArray(); ///< Creates a new _empty_ TypedArray instance.
+ TypedArray(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ napi_typedarray_type TypedArrayType()
+ const; ///< Gets the type of this typed-array.
+
+ // Gets the backing `ArrayBuffer`.
+ //
+ // If this `TypedArray` is not backed by an `ArrayBuffer`, this method will
+ // terminate the process with a fatal error when using
+ // `NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` or exhibit undefined behavior
+ // otherwise. Use `Buffer()` instead to get the backing buffer without
+ // assuming its type.
+ Napi::ArrayBuffer ArrayBuffer() const;
+
+ // Gets the backing buffer (an `ArrayBuffer` or `SharedArrayBuffer`).
+ //
+ // Use `IsArrayBuffer()` or `IsSharedArrayBuffer()` to check the type of the
+ // backing buffer prior to casting with `As<T>()`.
+ Napi::Value Buffer() const;
+
+ uint8_t ElementSize()
+ const; ///< Gets the size in bytes of one element in the array.
+ size_t ElementLength() const; ///< Gets the number of elements in the array.
+ size_t ByteOffset()
+ const; ///< Gets the offset into the buffer where the array starts.
+ size_t ByteLength() const; ///< Gets the length of the array in bytes.
+
+ protected:
+ /// !cond INTERNAL
+ napi_typedarray_type _type;
+ size_t _length;
+
+ TypedArray(napi_env env,
+ napi_value value,
+ napi_typedarray_type type,
+ size_t length);
+
+ template <typename T>
+ static
+#if defined(NAPI_HAS_CONSTEXPR)
+ constexpr
+#endif
+ napi_typedarray_type
+ TypedArrayTypeForPrimitiveType() {
+ return std::is_same<T, int8_t>::value ? napi_int8_array
+ : std::is_same<T, uint8_t>::value ? napi_uint8_array
+ : std::is_same<T, int16_t>::value ? napi_int16_array
+ : std::is_same<T, uint16_t>::value ? napi_uint16_array
+ : std::is_same<T, int32_t>::value ? napi_int32_array
+ : std::is_same<T, uint32_t>::value ? napi_uint32_array
+ : std::is_same<T, float>::value ? napi_float32_array
+ : std::is_same<T, double>::value ? napi_float64_array
+#if NAPI_VERSION > 5
+ : std::is_same<T, int64_t>::value ? napi_bigint64_array
+ : std::is_same<T, uint64_t>::value ? napi_biguint64_array
+#endif // NAPI_VERSION > 5
+ : napi_int8_array;
+ }
+ /// !endcond
+};
+
+/// A JavaScript typed-array value with known array type.
+///
+/// Note while it is possible to create and access Uint8 "clamped" arrays using
+/// this class, the _clamping_ behavior is only applied in JavaScript.
+template <typename T>
+class TypedArrayOf : public TypedArray {
+ public:
+ /// Creates a new TypedArray instance over a new automatically-allocated array
+ /// buffer.
+ ///
+ /// The array type parameter can normally be omitted (because it is inferred
+ /// from the template parameter T), except when creating a "clamped" array:
+ ///
+ /// Uint8Array::New(env, length, napi_uint8_clamped_array)
+ static TypedArrayOf New(
+ napi_env env, ///< Node-API environment
+ size_t elementLength, ///< Length of the created array, as a number of
+ ///< elements
+#if defined(NAPI_HAS_CONSTEXPR)
+ napi_typedarray_type type =
+ TypedArray::TypedArrayTypeForPrimitiveType<T>()
+#else
+ napi_typedarray_type type
+#endif
+ ///< Type of array, if different from the default array type for the
+ ///< template parameter T.
+ );
+
+ /// Creates a new TypedArray instance over a provided array buffer.
+ ///
+ /// The array type parameter can normally be omitted (because it is inferred
+ /// from the template parameter T), except when creating a "clamped" array:
+ ///
+ /// Uint8Array::New(env, length, buffer, 0, napi_uint8_clamped_array)
+ static TypedArrayOf New(
+ napi_env env, ///< Node-API environment
+ size_t elementLength, ///< Length of the created array, as a number of
+ ///< elements
+ Napi::ArrayBuffer arrayBuffer, ///< Backing array buffer instance to use
+ size_t bufferOffset, ///< Offset into the array buffer where the
+ ///< typed-array starts
+#if defined(NAPI_HAS_CONSTEXPR)
+ napi_typedarray_type type =
+ TypedArray::TypedArrayTypeForPrimitiveType<T>()
+#else
+ napi_typedarray_type type
+#endif
+ ///< Type of array, if different from the default array type for the
+ ///< template parameter T.
+ );
+
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+ /// Creates a new TypedArray instance over a provided SharedArrayBuffer.
+ ///
+ /// The array type parameter can normally be omitted (because it is inferred
+ /// from the template parameter T), except when creating a "clamped" array:
+ ///
+ /// Uint8Array::New(env, length, buffer, 0, napi_uint8_clamped_array)
+ static TypedArrayOf New(
+ napi_env env, ///< Node-API environment
+ size_t elementLength, ///< Length of the created array, as a number of
+ ///< elements
+ Napi::SharedArrayBuffer
+ arrayBuffer, ///< Backing shared array buffer instance to use
+ size_t bufferOffset, ///< Offset into the array buffer where the
+ ///< typed-array starts
+#if defined(NAPI_HAS_CONSTEXPR)
+ napi_typedarray_type type =
+ TypedArray::TypedArrayTypeForPrimitiveType<T>()
+#else
+ napi_typedarray_type type
+#endif
+ ///< Type of array, if different from the default array type for the
+ ///< template parameter T.
+ );
+#endif
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ TypedArrayOf(); ///< Creates a new _empty_ TypedArrayOf instance.
+ TypedArrayOf(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ T& operator[](size_t index); ///< Gets or sets an element in the array.
+ const T& operator[](size_t index) const; ///< Gets an element in the array.
+
+ /// Gets a pointer to the array's backing buffer.
+ ///
+ /// This is not necessarily the same as the `ArrayBuffer::Data()` pointer,
+ /// because the typed-array may have a non-zero `ByteOffset()` into the
+ /// `ArrayBuffer`.
+ T* Data();
+
+ /// Gets a pointer to the array's backing buffer.
+ ///
+ /// This is not necessarily the same as the `ArrayBuffer::Data()` pointer,
+ /// because the typed-array may have a non-zero `ByteOffset()` into the
+ /// `ArrayBuffer`.
+ const T* Data() const;
+
+ private:
+ T* _data;
+
+ TypedArrayOf(napi_env env,
+ napi_value value,
+ napi_typedarray_type type,
+ size_t length,
+ T* data);
+};
+
+/// The DataView provides a low-level interface for reading/writing multiple
+/// number types in an ArrayBuffer irrespective of the platform's endianness.
+class DataView : public Object {
+ public:
+ static DataView New(napi_env env, Napi::ArrayBuffer arrayBuffer);
+ static DataView New(napi_env env,
+ Napi::ArrayBuffer arrayBuffer,
+ size_t byteOffset);
+ static DataView New(napi_env env,
+ Napi::ArrayBuffer arrayBuffer,
+ size_t byteOffset,
+ size_t byteLength);
+
+#ifdef NODE_API_EXPERIMENTAL_HAS_SHAREDARRAYBUFFER
+ static DataView New(napi_env env, Napi::SharedArrayBuffer arrayBuffer);
+ static DataView New(napi_env env,
+ Napi::SharedArrayBuffer arrayBuffer,
+ size_t byteOffset);
+ static DataView New(napi_env env,
+ Napi::SharedArrayBuffer arrayBuffer,
+ size_t byteOffset,
+ size_t byteLength);
+#endif
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ DataView(); ///< Creates a new _empty_ DataView instance.
+ DataView(napi_env env,
+ napi_value value); ///< Wraps a Node-API value primitive.
+
+ // Gets the backing `ArrayBuffer`.
+ //
+ // If this `DataView` is not backed by an `ArrayBuffer`, this method will
+ // terminate the process with a fatal error when using
+ // `NODE_ADDON_API_ENABLE_TYPE_CHECK_ON_AS` or exhibit undefined behavior
+ // otherwise. Use `Buffer()` instead to get the backing buffer without
+ // assuming its type.
+ Napi::ArrayBuffer ArrayBuffer() const;
+
+ // Gets the backing buffer (an `ArrayBuffer` or `SharedArrayBuffer`).
+ //
+ // Use `IsArrayBuffer()` or `IsSharedArrayBuffer()` to check the type of the
+ // backing buffer prior to casting with `As<T>()`.
+ Napi::Value Buffer() const;
+ size_t ByteOffset()
+ const; ///< Gets the offset into the buffer where the array starts.
+ size_t ByteLength() const; ///< Gets the length of the array in bytes.
+
+ void* Data() const;
+
+ float GetFloat32(size_t byteOffset) const;
+ double GetFloat64(size_t byteOffset) const;
+ int8_t GetInt8(size_t byteOffset) const;
+ int16_t GetInt16(size_t byteOffset) const;
+ int32_t GetInt32(size_t byteOffset) const;
+ uint8_t GetUint8(size_t byteOffset) const;
+ uint16_t GetUint16(size_t byteOffset) const;
+ uint32_t GetUint32(size_t byteOffset) const;
+
+ void SetFloat32(size_t byteOffset, float value) const;
+ void SetFloat64(size_t byteOffset, double value) const;
+ void SetInt8(size_t byteOffset, int8_t value) const;
+ void SetInt16(size_t byteOffset, int16_t value) const;
+ void SetInt32(size_t byteOffset, int32_t value) const;
+ void SetUint8(size_t byteOffset, uint8_t value) const;
+ void SetUint16(size_t byteOffset, uint16_t value) const;
+ void SetUint32(size_t byteOffset, uint32_t value) const;
+
+ private:
+ template <typename T>
+ T ReadData(size_t byteOffset) const;
+
+ template <typename T>
+ void WriteData(size_t byteOffset, T value) const;
+
+ void* _data{};
+ size_t _length{};
+};
+
+class Function : public Object {
+ public:
+ using VoidCallback = void (*)(const CallbackInfo& info);
+ using Callback = Value (*)(const CallbackInfo& info);
+
+ template <VoidCallback cb>
+ static Function New(napi_env env,
+ const char* utf8name = nullptr,
+ void* data = nullptr);
+
+ template <Callback cb>
+ static Function New(napi_env env,
+ const char* utf8name = nullptr,
+ void* data = nullptr);
+
+ template <VoidCallback cb>
+ static Function New(napi_env env,
+ const std::string& utf8name,
+ void* data = nullptr);
+
+ template <Callback cb>
+ static Function New(napi_env env,
+ const std::string& utf8name,
+ void* data = nullptr);
+
+ /// Callable must implement operator() accepting a const CallbackInfo&
+ /// and return either void or Value.
+ template <typename Callable>
+ static Function New(napi_env env,
+ Callable cb,
+ const char* utf8name = nullptr,
+ void* data = nullptr);
+ /// Callable must implement operator() accepting a const CallbackInfo&
+ /// and return either void or Value.
+ template <typename Callable>
+ static Function New(napi_env env,
+ Callable cb,
+ const std::string& utf8name,
+ void* data = nullptr);
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Function();
+ Function(napi_env env, napi_value value);
+
+ MaybeOrValue<Value> operator()(
+ const std::initializer_list<napi_value>& args) const;
+
+ MaybeOrValue<Value> Call(const std::initializer_list<napi_value>& args) const;
+ MaybeOrValue<Value> Call(const std::vector<napi_value>& args) const;
+ MaybeOrValue<Value> Call(const std::vector<Value>& args) const;
+ MaybeOrValue<Value> Call(size_t argc, const napi_value* args) const;
+ MaybeOrValue<Value> Call(napi_value recv,
+ const std::initializer_list<napi_value>& args) const;
+ MaybeOrValue<Value> Call(napi_value recv,
+ const std::vector<napi_value>& args) const;
+ MaybeOrValue<Value> Call(napi_value recv,
+ const std::vector<Value>& args) const;
+ MaybeOrValue<Value> Call(napi_value recv,
+ size_t argc,
+ const napi_value* args) const;
+
+ MaybeOrValue<Value> MakeCallback(
+ napi_value recv,
+ const std::initializer_list<napi_value>& args,
+ napi_async_context context = nullptr) const;
+ MaybeOrValue<Value> MakeCallback(napi_value recv,
+ const std::vector<napi_value>& args,
+ napi_async_context context = nullptr) const;
+ MaybeOrValue<Value> MakeCallback(napi_value recv,
+ size_t argc,
+ const napi_value* args,
+ napi_async_context context = nullptr) const;
+
+ MaybeOrValue<Object> New(const std::initializer_list<napi_value>& args) const;
+ MaybeOrValue<Object> New(const std::vector<napi_value>& args) const;
+ MaybeOrValue<Object> New(size_t argc, const napi_value* args) const;
+};
+
+class Promise : public Object {
+ public:
+ class Deferred {
+ public:
+ static Deferred New(napi_env env);
+ Deferred(napi_env env);
+
+ Napi::Promise Promise() const;
+ Napi::Env Env() const;
+
+ void Resolve(napi_value value) const;
+ void Reject(napi_value value) const;
+
+ private:
+ napi_env _env;
+ napi_deferred _deferred;
+ napi_value _promise;
+ };
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Promise();
+ Promise(napi_env env, napi_value value);
+
+ MaybeOrValue<Promise> Then(napi_value onFulfilled) const;
+ MaybeOrValue<Promise> Then(napi_value onFulfilled,
+ napi_value onRejected) const;
+ MaybeOrValue<Promise> Catch(napi_value onRejected) const;
+
+ MaybeOrValue<Promise> Then(const Function& onFulfilled) const;
+ MaybeOrValue<Promise> Then(const Function& onFulfilled,
+ const Function& onRejected) const;
+ MaybeOrValue<Promise> Catch(const Function& onRejected) const;
+};
+
+template <typename T>
+class Buffer : public Uint8Array {
+ public:
+ static Buffer<T> New(napi_env env, size_t length);
+#ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
+ static Buffer<T> New(napi_env env, T* data, size_t length);
+
+ // Finalizer must implement `void operator()(Env env, T* data)`.
+ template <typename Finalizer>
+ static Buffer<T> New(napi_env env,
+ T* data,
+ size_t length,
+ Finalizer finalizeCallback);
+ // Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
+ template <typename Finalizer, typename Hint>
+ static Buffer<T> New(napi_env env,
+ T* data,
+ size_t length,
+ Finalizer finalizeCallback,
+ Hint* finalizeHint);
+#endif // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
+
+ static Buffer<T> NewOrCopy(napi_env env, T* data, size_t length);
+ // Finalizer must implement `void operator()(Env env, T* data)`.
+ template <typename Finalizer>
+ static Buffer<T> NewOrCopy(napi_env env,
+ T* data,
+ size_t length,
+ Finalizer finalizeCallback);
+ // Finalizer must implement `void operator()(Env env, T* data, Hint* hint)`.
+ template <typename Finalizer, typename Hint>
+ static Buffer<T> NewOrCopy(napi_env env,
+ T* data,
+ size_t length,
+ Finalizer finalizeCallback,
+ Hint* finalizeHint);
+
+ static Buffer<T> Copy(napi_env env, const T* data, size_t length);
+
+ static void CheckCast(napi_env env, napi_value value);
+
+ Buffer();
+ Buffer(napi_env env, napi_value value);
+ size_t Length() const;
+ T* Data() const;
+
+ private:
+};
+
+/// Holds a counted reference to a value; 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.
+template <typename T>
+class Reference {
+ public:
+ static Reference<T> New(const T& value, uint32_t initialRefcount = 0);
+
+ Reference();
+ Reference(napi_env env, napi_ref ref);
+ ~Reference();
+
+ // A reference can be moved but cannot be copied.
+ Reference(Reference<T>&& other);
+ Reference<T>& operator=(Reference<T>&& other);
+ NAPI_DISALLOW_ASSIGN(Reference<T>)
+
+ operator napi_ref() const;
+ bool operator==(const Reference<T>& other) const;
+ bool operator!=(const Reference<T>& other) const;
+
+ Napi::Env Env() const;
+ bool IsEmpty() const;
+
+ // Note when getting the value of a Reference it is usually correct to do so
+ // within a HandleScope so that the value handle gets cleaned up efficiently.
+ T Value() const;
+
+ uint32_t Ref() const;
+ uint32_t Unref() const;
+ void Reset();
+ void Reset(const T& value, uint32_t refcount = 0);
+
+ // Call this on a reference that is declared as static data, to prevent its
+ // destructor from running at program shutdown time, which would attempt to
+ // reset the reference when the environment is no longer valid. Avoid using
+ // this if at all possible. If you do need to use static data, MAKE SURE to
+ // warn your users that your addon is NOT threadsafe.
+ void SuppressDestruct();
+
+ protected:
+ Reference(const Reference<T>&);
+
+ /// !cond INTERNAL
+ napi_env _env;
+ napi_ref _ref;
+ /// !endcond
+
+ private:
+ bool _suppressDestruct;
+};
+
+class ObjectReference : public Reference<Object> {
+ public:
+ ObjectReference();
+ ObjectReference(napi_env env, napi_ref ref);
+
+ // A reference can be moved but cannot be copied.
+ ObjectReference(Reference<Object>&& other);
+ ObjectReference& operator=(Reference<Object>&& other);
+ ObjectReference(ObjectReference&& other);
+ ObjectReference& operator=(ObjectReference&& other);
+ NAPI_DISALLOW_ASSIGN(ObjectReference)
+
+ MaybeOrValue<Napi::Value> Get(const char* utf8name) const;
+ MaybeOrValue<Napi::Value> Get(const std::string& utf8name) const;
+ MaybeOrValue<bool> Set(const char* utf8name, napi_value value) const;
+ MaybeOrValue<bool> Set(const char* utf8name, Napi::Value value) const;
+ MaybeOrValue<bool> Set(const char* utf8name, const char* utf8value) const;
+ MaybeOrValue<bool> Set(const char* utf8name, bool boolValue) const;
+ MaybeOrValue<bool> Set(const char* utf8name, double numberValue) const;
+ MaybeOrValue<bool> Set(const std::string& utf8name, napi_value value) const;
+ MaybeOrValue<bool> Set(const std::string& utf8name, Napi::Value value) const;
+ MaybeOrValue<bool> Set(const std::string& utf8name,
+ const std::string& utf8value) const;
+ MaybeOrValue<bool> Set(const std::string& utf8name, bool boolValue) const;
+ MaybeOrValue<bool> Set(const std::string& utf8name, double numberValue) const;
+
+ MaybeOrValue<Napi::Value> Get(uint32_t index) const;
+ MaybeOrValue<bool> Set(uint32_t index, const napi_value value) const;
+ MaybeOrValue<bool> Set(uint32_t index, const Napi::Value value) const;
+ MaybeOrValue<bool> Set(uint32_t index, const char* utf8value) const;
+ MaybeOrValue<bool> Set(uint32_t index, const std::string& utf8value) const;
+ MaybeOrValue<bool> Set(uint32_t index, bool boolValue) const;
+ MaybeOrValue<bool> Set(uint32_t index, double numberValue) const;
+
+ protected:
+ ObjectReference(const ObjectReference&);
+};
+
+class FunctionReference : public Reference<Function> {
+ public:
+ FunctionReference();
+ FunctionReference(napi_env env, napi_ref ref);
+
+ // A reference can be moved but cannot be copied.
+ FunctionReference(Reference<Function>&& other);
+ FunctionReference& operator=(Reference<Function>&& other);
+ FunctionReference(FunctionReference&& other);
+ FunctionReference& operator=(FunctionReference&& other);
+ NAPI_DISALLOW_ASSIGN_COPY(FunctionReference)
+
+ MaybeOrValue<Napi::Value> operator()(
+ const std::initializer_list<napi_value>& args) const;
+
+ MaybeOrValue<Napi::Value> Call(
+ const std::initializer_list<napi_value>& args) const;
+ MaybeOrValue<Napi::Value> Call(const std::vector<napi_value>& args) const;
+ MaybeOrValue<Napi::Value> Call(
+ napi_value recv, const std::initializer_list<napi_value>& args) const;
+ MaybeOrValue<Napi::Value> Call(napi_value recv,
+ const std::vector<napi_value>& args) const;
+ MaybeOrValue<Napi::Value> Call(napi_value recv,
+ size_t argc,
+ const napi_value* args) const;
+
+ MaybeOrValue<Napi::Value> MakeCallback(
+ napi_value recv,
+ const std::initializer_list<napi_value>& args,
+ napi_async_context context = nullptr) const;
+ MaybeOrValue<Napi::Value> MakeCallback(
+ napi_value recv,
+ const std::vector<napi_value>& args,
+ napi_async_context context = nullptr) const;
+ MaybeOrValue<Napi::Value> MakeCallback(
+ napi_value recv,
+ size_t argc,
+ const napi_value* args,
+ napi_async_context context = nullptr) const;
+
+ MaybeOrValue<Object> New(const std::initializer_list<napi_value>& args) const;
+ MaybeOrValue<Object> New(const std::vector<napi_value>& args) const;
+};
+
+// Shortcuts to creating a new reference with inferred type and refcount = 0.
+template <typename T>
+Reference<T> Weak(T value);
+ObjectReference Weak(Object value);
+FunctionReference Weak(Function value);
+
+// Shortcuts to creating a new reference with inferred type and refcount = 1.
+template <typename T>
+Reference<T> Persistent(T value);
+ObjectReference Persistent(Object value);
+FunctionReference Persistent(Function value);
+
+/// A persistent reference to a JavaScript error object. Use of this class
+/// depends somewhat on whether C++ exceptions are enabled at compile time.
+///
+/// ### Handling Errors With C++ Exceptions
+///
+/// If C++ exceptions are enabled, then the `Error` class extends
+/// `std::exception` and enables integrated error-handling for C++ exceptions
+/// and JavaScript exceptions.
+///
+/// If a Node-API call fails without executing any JavaScript code (for
+/// example due to an invalid argument), then the Node-API wrapper
+/// automatically converts and throws the error as a C++ exception of type
+/// `Napi::Error`. Or if a JavaScript function called by C++ code via Node-API
+/// throws a JavaScript exception, then the Node-API wrapper automatically
+/// converts and throws it as a C++ exception of type `Napi::Error`.
+///
+/// If a C++ exception of type `Napi::Error` escapes from a Node-API C++
+/// callback, then the Node-API wrapper automatically converts and throws it
+/// as a JavaScript exception. Therefore, catching a C++ exception of type
+/// `Napi::Error` prevents a JavaScript exception from being thrown.
+///
+/// #### Example 1A - Throwing a C++ exception:
+///
+/// Napi::Env env = ...
+/// throw Napi::Error::New(env, "Example exception");
+///
+/// Following C++ statements will not be 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 the callback returns to JavaScript.
+///
+/// #### Example 2A - Propagating a Node-API C++ exception:
+///
+/// Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
+/// Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
+///
+/// Following C++ statements will not be 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 the callback returns to JavaScript.
+///
+/// #### Example 3A - Handling a Node-API C++ exception:
+///
+/// Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
+/// Napi::Value result;
+/// try {
+/// result = jsFunctionThatThrows({ arg1, arg2 });
+/// } catch (const Napi::Error& e) {
+/// cerr << "Caught JavaScript exception: " + e.what();
+/// }
+///
+/// Since the exception was caught here, it will not be propagated as a
+/// JavaScript exception.
+///
+/// ### Handling Errors Without C++ Exceptions
+///
+/// If C++ exceptions are disabled (by defining
+/// `NODE_ADDON_API_DISABLE_CPP_EXCEPTIONS`) then this class does not extend
+/// `std::exception`, and APIs in the `Napi` namespace do not throw C++
+/// exceptions when they fail. Instead, they raise _pending_ JavaScript
+/// exceptions and return _empty_ `Value`s. Calling code should check
+/// `Value::IsEmpty()` before attempting to use a returned value, and may use
+/// methods on the `Env` class to check for, get, and clear a pending JavaScript
+/// exception. If the pending exception is not cleared, it will be thrown when
+/// the native callback returns to JavaScript.
+///
+/// #### Example 1B - Throwing a JS exception
+///
+/// Napi::Env env = ...
+/// Napi::Error::New(env, "Example
+/// exception").ThrowAsJavaScriptException(); return;
+///
+/// After throwing a JS exception, the code should generally return
+/// immediately from the native callback, after performing any necessary
+/// cleanup.
+///
+/// #### Example 2B - Propagating a Node-API JS exception:
+///
+/// Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
+/// Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
+/// if (result.IsEmpty()) return;
+///
+/// An empty value result from a Node-API call indicates an error occurred,
+/// and 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.
+///
+/// #### Example 3B - Handling a Node-API JS exception:
+///
+/// Napi::Function jsFunctionThatThrows = someObj.As<Napi::Function>();
+/// Napi::Value result = jsFunctionThatThrows({ arg1, arg2 });
+/// if (result.IsEmpty()) {
+/// Napi::Error e = env.GetAndClearPendingException();
+/// cerr << "Caught JavaScript exception: " + e.Message();
+/// }
+///
+/// Since the exception was cleared here, it will not be propagated as a
+/// JavaScript exception after the native callback returns.
+class Error : public ObjectReference
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS
+ ,
+ public std::exception
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS
+{
+ public:
+ static Error New(napi_env env);
+ static Error New(napi_env env, const char* message);
+ static Error New(napi_env env, const std::string& message);
+
+ static NAPI_NO_RETURN void Fatal(const char* location, const char* message);
+
+ Error();
+ Error(napi_env env, napi_value value);
+
+ // An error can be moved or copied.
+ Error(Error&& other);
+ Error& operator=(Error&& other);
+ Error(const Error&);
+ Error& operator=(const Error&);
+
+ const std::string& Message() const NAPI_NOEXCEPT;
+ void ThrowAsJavaScriptException() const;
+
+ Object Value() const;
+
+#ifdef NODE_ADDON_API_CPP_EXCEPTIONS
+ const char* what() const NAPI_NOEXCEPT override;
+#endif // NODE_ADDON_API_CPP_EXCEPTIONS
+
+ protected:
+ /// !cond INTERNAL
+ using create_error_fn = napi_status (*)(napi_env envb,
+ napi_value code,
+ napi_value msg,
+ napi_value* result);
+
+ template <typename TError>
+ static TError New(napi_env env,
+ const char* message,
+ size_t length,
+ create_error_fn create_error);
+ /// !endcond
+
+ private:
+ static inline const char* ERROR_WRAP_VALUE() NAPI_NOEXCEPT;
+ mutable std::string _message;
+};
+
+class TypeError : public Error {
+ public:
+ static TypeError New(napi_env env, const char* message);
+ static TypeError New(napi_env env, const std::string& message);
+
+ TypeError();
+ TypeError(napi_env env, napi_value value);
+};
+
+class RangeError : public Error {
+ public:
+ static RangeError New(napi_env env, const char* message);
+ static RangeError New(napi_env env, const std::string& message);
+
+ RangeError();
+ RangeError(napi_env env, napi_value value);
+};
+
+#if NAPI_VERSION > 8
+class SyntaxError : public Error {
+ public:
+ static SyntaxError New(napi_env env, const char* message);
+ static SyntaxError New(napi_env env, const std::string& message);
+
+ SyntaxError();
+ SyntaxError(napi_env env, napi_value value);
+};
+#endif // NAPI_VERSION > 8
+
+class CallbackInfo {
+ public:
+ CallbackInfo(napi_env env, napi_callback_info info);
+ ~CallbackInfo();
+
+ // Disallow copying to prevent multiple free of _dynamicArgs
+ NAPI_DISALLOW_ASSIGN_COPY(CallbackInfo)
+
+ Napi::Env Env() const;
+ Value NewTarget() const;
+ bool IsConstructCall() const;
+ size_t Length() const;
+ const Value operator[](size_t index) const;
+ Value This() const;
+ void* Data() const;
+ void SetData(void* data);
+ explicit operator napi_callback_info() const;
+
+ private:
+ const size_t _staticArgCount = 6;
+ napi_env _env;
+ napi_callback_info _info;
+ napi_value _this;
+ size_t _argc;
+ napi_value* _argv;
+ napi_value _staticArgs[6]{};
+ napi_value* _dynamicArgs;
+ void* _data;
+};
+
+class PropertyDescriptor {
+ public:
+ using GetterCallback = Napi::Value (*)(const Napi::CallbackInfo& info);
+ using SetterCallback = void (*)(const Napi::CallbackInfo& info);
+
+#ifndef NODE_ADDON_API_DISABLE_DEPRECATED
+ template <typename Getter>
+ static PropertyDescriptor Accessor(
+ const char* utf8name,
+ Getter getter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter>
+ static PropertyDescriptor Accessor(
+ const std::string& utf8name,
+ Getter getter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter>
+ static PropertyDescriptor Accessor(
+ napi_value name,
+ Getter getter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter>
+ static PropertyDescriptor Accessor(
+ Name name,
+ Getter getter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter, typename Setter>
+ static PropertyDescriptor Accessor(
+ const char* utf8name,
+ Getter getter,
+ Setter setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter, typename Setter>
+ static PropertyDescriptor Accessor(
+ const std::string& utf8name,
+ Getter getter,
+ Setter setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter, typename Setter>
+ static PropertyDescriptor Accessor(
+ napi_value name,
+ Getter getter,
+ Setter setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter, typename Setter>
+ static PropertyDescriptor Accessor(
+ Name name,
+ Getter getter,
+ Setter setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Callable>
+ static PropertyDescriptor Function(
+ const char* utf8name,
+ Callable cb,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Callable>
+ static PropertyDescriptor Function(
+ const std::string& utf8name,
+ Callable cb,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Callable>
+ static PropertyDescriptor Function(
+ napi_value name,
+ Callable cb,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Callable>
+ static PropertyDescriptor Function(
+ Name name,
+ Callable cb,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+#endif // !NODE_ADDON_API_DISABLE_DEPRECATED
+
+ template <GetterCallback Getter>
+ static PropertyDescriptor Accessor(
+ const char* utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+
+ template <GetterCallback Getter>
+ static PropertyDescriptor Accessor(
+ const std::string& utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+
+ template <GetterCallback Getter>
+ static PropertyDescriptor Accessor(
+ Name name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+
+ template <GetterCallback Getter, SetterCallback Setter>
+ static PropertyDescriptor Accessor(
+ const char* utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+
+ template <GetterCallback Getter, SetterCallback Setter>
+ static PropertyDescriptor Accessor(
+ const std::string& utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+
+ template <GetterCallback Getter, SetterCallback Setter>
+ static PropertyDescriptor Accessor(
+ Name name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+
+ template <typename Getter>
+ static PropertyDescriptor Accessor(
+ Napi::Env env,
+ Napi::Object object,
+ const char* utf8name,
+ Getter getter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter>
+ static PropertyDescriptor Accessor(
+ Napi::Env env,
+ Napi::Object object,
+ const std::string& utf8name,
+ Getter getter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter>
+ static PropertyDescriptor Accessor(
+ Napi::Env env,
+ Napi::Object object,
+ Name name,
+ Getter getter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter, typename Setter>
+ static PropertyDescriptor Accessor(
+ Napi::Env env,
+ Napi::Object object,
+ const char* utf8name,
+ Getter getter,
+ Setter setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter, typename Setter>
+ static PropertyDescriptor Accessor(
+ Napi::Env env,
+ Napi::Object object,
+ const std::string& utf8name,
+ Getter getter,
+ Setter setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Getter, typename Setter>
+ static PropertyDescriptor Accessor(
+ Napi::Env env,
+ Napi::Object object,
+ Name name,
+ Getter getter,
+ Setter setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Callable>
+ static PropertyDescriptor Function(
+ Napi::Env env,
+ Napi::Object object,
+ const char* utf8name,
+ Callable cb,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Callable>
+ static PropertyDescriptor Function(
+ Napi::Env env,
+ Napi::Object object,
+ const std::string& utf8name,
+ Callable cb,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <typename Callable>
+ static PropertyDescriptor Function(
+ Napi::Env env,
+ Napi::Object object,
+ Name name,
+ Callable cb,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor Value(
+ const char* utf8name,
+ napi_value value,
+ napi_property_attributes attributes = napi_default);
+ static PropertyDescriptor Value(
+ const std::string& utf8name,
+ napi_value value,
+ napi_property_attributes attributes = napi_default);
+ static PropertyDescriptor Value(
+ napi_value name,
+ napi_value value,
+ napi_property_attributes attributes = napi_default);
+ static PropertyDescriptor Value(
+ Name name,
+ Napi::Value value,
+ napi_property_attributes attributes = napi_default);
+
+ PropertyDescriptor(napi_property_descriptor desc);
+
+ operator napi_property_descriptor&();
+ operator const napi_property_descriptor&() const;
+
+ private:
+ napi_property_descriptor _desc;
+};
+
+/// Property descriptor for use with `ObjectWrap::DefineClass()`.
+///
+/// This is different from the standalone `PropertyDescriptor` because it is
+/// specific to each `ObjectWrap<T>` subclass. This prevents using descriptors
+/// from a different class when defining a new class (preventing the callbacks
+/// from having incorrect `this` pointers).
+template <typename T>
+class ClassPropertyDescriptor {
+ public:
+ ClassPropertyDescriptor(napi_property_descriptor desc) : _desc(desc) {}
+
+ operator napi_property_descriptor&() { return _desc; }
+ operator const napi_property_descriptor&() const { return _desc; }
+
+ private:
+ napi_property_descriptor _desc;
+};
+
+template <typename T, typename TCallback>
+struct MethodCallbackData {
+ TCallback callback;
+ void* data;
+};
+
+template <typename T, typename TGetterCallback, typename TSetterCallback>
+struct AccessorCallbackData {
+ TGetterCallback getterCallback;
+ TSetterCallback setterCallback;
+ void* data;
+};
+
+template <typename T>
+class InstanceWrap {
+ public:
+ using InstanceVoidMethodCallback = void (T::*)(const CallbackInfo& info);
+ using InstanceMethodCallback = Napi::Value (T::*)(const CallbackInfo& info);
+ using InstanceGetterCallback = Napi::Value (T::*)(const CallbackInfo& info);
+ using InstanceSetterCallback = void (T::*)(const CallbackInfo& info,
+ const Napi::Value& value);
+
+ using PropertyDescriptor = ClassPropertyDescriptor<T>;
+
+ static PropertyDescriptor InstanceMethod(
+ const char* utf8name,
+ InstanceVoidMethodCallback method,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor InstanceMethod(
+ const char* utf8name,
+ InstanceMethodCallback method,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor InstanceMethod(
+ Symbol name,
+ InstanceVoidMethodCallback method,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor InstanceMethod(
+ Symbol name,
+ InstanceMethodCallback method,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <InstanceVoidMethodCallback method>
+ static PropertyDescriptor InstanceMethod(
+ const char* utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <InstanceMethodCallback method>
+ static PropertyDescriptor InstanceMethod(
+ const char* utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <InstanceVoidMethodCallback method>
+ static PropertyDescriptor InstanceMethod(
+ Symbol name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <InstanceMethodCallback method>
+ static PropertyDescriptor InstanceMethod(
+ Symbol name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor InstanceAccessor(
+ const char* utf8name,
+ InstanceGetterCallback getter,
+ InstanceSetterCallback setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor InstanceAccessor(
+ Symbol name,
+ InstanceGetterCallback getter,
+ InstanceSetterCallback setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <InstanceGetterCallback getter,
+ InstanceSetterCallback setter = nullptr>
+ static PropertyDescriptor InstanceAccessor(
+ const char* utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <InstanceGetterCallback getter,
+ InstanceSetterCallback setter = nullptr>
+ static PropertyDescriptor InstanceAccessor(
+ Symbol name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor InstanceValue(
+ const char* utf8name,
+ Napi::Value value,
+ napi_property_attributes attributes = napi_default);
+ static PropertyDescriptor InstanceValue(
+ Symbol name,
+ Napi::Value value,
+ napi_property_attributes attributes = napi_default);
+
+ protected:
+ static void AttachPropData(napi_env env,
+ napi_value value,
+ const napi_property_descriptor* prop);
+
+ private:
+ using This = InstanceWrap<T>;
+
+ using InstanceVoidMethodCallbackData =
+ MethodCallbackData<T, InstanceVoidMethodCallback>;
+ using InstanceMethodCallbackData =
+ MethodCallbackData<T, InstanceMethodCallback>;
+ using InstanceAccessorCallbackData =
+ AccessorCallbackData<T, InstanceGetterCallback, InstanceSetterCallback>;
+
+ static napi_value InstanceVoidMethodCallbackWrapper(napi_env env,
+ napi_callback_info info);
+ static napi_value InstanceMethodCallbackWrapper(napi_env env,
+ napi_callback_info info);
+ static napi_value InstanceGetterCallbackWrapper(napi_env env,
+ napi_callback_info info);
+ static napi_value InstanceSetterCallbackWrapper(napi_env env,
+ napi_callback_info info);
+
+ template <InstanceSetterCallback method>
+ static napi_value WrappedMethod(napi_env env,
+ napi_callback_info info) NAPI_NOEXCEPT;
+
+ template <InstanceSetterCallback setter>
+ struct SetterTag {};
+
+ template <InstanceSetterCallback setter>
+ static napi_callback WrapSetter(SetterTag<setter>) NAPI_NOEXCEPT {
+ return &This::WrappedMethod<setter>;
+ }
+ static napi_callback WrapSetter(SetterTag<nullptr>) NAPI_NOEXCEPT {
+ return nullptr;
+ }
+};
+
+/// Base class to be extended by C++ classes exposed to JavaScript; each C++
+/// class instance gets "wrapped" by a JavaScript object that is managed by this
+/// class.
+///
+/// At initialization time, the `DefineClass()` method must be used to
+/// hook up the accessor and method callbacks. It takes a list of
+/// property descriptors, which can be constructed via the various
+/// static methods on the base class.
+///
+/// #### Example:
+///
+/// class Example: public Napi::ObjectWrap<Example> {
+/// public:
+/// static void Initialize(Napi::Env& env, Napi::Object& target) {
+/// Napi::Function constructor = DefineClass(env, "Example", {
+/// InstanceAccessor<&Example::GetSomething,
+/// &Example::SetSomething>("value"),
+/// InstanceMethod<&Example::DoSomething>("doSomething"),
+/// });
+/// target.Set("Example", constructor);
+/// }
+///
+/// Example(const Napi::CallbackInfo& info); // Constructor
+/// Napi::Value GetSomething(const Napi::CallbackInfo& info);
+/// void SetSomething(const Napi::CallbackInfo& info, const Napi::Value&
+/// value); Napi::Value DoSomething(const Napi::CallbackInfo& info);
+/// }
+template <typename T>
+class ObjectWrap : public InstanceWrap<T>, public Reference<Object> {
+ public:
+ ObjectWrap(const CallbackInfo& callbackInfo);
+ virtual ~ObjectWrap();
+
+ static T* Unwrap(Object wrapper);
+
+ // Methods exposed to JavaScript must conform to one of these callback
+ // signatures.
+ using StaticVoidMethodCallback = void (*)(const CallbackInfo& info);
+ using StaticMethodCallback = Napi::Value (*)(const CallbackInfo& info);
+ using StaticGetterCallback = Napi::Value (*)(const CallbackInfo& info);
+ using StaticSetterCallback = void (*)(const CallbackInfo& info,
+ const Napi::Value& value);
+
+ using PropertyDescriptor = ClassPropertyDescriptor<T>;
+
+ static Function DefineClass(
+ Napi::Env env,
+ const char* utf8name,
+ const std::initializer_list<PropertyDescriptor>& properties,
+ void* data = nullptr);
+ static Function DefineClass(Napi::Env env,
+ const char* utf8name,
+ const std::vector<PropertyDescriptor>& properties,
+ void* data = nullptr);
+ static PropertyDescriptor StaticMethod(
+ const char* utf8name,
+ StaticVoidMethodCallback method,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor StaticMethod(
+ const char* utf8name,
+ StaticMethodCallback method,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor StaticMethod(
+ Symbol name,
+ StaticVoidMethodCallback method,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor StaticMethod(
+ Symbol name,
+ StaticMethodCallback method,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <StaticVoidMethodCallback method>
+ static PropertyDescriptor StaticMethod(
+ const char* utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <StaticVoidMethodCallback method>
+ static PropertyDescriptor StaticMethod(
+ Symbol name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <StaticMethodCallback method>
+ static PropertyDescriptor StaticMethod(
+ const char* utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <StaticMethodCallback method>
+ static PropertyDescriptor StaticMethod(
+ Symbol name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor StaticAccessor(
+ const char* utf8name,
+ StaticGetterCallback getter,
+ StaticSetterCallback setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor StaticAccessor(
+ Symbol name,
+ StaticGetterCallback getter,
+ StaticSetterCallback setter,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <StaticGetterCallback getter, StaticSetterCallback setter = nullptr>
+ static PropertyDescriptor StaticAccessor(
+ const char* utf8name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ template <StaticGetterCallback getter, StaticSetterCallback setter = nullptr>
+ static PropertyDescriptor StaticAccessor(
+ Symbol name,
+ napi_property_attributes attributes = napi_default,
+ void* data = nullptr);
+ static PropertyDescriptor StaticValue(
+ const char* utf8name,
+ Napi::Value value,
+ napi_property_attributes attributes = napi_default);
+ static PropertyDescriptor StaticValue(
+ Symbol name,
+ Napi::Value value,
+ napi_property_attributes attributes = napi_default);
+ static Napi::Value OnCalledAsFunction(const Napi::CallbackInfo& callbackInfo);
+ virtual void Finalize(Napi::Env env);
+ virtual void Finalize(BasicEnv env);
+
+ private:
+ using This = ObjectWrap<T>;
+
+ static napi_value ConstructorCallbackWrapper(napi_env env,
+ napi_callback_info info);
+ static napi_value StaticVoidMethodCallbackWrapper(napi_env env,
+ napi_callback_info info);
+ static napi_value StaticMethodCallbackWrapper(napi_env env,
+ napi_callback_info info);
+ static napi_value StaticGetterCallbackWrapper(napi_env env,
+ napi_callback_info info);
+ static napi_value StaticSetterCallbackWrapper(napi_env env,
+ napi_callback_info info);
+ static void FinalizeCallback(node_addon_api_basic_env env,
+ void* data,
+ void* hint);
+
+ static void PostFinalizeCallback(napi_env env, void* data, void* hint);
+
+ static Function DefineClass(Napi::Env env,
+ const char* utf8name,
+ const size_t props_count,
+ const napi_property_descriptor* props,
+ void* data = nullptr);
+
+ using StaticVoidMethodCallbackData =
+ MethodCallbackData<T, StaticVoidMethodCallback>;
+ using StaticMethodCallbackData = MethodCallbackData<T, StaticMethodCallback>;
+
+ using StaticAccessorCallbackData =
+ AccessorCallbackData<T, StaticGetterCallback, StaticSetterCallback>;
+
+ template <StaticSetterCallback method>
+ static napi_value WrappedMethod(napi_env env,
+ napi_callback_info info) NAPI_NOEXCEPT;
+
+ template <StaticSetterCallback setter>
+ struct StaticSetterTag {};
+
+ template <StaticSetterCallback setter>
+ static napi_callback WrapStaticSetter(StaticSetterTag<setter>) NAPI_NOEXCEPT {
+ return &This::WrappedMethod<setter>;
+ }
+ static napi_callback WrapStaticSetter(StaticSetterTag<nullptr>)
+ NAPI_NOEXCEPT {
+ return nullptr;
+ }
+
+ bool _construction_failed = true;
+ bool _finalized = false;
+};
+
+class HandleScope {
+ public:
+ HandleScope(napi_env env, napi_handle_scope scope);
+ explicit HandleScope(Napi::Env env);
+ ~HandleScope();
+
+ // Disallow copying to prevent double close of napi_handle_scope
+ NAPI_DISALLOW_ASSIGN_COPY(HandleScope)
+
+ operator napi_handle_scope() const;
+
+ Napi::Env Env() const;
+
+ private:
+ napi_env _env;
+ napi_handle_scope _scope;
+};
+
+class EscapableHandleScope {
+ public:
+ EscapableHandleScope(napi_env env, napi_escapable_handle_scope scope);
+ explicit EscapableHandleScope(Napi::Env env);
+ ~EscapableHandleScope();
+
+ // Disallow copying to prevent double close of napi_escapable_handle_scope
+ NAPI_DISALLOW_ASSIGN_COPY(EscapableHandleScope)
+
+ operator napi_escapable_handle_scope() const;
+
+ Napi::Env Env() const;
+ Value Escape(napi_value escapee);
+
+ private:
+ napi_env _env;
+ napi_escapable_handle_scope _scope;
+};
+
+#if (NAPI_VERSION > 2)
+class CallbackScope {
+ public:
+ CallbackScope(napi_env env, napi_callback_scope scope);
+ CallbackScope(napi_env env, napi_async_context context);
+ virtual ~CallbackScope();
+
+ // Disallow copying to prevent double close of napi_callback_scope
+ NAPI_DISALLOW_ASSIGN_COPY(CallbackScope)
+
+ operator napi_callback_scope() const;
+
+ Napi::Env Env() const;
+
+ private:
+ napi_env _env;
+ napi_callback_scope _scope;
+};
+#endif
+
+class AsyncContext {
+ public:
+ explicit AsyncContext(napi_env env, const char* resource_name);
+ explicit AsyncContext(napi_env env,
+ const char* resource_name,
+ const Object& resource);
+ virtual ~AsyncContext();
+
+ AsyncContext(AsyncContext&& other);
+ AsyncContext& operator=(AsyncContext&& other);
+ NAPI_DISALLOW_ASSIGN_COPY(AsyncContext)
+
+ operator napi_async_context() const;
+
+ Napi::Env Env() const;
+
+ private:
+ napi_env _env;
+ napi_async_context _context;
+};
+
+#if NAPI_HAS_THREADS
+class AsyncWorker {
+ public:
+ virtual ~AsyncWorker();
+
+ NAPI_DISALLOW_ASSIGN_COPY(AsyncWorker)
+
+ operator napi_async_work() const;
+
+ Napi::Env Env() const;
+
+ void Queue();
+ void Cancel();
+ void SuppressDestruct();
+
+ ObjectReference& Receiver();
+ FunctionReference& Callback();
+
+ virtual void OnExecute(Napi::Env env);
+ virtual void OnWorkComplete(Napi::Env env, napi_status status);
+
+ protected:
+ explicit AsyncWorker(const Function& callback);
+ explicit AsyncWorker(const Function& callback, const char* resource_name);
+ explicit AsyncWorker(const Function& callback,
+ const char* resource_name,
+ const Object& resource);
+ explicit AsyncWorker(const Object& receiver, const Function& callback);
+ explicit AsyncWorker(const Object& receiver,
+ const Function& callback,
+ const char* resource_name);
+ explicit AsyncWorker(const Object& receiver,
+ const Function& callback,
+ const char* resource_name,
+ const Object& resource);
+
+ explicit AsyncWorker(Napi::Env env);
+ explicit AsyncWorker(Napi::Env env, const char* resource_name);
+ explicit AsyncWorker(Napi::Env env,
+ const char* resource_name,
+ const Object& resource);
+
+ virtual void Execute() = 0;
+ virtual void OnOK();
+ virtual void OnError(const Error& e);
+ virtual void Destroy();
+ virtual std::vector<napi_value> GetResult(Napi::Env env);
+
+ void SetError(const std::string& error);
+
+ private:
+ static inline void OnAsyncWorkExecute(napi_env env, void* asyncworker);
+ static inline void OnAsyncWorkComplete(napi_env env,
+ napi_status status,
+ void* asyncworker);
+
+ napi_env _env;
+ napi_async_work _work;
+ ObjectReference _receiver;
+ FunctionReference _callback;
+ std::string _error;
+ bool _suppress_destruct;
+};
+#endif // NAPI_HAS_THREADS
+
+#if (NAPI_VERSION > 3 && NAPI_HAS_THREADS)
+class ThreadSafeFunction {
+ public:
+ // This API may only be called from the main thread.
+ template <typename ResourceString>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString, typename ContextType>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString, typename Finalizer>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ Finalizer finalizeCallback);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString,
+ typename Finalizer,
+ typename FinalizerDataType>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString, typename ContextType, typename Finalizer>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString,
+ typename ContextType,
+ typename Finalizer,
+ typename FinalizerDataType>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString, typename ContextType>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString, typename Finalizer>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ Finalizer finalizeCallback);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString,
+ typename Finalizer,
+ typename FinalizerDataType>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString, typename ContextType, typename Finalizer>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback);
+
+ // This API may only be called from the main thread.
+ template <typename ResourceString,
+ typename ContextType,
+ typename Finalizer,
+ typename FinalizerDataType>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data);
+
+ ThreadSafeFunction();
+ ThreadSafeFunction(napi_threadsafe_function tsFunctionValue);
+
+ operator napi_threadsafe_function() const;
+
+ // This API may be called from any thread.
+ napi_status BlockingCall() const;
+
+ // This API may be called from any thread.
+ template <typename Callback>
+ napi_status BlockingCall(Callback callback) const;
+
+ // This API may be called from any thread.
+ template <typename DataType, typename Callback>
+ napi_status BlockingCall(DataType* data, Callback callback) const;
+
+ // This API may be called from any thread.
+ napi_status NonBlockingCall() const;
+
+ // This API may be called from any thread.
+ template <typename Callback>
+ napi_status NonBlockingCall(Callback callback) const;
+
+ // This API may be called from any thread.
+ template <typename DataType, typename Callback>
+ napi_status NonBlockingCall(DataType* data, Callback callback) const;
+
+ // This API may only be called from the main thread.
+ void Ref(napi_env env) const;
+
+ // This API may only be called from the main thread.
+ void Unref(napi_env env) const;
+
+ // This API may be called from any thread.
+ napi_status Acquire() const;
+
+ // This API may be called from any thread.
+ napi_status Release() const;
+
+ // This API may be called from any thread.
+ napi_status Abort() const;
+
+ struct ConvertibleContext {
+ template <class T>
+ operator T*() {
+ return static_cast<T*>(context);
+ }
+ void* context;
+ };
+
+ // This API may be called from any thread.
+ ConvertibleContext GetContext() const;
+
+ private:
+ using CallbackWrapper = std::function<void(Napi::Env, Napi::Function)>;
+
+ template <typename ResourceString,
+ typename ContextType,
+ typename Finalizer,
+ typename FinalizerDataType>
+ static ThreadSafeFunction New(napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data,
+ napi_finalize wrapper);
+
+ napi_status CallInternal(CallbackWrapper* callbackWrapper,
+ napi_threadsafe_function_call_mode mode) const;
+
+ static void CallJS(napi_env env,
+ napi_value jsCallback,
+ void* context,
+ void* data);
+
+ napi_threadsafe_function _tsfn;
+};
+
+// A TypedThreadSafeFunction by default has no context (nullptr) and can
+// accept any type (void) to its CallJs.
+template <typename ContextType = std::nullptr_t,
+ typename DataType = void,
+ void (*CallJs)(Napi::Env, Napi::Function, ContextType*, DataType*) =
+ nullptr>
+class TypedThreadSafeFunction {
+ public:
+ // This API may only be called from the main thread.
+ // Helper function that returns nullptr if running Node-API 5+, otherwise a
+ // non-empty, no-op Function. This provides the ability to specify at
+ // compile-time a callback parameter to `New` that safely does no action
+ // when targeting _any_ Node-API version.
+#if NAPI_VERSION > 4
+ static std::nullptr_t EmptyFunctionFactory(Napi::Env env);
+#else
+ static Napi::Function EmptyFunctionFactory(Napi::Env env);
+#endif
+ static Napi::Function FunctionOrEmpty(Napi::Env env,
+ Napi::Function& callback);
+
+#if NAPI_VERSION > 4
+ // This API may only be called from the main thread.
+ // Creates a new threadsafe function with:
+ // Callback [missing] Resource [missing] Finalizer [missing]
+ template <typename ResourceString>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context = nullptr);
+
+ // This API may only be called from the main thread.
+ // Creates a new threadsafe function with:
+ // Callback [missing] Resource [passed] Finalizer [missing]
+ template <typename ResourceString>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context = nullptr);
+
+ // This API may only be called from the main thread.
+ // Creates a new threadsafe function with:
+ // Callback [missing] Resource [missing] Finalizer [passed]
+ template <typename ResourceString,
+ typename Finalizer,
+ typename FinalizerDataType = void>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data = nullptr);
+
+ // This API may only be called from the main thread.
+ // Creates a new threadsafe function with:
+ // Callback [missing] Resource [passed] Finalizer [passed]
+ template <typename ResourceString,
+ typename Finalizer,
+ typename FinalizerDataType = void>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data = nullptr);
+#endif
+
+ // This API may only be called from the main thread.
+ // Creates a new threadsafe function with:
+ // Callback [passed] Resource [missing] Finalizer [missing]
+ template <typename ResourceString>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ const Function& callback,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context = nullptr);
+
+ // This API may only be called from the main thread.
+ // Creates a new threadsafe function with:
+ // Callback [passed] Resource [passed] Finalizer [missing]
+ template <typename ResourceString>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context = nullptr);
+
+ // This API may only be called from the main thread.
+ // Creates a new threadsafe function with:
+ // Callback [passed] Resource [missing] Finalizer [passed]
+ template <typename ResourceString,
+ typename Finalizer,
+ typename FinalizerDataType = void>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ const Function& callback,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data = nullptr);
+
+ // This API may only be called from the main thread.
+ // Creates a new threadsafe function with:
+ // Callback [passed] Resource [passed] Finalizer [passed]
+ template <typename CallbackType,
+ typename ResourceString,
+ typename Finalizer,
+ typename FinalizerDataType>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ CallbackType callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data = nullptr);
+
+ TypedThreadSafeFunction();
+ TypedThreadSafeFunction(napi_threadsafe_function tsFunctionValue);
+
+ operator napi_threadsafe_function() const;
+
+ // This API may be called from any thread.
+ napi_status BlockingCall(DataType* data = nullptr) const;
+
+ // This API may be called from any thread.
+ napi_status NonBlockingCall(DataType* data = nullptr) const;
+
+ // This API may only be called from the main thread.
+ void Ref(napi_env env) const;
+
+ // This API may only be called from the main thread.
+ void Unref(napi_env env) const;
+
+ // This API may be called from any thread.
+ napi_status Acquire() const;
+
+ // This API may be called from any thread.
+ napi_status Release() const;
+
+ // This API may be called from any thread.
+ napi_status Abort() const;
+
+ // This API may be called from any thread.
+ ContextType* GetContext() const;
+
+ private:
+ template <typename ResourceString,
+ typename Finalizer,
+ typename FinalizerDataType>
+ static TypedThreadSafeFunction<ContextType, DataType, CallJs> New(
+ napi_env env,
+ const Function& callback,
+ const Object& resource,
+ ResourceString resourceName,
+ size_t maxQueueSize,
+ size_t initialThreadCount,
+ ContextType* context,
+ Finalizer finalizeCallback,
+ FinalizerDataType* data,
+ napi_finalize wrapper);
+
+ static void CallJsInternal(napi_env env,
+ napi_value jsCallback,
+ void* context,
+ void* data);
+
+ protected:
+ napi_threadsafe_function _tsfn;
+};
+template <typename DataType>
+class AsyncProgressWorkerBase : public AsyncWorker {
+ public:
+ virtual void OnWorkProgress(DataType* data) = 0;
+ class ThreadSafeData {
+ public:
+ ThreadSafeData(AsyncProgressWorkerBase* asyncprogressworker, DataType* data)
+ : _asyncprogressworker(asyncprogressworker), _data(data) {}
+
+ AsyncProgressWorkerBase* asyncprogressworker() {
+ return _asyncprogressworker;
+ }
+ DataType* data() { return _data; }
+
+ private:
+ AsyncProgressWorkerBase* _asyncprogressworker;
+ DataType* _data;
+ };
+ void OnWorkComplete(Napi::Env env, napi_status status) override;
+
+ protected:
+ explicit AsyncProgressWorkerBase(const Object& receiver,
+ const Function& callback,
+ const char* resource_name,
+ const Object& resource,
+ size_t queue_size = 1);
+ virtual ~AsyncProgressWorkerBase();
+
+// Optional callback of Napi::ThreadSafeFunction only available after
+// NAPI_VERSION 4. Refs: https://github.com/nodejs/node/pull/27791
+#if NAPI_VERSION > 4
+ explicit AsyncProgressWorkerBase(Napi::Env env,
+ const char* resource_name,
+ const Object& resource,
+ size_t queue_size = 1);
+#endif
+
+ static inline void OnAsyncWorkProgress(Napi::Env env,
+ Napi::Function jsCallback,
+ void* data);
+
+ napi_status NonBlockingCall(DataType* data);
+
+ private:
+ ThreadSafeFunction _tsfn;
+ bool _work_completed = false;
+ napi_status _complete_status;
+ static inline void OnThreadSafeFunctionFinalize(
+ Napi::Env env, void* data, AsyncProgressWorkerBase* context);
+};
+
+template <class T>
+class AsyncProgressWorker : public AsyncProgressWorkerBase<void> {
+ public:
+ virtual ~AsyncProgressWorker();
+
+ class ExecutionProgress {
+ friend class AsyncProgressWorker;
+
+ public:
+ void Signal() const;
+ void Send(const T* data, size_t count) const;
+
+ private:
+ explicit ExecutionProgress(AsyncProgressWorker* worker) : _worker(worker) {}
+ AsyncProgressWorker* const _worker;
+ };
+
+ void OnWorkProgress(void*) override;
+
+ protected:
+ explicit AsyncProgressWorker(const Function& callback);
+ explicit AsyncProgressWorker(const Function& callback,
+ const char* resource_name);
+ explicit AsyncProgressWorker(const Function& callback,
+ const char* resource_name,
+ const Object& resource);
+ explicit AsyncProgressWorker(const Object& receiver,
+ const Function& callback);
+ explicit AsyncProgressWorker(const Object& receiver,
+ const Function& callback,
+ const char* resource_name);
+ explicit AsyncProgressWorker(const Object& receiver,
+ const Function& callback,
+ const char* resource_name,
+ const Object& resource);
+
+// Optional callback of Napi::ThreadSafeFunction only available after
+// NAPI_VERSION 4. Refs: https://github.com/nodejs/node/pull/27791
+#if NAPI_VERSION > 4
+ explicit AsyncProgressWorker(Napi::Env env);
+ explicit AsyncProgressWorker(Napi::Env env, const char* resource_name);
+ explicit AsyncProgressWorker(Napi::Env env,
+ const char* resource_name,
+ const Object& resource);
+#endif
+ virtual void Execute(const ExecutionProgress& progress) = 0;
+ virtual void OnProgress(const T* data, size_t count) = 0;
+
+ private:
+ void Execute() override;
+ void Signal();
+ void SendProgress_(const T* data, size_t count);
+
+ std::mutex _mutex;
+ T* _asyncdata;
+ size_t _asyncsize;
+ bool _signaled;
+};
+
+template <class T>
+class AsyncProgressQueueWorker
+ : public AsyncProgressWorkerBase<std::pair<T*, size_t>> {
+ public:
+ virtual ~AsyncProgressQueueWorker(){};
+
+ class ExecutionProgress {
+ friend class AsyncProgressQueueWorker;
+
+ public:
+ void Signal() const;
+ void Send(const T* data, size_t count) const;
+
+ private:
+ explicit ExecutionProgress(AsyncProgressQueueWorker* worker)
+ : _worker(worker) {}
+ AsyncProgressQueueWorker* const _worker;
+ };
+
+ void OnWorkComplete(Napi::Env env, napi_status status) override;
+ void OnWorkProgress(std::pair<T*, size_t>*) override;
+
+ protected:
+ explicit AsyncProgressQueueWorker(const Function& callback);
+ explicit AsyncProgressQueueWorker(const Function& callback,
+ const char* resource_name);
+ explicit AsyncProgressQueueWorker(const Function& callback,
+ const char* resource_name,
+ const Object& resource);
+ explicit AsyncProgressQueueWorker(const Object& receiver,
+ const Function& callback);
+ explicit AsyncProgressQueueWorker(const Object& receiver,
+ const Function& callback,
+ const char* resource_name);
+ explicit AsyncProgressQueueWorker(const Object& receiver,
+ const Function& callback,
+ const char* resource_name,
+ const Object& resource);
+
+// Optional callback of Napi::ThreadSafeFunction only available after
+// NAPI_VERSION 4. Refs: https://github.com/nodejs/node/pull/27791
+#if NAPI_VERSION > 4
+ explicit AsyncProgressQueueWorker(Napi::Env env);
+ explicit AsyncProgressQueueWorker(Napi::Env env, const char* resource_name);
+ explicit AsyncProgressQueueWorker(Napi::Env env,
+ const char* resource_name,
+ const Object& resource);
+#endif
+ virtual void Execute(const ExecutionProgress& progress) = 0;
+ virtual void OnProgress(const T* data, size_t count) = 0;
+
+ private:
+ void Execute() override;
+ void Signal() const;
+ void SendProgress_(const T* data, size_t count);
+};
+#endif // NAPI_VERSION > 3 && NAPI_HAS_THREADS
+
+// Memory management.
+class MemoryManagement {
+ public:
+ static int64_t AdjustExternalMemory(BasicEnv env, int64_t change_in_bytes);
+};
+
+// Version management
+class VersionManagement {
+ public:
+ static uint32_t GetNapiVersion(BasicEnv env);
+ static const napi_node_version* GetNodeVersion(BasicEnv env);
+};
+
+#if NAPI_VERSION > 5
+template <typename T>
+class Addon : public InstanceWrap<T> {
+ public:
+ static inline Object Init(Env env, Object exports);
+ static T* Unwrap(Object wrapper);
+
+ protected:
+ using AddonProp = ClassPropertyDescriptor<T>;
+ void DefineAddon(Object exports,
+ const std::initializer_list<AddonProp>& props);
+ Napi::Object DefineProperties(Object object,
+ const std::initializer_list<AddonProp>& props);
+
+ private:
+ Object entry_point_;
+};
+#endif // NAPI_VERSION > 5
+
+#ifdef NAPI_CPP_CUSTOM_NAMESPACE
+} // namespace NAPI_CPP_CUSTOM_NAMESPACE
+#endif
+
+} // namespace Napi
+
+// Inline implementations of all the above class methods are included here.
+#include "napi-inl.h"
+
+#endif // SRC_NAPI_H_