src: restore ability to run under NAPI_EXPERIMENTAL

Since we made the default for Node.js core finalizers synchronous for
users running with `NAPI_EXPERIMENTAL` and introduced
`env->CheckGCAccess()` in Node.js core, we must now defer all
finalizers in node-addon-api, because our users likely make
non-gc-safe Node-API calls from existing finalizers. To that end,

  * Use the NAPI_VERSION environment variable to detect whether
    `NAPI_EXPERIMENTAL` should be on, and add it to the defines if
    `NAPI_VERSION` is set to `NAPI_VERSION_EXPERIMENTAL`, i.e.
    2147483647.
  * When building with `NAPI_EXPERIMENTAL`,
    * render all finalizers asynchronous, and
    * expect `napi_cannot_run_js` instead of `napi_exception_pending`.

.github/workflows/ci.yml

@@ -13,6 +13,9 @@ jobs:
     timeout-minutes: 30
     strategy:
       matrix:
+        api_version:
+          - standard
+          - experimental
         node-version: [ 18.x, 20.x, 21.x ]
         os:
           - macos-latest
@@ -43,6 +46,9 @@ jobs:
         npm install
     - name: npm test
       run: |
+        if [ "${{ matrix.api_version }}" = "experimental" ]; then
+          export NAPI_VERSION=2147483647
+        fi
         if [ "${{ matrix.compiler }}" = "gcc" ]; then
           export CC="gcc" CXX="g++"
         fi

common.gypi

@@ -5,6 +5,7 @@
   },
   'conditions': [
     ['NAPI_VERSION!=""', { 'defines': ['NAPI_VERSION=<@(NAPI_VERSION)'] } ],
+    ['NAPI_VERSION==2147483647', { 'defines': ['NAPI_EXPERIMENTAL'] } ],
     ['disable_deprecated=="true"', {
       'defines': ['NODE_ADDON_API_DISABLE_DEPRECATED']
     }],

napi-inl.h

@@ -180,11 +180,36 @@ napi_value TemplatedInstanceVoidCallback(napi_env env, napi_callback_info info)
   });
 }
 
+inline void DeferredCallback(const char* placeOfFailure,
+                             napi_env env,
+                             void* data,
+                             void* hint,
+                             napi_finalize fini) {
+#ifdef NAPI_EXPERIMENTAL
+  napi_status status = node_api_post_finalizer(env, fini, data, hint);
+  NAPI_FATAL_IF_FAILED(
+      status, placeOfFailure, "DeferredCallback -> node_api_post_finalizer");
+#else
+  (void)placeOfFailure;
+  fini(env, data, hint);
+#endif
+}
+
 template <typename T, typename Finalizer, typename Hint = void>
 struct FinalizeData {
   static inline void Wrapper(napi_env env,
                              void* data,
                              void* finalizeHint) NAPI_NOEXCEPT {
+    DeferredCallback("FinalizeData::Wrapper",
+                     env,
+                     data,
+                     finalizeHint,
+                     FinalizeData<T, Finalizer>::SyncWrapper);
+  }
+
+  static inline void SyncWrapper(napi_env env,
+                                 void* data,
+                                 void* finalizeHint) NAPI_NOEXCEPT {
     WrapVoidCallback([&] {
       FinalizeData* finalizeData = static_cast<FinalizeData*>(finalizeHint);
       finalizeData->callback(Env(env), static_cast<T*>(data));
@@ -195,6 +220,16 @@ struct FinalizeData {
   static inline void WrapperWithHint(napi_env env,
                                      void* data,
                                      void* finalizeHint) NAPI_NOEXCEPT {
+    DeferredCallback("FinalizeData::WrapperWithHint",
+                     env,
+                     data,
+                     finalizeHint,
+                     FinalizeData<T, Finalizer, Hint>::SyncWrapperWithHint);
+  }
+
+  static inline void SyncWrapperWithHint(napi_env env,
+                                         void* data,
+                                         void* finalizeHint) NAPI_NOEXCEPT {
     WrapVoidCallback([&] {
       FinalizeData* finalizeData = static_cast<FinalizeData*>(finalizeHint);
       finalizeData->callback(
@@ -2731,7 +2766,7 @@ inline Buffer<T> Buffer<T>::NewOrCopy(napi_env env,
 #endif  // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
     // If we can't create an external buffer, we'll just copy the data.
     Buffer<T> ret = Buffer<T>::Copy(env, data, length);
-    details::FinalizeData<T, Finalizer>::Wrapper(env, data, finalizeData);
+    details::FinalizeData<T, Finalizer>::SyncWrapper(env, data, finalizeData);
     return ret;
 #ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
   }
@@ -2766,7 +2801,7 @@ inline Buffer<T> Buffer<T>::NewOrCopy(napi_env env,
 #endif
     // If we can't create an external buffer, we'll just copy the data.
     Buffer<T> ret = Buffer<T>::Copy(env, data, length);
-    details::FinalizeData<T, Finalizer, Hint>::WrapperWithHint(
+    details::FinalizeData<T, Finalizer, Hint>::SyncWrapperWithHint(
         env, data, finalizeData);
     return ret;
 #ifndef NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
@@ -3054,7 +3089,13 @@ inline void Error::ThrowAsJavaScriptException() const {
 
       status = napi_throw(_env, Value());
 
-      if (status == napi_pending_exception) {
+#ifdef NAPI_EXPERIMENTAL
+      napi_status expected_failure_mode = napi_cannot_run_js;
+#else
+      napi_status expected_failure_mode = napi_pending_exception;
+#endif
+
+      if (status == expected_failure_mode) {
         // The environment must be terminating as we checked earlier and there
         // was no pending exception. In this case continuing will result
         // in a fatal error and there is nothing the author has done incorrectly
@@ -4879,10 +4920,16 @@ template <typename T>
 inline void ObjectWrap<T>::FinalizeCallback(napi_env env,
                                             void* data,
                                             void* /*hint*/) {
-  HandleScope scope(env);
-  T* instance = static_cast<T*>(data);
-  instance->Finalize(Napi::Env(env));
-  delete instance;
+  details::DeferredCallback("ObjectWrap<T>::FinalizeCallback",
+                            env,
+                            data,
+                            nullptr,
+                            [](napi_env env, void* data, void* /*hint*/) {
+                              HandleScope scope(env);
+                              T* instance = static_cast<T*>(data);
+                              instance->Finalize(Napi::Env(env));
+                              delete instance;
+                            });
 }
 
 template <typename T>