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

CMakeLists.txt

@@ -154,6 +154,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/CMakeLists.txt

@@ -70,7 +70,11 @@ if(NAPI_BUILD_ABI)
         if(ANDROID)
             set(V8_PACKAGE_NAME "jsc-android")
             set(JSC_ANDROID_DIR "${CMAKE_CURRENT_BINARY_DIR}/${V8_PACKAGE_NAME}")
-            napi_install_android_package(jsc "dist/org/webkit/android-jsc" ${JSC_ANDROID_DIR})
+            # r294992 is the newest jsc-android build (dist-tag `next`; `latest` is still the 2019
+            # r250231). It is the first with BigInt enabled by default -- r250231 gates BigInt behind
+            # the `useBigInt` runtime option, off, so its parser rejects `0n`. r294992 publishes only
+            # the `-intl` variant, and statically links libc++ (no libc++_shared.so dependency).
+            napi_install_android_package(jsc "dist/org/webkit/android-jsc-intl" ${JSC_ANDROID_DIR})
 
             # Add `JavaScriptCore` prefix to the include path
             file(RENAME "${JSC_ANDROID_DIR}/include" "${JSC_ANDROID_DIR}/JavaScriptCore")
@@ -261,7 +265,24 @@ 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 AND NOT NAPI_JAVASCRIPT_ENGINE STREQUAL "Hermes")
+    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})
@@ -277,5 +298,11 @@ if(NAPI_JAVASCRIPT_ENGINE STREQUAL "Hermes")
         NAPI_HERMES_MAX_HEAP_SIZE_MB=${NAPI_HERMES_MAX_HEAP_SIZE_MB})
 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})
+
 set_property(TARGET napi PROPERTY FOLDER Dependencies)
 source_group(TREE ${CMAKE_CURRENT_SOURCE_DIR} FILES ${SOURCES})

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

@@ -8,8 +8,13 @@
 #ifndef NODE_ADDON_API_DISABLE_NODE_SPECIFIC
 #define NODE_ADDON_API_DISABLE_NODE_SPECIFIC
 #endif
+// [BABYLON-NATIVE-ADDITION] Keep this in step with js_native_api.h / js_native_api_types.h. The C
+// headers already default to 7, but this one is reached first by every consumer that includes
+// <napi/napi.h> (all of Babylon Native, and every node-addon-api addon), and #ifndef made it win --
+// so Napi::BigInt, Value::IsBigInt, GetInstanceData<T> and Napi::Addon stayed compiled out even
+// though the C entry points behind them were implemented.
 #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/js_native_api_chakra.cc

@@ -2486,6 +2486,119 @@ napi_status napi_run_script(napi_env env,
   return napi_ok;
 }
 
+// === N-API v6 / v7 ===
+//
+// napi_set_instance_data / napi_get_instance_data (v6): per-env data slot, finalized at env teardown
+// by ~napi_env__ (see js_native_api_chakra.h).
+napi_status napi_set_instance_data(napi_env env,
+                                   void* data,
+                                   napi_finalize finalize_cb,
+                                   void* finalize_hint) {
+  CHECK_ENV(env);
+  env->instance_data = data;
+  env->instance_data_finalize_cb = finalize_cb;
+  env->instance_data_finalize_hint = finalize_hint;
+  return napi_ok;
+}
+
+napi_status napi_get_instance_data(napi_env env, void** data) {
+  CHECK_ENV(env);
+  CHECK_ARG(env, data);
+  *data = env->instance_data;
+  return napi_ok;
+}
+
+// N-API v7 ArrayBuffer detach. Win10's OS Chakra exposes no way to detach an ArrayBuffer: the
+// runtime has no detach entry point, and its JavaScript engine predates ES2024
+// ArrayBuffer.prototype.transfer(). As with BigInt below, report that honestly rather than failing
+// with a bare status an addon cannot tell from a real error.
+napi_status napi_detach_arraybuffer(napi_env env, napi_value arraybuffer) {
+  CHECK_ENV(env);
+  CHECK_ARG(env, arraybuffer);
+  CHECK_NAPI(napi_throw_error(
+      env, "ENOTSUP",
+      "ArrayBuffer detach is not supported by the underlying JavaScript engine (Chakra)."));
+  return napi_set_last_error(env, napi_pending_exception);
+}
+
+napi_status napi_is_detached_arraybuffer(napi_env env,
+                                         napi_value arraybuffer,
+                                         bool* result) {
+  CHECK_ENV(env);
+  CHECK_ARG(env, arraybuffer);
+  CHECK_ARG(env, result);
+
+  // Nothing can detach a buffer on this engine (see above), so an ArrayBuffer that still reports
+  // storage is live. Non-ArrayBuffers are not detached either, matching Node's contract.
+  JsValueType valueType;
+  CHECK_JSRT(env, JsGetValueType(reinterpret_cast<JsValueRef>(arraybuffer), &valueType));
+  if (valueType != JsArrayBuffer) {
+    *result = false;
+    return napi_ok;
+  }
+
+  BYTE* storageData;
+  unsigned int storageLength;
+  CHECK_JSRT(env, JsGetArrayBufferStorage(
+    reinterpret_cast<JsValueRef>(arraybuffer),
+    &storageData,
+    &storageLength));
+
+  *result = (storageData == nullptr);
+  return napi_ok;
+}
+
+// BigInt (v6): the Win10 OS edge-mode Chakra (jsrt) predates BigInt and exposes no JsBigInt* API, so
+// there is no value-preserving fallback. Per the Node-API feature-detection-by-exception pattern, throw
+// a JS-catchable error tagged "ENOTSUP" (so JS land can detect + polyfill) and return a pending
+// exception rather than silently failing. (ChakraCore added BigInt behind a flag, but the OS Chakra
+// this backend targets did not ship it.)
+static napi_status napi_bigint_not_supported(napi_env env) {
+  CHECK_ENV(env);
+  CHECK_NAPI(napi_throw_error(
+      env, "ENOTSUP",
+      "BigInt is not supported by the underlying JavaScript engine (Chakra)."));
+  return napi_set_last_error(env, napi_pending_exception);
+}
+
+napi_status napi_create_bigint_int64(napi_env env, int64_t value, napi_value* result) {
+  return napi_bigint_not_supported(env);
+}
+
+napi_status napi_create_bigint_uint64(napi_env env, uint64_t value, napi_value* result) {
+  return napi_bigint_not_supported(env);
+}
+
+napi_status napi_create_bigint_words(napi_env env,
+                                     int sign_bit,
+                                     size_t word_count,
+                                     const uint64_t* words,
+                                     napi_value* result) {
+  return napi_bigint_not_supported(env);
+}
+
+napi_status napi_get_value_bigint_int64(napi_env env,
+                                        napi_value value,
+                                        int64_t* result,
+                                        bool* lossless) {
+  return napi_bigint_not_supported(env);
+}
+
+napi_status napi_get_value_bigint_uint64(napi_env env,
+                                         napi_value value,
+                                         uint64_t* result,
+                                         bool* lossless) {
+  return napi_bigint_not_supported(env);
+}
+
+napi_status napi_get_value_bigint_words(napi_env env,
+                                        napi_value value,
+                                        int* sign_bit,
+                                        size_t* word_count,
+                                        uint64_t* words) {
+  return napi_bigint_not_supported(env);
+}
+
 napi_status napi_add_finalizer(napi_env env,
                                napi_value js_object,
                                void* native_object,

Core/Node-API/Source/js_native_api_chakra.h

@@ -24,7 +24,19 @@ struct napi_env__ {
   size_t next_escapable_scope_token = 0;
   std::map<size_t, bool> open_escapable_scopes;
 
+  // napi_set_instance_data / napi_get_instance_data (N-API v6).
+  void* instance_data = nullptr;
+  napi_finalize instance_data_finalize_cb = nullptr;
+  void* instance_data_finalize_hint = nullptr;
+
   const std::thread::id thread_id{std::this_thread::get_id()};
+
+  ~napi_env__() {
+    // Run the instance-data finalizer at env teardown (env_chakra.cc deletes the env), matching V8/JSC.
+    if (instance_data_finalize_cb != nullptr) {
+      instance_data_finalize_cb(this, instance_data, instance_data_finalize_hint);
+    }
+  }
 };
 
 #define RETURN_STATUS_IF_FALSE(env, condition, status) \