Splitting WeakNodeApiHost out of weak_node_api and renaming to NodeApiHost

Author: kraenhansen

packages/host/scripts/generate-injector.mts

@@ -59,8 +59,8 @@ export function generateSource(functions: FunctionDecl[]) {
       abort();
     }
 
-    log_debug("Injecting WeakNodeApiHost");
-    inject_weak_node_api_host(WeakNodeApiHost {
+    log_debug("Injecting NodeApiHost");
+    inject_weak_node_api_host(NodeApiHost {
       ${functions
         .filter(
           ({ kind, name }) =>

packages/weak-node-api/.gitignore

@@ -5,8 +5,7 @@
 /build-tests/
 /*.xcframework
 /*.android.node
-/generated/weak_node_api.cpp
-/generated/weak_node_api.hpp
+/generated/
 
 # Copied from node-api-headers by scripts/copy-node-api-headers.ts
 /include/

packages/weak-node-api/CMakeLists.txt

@@ -16,6 +16,7 @@ target_sources(${PROJECT_NAME}
   PUBLIC FILE_SET HEADERS
   BASE_DIRS ${GENERATED_SOURCE_DIR} ${INCLUDE_DIR} FILES
     ${GENERATED_SOURCE_DIR}/weak_node_api.hpp
+    ${GENERATED_SOURCE_DIR}/NodeApiHost.hpp
     ${INCLUDE_DIR}/js_native_api_types.h
     ${INCLUDE_DIR}/js_native_api.h
     ${INCLUDE_DIR}/node_api_types.h

packages/weak-node-api/scripts/generate.ts

@@ -9,6 +9,7 @@ import {
 } from "../src/node-api-functions.js";
 
 import * as weakNodeApiGenerator from "./generators/weak-node-api.js";
+import * as hostGenerator from "./generators/NodeApiHost.js";
 
 export const OUTPUT_PATH = path.join(import.meta.dirname, "../generated");
 
@@ -41,6 +42,16 @@ async function run() {
   await fs.promises.mkdir(OUTPUT_PATH, { recursive: true });
 
   const functions = getNodeApiFunctions();
+  await generateFile({
+    functions,
+    fileName: "NodeApiHost.hpp",
+    generator: hostGenerator.generateHeader,
+    headingComment: `
+      @brief NodeApiHost struct.
+     
+      This header provides a struct of Node-API functions implemented by a host to inject its implementations.
+    `,
+  });
   await generateFile({
     functions,
     fileName: "weak_node_api.hpp",
@@ -50,6 +61,11 @@ async function run() {
     functions,
     fileName: "weak_node_api.cpp",
     generator: weakNodeApiGenerator.generateSource,
+    headingComment: `
+      @brief Weak Node-API host injection implementation.
+     
+      Provides the implementation for deferring Node-API function calls from addons into a Node-API host.
+    `,
   });
 }
 

packages/weak-node-api/scripts/generators/NodeApiHost.ts

@@ -0,0 +1,35 @@
+import type { FunctionDecl } from "../../src/node-api-functions.js";
+
+export function generateFunctionDecl({
+  returnType,
+  name,
+  argumentTypes,
+}: FunctionDecl) {
+  return `${returnType} (*${name})(${argumentTypes.join(", ")});`;
+}
+
+/**
+ * Generates source code for a version script for the given Node API version.
+ */
+export function generateHeader(functions: FunctionDecl[]) {
+  return `
+    #pragma once
+
+    #include <node_api.h>
+    
+    // Ideally we would have just used NAPI_NO_RETURN, but
+    // __declspec(noreturn) (when building with Microsoft Visual C++) cannot be used on members of a struct
+    // TODO: If we targeted C++23 we could use std::unreachable()
+
+    #if defined(__GNUC__)
+    #define WEAK_NODE_API_UNREACHABLE __builtin_unreachable()
+    #else
+    #define WEAK_NODE_API_UNREACHABLE __assume(0)
+    #endif
+    
+    // Generate the struct of function pointers
+    struct NodeApiHost {
+      ${functions.map(generateFunctionDecl).join("\n")}
+    };
+  `;
+}

packages/weak-node-api/scripts/generators/weak-node-api.ts

@@ -1,41 +1,21 @@
 import type { FunctionDecl } from "../../src/node-api-functions.js";
 import { generateFunction } from "./shared.js";
 
-export function generateFunctionDecl({
-  returnType,
-  name,
-  argumentTypes,
-}: FunctionDecl) {
-  return `${returnType} (*${name})(${argumentTypes.join(", ")});`;
-}
-
 /**
  * Generates source code for a version script for the given Node API version.
  */
-export function generateHeader(functions: FunctionDecl[]) {
+export function generateHeader() {
   return `
     #pragma once
 
-    #include <node_api.h> // Node-API
+    #include <node_api.h>
     #include <stdio.h> // fprintf()
     #include <stdlib.h> // abort()
-
-    // Ideally we would have just used NAPI_NO_RETURN, but
-    // __declspec(noreturn) (when building with Microsoft Visual C++) cannot be used on members of a struct
-    // TODO: If we targeted C++23 we could use std::unreachable()
-
-    #if defined(__GNUC__)
-    #define WEAK_NODE_API_UNREACHABLE __builtin_unreachable()
-    #else
-    #define WEAK_NODE_API_UNREACHABLE __assume(0)
-    #endif
     
-    // Generate the struct of function pointers
-    struct WeakNodeApiHost {
-      ${functions.map(generateFunctionDecl).join("\n")}
-    };
-    typedef void(*InjectHostFunction)(const WeakNodeApiHost&);
-    extern "C" void inject_weak_node_api_host(const WeakNodeApiHost& host);
+    #include "NodeApiHost.hpp"
+    
+    typedef void(*InjectHostFunction)(const NodeApiHost&);
+    extern "C" void inject_weak_node_api_host(const NodeApiHost& host);
   `;
 }
 
@@ -63,8 +43,15 @@ export function generateSource(functions: FunctionDecl[]) {
   return `
     #include "weak_node_api.hpp"
 
-    WeakNodeApiHost g_host;
-    void inject_weak_node_api_host(const WeakNodeApiHost& host) {
+    /**
+     * @brief Global instance of the injected Node-API host.
+     *
+     * This variable holds the function table for Node-API calls.
+     * It is set via inject_weak_node_api_host() before any Node-API function is dispatched.
+     * All Node-API calls are routed through this host.
+     */
+    NodeApiHost g_host;
+    void inject_weak_node_api_host(const NodeApiHost& host) {
       g_host = host;
     };
     

packages/weak-node-api/tests/test_inject.cpp

@@ -3,7 +3,7 @@
 
 TEST_CASE("inject_weak_node_api_host") {
   SECTION("is callable") {
-    WeakNodeApiHost host{};
+    NodeApiHost host{};
     inject_weak_node_api_host(host);
   }
 
@@ -14,7 +14,7 @@ TEST_CASE("inject_weak_node_api_host") {
       called = true;
       return napi_status::napi_ok;
     };
-    WeakNodeApiHost host{.napi_create_object = my_create_object};
+    NodeApiHost host{.napi_create_object = my_create_object};
     inject_weak_node_api_host(host);
 
     napi_value result;