node-addon-api 8.2.0 → 8.2.2

package/README.md

@@ -19,7 +19,7 @@ and exception handling semantics with low overhead.
 API references are available in the [doc](doc/README.md) directory.
 
 <!-- x-release-please-start-version -->
-## Current version: 8.2.0
+## Current version: 8.2.2
 <!-- x-release-please-end -->
 
 (See [CHANGELOG.md](CHANGELOG.md) for complete Changelog)

package/napi-inl.h

@@ -35,7 +35,7 @@ namespace details {
 constexpr int napi_no_external_buffers_allowed = 22;
 
 template <typename FreeType>
-inline void default_basic_finalizer(node_api_nogc_env /*env*/,
+inline void default_basic_finalizer(node_addon_api_basic_env /*env*/,
                                     void* data,
                                     void* /*hint*/) {
   delete static_cast<FreeType*>(data);
@@ -45,8 +45,9 @@ inline void default_basic_finalizer(node_api_nogc_env /*env*/,
 // garbage-collected.
 // TODO: Replace this code with `napi_add_finalizer()` whenever it becomes
 // available on all supported versions of Node.js.
-template <typename FreeType,
-          node_api_nogc_finalize finalizer = default_basic_finalizer<FreeType>>
+template <
+    typename FreeType,
+    node_addon_api_basic_finalize finalizer = default_basic_finalizer<FreeType>>
 inline napi_status AttachData(napi_env env,
                               napi_value obj,
                               FreeType* data,
@@ -192,10 +193,10 @@ template <typename T, typename Finalizer, typename Hint = void>
 struct FinalizeData {
 #ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
   template <typename F = Finalizer,
-            typename =
-                std::enable_if_t<std::is_invocable_v<F, node_api_nogc_env, T*>>>
+            typename = std::enable_if_t<
+                std::is_invocable_v<F, node_addon_api_basic_env, T*>>>
 #endif
-  static inline void Wrapper(node_api_nogc_env env,
+  static inline void Wrapper(node_addon_api_basic_env env,
                              void* data,
                              void* finalizeHint) NAPI_NOEXCEPT {
     WrapVoidCallback([&] {
@@ -208,9 +209,9 @@ struct FinalizeData {
 #ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
   template <typename F = Finalizer,
             typename = std::enable_if_t<
-                !std::is_invocable_v<F, node_api_nogc_env, T*>>,
+                !std::is_invocable_v<F, node_addon_api_basic_env, T*>>,
             typename = void>
-  static inline void Wrapper(node_api_nogc_env env,
+  static inline void Wrapper(node_addon_api_basic_env env,
                              void* data,
                              void* finalizeHint) NAPI_NOEXCEPT {
 #ifdef NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS
@@ -228,9 +229,9 @@ struct FinalizeData {
 #ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
   template <typename F = Finalizer,
             typename = std::enable_if_t<
-                std::is_invocable_v<F, node_api_nogc_env, T*, Hint*>>>
+                std::is_invocable_v<F, node_addon_api_basic_env, T*, Hint*>>>
 #endif
-  static inline void WrapperWithHint(node_api_nogc_env env,
+  static inline void WrapperWithHint(node_addon_api_basic_env env,
                                      void* data,
                                      void* finalizeHint) NAPI_NOEXCEPT {
     WrapVoidCallback([&] {
@@ -243,9 +244,9 @@ struct FinalizeData {
 #ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
   template <typename F = Finalizer,
             typename = std::enable_if_t<
-                !std::is_invocable_v<F, node_api_nogc_env, T*, Hint*>>,
+                !std::is_invocable_v<F, node_addon_api_basic_env, T*, Hint*>>,
             typename = void>
-  static inline void WrapperWithHint(node_api_nogc_env env,
+  static inline void WrapperWithHint(node_addon_api_basic_env env,
                                      void* data,
                                      void* finalizeHint) NAPI_NOEXCEPT {
 #ifdef NODE_ADDON_API_REQUIRE_BASIC_FINALIZERS
@@ -576,9 +577,9 @@ inline Maybe<T> Just(const T& t) {
 // BasicEnv / Env class
 ////////////////////////////////////////////////////////////////////////////////
 
-inline BasicEnv::BasicEnv(node_api_nogc_env env) : _env(env) {}
+inline BasicEnv::BasicEnv(node_addon_api_basic_env env) : _env(env) {}
 
-inline BasicEnv::operator node_api_nogc_env() const {
+inline BasicEnv::operator node_addon_api_basic_env() const {
   return _env;
 }
 
@@ -896,6 +897,16 @@ inline T Value::As() const {
   return T(_env, _value);
 }
 
+template <typename T>
+inline T Value::UnsafeAs() const {
+  return T(_env, _value);
+}
+
+// static
+inline void Value::CheckCast(napi_env /* env */, napi_value value) {
+  NAPI_CHECK(value != nullptr, "Value::CheckCast", "empty value");
+}
+
 inline MaybeOrValue<Boolean> Value::ToBoolean() const {
   napi_value result;
   napi_status status = napi_coerce_to_bool(_env, _value, &result);
@@ -1303,12 +1314,15 @@ inline Symbol Symbol::New(napi_env env, napi_value description) {
 
 inline MaybeOrValue<Symbol> Symbol::WellKnown(napi_env env,
                                               const std::string& name) {
+  // No need to check if the return value is a symbol or undefined.
+  // Well known symbols are definite and it is an develop time error
+  // if the symbol does not exist.
 #if defined(NODE_ADDON_API_ENABLE_MAYBE)
   Value symbol_obj;
   Value symbol_value;
   if (Napi::Env(env).Global().Get("Symbol").UnwrapTo(&symbol_obj) &&
       symbol_obj.As<Object>().Get(name).UnwrapTo(&symbol_value)) {
-    return Just<Symbol>(symbol_value.As<Symbol>());
+    return Just<Symbol>(symbol_value.UnsafeAs<Symbol>());
   }
   return Nothing<Symbol>();
 #else
@@ -1317,7 +1331,7 @@ inline MaybeOrValue<Symbol> Symbol::WellKnown(napi_env env,
       .Get("Symbol")
       .As<Object>()
       .Get(name)
-      .As<Symbol>();
+      .UnsafeAs<Symbol>();
 #endif
 }
 
@@ -1535,7 +1549,10 @@ inline void Object::CheckCast(napi_env env, napi_value value) {
   napi_valuetype type;
   napi_status status = napi_typeof(env, value, &type);
   NAPI_CHECK(status == napi_ok, "Object::CheckCast", "napi_typeof failed");
-  NAPI_INTERNAL_CHECK_EQ(type, napi_object, "%d", "Object::CheckCast");
+  NAPI_INTERNAL_CHECK(type == napi_object || type == napi_function,
+                      "Object::CheckCast",
+                      "Expect napi_object or napi_function, but got %d.",
+                      type);
 }
 
 inline Object::Object() : TypeTaggable() {}
@@ -3324,6 +3341,8 @@ template <typename T>
 inline Reference<T>::~Reference() {
   if (_ref != nullptr) {
     if (!_suppressDestruct) {
+      // TODO(legendecas): napi_delete_reference should be invoked immediately.
+      // Fix this when https://github.com/nodejs/node/pull/55620 lands.
 #ifdef NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER
       Env().PostFinalizer(
           [](Napi::Env env, napi_ref ref) { napi_delete_reference(env, ref); },
@@ -4578,7 +4597,7 @@ template <typename T>
 inline ObjectWrap<T>::~ObjectWrap() {
   // If the JS object still exists at this point, remove the finalizer added
   // through `napi_wrap()`.
-  if (!IsEmpty()) {
+  if (!IsEmpty() && !_finalized) {
     Object object = Value();
     // It is not valid to call `napi_remove_wrap()` with an empty `object`.
     // This happens e.g. during garbage collection.
@@ -5018,7 +5037,7 @@ inline napi_value ObjectWrap<T>::StaticSetterCallbackWrapper(
 }
 
 template <typename T>
-inline void ObjectWrap<T>::FinalizeCallback(node_api_nogc_env env,
+inline void ObjectWrap<T>::FinalizeCallback(node_addon_api_basic_env env,
                                             void* data,
                                             void* /*hint*/) {
   // If the child class does not override _any_ Finalize() method, `env` will be
@@ -5027,8 +5046,10 @@ inline void ObjectWrap<T>::FinalizeCallback(node_api_nogc_env env,
   (void)env;
   T* instance = static_cast<T*>(data);
 
-  // Prevent ~ObjectWrap from calling napi_remove_wrap
-  instance->_ref = nullptr;
+  // Prevent ~ObjectWrap from calling napi_remove_wrap.
+  // The instance->_ref should be deleted with napi_delete_reference in
+  // ~Reference.
+  instance->_finalized = true;
 
   // If class overrides the basic finalizer, execute it.
   if constexpr (details::HasBasicFinalizer<T>::value) {
@@ -6682,12 +6703,14 @@ inline void AsyncProgressQueueWorker<T>::ExecutionProgress::Send(
 // Memory Management class
 ////////////////////////////////////////////////////////////////////////////////
 
-inline int64_t MemoryManagement::AdjustExternalMemory(Env env,
+inline int64_t MemoryManagement::AdjustExternalMemory(BasicEnv env,
                                                       int64_t change_in_bytes) {
   int64_t result;
   napi_status status =
       napi_adjust_external_memory(env, change_in_bytes, &result);
-  NAPI_THROW_IF_FAILED(env, status, 0);
+  NAPI_FATAL_IF_FAILED(status,
+                       "MemoryManagement::AdjustExternalMemory",
+                       "napi_adjust_external_memory");
   return result;
 }
 
@@ -6695,17 +6718,20 @@ inline int64_t MemoryManagement::AdjustExternalMemory(Env env,
 // Version Management class
 ////////////////////////////////////////////////////////////////////////////////
 
-inline uint32_t VersionManagement::GetNapiVersion(Env env) {
+inline uint32_t VersionManagement::GetNapiVersion(BasicEnv env) {
   uint32_t result;
   napi_status status = napi_get_version(env, &result);
-  NAPI_THROW_IF_FAILED(env, status, 0);
+  NAPI_FATAL_IF_FAILED(
+      status, "VersionManagement::GetNapiVersion", "napi_get_version");
   return result;
 }
 
-inline const napi_node_version* VersionManagement::GetNodeVersion(Env env) {
+inline const napi_node_version* VersionManagement::GetNodeVersion(
+    BasicEnv env) {
   const napi_node_version* result;
   napi_status status = napi_get_node_version(env, &result);
-  NAPI_THROW_IF_FAILED(env, status, 0);
+  NAPI_FATAL_IF_FAILED(
+      status, "VersionManagement::GetNodeVersion", "napi_get_node_version");
   return result;
 }
 

package/napi.h

@@ -299,6 +299,14 @@ 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.
@@ -307,14 +315,13 @@ using MaybeOrValue = T;
 /// Node-API operations within the callback. (Many methods infer the
 /// environment from the `this` instance that the method is called on.)
 ///
-/// In the future, multiple environments per process may be supported,
-/// although current implementations only support one environment per process.
+/// 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_api_nogc_env _env;
+  node_addon_api_basic_env _env;
 #if NAPI_VERSION > 5
   template <typename T>
   static void DefaultFini(Env, T* data);
@@ -322,8 +329,9 @@ class BasicEnv {
   static void DefaultFiniWithHint(Env, DataType* data, HintType* hint);
 #endif  // NAPI_VERSION > 5
  public:
-  BasicEnv(node_api_nogc_env env);
-  operator node_api_nogc_env() const;
+  BasicEnv(node_addon_api_basic_env env);
+
+  operator node_addon_api_basic_env() const;
 
   // Without these operator overloads, the error:
   //
@@ -461,6 +469,8 @@ class 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`.
@@ -527,6 +537,10 @@ class Value {
   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()
@@ -2464,7 +2478,9 @@ class ObjectWrap : public InstanceWrap<T>, public Reference<Object> {
                                                 napi_callback_info info);
   static napi_value StaticSetterCallbackWrapper(napi_env env,
                                                 napi_callback_info info);
-  static void FinalizeCallback(node_api_nogc_env env, void* data, void* hint);
+  static void FinalizeCallback(node_addon_api_basic_env env,
+                               void* data,
+                               void* hint);
 
   static void PostFinalizeCallback(napi_env env, void* data, void* hint);
 
@@ -2498,6 +2514,7 @@ class ObjectWrap : public InstanceWrap<T>, public Reference<Object> {
   }
 
   bool _construction_failed = true;
+  bool _finalized = false;
 };
 
 class HandleScope {
@@ -3218,14 +3235,14 @@ class AsyncProgressQueueWorker
 // Memory management.
 class MemoryManagement {
  public:
-  static int64_t AdjustExternalMemory(Env env, int64_t change_in_bytes);
+  static int64_t AdjustExternalMemory(BasicEnv env, int64_t change_in_bytes);
 };
 
 // Version management
 class VersionManagement {
  public:
-  static uint32_t GetNapiVersion(Env env);
-  static const napi_node_version* GetNodeVersion(Env env);
+  static uint32_t GetNapiVersion(BasicEnv env);
+  static const napi_node_version* GetNodeVersion(BasicEnv env);
 };
 
 #if NAPI_VERSION > 5

package/package.json

@@ -478,7 +478,7 @@
     "lint:fix": "node tools/clang-format --fix && node tools/eslint-format --fix"
   },
   "pre-commit": "lint",
-  "version": "8.2.0",
+  "version": "8.2.2",
   "support": true,
   "engines": {
     "node": "^18 || ^20 || >= 21"