objc-js 1.1.0 → 1.2.0

package/src/native/bridge.h

@@ -4,6 +4,7 @@
 #include <format>
 #include <napi.h>
 #include <objc/objc.h>
+#include <string_view>
 
 #ifndef NATIVE_BRIDGE_H
 #define NATIVE_BRIDGE_H
@@ -66,8 +67,8 @@ template <typename T1, typename T2> bool IsInRange(T1 value) {
 // MARK: - Conversion Implementation
 
 struct ObjcArgumentContext {
-  std::string className;
-  std::string selectorName;
+  std::string_view className;
+  std::string_view selectorName;
   int argumentIndex;
 };
 
@@ -277,6 +278,9 @@ inline auto AsObjCArgument(const Napi::Value &value, const char *typeEncoding,
     return ConvertToNativeValue<SEL>(value, context);
   case '@':
     return ConvertToNativeValue<id>(value, context);
+  case '#':
+    // Class is also an id in ObjC — an ObjcObject wrapping a Class works here
+    return ConvertToNativeValue<id>(value, context);
   case '^': // Pointer type (^v, ^c, etc.)
     if (value.IsBuffer()) {
       Napi::Buffer<uint8_t> buffer = value.As<Napi::Buffer<uint8_t>>();

package/src/native/call-function.h

@@ -0,0 +1,274 @@
+#pragma once
+
+// ============================================================================
+// call-function.h - C Function Calling via dlsym + libffi
+// ============================================================================
+//
+// Provides the ability to call C functions (like NSLog, CGRectMake, etc.)
+// exported from loaded frameworks. Uses dlsym to look up the function
+// symbol and libffi to perform the call with correct ABI handling.
+//
+// NOTE: No @autoreleasepool is used here. C functions like NSHomeDirectory()
+// return autoreleased objects, and wrapping the call in @autoreleasepool would
+// drain the pool before ObjcObject::NewInstance can retain the returned object,
+// leaving the ObjcObject holding a dangling pointer. The caller's autorelease
+// pool (from Node's/Bun's event loop) handles cleanup instead.
+//
+
+#include "constants.h"
+#include "debug.h"
+#include "ffi-utils.h"
+#include "struct-utils.h"
+#include "type-conversion.h"
+#include <Foundation/Foundation.h>
+#include <dlfcn.h>
+#include <ffi.h>
+#include <memory>
+#include <napi.h>
+#include <string>
+#include <vector>
+
+// MARK: - Argument Extraction
+
+/// Extract a JS argument into a buffer based on the type encoding.
+/// Handles struct types via PackJSValueAsStruct, and simple types via
+/// ExtractJSArgumentToBuffer.
+///
+/// Returns the owned buffer (for structs) so the caller can keep it alive.
+inline std::unique_ptr<uint8_t[]>
+ExtractFunctionArgument(Napi::Env env, const Napi::Value &jsValue,
+                        const std::string &typeEncoding, void **outArgPtr,
+                        const std::string &functionName, int argIndex,
+                        FFITypeGuard &guard) {
+  const char *simplified = SimplifyTypeEncoding(typeEncoding.c_str());
+
+  if (*simplified == '{') {
+    // Struct argument: pack JS value into struct buffer
+    auto structBytes = PackJSValueAsStruct(env, jsValue, typeEncoding.c_str());
+    auto buffer = std::make_unique<uint8_t[]>(structBytes.size());
+    memcpy(buffer.get(), structBytes.data(), structBytes.size());
+    *outArgPtr = buffer.get();
+    NOBJC_LOG("ExtractFunctionArgument: Packed struct arg %d (%zu bytes)",
+              argIndex, structBytes.size());
+    return buffer;
+  }
+
+  // Simple type: compute size and extract
+  size_t argSize = GetSizeForTypeEncoding(*simplified);
+  if (argSize == 0 && *simplified != 'v') {
+    // Complex type - use NSGetSizeAndAlignment
+    NSUInteger nsSize, nsAlignment;
+    NSGetSizeAndAlignment(typeEncoding.c_str(), &nsSize, &nsAlignment);
+    argSize = nsSize;
+  }
+
+  if (argSize == 0) {
+    argSize = nobjc::kDefaultArgBufferSize;
+  }
+
+  auto buffer = std::make_unique<uint8_t[]>(argSize);
+  memset(buffer.get(), 0, argSize);
+
+  ObjcArgumentContext context = {
+      .className = functionName,
+      .selectorName = functionName,
+      .argumentIndex = argIndex,
+  };
+
+  ExtractJSArgumentToBuffer(env, jsValue, typeEncoding.c_str(), buffer.get(),
+                            context);
+  *outArgPtr = buffer.get();
+
+  NOBJC_LOG("ExtractFunctionArgument: Extracted arg %d (type=%s, size=%zu)",
+            argIndex, typeEncoding.c_str(), argSize);
+  return buffer;
+}
+
+// MARK: - Return Value Conversion
+
+/// Convert an FFI return buffer to a JS value, handling structs.
+inline Napi::Value ConvertFunctionReturnToJS(Napi::Env env, void *returnBuffer,
+                                             const std::string &typeEncoding) {
+  const char *simplified = SimplifyTypeEncoding(typeEncoding.c_str());
+
+  if (*simplified == '{') {
+    // Struct return: unpack to JS object
+    return UnpackStructToJSValue(env, static_cast<const uint8_t *>(returnBuffer),
+                                 typeEncoding.c_str());
+  }
+
+  // Simple type
+  return ConvertFFIReturnToJS(env, returnBuffer, typeEncoding.c_str());
+}
+
+// MARK: - CallFunction Implementation
+
+/// Native implementation of CallFunction.
+///
+/// Arguments:
+///   info[0]: function name (string)
+///   info[1]: return type encoding (string)
+///   info[2]: argument type encodings (array of strings)
+///   info[3]: fixed argument count (number) - if < total args, uses
+///            ffi_prep_cif_var for variadic calling convention
+///   info[4+]: actual arguments
+inline Napi::Value CallFunction(const Napi::CallbackInfo &info) {
+  Napi::Env env = info.Env();
+
+  // Validate minimum arguments
+  if (info.Length() < 4) {
+    throw Napi::TypeError::New(
+        env,
+        "CallFunction requires at least 4 arguments: name, returnType, "
+        "argTypes, fixedArgCount");
+  }
+
+  // Parse function name
+  if (!info[0].IsString()) {
+    throw Napi::TypeError::New(env, "First argument (function name) must be "
+                                    "a string");
+  }
+  std::string functionName = info[0].As<Napi::String>().Utf8Value();
+
+  // Parse return type encoding
+  if (!info[1].IsString()) {
+    throw Napi::TypeError::New(
+        env, "Second argument (return type) must be a string");
+  }
+  std::string returnType = info[1].As<Napi::String>().Utf8Value();
+
+  // Parse argument type encodings
+  if (!info[2].IsArray()) {
+    throw Napi::TypeError::New(
+        env, "Third argument (arg types) must be an array of strings");
+  }
+  Napi::Array argTypesArray = info[2].As<Napi::Array>();
+  uint32_t argCount = argTypesArray.Length();
+
+  std::vector<std::string> argTypes;
+  argTypes.reserve(argCount);
+  for (uint32_t i = 0; i < argCount; i++) {
+    Napi::Value v = argTypesArray.Get(i);
+    if (!v.IsString()) {
+      throw Napi::TypeError::New(
+          env,
+          "Each element of argTypes must be a string (ObjC type encoding)");
+    }
+    argTypes.push_back(v.As<Napi::String>().Utf8Value());
+  }
+
+  // Parse fixed arg count
+  if (!info[3].IsNumber()) {
+    throw Napi::TypeError::New(
+        env, "Fourth argument (fixedArgCount) must be a number");
+  }
+  int fixedArgCount = info[3].As<Napi::Number>().Int32Value();
+
+  // Validate argument count
+  uint32_t providedArgs = info.Length() - 4;
+  if (providedArgs != argCount) {
+    throw Napi::Error::New(
+        env, "Expected " + std::to_string(argCount) +
+                 " arguments but got " + std::to_string(providedArgs) +
+                 " for function '" + functionName + "'");
+  }
+
+  NOBJC_LOG("CallFunction: Looking up '%s' (return=%s, %u args, %d fixed)",
+            functionName.c_str(), returnType.c_str(), argCount,
+            fixedArgCount);
+
+  // Look up the function symbol
+  void *funcPtr = dlsym(RTLD_DEFAULT, functionName.c_str());
+  if (!funcPtr) {
+    throw Napi::Error::New(
+        env, "Function '" + functionName +
+                 "' not found. Make sure the framework is loaded first. "
+                 "dlsym error: " +
+                 std::string(dlerror() ?: "unknown"));
+  }
+
+  NOBJC_LOG("CallFunction: Found '%s' at %p", functionName.c_str(), funcPtr);
+
+  // Build FFI type arrays
+  FFITypeGuard guard;
+
+  // Return type
+  size_t returnSize = 0;
+  ffi_type *returnFFIType =
+      GetFFITypeForEncoding(returnType.c_str(), &returnSize, guard);
+
+  // Argument types
+  std::vector<ffi_type *> argFFITypes;
+  argFFITypes.reserve(argCount);
+  for (uint32_t i = 0; i < argCount; i++) {
+    ffi_type *argType =
+        GetFFITypeForEncoding(argTypes[i].c_str(), nullptr, guard);
+    argFFITypes.push_back(argType);
+  }
+
+  // Prepare the FFI CIF
+  ffi_cif cif;
+  ffi_status status;
+  bool isVariadic =
+      (fixedArgCount >= 0 && static_cast<uint32_t>(fixedArgCount) < argCount);
+
+  if (isVariadic) {
+    NOBJC_LOG("CallFunction: Using variadic CIF (%d fixed, %u total)",
+              fixedArgCount, argCount);
+    status = ffi_prep_cif_var(&cif, FFI_DEFAULT_ABI, fixedArgCount, argCount,
+                              returnFFIType, argFFITypes.data());
+  } else {
+    status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI, argCount, returnFFIType,
+                          argFFITypes.data());
+  }
+
+  if (status != FFI_OK) {
+    throw Napi::Error::New(env,
+                           "Failed to prepare FFI call for function '" +
+                               functionName + "' (ffi_prep_cif status: " +
+                               std::to_string(status) + ")");
+  }
+
+  // Extract arguments from JS values
+  std::vector<void *> argValues(argCount);
+  std::vector<std::unique_ptr<uint8_t[]>> argBuffers;
+  argBuffers.reserve(argCount);
+
+  for (uint32_t i = 0; i < argCount; i++) {
+    void *argPtr = nullptr;
+    auto buffer = ExtractFunctionArgument(env, info[4 + i], argTypes[i],
+                                          &argPtr, functionName, i, guard);
+    argValues[i] = argPtr;
+    argBuffers.push_back(std::move(buffer));
+  }
+
+  // Prepare return buffer
+  std::unique_ptr<uint8_t[]> returnBuffer;
+  const char *simplifiedReturn = SimplifyTypeEncoding(returnType.c_str());
+  bool isVoidReturn = (*simplifiedReturn == 'v');
+
+  if (!isVoidReturn) {
+    size_t bufferSize =
+        returnSize > 0 ? returnSize : nobjc::kMinReturnBufferSize;
+    // Ensure minimum size for ffi_call (must be at least ffi_arg size)
+    if (bufferSize < sizeof(ffi_arg)) {
+      bufferSize = sizeof(ffi_arg);
+    }
+    returnBuffer = std::make_unique<uint8_t[]>(bufferSize);
+    memset(returnBuffer.get(), 0, bufferSize);
+  }
+
+  // Make the FFI call
+  NOBJC_LOG("CallFunction: Calling '%s' with %u args...",
+            functionName.c_str(), argCount);
+  ffi_call(&cif, FFI_FN(funcPtr), returnBuffer ? returnBuffer.get() : nullptr,
+           argCount > 0 ? argValues.data() : nullptr);
+  NOBJC_LOG("CallFunction: '%s' returned successfully", functionName.c_str());
+
+  // Convert return value
+  if (isVoidReturn) {
+    return env.Undefined();
+  }
+
+  return ConvertFunctionReturnToJS(env, returnBuffer.get(), returnType);
+}

package/src/native/forwarding-common.h

@@ -3,6 +3,7 @@
 
 #include "memory-utils.h"
 #include "protocol-storage.h"
+#include <cstring>
 #include <functional>
 #include <napi.h>
 #include <optional>
@@ -13,6 +14,42 @@
 typedef struct NSInvocation NSInvocation;
 #endif
 
+// MARK: - Forwarding Pipeline Cache
+
+/**
+ * Thread-local cache to avoid redundant lock acquisition in the
+ * RespondsToSelector -> MethodSignatureForSelector pipeline.
+ *
+ * A single forwarded call triggers both methods sequentially on the same thread.
+ * By caching the type encoding from RespondsToSelector, MethodSignatureForSelector
+ * can skip the lock entirely on cache hit.
+ */
+struct ForwardingPipelineCache {
+  void* key;        // instance ptr (protocols) or class ptr (subclasses)
+  SEL selector;
+  char typeEncoding[128];
+  bool valid;
+
+  void store(void* k, SEL sel, const char* encoding) {
+    key = k;
+    selector = sel;
+    std::strncpy(typeEncoding, encoding, sizeof(typeEncoding) - 1);
+    typeEncoding[sizeof(typeEncoding) - 1] = '\0';
+    valid = true;
+  }
+
+  void invalidate() { valid = false; }
+
+  bool matches(void* k, SEL sel) const {
+    return valid && key == k && selector == sel;
+  }
+};
+
+inline ForwardingPipelineCache& GetForwardingCache() {
+  static thread_local ForwardingPipelineCache cache = {nullptr, nullptr, "", false};
+  return cache;
+}
+
 // MARK: - Forwarding Context
 
 /**
@@ -51,18 +88,18 @@ struct ForwardingCallbacks {
   // Look up context data under lock. Returns nullopt if not found.
   // Also acquires the TSFN.
   std::function<std::optional<ForwardingContext>(
-      void *lookupKey, const std::string &selectorName)>
+      void *lookupKey, SEL selector)>
       lookupContext;
 
   // Get the JS function for direct call (called within HandleScope).
   // Returns empty function if not found.
-  std::function<Napi::Function(void *lookupKey, const std::string &selectorName,
-                               Napi::Env env)>
+  std::function<Napi::Function(void *lookupKey, SEL selector,
+                                Napi::Env env)>
       getJSFunction;
 
   // Re-acquire TSFN for fallback path. Returns nullopt if not found.
   std::function<std::optional<Napi::ThreadSafeFunction>(
-      void *lookupKey, const std::string &selectorName)>
+      void *lookupKey, SEL selector)>
       reacquireTSFN;
 
   // What callback type to use
@@ -81,7 +118,7 @@ struct ForwardingCallbacks {
  * @param callbacks The storage-specific callback functions
  */
 void ForwardInvocationCommon(NSInvocation *invocation,
-                             const std::string &selectorName, void *lookupKey,
+                             SEL selector, void *lookupKey,
                              const ForwardingCallbacks &callbacks);
 
 #endif // FORWARDING_COMMON_H

package/src/native/forwarding-common.mm

@@ -9,12 +9,14 @@
 // MARK: - ForwardInvocationCommon Implementation
 
 void ForwardInvocationCommon(NSInvocation *invocation,
-                             const std::string &selectorName, void *lookupKey,
+                             SEL selector, void *lookupKey,
                              const ForwardingCallbacks &callbacks) {
+  const char *selectorCStr = sel_getName(selector);
+
   // Look up context data (acquires TSFN)
-  auto contextOpt = callbacks.lookupContext(lookupKey, selectorName);
+  auto contextOpt = callbacks.lookupContext(lookupKey, selector);
   if (!contextOpt) {
-    NOBJC_WARN("Lookup failed for selector %s", selectorName.c_str());
+    NOBJC_WARN("Lookup failed for selector %s", selectorCStr);
     [invocation release];
     return;
   }
@@ -27,7 +29,7 @@ void ForwardInvocationCommon(NSInvocation *invocation,
   // Create invocation data with RAII guard
   auto data = new InvocationData();
   data->invocation = invocation;
-  data->selectorName = selectorName;
+  data->selectorName = selectorCStr;
   data->typeEncoding = ctx.typeEncoding;
   data->callbackType = callbacks.callbackType;
   data->instancePtr = ctx.instancePtr;
@@ -45,7 +47,7 @@ void ForwardInvocationCommon(NSInvocation *invocation,
 
   if (use_direct_call) {
     NOBJC_LOG("ForwardInvocationCommon: Using direct call path for selector %s",
-              selectorName.c_str());
+              selectorCStr);
 
     // Release the TSFN since we're calling directly
     ctx.tsfn.Release();
@@ -66,28 +68,28 @@ void ForwardInvocationCommon(NSInvocation *invocation,
       
       // Fallback to callback lookup if cache miss (shouldn't happen)
       if (jsFn.IsEmpty()) {
-        jsFn = callbacks.getJSFunction(lookupKey, selectorName, callEnv);
+        jsFn = callbacks.getJSFunction(lookupKey, selector, callEnv);
       }
       
       if (jsFn.IsEmpty()) {
         NOBJC_WARN("JS function not found for selector %s (direct path)",
-                   selectorName.c_str());
+                   selectorCStr);
         return; // dataGuard cleans up
       }
 
       // Transfer ownership to CallJSCallback - it will clean up
       CallJSCallback(callEnv, jsFn, dataGuard.release());
       NOBJC_LOG("ForwardInvocationCommon: Direct call succeeded for %s",
-                selectorName.c_str());
+                selectorCStr);
     } catch (const std::exception &e) {
       NOBJC_ERROR("Error calling JS callback directly: %s", e.what());
       NOBJC_LOG("Falling back to ThreadSafeFunction for selector %s",
-                selectorName.c_str());
+                selectorCStr);
 
       // Re-create data for fallback since we may have released it
       auto fallbackData = new InvocationData();
       fallbackData->invocation = invocation;
-      fallbackData->selectorName = selectorName;
+      fallbackData->selectorName = selectorCStr;
       fallbackData->typeEncoding = ctx.typeEncoding;
       fallbackData->callbackType = callbacks.callbackType;
       fallbackData->instancePtr = ctx.instancePtr;
@@ -95,20 +97,21 @@ void ForwardInvocationCommon(NSInvocation *invocation,
       InvocationDataGuard fallbackGuard(fallbackData);
 
       // Re-acquire TSFN for fallback
-      auto tsfnOpt = callbacks.reacquireTSFN(lookupKey, selectorName);
+      auto tsfnOpt = callbacks.reacquireTSFN(lookupKey, selector);
       if (tsfnOpt) {
-        if (FallbackToTSFN(*tsfnOpt, fallbackGuard.release(), selectorName)) {
+        std::string selectorStr(selectorCStr);
+        if (FallbackToTSFN(*tsfnOpt, fallbackGuard.release(), selectorStr)) {
           return; // Data cleaned up in callback
         }
         NOBJC_ERROR("ForwardInvocationCommon: Fallback failed for %s",
-                    selectorName.c_str());
+                    selectorCStr);
       }
       // If we get here, fallbackGuard cleans up
     }
   } else {
     // Cross-thread call via TSFN (or Electron forcing TSFN)
     NOBJC_LOG("ForwardInvocationCommon: Using TSFN+runloop path for selector %s",
-              selectorName.c_str());
+              selectorCStr);
 
     std::mutex completionMutex;
     std::condition_variable completionCv;
@@ -124,7 +127,7 @@ void ForwardInvocationCommon(NSInvocation *invocation,
 
     if (status != napi_ok) {
       NOBJC_ERROR("Failed to call ThreadSafeFunction for selector %s (status: %d)",
-                  selectorName.c_str(), status);
+                  selectorCStr, status);
       // We already released from guard, so clean up manually
       [invocation release];
       delete data;