node-addon-api 8.2.0 → 8.2.1

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.1
 <!-- 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() {}
@@ -5018,7 +5035,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

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);
 

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.1",
   "support": true,
   "engines": {
     "node": "^18 || ^20 || >= 21"