objc-js 0.0.15 → 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.15",
+  "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/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
+}

package/src/native/memory-utils.h

@@ -0,0 +1,197 @@
+#ifndef MEMORY_UTILS_H
+#define MEMORY_UTILS_H
+
+#include "debug.h"
+#include "protocol-storage.h"
+#include <Foundation/Foundation.h>
+
+// MARK: - InvocationDataGuard RAII Wrapper
+
+/**
+ * RAII wrapper for InvocationData to ensure proper cleanup.
+ * 
+ * This class manages the lifetime of InvocationData*, ensuring that:
+ * 1. The NSInvocation is released
+ * 2. The InvocationData is deleted
+ * 3. Cleanup happens even when exceptions are thrown
+ * 
+ * Usage:
+ *   auto data = new InvocationData();
+ *   InvocationDataGuard guard(data);
+ *   // ... use data ...
+ *   guard.release();  // Transfer ownership on success
+ * 
+ * If release() is not called, cleanup happens in destructor.
+ */
+class InvocationDataGuard {
+public:
+  explicit InvocationDataGuard(InvocationData* data) : data_(data), released_(false) {
+#if NOBJC_DEBUG
+    if (data_) {
+      NOBJC_LOG("InvocationDataGuard: acquired data=%p, selector=%s", 
+                data_, data_->selectorName.c_str());
+    }
+#endif
+  }
+  
+  // Non-copyable
+  InvocationDataGuard(const InvocationDataGuard&) = delete;
+  InvocationDataGuard& operator=(const InvocationDataGuard&) = delete;
+  
+  // Movable
+  InvocationDataGuard(InvocationDataGuard&& other) noexcept 
+      : data_(other.data_), released_(other.released_) {
+    other.data_ = nullptr;
+    other.released_ = true;
+  }
+  
+  InvocationDataGuard& operator=(InvocationDataGuard&& other) noexcept {
+    if (this != &other) {
+      cleanup();
+      data_ = other.data_;
+      released_ = other.released_;
+      other.data_ = nullptr;
+      other.released_ = true;
+    }
+    return *this;
+  }
+  
+  ~InvocationDataGuard() {
+    cleanup();
+  }
+  
+  /**
+   * Release ownership of the data without cleanup.
+   * Call this when you're transferring ownership elsewhere (e.g., to a callback).
+   * @return The raw pointer (caller takes ownership)
+   */
+  InvocationData* release() {
+    released_ = true;
+    InvocationData* ptr = data_;
+    data_ = nullptr;
+#if NOBJC_DEBUG
+    if (ptr) {
+      NOBJC_LOG("InvocationDataGuard: released ownership of data=%p", ptr);
+    }
+#endif
+    return ptr;
+  }
+  
+  /**
+   * Get the raw pointer without releasing ownership.
+   */
+  InvocationData* get() const { return data_; }
+  
+  /**
+   * Check if the guard has valid data.
+   */
+  explicit operator bool() const { return data_ != nullptr && !released_; }
+  
+  /**
+   * Arrow operator for convenient access.
+   */
+  InvocationData* operator->() const { return data_; }
+  
+private:
+  void cleanup() {
+    if (data_ && !released_) {
+#if NOBJC_DEBUG
+      NOBJC_LOG("InvocationDataGuard: cleaning up data=%p, selector=%s", 
+                data_, data_->selectorName.c_str());
+#endif
+      // Release the NSInvocation if present
+      if (data_->invocation) {
+        [data_->invocation release];
+        data_->invocation = nil;
+      }
+      
+      // Delete the data
+      delete data_;
+      data_ = nullptr;
+    }
+  }
+  
+  InvocationData* data_;
+  bool released_;
+};
+
+// MARK: - Cleanup Callback for CallJSCallback
+
+/**
+ * Helper function to clean up InvocationData after a JS callback completes.
+ * This is called from CallJSCallback to ensure proper cleanup regardless of
+ * success or failure.
+ * 
+ * @param data The InvocationData to clean up (takes ownership)
+ */
+inline void CleanupInvocationData(InvocationData* data) {
+  if (!data) return;
+  
+#if NOBJC_DEBUG
+  NOBJC_LOG("CleanupInvocationData: cleaning up selector=%s", 
+            data->selectorName.c_str());
+#endif
+  
+  // Signal completion if we have synchronization primitives
+  SignalInvocationComplete(data);
+  
+  // Release the invocation
+  if (data->invocation) {
+    [data->invocation release];
+    data->invocation = nil;
+  }
+  
+  // Delete the data
+  delete data;
+}
+
+// MARK: - ScopeGuard for Generic Cleanup
+
+/**
+ * Generic scope guard for executing cleanup code on scope exit.
+ * 
+ * Usage:
+ *   auto guard = MakeScopeGuard([&] { cleanup_code(); });
+ *   // ... do work ...
+ *   guard.dismiss();  // Don't run cleanup on success
+ */
+template<typename Func>
+class ScopeGuard {
+public:
+  explicit ScopeGuard(Func&& func) : func_(std::forward<Func>(func)), active_(true) {}
+  
+  ScopeGuard(ScopeGuard&& other) noexcept 
+      : func_(std::move(other.func_)), active_(other.active_) {
+    other.active_ = false;
+  }
+  
+  ~ScopeGuard() {
+    if (active_) {
+      try {
+        func_();
+      } catch (...) {
+        // Suppress exceptions in destructor
+#if NOBJC_DEBUG
+        NOBJC_ERROR("ScopeGuard: exception during cleanup (suppressed)");
+#endif
+      }
+    }
+  }
+  
+  void dismiss() { active_ = false; }
+  
+  // Non-copyable
+  ScopeGuard(const ScopeGuard&) = delete;
+  ScopeGuard& operator=(const ScopeGuard&) = delete;
+  
+private:
+  Func func_;
+  bool active_;
+};
+
+template<typename Func>
+ScopeGuard<Func> MakeScopeGuard(Func&& func) {
+  return ScopeGuard<Func>(std::forward<Func>(func));
+}
+
+#endif // MEMORY_UTILS_H