N-API v7 across runtimes (V8 / JavaScriptCore / Chakra)

.github/workflows/build-linux.yml

@@ -54,14 +54,24 @@ jobs:
 
       - name: Run Tests
         working-directory: Build/ubuntu/Tests/UnitTests
-        run: ./UnitTests
-        env:
-          TSAN_OPTIONS: ${{ inputs.enable-thread-sanitizer && format('suppressions={0}/.github/tsan_suppressions.txt', github.workspace) || '' }}
+        run: |
           # JSC's concurrent GC on Linux uses SIGUSR1 + sem_wait to suspend mutator
           # threads at safepoints. TSan's signal interception delays SIGUSR1 delivery
           # indefinitely, deadlocking the Collector Thread's sem_wait. Disabling the
           # concurrent collector removes the dedicated Collector Thread, so GC runs
           # on the mutator without cross-thread signals. macOS JSC uses Mach
           # thread_suspend() and is unaffected.
-          JSC_useConcurrentGC: ${{ inputs.enable-thread-sanitizer && '0' || '' }}
+          if [[ "${{ inputs.enable-thread-sanitizer }}" == "true" ]]; then
+            export TSAN_OPTIONS="suppressions=${{ github.workspace }}/.github/tsan_suppressions.txt"
+            export JSC_useConcurrentGC=0
+          fi
+          ./UnitTests
 
+      - name: Run Node-API v7 conformance
+        working-directory: Build/ubuntu/Tests/NodeApi
+        run: |
+          if [[ "${{ inputs.enable-thread-sanitizer }}" == "true" ]]; then
+            export TSAN_OPTIONS="suppressions=${{ github.workspace }}/.github/tsan_suppressions.txt"
+            export JSC_useConcurrentGC=0
+          fi
+          ./NodeApiTests

.github/workflows/build-macos.yml

@@ -41,11 +41,16 @@ jobs:
             -D ENABLE_THREAD_SANITIZER=${{ inputs.enable-thread-sanitizer && 'ON' || 'OFF' }}
 
       - name: Build
-        run: cmake --build Build/macOS --target UnitTests --config RelWithDebInfo
+        run: cmake --build Build/macOS --target UnitTests NodeApiTests --config RelWithDebInfo
 
       - name: Run Tests
         working-directory: Build/macOS/Tests/UnitTests/RelWithDebInfo
         run: ./UnitTests
         env:
           TSAN_OPTIONS: ${{ inputs.enable-thread-sanitizer && format('suppressions={0}/.github/tsan_suppressions.txt', github.workspace) || '' }}
 
+      - name: Run Node-API v7 conformance
+        working-directory: Build/macOS/Tests/NodeApi/RelWithDebInfo
+        run: ./NodeApiTests
+        env:
+          TSAN_OPTIONS: ${{ inputs.enable-thread-sanitizer && format('suppressions={0}/.github/tsan_suppressions.txt', github.workspace) || '' }}

CMakeLists.txt

@@ -55,7 +55,7 @@ FetchContent_Declare(quickjs-ng
     GIT_REPOSITORY https://github.com/quickjs-ng/quickjs.git
     GIT_TAG 93d3f7df465027f487ed37e175a0bc3012fee79e
     EXCLUDE_FROM_ALL)
-    
+
 # --------------------------------------------------
 
 FetchContent_MakeAvailable(CMakeExtensions)
@@ -75,6 +75,14 @@ set_property(GLOBAL PROPERTY USE_FOLDERS ON)
 set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 
+# A newer MSVC (windows-latest) emits C4875 ("a non-string literal argument to [[gsl::suppress]] is
+# deprecated") from the vendored GSL headers, which several targets compile with warnings-as-error.
+# Suppress this dependency-side deprecation so the Windows build isn't broken by toolchain drift. Must
+# be set before arcana.cpp / Core / Polyfills are added below so they inherit it.
+if(MSVC)
+    add_compile_options(/wd4875)
+endif()
+
 # --------------------------------------------------
 # Options
 # --------------------------------------------------
@@ -154,6 +162,17 @@ endif()
 FetchContent_MakeAvailable_With_Message(arcana.cpp)
 set_property(TARGET arcana PROPERTY FOLDER Dependencies)
 
+if(ANDROID)
+    FetchContent_GetProperties(AndroidExtensions)
+    if(NOT AndroidExtensions_POPULATED)
+        FetchContent_Populate(AndroidExtensions)
+        FetchContent_GetProperties(AndroidExtensions)
+        add_subdirectory(${androidextensions_SOURCE_DIR} ${androidextensions_BINARY_DIR})
+    else()
+        add_subdirectory(${androidextensions_SOURCE_DIR} ${androidextensions_BINARY_DIR})
+    endif()
+endif()
+
 if(JSRUNTIMEHOST_POLYFILL_XMLHTTPREQUEST OR JSRUNTIMEHOST_POLYFILL_FETCH)
     FetchContent_MakeAvailable_With_Message(UrlLib)
     set_property(TARGET UrlLib PROPERTY FOLDER Dependencies)

Core/Node-API-JSI/CMakeLists.txt

@@ -57,7 +57,12 @@ if(NOT TARGET jsi)
 endif()
 
 target_include_directories(napi
-    PUBLIC "include")
+    PUBLIC "include"
+    # napi.h pulls in the shared <napi/js_native_api_types.h>, which lives in
+    # Core/Node-API/Include/Shared. That sibling isn't built when the engine is JSI
+    # (Core/CMakeLists.txt selects Node-API-JSI instead of Node-API), so reference the shared
+    # headers directly here -- otherwise the JSI napi fails to compile with C1083.
+    PUBLIC "${CMAKE_CURRENT_SOURCE_DIR}/../Node-API/Include/Shared")
 
 target_link_libraries(napi
     PUBLIC jsi)

Core/Node-API-JSI/Include/napi/napi.h

@@ -1,49 +1,14 @@
 #pragma once
 
 #include <jsi/jsi.h>
+#include <napi/js_native_api_types.h>
 #include <functional>
 #include <initializer_list>
 #include <memory>
 #include <string>
 #include <vector>
 #include <optional>
 
-// Copied from js_native_api_types.h (https://git.io/J8aI5)
-typedef enum {
-  napi_default = 0,
-  napi_writable = 1 << 0,
-  napi_enumerable = 1 << 1,
-  napi_configurable = 1 << 2,
-} napi_property_attributes;
-
-typedef enum {
-  // ES6 types (corresponds to typeof)
-  napi_undefined,
-  napi_null,
-  napi_boolean,
-  napi_number,
-  napi_string,
-  napi_symbol,
-  napi_object,
-  napi_function,
-  napi_external,
-} napi_valuetype;
-
-typedef enum {
-  napi_int8_array,
-  napi_uint8_array,
-  napi_uint8_clamped_array,
-  napi_int16_array,
-  napi_uint16_array,
-  napi_int32_array,
-  napi_uint32_array,
-  napi_float32_array,
-  napi_float64_array,
-  // JSI doesn't support bigint.
-  // napi_bigint64_array,
-  // napi_biguint64_array,
-} napi_typedarray_type;
-
 struct napi_env__ {
   napi_env__(facebook::jsi::Runtime& rt)
     : rt{rt}

Core/Node-API/CMakeLists.txt

@@ -1,15 +1,23 @@
-# Set per-platform defaults if unspecified.
-if(WIN32)
-    set(NAPI_JAVASCRIPT_ENGINE "Chakra" CACHE STRING "JavaScript engine for Node-API")
-elseif(APPLE)
-    set(NAPI_JAVASCRIPT_ENGINE "JavaScriptCore" CACHE STRING "JavaScript engine for Node-API")
-elseif(ANDROID)
-    set(NAPI_JAVASCRIPT_ENGINE "V8" CACHE STRING "JavaScript engine for Node-API")
-elseif(UNIX)
-    set(NAPI_JAVASCRIPT_ENGINE "JavaScriptCore" CACHE STRING "JavaScript engine for Node-API")
-    set(JAVASCRIPTCORE_LIBRARY "/usr/lib/x86_64-linux-gnu/libjavascriptcoregtk-4.1.so" CACHE STRING "Path to the JavaScriptCore shared library")
-else()
-    message(FATAL_ERROR "Unable to select Node-API JavaScript engine for platform")
+# Set per-platform defaults only when the caller did not select an engine.
+if(NOT NAPI_JAVASCRIPT_ENGINE)
+    if(WIN32)
+        set(NAPI_JAVASCRIPT_ENGINE "Chakra" CACHE STRING "JavaScript engine for Node-API")
+    elseif(APPLE)
+        set(NAPI_JAVASCRIPT_ENGINE "JavaScriptCore" CACHE STRING "JavaScript engine for Node-API")
+    elseif(ANDROID)
+        set(NAPI_JAVASCRIPT_ENGINE "V8" CACHE STRING "JavaScript engine for Node-API")
+    elseif(UNIX)
+        set(NAPI_JAVASCRIPT_ENGINE "JavaScriptCore" CACHE STRING "JavaScript engine for Node-API")
+    else()
+        message(FATAL_ERROR "Unable to select Node-API JavaScript engine for platform")
+    endif()
+endif()
+
+if(UNIX AND NOT APPLE AND NOT ANDROID AND NAPI_JAVASCRIPT_ENGINE STREQUAL "JavaScriptCore")
+    find_library(JAVASCRIPTCORE_LIBRARY javascriptcoregtk-4.1)
+    if(NOT JAVASCRIPTCORE_LIBRARY)
+        message(FATAL_ERROR "JavaScriptCore library not found. Please install libwebkit2gtk-4.1-dev")
+    endif()
 endif()
 
 set(SOURCES
@@ -94,6 +102,13 @@ if(NAPI_BUILD_ABI)
         else()
             message(FATAL_ERROR "Unsupported JavaScript engine: ${NAPI_JAVASCRIPT_ENGINE}")
         endif()
+
+        # The maintained Apple and WebKitGTK headers/runtimes expose the
+        # BigInt typed-array enum values. The frozen jsc-android package does
+        # not, so keep its capability-gated build on the older enum surface.
+        if(NOT ANDROID)
+            set(JSR_JSC_HAS_BIGINT_TYPED_ARRAYS ON)
+        endif()
     elseif(NAPI_JAVASCRIPT_ENGINE STREQUAL "V8")
         set(SOURCES ${SOURCES}
             "Source/env_v8.cc"
@@ -187,9 +202,9 @@ Make sure Hermes was fetched at the top-level CMakeLists.txt and NAPI_JAVASCRIPT
         # (bigint::exponentiate, regex::parseRegex, hbc::compileEvalModule,
         # llvh::raw_ostream, platform_unicode::normalize, ...) which
         # `hermesvm_a` bundles together for us.
-        set(LINK_LIBRARIES ${LINK_LIBRARIES}
-            PRIVATE hermesNapi
-            PRIVATE hermesvm_a)
+        set(NAPI_HERMES_LINK_LIBRARIES
+            hermesNapi
+            hermesvm_a)
 
         # `hermes_napi.h` lives in Hermes's `API/napi/` source directory and
         # is NOT installed alongside the other `include/hermes/napi/`
@@ -261,11 +276,61 @@ Make sure Hermes was fetched at the top-level CMakeLists.txt and NAPI_JAVASCRIPT
     message(STATUS "Selected ${NAPI_JAVASCRIPT_ENGINE}")
 endif()
 
-add_library(napi ${SOURCES})
+# On Android, native addons are dlopen'd as standalone .node modules and resolve their napi_* imports
+# from a shared napi at load time -- bionic will not surface a statically-linked host's napi to a
+# dlopen'd module, so the host and every addon must share a single libnapi.so. Default napi to a
+# shared library on Android so that model works out of the box; an integrator who wants a static napi
+# (e.g. for size/packaging) can override with -DJSR_NAPI_SHARED=OFF. The option defaults OFF on other
+# platforms, where napi keeps following the project's default library type (i.e. honors
+# BUILD_SHARED_LIBS).
+set(JSR_NAPI_SHARED_DEFAULT OFF)
+if(ANDROID)
+    set(JSR_NAPI_SHARED_DEFAULT ON)
+endif()
+option(JSR_NAPI_SHARED "Build napi as a shared library (libnapi.so)" ${JSR_NAPI_SHARED_DEFAULT})
+
+if(JSR_NAPI_SHARED)
+    add_library(napi SHARED ${SOURCES})
+else()
+    add_library(napi ${SOURCES})
+endif()
 
 target_include_directories(napi ${INCLUDE_DIRECTORIES})
 target_link_libraries(napi ${LINK_LIBRARIES})
 
+if(NAPI_JAVASCRIPT_ENGINE STREQUAL "Hermes")
+    if(JSR_NAPI_SHARED)
+        # hermesNapi is a static archive. When it is folded into libnapi.so,
+        # the linker would normally extract only the objects referenced by
+        # env_hermes.cc, leaving most exported napi_* entry points out of the
+        # shared library. Android addons then fail to resolve even core APIs
+        # such as napi_create_arraybuffer and napi_wrap. Include the complete
+        # archive so the shared library provides the full Node-API surface.
+        if(MSVC)
+            target_link_libraries(napi PRIVATE ${NAPI_HERMES_LINK_LIBRARIES})
+            target_link_options(napi PRIVATE "/WHOLEARCHIVE:$<TARGET_FILE:hermesNapi>")
+        else()
+            target_link_libraries(napi PRIVATE
+                "-Wl,--whole-archive"
+                hermesNapi
+                "-Wl,--no-whole-archive"
+                hermesvm_a)
+        endif()
+    else()
+        target_link_libraries(napi PRIVATE ${NAPI_HERMES_LINK_LIBRARIES})
+    endif()
+endif()
+
+if(JSR_JSC_HAS_BIGINT_TYPED_ARRAYS)
+    target_compile_definitions(napi PRIVATE JSR_JSC_HAS_BIGINT_TYPED_ARRAYS=1)
+endif()
+
+# Expose the selected engine as a compile definition so engine-agnostic consumers (the node_lite test
+# harness) can branch on engine capability instead of guessing from the platform
+# (__APPLE__ == JSC / __ANDROID__ == V8 breaks Android-JSC, Linux-V8, Windows-Chakra, ...).
+string(TOUPPER "${NAPI_JAVASCRIPT_ENGINE}" NAPI_ENGINE_UPPER)
+target_compile_definitions(napi PUBLIC JSR_NAPI_ENGINE_${NAPI_ENGINE_UPPER})
+
 if(NAPI_JAVASCRIPT_ENGINE STREQUAL "Hermes")
     # Apply Hermes-specific warning suppressions ONLY to env_hermes.cc so
     # they don't relax the rules for the rest of the napi sources.

Core/Node-API/Include/Engine/Hermes/napi/env.h

@@ -30,4 +30,7 @@ namespace Napi
     // top-level dispatch.  Equivalent engines (V8, Chakra) auto-drain
     // microtasks at scope exit; Hermes requires an explicit drainJobs().
     void DrainJobs(Napi::Env env);
+
+    // Force a collection for conformance tests that expose global.gc().
+    void CollectGarbage(Napi::Env env);
 }

Core/Node-API/Include/Shared/napi/js_native_api.h

@@ -3,7 +3,7 @@
 
 // [BABYLON-NATIVE-ADDITION]
 #ifndef NAPI_VERSION
-#define NAPI_VERSION 5
+#define NAPI_VERSION 7
 #endif
 
 // This file needs to be compatible with C compilers.

Core/Node-API/Include/Shared/napi/js_native_api_types.h

@@ -3,7 +3,7 @@
 
 // [BABYLON-NATIVE-ADDITION]
 #ifndef NAPI_VERSION
-#define NAPI_VERSION 5
+#define NAPI_VERSION 7
 #endif
 
 // This file needs to be compatible with C compilers.

Core/Node-API/Include/Shared/napi/napi.h

@@ -9,7 +9,7 @@
 #define NODE_ADDON_API_DISABLE_NODE_SPECIFIC
 #endif
 #ifndef NAPI_VERSION
-#define NAPI_VERSION 5
+#define NAPI_VERSION 7
 #endif
 #ifndef NAPI_HAS_THREADS
 #define NAPI_HAS_THREADS 0

Core/Node-API/Source/env_hermes.cc

@@ -26,7 +26,7 @@
 //     `hermes_run_script` directly — so the linker is never asked to find
 //     the 4-arg symbol).
 //
-// We keep `NAPI_VERSION` at the shared default (5) so the inline wrappers
+// We keep `NAPI_VERSION` at the shared default (7) so the inline wrappers
 // in napi-inl.h that target newer NAPI revisions (e.g.
 // `Env::GetModuleFileName` which calls `node_api_get_module_file_name`)
 // aren't pulled in — they would reference symbols absent from our shared
@@ -166,6 +166,15 @@ namespace Napi
         (void)runtime->drainJobs();
     }
 
+    void CollectGarbage(Napi::Env env)
+    {
+        hermes::vm::Runtime* runtime = LookupRuntime(env);
+        if (runtime != nullptr)
+        {
+            runtime->collect("node_lite explicit collection");
+        }
+    }
+
     Napi::Value Eval(Napi::Env env, const char* source, const char* sourceUrl)
     {
         napi_env env_ptr{env};

Core/Node-API/Source/env_quickjs.cc

@@ -65,6 +65,20 @@ namespace Napi
         napi_env env_ptr{env};
         if (env_ptr)
         {
+            // Node-API instance data belongs to the environment rather than a
+            // JS object. Finalize it while both the context and env are still
+            // valid; user finalizers are permitted to call Node-API.
+            if (env_ptr->instance_data_finalize != nullptr)
+            {
+                auto finalize = env_ptr->instance_data_finalize;
+                void* data = env_ptr->instance_data;
+                void* hint = env_ptr->instance_data_finalize_hint;
+                env_ptr->instance_data = nullptr;
+                env_ptr->instance_data_finalize = nullptr;
+                env_ptr->instance_data_finalize_hint = nullptr;
+                finalize(env_ptr, data, hint);
+            }
+
             // Release every strong napi_ref still outstanding. This mirrors
             // the V8 impl (napi_env__::DeleteMe) and is essential on QuickJS:
             // any surviving strong ref pins a JS value from outside the GC