objc-js 0.0.14 → 1.0.0

package/binding.gyp

@@ -7,7 +7,8 @@
                 "src/native/ObjcObject.mm",
                 "src/native/protocol-impl.mm",
                 "src/native/method-forwarding.mm",
-                "src/native/subclass-impl.mm"
+                "src/native/subclass-impl.mm",
+                "src/native/forwarding-common.mm"
             ],
             "defines": [
                 "NODE_ADDON_API_CPP_EXCEPTIONS",

package/package.json

@@ -7,6 +7,7 @@
     "darwin"
   ],
   "repository": "https://github.com/iamEvanYT/objc-js",
+  "homepage": "https://github.com/iamEvanYT/objc-js#readme",
   "author": "iamEvan",
   "imports": {
     "#nobjc_native": "./build/Release/nobjc_native.node"
@@ -39,7 +40,7 @@
     "format": "prettier --write \"**/*.{ts,js,json,md}\"",
     "preinstall-disabled": "npm run build-scripts && npm run make-clangd-config"
   },
-  "version": "0.0.14",
+  "version": "1.0.0",
   "description": "Objective-C bridge for Node.js",
   "main": "dist/index.js",
   "dependencies": {

package/src/native/ObjcObject.mm

@@ -1,5 +1,6 @@
 #include "ObjcObject.h"
 #include "bridge.h"
+#include "pointer-utils.h"
 #include <Foundation/Foundation.h>
 #include <napi.h>
 #include <objc/objc.h>
@@ -133,18 +134,5 @@ Napi::Value ObjcObject::$MsgSend(const Napi::CallbackInfo &info) {
 
 Napi::Value ObjcObject::GetPointer(const Napi::CallbackInfo &info) {
   Napi::Env env = info.Env();
-  
-  // Get the pointer value of the Objective-C object
-  uintptr_t ptrValue = reinterpret_cast<uintptr_t>(objcObject);
-  
-  // Create a Buffer to hold the pointer (8 bytes on 64-bit macOS)
-  Napi::Buffer<uint8_t> buffer = Napi::Buffer<uint8_t>::New(env, sizeof(void*));
-  
-  // Write the pointer value to the buffer in little-endian format
-  uint8_t* data = buffer.Data();
-  for (size_t i = 0; i < sizeof(void*); ++i) {
-    data[i] = static_cast<uint8_t>((ptrValue >> (i * 8)) & 0xFF);
-  }
-  
-  return buffer;
+  return PointerToBuffer(env, objcObject);
 }

package/src/native/bridge.h

@@ -173,6 +173,10 @@ template <typename T>
 T ConvertToNativeValue(const Napi::Value &value,
                        const ObjcArgumentContext &context) {
   if constexpr (std::is_same_v<T, id>) {
+    // Handle null/undefined as nil
+    if (value.IsNull() || value.IsUndefined()) {
+      return nil;
+    }
     // is value an ObjcObject instance?
     if (value.IsObject()) {
       Napi::Object obj = value.As<Napi::Object>();
@@ -183,6 +187,10 @@ T ConvertToNativeValue(const Napi::Value &value,
     }
   }
   if constexpr (std::is_same_v<T, SEL>) {
+    // Handle null/undefined as NULL selector
+    if (value.IsNull() || value.IsUndefined()) {
+      return nullptr;
+    }
     if (!value.IsString()) {
       throw Napi::TypeError::New(value.Env(),
                                  CONVERT_ARG_ERROR_MSG("Expected a string"));
@@ -191,18 +199,30 @@ T ConvertToNativeValue(const Napi::Value &value,
     return sel_registerName(selName.c_str());
   }
   if constexpr (std::is_same_v<T, bool>) {
+    // Handle null/undefined as false
+    if (value.IsNull() || value.IsUndefined()) {
+      return false;
+    }
     if (!value.IsBoolean()) {
       throw Napi::TypeError::New(value.Env(),
                                  CONVERT_ARG_ERROR_MSG("Expected a boolean"));
     }
     return value.As<Napi::Boolean>().Value();
   } else if constexpr (std::is_same_v<T, std::string>) {
+    // Handle null/undefined as empty string
+    if (value.IsNull() || value.IsUndefined()) {
+      return std::string();
+    }
     if (!value.IsString()) {
       throw Napi::TypeError::New(value.Env(),
                                  CONVERT_ARG_ERROR_MSG("Expected a string"));
     }
     return value.As<Napi::String>().Utf8Value();
   } else if constexpr (std::is_arithmetic_v<T>) {
+    // Handle null/undefined as 0
+    if (value.IsNull() || value.IsUndefined()) {
+      return static_cast<T>(0);
+    }
     if (value.IsNumber()) {
       return ConvertJSNumberToNativeValue<T>(value, context);
     } else if (value.IsBigInt()) {

package/src/native/constants.h

@@ -0,0 +1,42 @@
+#pragma once
+
+// ============================================================================
+// constants.h - Named Constants for nobjc
+// ============================================================================
+//
+// This header centralizes magic numbers and configuration values used
+// throughout the codebase for better maintainability and documentation.
+//
+
+#include <cstddef>
+#include <CoreFoundation/CoreFoundation.h>
+
+namespace nobjc {
+
+// MARK: - RunLoop Configuration
+
+/// Time interval (in seconds) for each CFRunLoop iteration when waiting for
+/// JS callback completion. Smaller values = more responsive but higher CPU.
+constexpr CFTimeInterval kRunLoopPumpInterval = 0.001;  // 1ms
+
+/// Number of runloop iterations between debug log messages when waiting.
+/// Set to 1000 = log every ~1 second at kRunLoopPumpInterval of 1ms.
+constexpr int kRunLoopDebugLogInterval = 1000;
+
+// MARK: - Buffer Sizes
+
+/// Minimum size for return value buffers (handles pointer-sized returns).
+constexpr size_t kMinReturnBufferSize = 16;
+
+/// Buffer size for type encoding strings (stack allocation).
+constexpr size_t kTypeEncodingBufferSize = 64;
+
+// MARK: - FFI Configuration
+
+/// Default buffer size for FFI argument storage when type size is unknown.
+constexpr size_t kDefaultArgBufferSize = sizeof(void*);
+
+/// Size of pointer storage for out-parameters (e.g., NSError**).
+constexpr size_t kOutParamPointerSize = sizeof(void*);
+
+}  // namespace nobjc

package/src/native/ffi-utils.h

@@ -12,6 +12,102 @@
 #include "bridge.h"
 #include "type-conversion.h"
 
+// MARK: - FFITypeGuard RAII Wrapper
+
+/**
+ * RAII wrapper for managing dynamically allocated ffi_type structs.
+ * 
+ * FFI struct types require heap allocation for their elements arrays.
+ * This class ensures proper cleanup when going out of scope, even if
+ * exceptions are thrown.
+ * 
+ * Usage:
+ *   FFITypeGuard guard;
+ *   ffi_type* structType = ParseStructEncoding(encoding, &size, guard);
+ *   // ... use structType ...
+ *   // Cleanup happens automatically when guard goes out of scope
+ */
+class FFITypeGuard {
+public:
+  FFITypeGuard() = default;
+  
+  // Non-copyable
+  FFITypeGuard(const FFITypeGuard&) = delete;
+  FFITypeGuard& operator=(const FFITypeGuard&) = delete;
+  
+  // Movable
+  FFITypeGuard(FFITypeGuard&& other) noexcept : allocatedTypes_(std::move(other.allocatedTypes_)) {
+    other.allocatedTypes_.clear();
+  }
+  
+  FFITypeGuard& operator=(FFITypeGuard&& other) noexcept {
+    if (this != &other) {
+      cleanup();
+      allocatedTypes_ = std::move(other.allocatedTypes_);
+      other.allocatedTypes_.clear();
+    }
+    return *this;
+  }
+  
+  ~FFITypeGuard() {
+    cleanup();
+  }
+  
+  /**
+   * Add a dynamically allocated ffi_type to be managed.
+   * The guard takes ownership and will free it on destruction.
+   */
+  void add(ffi_type* type) {
+    if (type) {
+      allocatedTypes_.push_back(type);
+#if NOBJC_DEBUG
+      NOBJC_LOG("FFITypeGuard: added type=%p (total: %zu)", type, allocatedTypes_.size());
+#endif
+    }
+  }
+  
+  /**
+   * Get the underlying vector (for passing to legacy functions).
+   */
+  std::vector<ffi_type*>& types() { return allocatedTypes_; }
+  
+  /**
+   * Release ownership of all types without cleanup.
+   * Use when transferring ownership elsewhere.
+   */
+  std::vector<ffi_type*> release() {
+    std::vector<ffi_type*> result = std::move(allocatedTypes_);
+    allocatedTypes_.clear();
+#if NOBJC_DEBUG
+    NOBJC_LOG("FFITypeGuard: released ownership of %zu types", result.size());
+#endif
+    return result;
+  }
+  
+  /**
+   * Get number of managed types.
+   */
+  size_t size() const { return allocatedTypes_.size(); }
+  
+private:
+  void cleanup() {
+    if (!allocatedTypes_.empty()) {
+#if NOBJC_DEBUG
+      NOBJC_LOG("FFITypeGuard: cleaning up %zu types", allocatedTypes_.size());
+#endif
+      for (ffi_type* type : allocatedTypes_) {
+        if (type && type->type == FFI_TYPE_STRUCT && type->elements) {
+          delete[] type->elements;
+        }
+        delete type;
+      }
+      allocatedTypes_.clear();
+    }
+  }
+  
+  std::vector<ffi_type*> allocatedTypes_;
+};
+
 // MARK: - Type Size Calculation
 
 inline size_t GetSizeForTypeEncoding(char typeCode) {
@@ -73,10 +169,16 @@ inline ffi_type* GetFFITypeForSimpleEncoding(char typeCode) {
   }
 }
 
-// Forward declaration
+// Forward declarations
 inline ffi_type* GetFFITypeForEncoding(const char* encoding, size_t* outSize, 
                                       std::vector<ffi_type*>& allocatedTypes);
 
+// Overload that works with FFITypeGuard (preferred)
+inline ffi_type* GetFFITypeForEncoding(const char* encoding, size_t* outSize, 
+                                      FFITypeGuard& guard) {
+  return GetFFITypeForEncoding(encoding, outSize, guard.types());
+}
+
 // MARK: - Struct Type Parsing
 
 inline ffi_type* ParseStructEncoding(const char* encoding, size_t* outSize, 

package/src/native/forwarding-common.h

@@ -0,0 +1,87 @@
+#ifndef FORWARDING_COMMON_H
+#define FORWARDING_COMMON_H
+
+#include "memory-utils.h"
+#include "protocol-storage.h"
+#include <functional>
+#include <napi.h>
+#include <optional>
+
+#ifdef __OBJC__
+@class NSInvocation;
+#else
+typedef struct NSInvocation NSInvocation;
+#endif
+
+// MARK: - Forwarding Context
+
+/**
+ * Context data gathered during the initial lookup phase.
+ * This contains everything needed to perform the invocation.
+ * 
+ * Performance optimization: We cache the JS function reference here
+ * so that getJSFunction doesn't need to re-acquire the mutex.
+ */
+struct ForwardingContext {
+  Napi::ThreadSafeFunction tsfn;
+  std::string typeEncoding;
+  pthread_t js_thread;
+  napi_env env;
+  bool skipDirectCallForElectron;  // Protocol path skips direct for Electron
+
+  // Subclass-specific (set to nullptr/0 for protocols)
+  void *instancePtr;
+  void *superClassPtr;
+  
+  // Cached JS function reference (avoids re-acquiring mutex in getJSFunction)
+  // This is a raw pointer to the FunctionReference stored in the global map.
+  // It remains valid as long as the implementation exists.
+  Napi::FunctionReference* cachedJsCallback;
+
+  ForwardingContext()
+      : js_thread(0), env(nullptr), skipDirectCallForElectron(false),
+        instancePtr(nullptr), superClassPtr(nullptr), cachedJsCallback(nullptr) {}
+};
+
+/**
+ * Callbacks for storage-specific operations.
+ * This allows ForwardInvocationCommon to work with both protocols and subclasses.
+ */
+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)>
+      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)>
+      getJSFunction;
+
+  // Re-acquire TSFN for fallback path. Returns nullopt if not found.
+  std::function<std::optional<Napi::ThreadSafeFunction>(
+      void *lookupKey, const std::string &selectorName)>
+      reacquireTSFN;
+
+  // What callback type to use
+  CallbackType callbackType;
+};
+
+// MARK: - Common Implementation
+
+/**
+ * Common implementation for method forwarding.
+ *
+ * @param invocation The NSInvocation to forward
+ * @param selectorName The selector name as a string
+ * @param lookupKey The key to use for storage lookup (instance ptr for protocols,
+ *                  class ptr for subclasses)
+ * @param callbacks The storage-specific callback functions
+ */
+void ForwardInvocationCommon(NSInvocation *invocation,
+                             const std::string &selectorName, void *lookupKey,
+                             const ForwardingCallbacks &callbacks);
+
+#endif // FORWARDING_COMMON_H

package/src/native/forwarding-common.mm

@@ -0,0 +1,155 @@
+#include "forwarding-common.h"
+#include "constants.h"
+#include "debug.h"
+#include "method-forwarding.h"
+#include <Foundation/Foundation.h>
+#include <atomic>
+#include <chrono>
+
+// MARK: - ForwardInvocationCommon Implementation
+
+void ForwardInvocationCommon(NSInvocation *invocation,
+                             const std::string &selectorName, void *lookupKey,
+                             const ForwardingCallbacks &callbacks) {
+  // Look up context data (acquires TSFN)
+  auto contextOpt = callbacks.lookupContext(lookupKey, selectorName);
+  if (!contextOpt) {
+    NOBJC_WARN("Lookup failed for selector %s", selectorName.c_str());
+    [invocation release];
+    return;
+  }
+
+  ForwardingContext ctx = std::move(*contextOpt);
+
+  // Check if we're on the JS thread
+  bool is_js_thread = pthread_equal(pthread_self(), ctx.js_thread);
+
+  // Create invocation data with RAII guard
+  auto data = new InvocationData();
+  data->invocation = invocation;
+  data->selectorName = selectorName;
+  data->typeEncoding = ctx.typeEncoding;
+  data->callbackType = callbacks.callbackType;
+  data->instancePtr = ctx.instancePtr;
+  data->superClassPtr = ctx.superClassPtr;
+
+  InvocationDataGuard dataGuard(data);
+
+  napi_status status;
+
+  // IMPORTANT: We call directly on the JS thread so return values are set
+  // synchronously; otherwise we use a ThreadSafeFunction to marshal work.
+  // EXCEPTION: For protocols in Electron, we ALWAYS use TSFN even on the JS
+  // thread because Electron's V8 context may not be properly set up.
+  bool use_direct_call = is_js_thread && !ctx.skipDirectCallForElectron;
+
+  if (use_direct_call) {
+    NOBJC_LOG("ForwardInvocationCommon: Using direct call path for selector %s",
+              selectorName.c_str());
+
+    // Release the TSFN since we're calling directly
+    ctx.tsfn.Release();
+
+    data->completionMutex = nullptr;
+    data->completionCv = nullptr;
+    data->isComplete = nullptr;
+
+    try {
+      Napi::Env callEnv(ctx.env);
+      Napi::HandleScope scope(callEnv);
+
+      // Use cached JS function reference (avoids re-acquiring mutex)
+      Napi::Function jsFn;
+      if (ctx.cachedJsCallback && !ctx.cachedJsCallback->IsEmpty()) {
+        jsFn = ctx.cachedJsCallback->Value();
+      }
+      
+      // Fallback to callback lookup if cache miss (shouldn't happen)
+      if (jsFn.IsEmpty()) {
+        jsFn = callbacks.getJSFunction(lookupKey, selectorName, callEnv);
+      }
+      
+      if (jsFn.IsEmpty()) {
+        NOBJC_WARN("JS function not found for selector %s (direct path)",
+                   selectorName.c_str());
+        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());
+    } 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());
+
+      // Re-create data for fallback since we may have released it
+      auto fallbackData = new InvocationData();
+      fallbackData->invocation = invocation;
+      fallbackData->selectorName = selectorName;
+      fallbackData->typeEncoding = ctx.typeEncoding;
+      fallbackData->callbackType = callbacks.callbackType;
+      fallbackData->instancePtr = ctx.instancePtr;
+      fallbackData->superClassPtr = ctx.superClassPtr;
+      InvocationDataGuard fallbackGuard(fallbackData);
+
+      // Re-acquire TSFN for fallback
+      auto tsfnOpt = callbacks.reacquireTSFN(lookupKey, selectorName);
+      if (tsfnOpt) {
+        if (FallbackToTSFN(*tsfnOpt, fallbackGuard.release(), selectorName)) {
+          return; // Data cleaned up in callback
+        }
+        NOBJC_ERROR("ForwardInvocationCommon: Fallback failed for %s",
+                    selectorName.c_str());
+      }
+      // 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());
+
+    std::mutex completionMutex;
+    std::condition_variable completionCv;
+    bool isComplete = false;
+
+    data->completionMutex = &completionMutex;
+    data->completionCv = &completionCv;
+    data->isComplete = &isComplete;
+
+    // Transfer ownership to TSFN callback
+    status = ctx.tsfn.NonBlockingCall(dataGuard.release(), CallJSCallback);
+    ctx.tsfn.Release();
+
+    if (status != napi_ok) {
+      NOBJC_ERROR("Failed to call ThreadSafeFunction for selector %s (status: %d)",
+                  selectorName.c_str(), status);
+      // We already released from guard, so clean up manually
+      [invocation release];
+      delete data;
+      return;
+    }
+
+    // Wait for callback by pumping CFRunLoop
+    int iterations = 0;
+
+    while (true) {
+      {
+        std::unique_lock<std::mutex> lock(completionMutex);
+        if (isComplete) {
+          break;
+        }
+      }
+      iterations++;
+      if (iterations % nobjc::kRunLoopDebugLogInterval == 0) {
+        NOBJC_LOG("ForwardInvocationCommon: Still waiting... (%d iterations)",
+                  iterations);
+      }
+      CFRunLoopRunInMode(kCFRunLoopDefaultMode, nobjc::kRunLoopPumpInterval, true);
+    }
+    // Data cleaned up in callback
+  }
+
+  // Return value (if any) has been set on the invocation
+}