objc-js 1.2.1 → 1.3.1

package/README.md

@@ -36,6 +36,7 @@ The documentation is organized into several guides:
 - **[C Functions](./docs/c-functions.md)** - Calling C functions like NSLog, NSHomeDirectory, NSStringFromClass
 - **[Structs](./docs/structs.md)** - Passing and receiving C structs (CGRect, NSRange, etc.)
 - **[Subclassing Objective-C Classes](./docs/subclassing.md)** - Creating and subclassing Objective-C classes from JavaScript
+- **[Blocks](./docs/blocks.md)** - Passing JavaScript functions as Objective-C blocks (closures)
 - **[Protocol Implementation](./docs/protocol-implementation.md)** - Creating delegate objects that implement protocols
 - **[API Reference](./docs/api-reference.md)** - Complete API documentation for all classes and functions
 

package/dist/index.js

@@ -32,7 +32,12 @@ class NobjcLibrary {
                     LoadLibrary(library);
                     this.wasLoaded = true;
                 }
-                cls = new NobjcObject(GetClassObject(className));
+                const classObject = GetClassObject(className);
+                if (classObject === undefined) {
+                    // Class not found. Make sure the class exists before trying to access it.
+                    return undefined;
+                }
+                cls = new NobjcObject(classObject);
                 classCache.set(className, cls);
                 return cls;
             }
@@ -55,6 +60,9 @@ class NobjcObject {
                 // Return true for the special Symbol to enable unwrapping
                 if (p === NATIVE_OBJC_OBJECT)
                     return true;
+                // Return true for inspect symbols so console.log uses custom inspect
+                if (p === customInspectSymbol)
+                    return true;
                 // guard against other symbols
                 if (typeof p === "symbol")
                     return Reflect.has(target, p);
@@ -117,6 +125,10 @@ class NobjcObject {
                     // object (avoids triggering proxy 'has' trap which would be a second FFI call)
                     const selector = NobjcMethodNameToObjcSelector(methodName);
                     if (!target.$respondsToSelector(selector)) {
+                        // special case since JS checks for `.then` on Promise objects
+                        if (methodName === "then")
+                            return undefined;
+                        // Otherwise, throw an error
                         throw new Error(`Method ${methodName} not found on object`);
                     }
                     method = NobjcMethod(object, methodName);
@@ -127,6 +139,9 @@ class NobjcObject {
         };
         // Create the proxy
         const proxy = new Proxy(object, handler);
+        // Set custom inspect on the native object so console.log works through the Proxy.
+        // Runtimes (Node, Bun) bypass Proxy traps during inspect and read the target directly.
+        object[customInspectSymbol] = () => proxy.toString();
         // Store proxy → native mapping in WeakMap for O(1) unwrap (bypasses Proxy traps)
         nativeObjectMap.set(proxy, object);
         // Return the proxy
@@ -137,6 +152,20 @@ function unwrapArg(arg) {
     if (arg && typeof arg === "object") {
         return nativeObjectMap.get(arg) ?? arg;
     }
+    // Wrap function arguments so that when called from native (e.g., as ObjC blocks),
+    // the native ObjcObject args are automatically wrapped in NobjcObject proxies.
+    if (typeof arg === "function") {
+        const wrapped = function (...nativeArgs) {
+            for (let i = 0; i < nativeArgs.length; i++) {
+                nativeArgs[i] = wrapObjCObjectIfNeeded(nativeArgs[i]);
+            }
+            return unwrapArg(arg(...nativeArgs));
+        };
+        // Preserve the original function's .length so the native layer can read it
+        // (used to infer block parameter count when extended encoding is unavailable)
+        Object.defineProperty(wrapped, "length", { value: arg.length });
+        return wrapped;
+    }
     return arg;
 }
 function wrapObjCObjectIfNeeded(result) {

package/package.json

@@ -30,7 +30,9 @@
     "prebuild": "node-gyp clean && node-gyp configure",
     "build": "npm run build-native && npm run build-scripts && npm run build-source",
     "pretest": "npm run build",
-    "test": "bun test",
+    "test": "bun run test:bun",
+    "test:bun": "bun run build && bun test",
+    "test:node": "bun run build && npx vitest run",
     "test:native": "bun test tests/test-native-code.test.ts",
     "test:js": "bun test tests/test-js-code.test.ts",
     "test:string-lifetime": "bun test tests/test-string-lifetime.test.ts",
@@ -44,7 +46,7 @@
     "prebuild:x64": "prebuildify --napi --strip --arch x64 -r node",
     "prebuild:all": "bun run prebuild:arm64 && bun run prebuild:x64"
   },
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Objective-C bridge for Node.js",
   "main": "dist/index.js",
   "dependencies": {
@@ -57,7 +59,8 @@
     "node-gyp": "^12.1.0",
     "prebuildify": "^6.0.1",
     "prettier": "^3.7.4",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   },
   "gypfile": true,
   "patchedDependencies": {

package/src/native/ObjcObject.h

@@ -4,11 +4,18 @@
 #include <napi.h>
 #include <objc/objc.h>
 #include <objc/runtime.h>
+#include <objc/message.h>
 #include <optional>
 #include <variant>
 #include <unordered_map>
 #include <vector>
 
+// objc_retain/objc_release are part of the stable ObjC ABI (macOS 10.12+)
+// but not declared in public headers. We use them for manual reference counting
+// since ARC is not enabled for .mm files in this project.
+extern "C" id objc_retain(id value);
+extern "C" void objc_release(id value);
+
 #ifdef __OBJC__
 @class NSMethodSignature;
 #else
@@ -51,6 +58,14 @@ public:
       // This better be an Napi::External<id>! We lost the type info at runtime.
       Napi::External<id> external = info[0].As<Napi::External<id>>();
       objcObject = *(external.Data());
+      // Retain the ObjC object so it stays alive as long as this JS wrapper
+      // exists. Without this, ARC/autorelease can deallocate the object while
+      // JS still holds a reference, causing Use-After-Free crashes (SIGTRAP)
+      // in completion handler callbacks and other async contexts.
+      // Note: ARC is not enabled for .mm files in this project (the -fobjc-arc
+      // flag is in OTHER_CFLAGS, not OTHER_CPLUSPLUSFLAGS), so __strong has
+      // no effect — we must manage retain/release manually.
+      if (objcObject) objc_retain(objcObject);
       return;
     }
     // If someone tries `new ObjcObject()` from JS, forbid it:
@@ -58,7 +73,12 @@ public:
         .ThrowAsJavaScriptException();
   }
   static Napi::Object NewInstance(Napi::Env env, id obj);
-  ~ObjcObject() = default;
+  ~ObjcObject() {
+    if (objcObject) {
+      objc_release(objcObject);
+      objcObject = nil;
+    }
+  }
 
 private:
   Napi::Value $MsgSend(const Napi::CallbackInfo &info);

package/src/native/ObjcObject.mm

@@ -2,6 +2,7 @@
 #include "bridge.h"
 #include "pointer-utils.h"
 #include "struct-utils.h"
+#include "nobjc_block.h"
 #include <Foundation/Foundation.h>
 #include <napi.h>
 #include <objc/objc.h>
@@ -153,6 +154,8 @@ static bool TryFastMsgSend(Napi::Env env, id target, SEL selector,
     const char *argType = SimplifyTypeEncoding(
         [methodSignature getArgumentTypeAtIndex:i + 2]);
     char code = *argType;
+    // Block args (@?) need special handling — bail out of fast path
+    if (code == '@' && argType[1] == '?') return false;
     if (!IsFastPathArgTypeCode(code)) return false;
     argTypeCodes[i] = code;
     if (code == 'f' || code == 'd') hasFloatArgs = true;
@@ -476,6 +479,28 @@ Napi::Value ObjcObject::$MsgSend(const Napi::CallbackInfo &info) {
       continue;
     }
 
+    // Block argument: convert JS function to ObjC block
+    if (IsBlockTypeEncoding(typeEncoding) && info[i].IsFunction()) {
+      // Get extended encoding from method_getTypeEncoding() which preserves @?<...>
+      // NSMethodSignature strips the extended encoding, so we use the runtime directly.
+      // Argument index in NSInvocation is i+1 (0=self, 1=_cmd, 2+=user args)
+      std::string extEncoding = GetExtendedBlockEncoding(
+          object_getClass(objcObject), selector, i + 1);
+      const char *blockEncoding = extEncoding.empty()
+          ? [methodSignature getArgumentTypeAtIndex:i + 1]
+          : extEncoding.c_str();
+      id block = CreateBlockFromJSFunction(env, info[i], blockEncoding);
+      if (env.IsExceptionPending()) return env.Null();
+      [invocation setArgument:&block atIndex:i + 1];
+      // Store block as id in arg buffer to keep it alive until after invoke
+      if (useHeap) {
+        heapArgBuf.push_back(BaseObjcType{block});
+      } else {
+        smallArgBuf[argIdx] = BaseObjcType{block};
+      }
+      continue;
+    }
+
     auto arg = AsObjCArgument(info[i], typeEncoding, context);
     if (!arg.has_value()) {
       std::string errorMessageStr = std::format("Unsupported argument type {}",
@@ -634,6 +659,10 @@ Napi::Value ObjcObject::$PrepareSend(const Napi::CallbackInfo &info) {
         [methodSignature getArgumentTypeAtIndex:i + 2]);
     char code = *argType;
     prepared->argInfos[i] = {code, code == '{'};
+    // Block args (@?) need slow path for JS function → block conversion
+    if (code == '@' && argType[1] == '?') {
+      canFast = false;
+    }
     if (code == '{' || !IsFastPathArgTypeCode(code)) {
       canFast = false;
     }
@@ -738,6 +767,26 @@ Napi::Value ObjcObject::$MsgSendPrepared(const Napi::CallbackInfo &info) {
       continue;
     }
 
+    // Block argument: convert JS function to ObjC block
+    if (IsBlockTypeEncoding(typeEncoding) && info[jsArgIdx].IsFunction()) {
+      // Get extended encoding from method_getTypeEncoding() which preserves @?<...>
+      // Argument index in NSInvocation is i+2 (0=self, 1=_cmd, 2+=user args)
+      std::string extEncoding = GetExtendedBlockEncoding(
+          object_getClass(objcObject), prepared->selector, i + 2);
+      const char *blockEncoding = extEncoding.empty()
+          ? [prepared->methodSignature getArgumentTypeAtIndex:i + 2]
+          : extEncoding.c_str();
+      id block = CreateBlockFromJSFunction(env, info[jsArgIdx], blockEncoding);
+      if (env.IsExceptionPending()) return env.Null();
+      [invocation setArgument:&block atIndex:i + 2];
+      if (useHeap) {
+        heapArgBuf.push_back(BaseObjcType{block});
+      } else {
+        smallArgBuf[i] = BaseObjcType{block};
+      }
+      continue;
+    }
+
     auto arg = AsObjCArgument(info[jsArgIdx], typeEncoding, context);
     if (!arg.has_value()) {
       Napi::TypeError::New(env, std::string("Unsupported argument type ") + typeEncoding)

package/src/native/ffi-utils.h

@@ -208,7 +208,7 @@ inline ffi_type* ParseStructEncoding(const char* encoding, size_t* outSize,
     
     if (*ptr == '}') break;
     
-    std::string fieldEncoding = SkipOneFieldEncoding(ptr);
+    std::string fieldEncoding = SkipOneTypeEncoding(ptr);
     NOBJC_LOG("ParseStructEncoding: parsing field '%s'", fieldEncoding.c_str());
     
     // Recursively get FFI type for this field
@@ -271,6 +271,14 @@ inline ffi_type* GetFFITypeForEncoding(const char* encoding, size_t* outSize,
   
   char firstChar = simpleEncoding[0];
   
+  // Handle block type (@?) — blocks are pointers
+  if (firstChar == '@' && simpleEncoding[1] == '?') {
+    if (outSize) {
+      *outSize = sizeof(void*);
+    }
+    return &ffi_type_pointer;
+  }
+
   // Handle structs and unions
   if (firstChar == '{') {
     return ParseStructEncoding(simpleEncoding, outSize, allocatedTypes);

package/src/native/forwarding-common.h

@@ -3,10 +3,15 @@
 
 #include "memory-utils.h"
 #include "protocol-storage.h"
+#include "constants.h"
+#include "debug.h"
 #include <cstring>
+#include <condition_variable>
 #include <functional>
+#include <mutex>
 #include <napi.h>
 #include <optional>
+#include <CoreFoundation/CoreFoundation.h>
 
 #ifdef __OBJC__
 @class NSInvocation;
@@ -106,6 +111,46 @@ struct ForwardingCallbacks {
   CallbackType callbackType;
 };
 
+// MARK: - Shared Helpers
+
+/**
+ * Pump the CFRunLoop until a completion flag is set.
+ * Used by protocol forwarding, subclass forwarding, and block invocation
+ * to wait for cross-thread JS callbacks to complete.
+ *
+ * @param mutex      Mutex protecting the isComplete flag
+ * @param isComplete Flag set to true when the JS callback completes
+ * @param label      Optional label for debug logging (nullptr to disable)
+ */
+inline void PumpRunLoopUntilComplete(std::mutex &mutex, bool &isComplete,
+                                     const char *label = nullptr) {
+  int iterations = 0;
+  while (true) {
+    {
+      std::unique_lock<std::mutex> lock(mutex);
+      if (isComplete) break;
+    }
+    iterations++;
+    if (label && iterations % nobjc::kRunLoopDebugLogInterval == 0) {
+      NOBJC_LOG("%s: Still waiting... (%d iterations)", label, iterations);
+    }
+    CFRunLoopRunInMode(kCFRunLoopDefaultMode, nobjc::kRunLoopPumpInterval, true);
+  }
+}
+
+/**
+ * Create a ThreadSafeFunction for method forwarding.
+ * Shared factory for protocol, subclass, and block TSFN creation.
+ *
+ * @param env   Napi environment
+ * @param fn    The JS function to wrap
+ * @param name  Resource name for debugging
+ */
+inline Napi::ThreadSafeFunction CreateMethodTSFN(
+    Napi::Env env, const Napi::Function &fn, const std::string &name) {
+  return Napi::ThreadSafeFunction::New(env, fn, name, 0, 1, [](Napi::Env) {});
+}
+
 // MARK: - Common Implementation
 
 /**

package/src/native/forwarding-common.mm

@@ -135,22 +135,8 @@ void ForwardInvocationCommon(NSInvocation *invocation,
     }
 
     // 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);
-    }
+    PumpRunLoopUntilComplete(completionMutex, isComplete,
+                            "ForwardInvocationCommon");
     // Data cleaned up in callback
   }
 

package/src/native/method-forwarding.mm

@@ -158,16 +158,7 @@ bool FallbackToTSFN(Napi::ThreadSafeFunction &tsfn, InvocationData *data,
   }
 
   // Wait for callback by pumping CFRunLoop
-  CFTimeInterval timeout = 0.001; // 1ms per iteration
-  while (true) {
-    {
-      std::unique_lock<std::mutex> lock(completionMutex);
-      if (isComplete) {
-        break;
-      }
-    }
-    CFRunLoopRunInMode(kCFRunLoopDefaultMode, timeout, true);
-  }
+  PumpRunLoopUntilComplete(completionMutex, isComplete);
   
   return true;
 }