objc-js 1.4.0 → 1.5.0

package/dist/index.d.ts

@@ -7,6 +7,37 @@ declare class NobjcObject {
     [key: string]: NobjcMethod;
     constructor(object: NobjcNative.ObjcObject);
 }
+export interface TypedBlockOptions {
+    /**
+     * Block return type encoding. Example: "v" (void), "@" (id), "B" (BOOL).
+     */
+    returns: string;
+    /**
+     * Block argument type encodings, excluding the implicit block-self (@?) parameter.
+     * Example: ["@", "Q", "^B"] for enumerateObjectsUsingBlock:.
+     */
+    args?: string[];
+    /**
+     * Full block type encoding. Example: "@?<v@?@Q^B>".
+     * When provided, this takes precedence over returns/args.
+     */
+    types?: string;
+}
+/**
+ * Attach an explicit block signature to a JavaScript function.
+ *
+ * Use this when Objective-C only exposes `@?` for a block parameter and
+ * objc-js would otherwise have to guess the callback argument types.
+ *
+ * @example
+ * ```typescript
+ * const handler = typedBlock({ returns: "v", args: ["@", "Q", "^B"] }, (obj, idx, stop) => {
+ *   console.log(obj.toString(), idx, stop);
+ * });
+ * array.enumerateObjectsUsingBlock$(handler);
+ * ```
+ */
+declare function typedBlock<T extends (...args: any[]) => any>(signature: string | TypedBlockOptions, fn: T): T;
 interface NobjcMethod {
     (...args: any[]): any;
 }
@@ -297,4 +328,4 @@ declare const RunLoop: {
      */
     stop(): void;
 };
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, RunLoop, getPointer, fromPointer, callFunction, callVariadicFunction };
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, typedBlock, RunLoop, getPointer, fromPointer, callFunction, callVariadicFunction };

package/dist/index.js

@@ -1,6 +1,7 @@
 import { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction } from "./native.js";
 const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
 const NATIVE_OBJC_OBJECT = Symbol("nativeObjcObject");
+const TYPED_BLOCK_ENCODING = "__nobjcBlockTypeEncoding";
 // WeakMap side-channel for O(1) proxy → native object lookup (bypasses Proxy traps)
 const nativeObjectMap = new WeakMap();
 // Module-scope Set for O(1) lookup instead of per-access array with O(n) .includes()
@@ -148,6 +149,44 @@ class NobjcObject {
         return proxy;
     }
 }
+function normalizeTypedBlockEncoding(signature) {
+    if (typeof signature === "string") {
+        if (!signature.startsWith("@?")) {
+            throw new TypeError("typedBlock(string, fn) expects a full block type encoding starting with '@?'");
+        }
+        return signature;
+    }
+    if (signature.types !== undefined) {
+        if (!signature.types.startsWith("@?")) {
+            throw new TypeError("typedBlock({ types }, fn) expects a full block type encoding starting with '@?'");
+        }
+        return signature.types;
+    }
+    const args = signature.args ?? [];
+    return `@?<${signature.returns}@?${args.join("")}>`;
+}
+/**
+ * Attach an explicit block signature to a JavaScript function.
+ *
+ * Use this when Objective-C only exposes `@?` for a block parameter and
+ * objc-js would otherwise have to guess the callback argument types.
+ *
+ * @example
+ * ```typescript
+ * const handler = typedBlock({ returns: "v", args: ["@", "Q", "^B"] }, (obj, idx, stop) => {
+ *   console.log(obj.toString(), idx, stop);
+ * });
+ * array.enumerateObjectsUsingBlock$(handler);
+ * ```
+ */
+function typedBlock(signature, fn) {
+    Object.defineProperty(fn, TYPED_BLOCK_ENCODING, {
+        value: normalizeTypedBlockEncoding(signature),
+        enumerable: false,
+        configurable: true
+    });
+    return fn;
+}
 function unwrapArg(arg) {
     if (arg && typeof arg === "object") {
         return nativeObjectMap.get(arg) ?? arg;
@@ -161,6 +200,14 @@ function unwrapArg(arg) {
             }
             return unwrapArg(arg(...nativeArgs));
         };
+        const explicitBlockEncoding = arg[TYPED_BLOCK_ENCODING];
+        if (typeof explicitBlockEncoding === "string") {
+            Object.defineProperty(wrapped, TYPED_BLOCK_ENCODING, {
+                value: explicitBlockEncoding,
+                enumerable: false,
+                configurable: true
+            });
+        }
         // 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 });
@@ -697,4 +744,4 @@ const RunLoop = {
         }
     }
 };
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, RunLoop, getPointer, fromPointer, callFunction, callVariadicFunction };
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, typedBlock, RunLoop, getPointer, fromPointer, callFunction, callVariadicFunction };

package/package.json

@@ -47,7 +47,7 @@
     "prebuild:x64": "prebuildify --napi --strip --arch x64 -r node",
     "prebuild:all": "bun run prebuild:arm64 && bun run prebuild:x64"
   },
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Objective-C bridge for Node.js",
   "main": "dist/index.js",
   "dependencies": {

package/src/native/ObjcObject.h

@@ -47,11 +47,17 @@ struct PreparedSend {
   std::vector<ArgInfo> argInfos;
 };
 
+struct NobjcEnvData {
+  Napi::FunctionReference objcObjectConstructor;
+};
+
 class ObjcObject : public Napi::ObjectWrap<ObjcObject> {
 public:
   __strong id objcObject;
-  static Napi::FunctionReference constructor;
   static void Init(Napi::Env env, Napi::Object exports);
+  static NobjcEnvData *GetEnvData(Napi::Env env);
+  static Napi::FunctionReference &GetConstructorRef(Napi::Env env);
+  static bool IsInstance(Napi::Env env, const Napi::Value &value);
   ObjcObject(const Napi::CallbackInfo &info)
       : Napi::ObjectWrap<ObjcObject>(info), objcObject(nil) {
     if (info.Length() == 1 && info[0].IsExternal()) {

package/src/native/ObjcObject.mm

@@ -311,7 +311,24 @@ struct ClassSELHash {
 static std::unordered_map<std::pair<Class, SEL>, NSMethodSignature *, ClassSELHash>
     methodSignatureCache;
 
-Napi::FunctionReference ObjcObject::constructor;
+NobjcEnvData *ObjcObject::GetEnvData(Napi::Env env) {
+  NobjcEnvData *data = env.GetInstanceData<NobjcEnvData>();
+  if (data == nullptr) {
+    throw Napi::Error::New(env, "objc-js addon state is not initialized");
+  }
+  return data;
+}
+
+Napi::FunctionReference &ObjcObject::GetConstructorRef(Napi::Env env) {
+  return GetEnvData(env)->objcObjectConstructor;
+}
+
+bool ObjcObject::IsInstance(Napi::Env env, const Napi::Value &value) {
+  if (!value.IsObject()) {
+    return false;
+  }
+  return value.As<Napi::Object>().InstanceOf(GetConstructorRef(env).Value());
+}
 
 void ObjcObject::Init(Napi::Env env, Napi::Object exports) {
   Napi::Function func =
@@ -323,8 +340,7 @@ void ObjcObject::Init(Napi::Env env, Napi::Object exports) {
                       InstanceMethod("$msgSendPrepared", &ObjcObject::$MsgSendPrepared),
                       InstanceMethod("$getPointer", &ObjcObject::GetPointer),
                   });
-  constructor = Napi::Persistent(func);
-  constructor.SuppressDestruct();
+  GetConstructorRef(env) = Napi::Persistent(func);
   exports.Set("ObjcObject", func);
 }
 
@@ -332,7 +348,8 @@ Napi::Object ObjcObject::NewInstance(Napi::Env env, id obj) {
   Napi::EscapableHandleScope scope(env);
   // `obj` is already a pointer, technically, but the Napi::External
   //  API expects a pointer, so we have to pointer to the pointer.
-  Napi::Object jsObj = constructor.New({Napi::External<id>::New(env, &obj)});
+  Napi::Object jsObj =
+      GetConstructorRef(env).New({Napi::External<id>::New(env, &obj)});
   return scope.Escape(jsObj).ToObject();
 }
 

package/src/native/bridge.h

@@ -181,7 +181,7 @@ T ConvertToNativeValue(const Napi::Value &value,
     // is value an ObjcObject instance?
     if (value.IsObject()) {
       Napi::Object obj = value.As<Napi::Object>();
-      if (obj.InstanceOf(ObjcObject::constructor.Value())) {
+      if (ObjcObject::IsInstance(value.Env(), obj)) {
         ObjcObject *objcObj = Napi::ObjectWrap<ObjcObject>::Unwrap(obj);
         return objcObj->objcObject;
       }

package/src/native/nobjc.mm

@@ -43,7 +43,7 @@ Napi::Value GetPointer(const Napi::CallbackInfo &info) {
   }
   
   Napi::Object obj = info[0].As<Napi::Object>();
-  if (!obj.InstanceOf(ObjcObject::constructor.Value())) {
+  if (!ObjcObject::IsInstance(env, obj)) {
     throw Napi::TypeError::New(env, "Argument must be an ObjcObject instance");
   }
   
@@ -103,7 +103,12 @@ Napi::Value PumpRunLoop(const Napi::CallbackInfo &info) {
   }
 }
 
+static void CleanupEnvData(napi_env, void *data, void *) {
+  delete static_cast<NobjcEnvData *>(data);
+}
+
 Napi::Object InitAll(Napi::Env env, Napi::Object exports) {
+  napi_set_instance_data(env, new NobjcEnvData(), CleanupEnvData, nullptr);
   ObjcObject::Init(env, exports);
   exports.Set("LoadLibrary", Napi::Function::New(env, LoadLibrary));
   exports.Set("GetClassObject", Napi::Function::New(env, GetClassObject));

package/src/native/nobjc_block.h

@@ -40,6 +40,7 @@
 #include <Block.h>
 #include <Foundation/Foundation.h>
 #include <atomic>
+#include <dlfcn.h>
 #include <ffi.h>
 #include <napi.h>
 #include <objc/runtime.h>
@@ -316,6 +317,8 @@ struct BlockInfo {
   }
 };
 
+constexpr const char *kTypedBlockEncodingProperty = "__nobjcBlockTypeEncoding";
+
 // MARK: - Block Call Data (transient, for cross-thread invocation)
 
 /**
@@ -400,7 +403,64 @@ inline void NobjcBlockDisposeHelper(const void *src) {
  * 1. Tagged pointers (arm64: high bit set) are always valid objects
  * 2. Use malloc_zone_from_ptr() to check if it's a heap allocation
  * 3. If it is, verify it has a valid class pointer
+ * 4. Fall back to image-backed singleton detection for constant objects like
+ *    __NSArray0 that live in the dyld shared cache instead of malloc heap
  */
+inline bool PointerResolvesToLoadedImage(const void *ptr) {
+  if (!ptr) return false;
+  Dl_info info;
+  return dladdr(ptr, &info) != 0;
+}
+
+inline uintptr_t GetObjCIsaClassMask() {
+  static uintptr_t mask = []() -> uintptr_t {
+    void *symbol = dlsym(RTLD_DEFAULT, "objc_debug_isa_class_mask");
+    if (symbol) {
+      return *static_cast<const uintptr_t *>(symbol);
+    }
+
+#if defined(__aarch64__) || defined(__arm64__)
+    return 0x0000000ffffffff8ULL;
+#elif defined(__x86_64__)
+    return 0x00007ffffffffff8ULL;
+#else
+    return 0;
+#endif
+  }();
+  return mask;
+}
+
+inline bool LooksLikeImageBackedObjCObject(uintptr_t val) {
+  void *ptr = reinterpret_cast<void *>(val);
+  if (!PointerResolvesToLoadedImage(ptr)) return false;
+
+  // Image-backed singleton objects (for example __NSArray0) are not malloc
+  // allocations, so inspect the isa word and see if it resolves to something
+  // that also looks like a class pointer in a loaded image.
+  uintptr_t isaBits = *reinterpret_cast<const uintptr_t *>(ptr);
+  if (isaBits < 4096) return false;
+
+  const uintptr_t isaMask = GetObjCIsaClassMask();
+  const uintptr_t isaCandidates[] = {
+      isaBits,
+      isaMask == 0 ? 0 : (isaBits & isaMask),
+  };
+
+  for (uintptr_t candidate : isaCandidates) {
+    if (candidate < 4096 || (candidate & (alignof(void *) - 1)) != 0) {
+      continue;
+    }
+
+    void *candidatePtr = reinterpret_cast<void *>(candidate);
+    if (malloc_zone_from_ptr(candidatePtr) ||
+        PointerResolvesToLoadedImage(candidatePtr)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
 inline bool LooksLikeObjCObject(uintptr_t val) {
   if (val == 0) return false;  // nil
 
@@ -415,12 +475,14 @@ inline bool LooksLikeObjCObject(uintptr_t val) {
   // malloc_zone_from_ptr returns non-NULL only for valid heap allocations.
   void *ptr = (void *)val;
   malloc_zone_t *zone = malloc_zone_from_ptr(ptr);
-  if (!zone) return false;
+  if (zone) {
+    // It's a heap allocation — very likely an ObjC object.
+    // Do a final check: object_getClass should return a valid class.
+    Class cls = object_getClass((__bridge id)ptr);
+    if (cls != nil) return true;
+  }
 
-  // It's a heap allocation — very likely an ObjC object.
-  // Do a final check: object_getClass should return a valid class.
-  Class cls = object_getClass((__bridge id)ptr);
-  return cls != nil;
+  return LooksLikeImageBackedObjCObject(val);
 }
 
 /**
@@ -530,7 +592,7 @@ inline void SetBlockReturnFromJS(Napi::Value result, void *returnPtr,
       id objcVal = nil;
       if (result.IsObject()) {
         Napi::Object obj = result.As<Napi::Object>();
-        if (obj.InstanceOf(ObjcObject::constructor.Value())) {
+        if (ObjcObject::IsInstance(result.Env(), obj)) {
           ObjcObject *wrapper = Napi::ObjectWrap<ObjcObject>::Unwrap(obj);
           objcVal = wrapper->objcObject;
         }
@@ -718,8 +780,22 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
                                      const char *typeEncoding) {
   NOBJC_LOG("CreateBlockFromJSFunction: encoding='%s'", typeEncoding);
 
+  std::string explicitTypeEncoding;
+  if (jsFunction.IsFunction()) {
+    Napi::Value encodingValue =
+        jsFunction.As<Napi::Function>().Get(kTypedBlockEncodingProperty);
+    if (encodingValue.IsString()) {
+      explicitTypeEncoding = encodingValue.As<Napi::String>().Utf8Value();
+      NOBJC_LOG("CreateBlockFromJSFunction: using explicit encoding='%s'",
+                explicitTypeEncoding.c_str());
+    }
+  }
+
+  const char *effectiveTypeEncoding =
+      explicitTypeEncoding.empty() ? typeEncoding : explicitTypeEncoding.c_str();
+
   // Parse the block signature
-  BlockSignature sig = ParseBlockSignature(typeEncoding);
+  BlockSignature sig = ParseBlockSignature(effectiveTypeEncoding);
   if (!sig.valid) {
     // No extended encoding — infer from JS function's .length
     // All params are treated as pointer-sized (heuristic detection in callback)
@@ -728,7 +804,7 @@ inline id CreateBlockFromJSFunction(Napi::Env env,
 
     NOBJC_LOG("CreateBlockFromJSFunction: No extended block encoding, "
               "inferring %u params from JS function.length. Encoding: '%s'",
-              jsParamCount, typeEncoding);
+              jsParamCount, effectiveTypeEncoding);
 
     sig.returnType = "v";  // Assume void return
     sig.paramTypes.clear();

package/src/native/subclass-impl.mm

@@ -279,7 +279,7 @@ Napi::Value DefineClass(const Napi::CallbackInfo &info) {
     }
   } else if (superValue.IsObject()) {
     Napi::Object superObj = superValue.As<Napi::Object>();
-    if (superObj.InstanceOf(ObjcObject::constructor.Value())) {
+    if (ObjcObject::IsInstance(env, superObj)) {
       ObjcObject *objcObj = Napi::ObjectWrap<ObjcObject>::Unwrap(superObj);
       superClass = (Class)objcObj->objcObject;
     }
@@ -627,7 +627,7 @@ Napi::Value CallSuper(const Napi::CallbackInfo &info) {
     throw Napi::TypeError::New(env, "First argument must be an ObjcObject (self)");
   }
   Napi::Object selfObj = info[0].As<Napi::Object>();
-  if (!selfObj.InstanceOf(ObjcObject::constructor.Value())) {
+  if (!ObjcObject::IsInstance(env, selfObj)) {
     throw Napi::TypeError::New(env, "First argument must be an ObjcObject (self)");
   }
   ObjcObject *selfWrapper = Napi::ObjectWrap<ObjcObject>::Unwrap(selfObj);

package/src/native/type-conversion.h

@@ -583,7 +583,7 @@ inline void SetInvocationReturnFromJS(NSInvocation *invocation,
   case '@': {
     if (result.IsObject()) {
       Napi::Object resultObj = result.As<Napi::Object>();
-      if (resultObj.InstanceOf(ObjcObject::constructor.Value())) {
+      if (ObjcObject::IsInstance(result.Env(), resultObj)) {
         ObjcObject *objcObj = Napi::ObjectWrap<ObjcObject>::Unwrap(resultObj);
         id objcValue = objcObj->objcObject;
         [invocation setReturnValue:&objcValue];