objc-js 1.1.0 → 1.2.0

package/README.md

@@ -33,6 +33,7 @@ bun add objc-js
 The documentation is organized into several guides:
 
 - **[Basic Usage](./docs/basic-usage.md)** - Getting started with loading frameworks and calling methods
+- **[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
 - **[Protocol Implementation](./docs/protocol-implementation.md)** - Creating delegate objects that implement protocols

package/dist/index.d.ts

@@ -173,4 +173,80 @@ declare class NobjcClass {
      */
     static super(self: NobjcObject, selector: string, ...args: any[]): any;
 }
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, getPointer, fromPointer };
+/**
+ * Call a C function by name.
+ *
+ * The framework containing the function must be loaded first (e.g., via `new NobjcLibrary(...)`).
+ * Uses `dlsym` to look up the function symbol and `libffi` to call it with the correct ABI.
+ *
+ * Argument types are inferred from JS values by default:
+ * - NobjcObject → `@` (id)
+ * - string → `@` (auto-converted to NSString)
+ * - boolean → `B` (BOOL)
+ * - number → `d` (double/CGFloat)
+ * - null → `@` (nil)
+ *
+ * Return type defaults to `"v"` (void). Pass an options object to specify return/arg types.
+ *
+ * @param name - The function name (e.g., "NSLog", "NSHomeDirectory")
+ * @param optionsOrFirstArg - Either a CallFunctionOptions object or the first function argument
+ * @param args - The actual arguments to pass to the function
+ * @returns The return value converted to a JavaScript type, or undefined for void functions
+ *
+ * @example
+ * ```typescript
+ * import { NobjcLibrary, callFunction } from "objc-js";
+ *
+ * const Foundation = new NobjcLibrary(
+ *   "/System/Library/Frameworks/Foundation.framework/Foundation"
+ * );
+ * const NSString = Foundation.NSString;
+ *
+ * // Void function — simplest form, no options needed
+ * const msg = NSString.stringWithUTF8String$("Hello!");
+ * callFunction("NSLog", msg);
+ *
+ * // Function that returns a value — specify { returns }
+ * const homeDir = callFunction("NSHomeDirectory", { returns: "@" });
+ * console.log(homeDir.toString());
+ *
+ * // Explicit arg types when inference isn't enough
+ * const selName = callFunction("NSStringFromSelector", { returns: "@", args: [":"] }, "description");
+ *
+ * // Combined type string shorthand (return + args)
+ * const className = callFunction("NSStringFromClass", { types: "@#" }, NSString);
+ * ```
+ */
+declare function callFunction(name: string, ...rest: any[]): any;
+/**
+ * Call a variadic C function by name.
+ *
+ * Correctly handles variadic calling conventions (important on Apple Silicon / ARM64
+ * where variadic args go on the stack while fixed args go in registers).
+ *
+ * @param name - The function name (e.g., "NSLog")
+ * @param optionsOrFixedCount - Either a CallFunctionOptions object or the fixedArgCount directly
+ * @param fixedArgCountOrFirstArg - Number of fixed (non-variadic) arguments, or first arg if options were provided
+ * @param args - The actual arguments to pass to the function
+ * @returns The return value converted to a JavaScript type
+ *
+ * @example
+ * ```typescript
+ * import { NobjcLibrary, callVariadicFunction } from "objc-js";
+ *
+ * const Foundation = new NobjcLibrary(
+ *   "/System/Library/Frameworks/Foundation.framework/Foundation"
+ * );
+ * const NSString = Foundation.NSString;
+ *
+ * // Simplest: void return, inferred args, fixedArgCount = 1
+ * const format = NSString.stringWithUTF8String$("Hello, %@!");
+ * const name = NSString.stringWithUTF8String$("World");
+ * callVariadicFunction("NSLog", 1, format, name);
+ *
+ * // With explicit types
+ * callVariadicFunction("NSLog", { returns: "v", args: ["@", "i"] }, 1, format, 42);
+ * ```
+ */
+declare function callVariadicFunction(name: string, ...rest: any[]): any;
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, getPointer, fromPointer, callFunction, callVariadicFunction };

package/dist/index.js

@@ -1,16 +1,40 @@
-import { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper } from "./native.js";
+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");
+// 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()
+const BUILT_IN_PROPS = new Set([
+    "constructor",
+    "valueOf",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "toLocaleString",
+    "__proto__",
+    "__defineGetter__",
+    "__defineSetter__",
+    "__lookupGetter__",
+    "__lookupSetter__"
+]);
+// WeakMap cache for NobjcMethod proxies per object to avoid GC pressure
+const methodCache = new WeakMap();
 class NobjcLibrary {
     constructor(library) {
+        const classCache = new Map();
         const handler = {
             wasLoaded: false,
             get(_, className) {
+                let cls = classCache.get(className);
+                if (cls)
+                    return cls;
                 if (!this.wasLoaded) {
                     LoadLibrary(library);
                     this.wasLoaded = true;
                 }
-                return new NobjcObject(GetClassObject(className));
+                cls = new NobjcObject(GetClassObject(className));
+                classCache.set(className, cls);
+                return cls;
             }
         };
         return new Proxy({}, handler);
@@ -39,7 +63,7 @@ class NobjcObject {
                     return true;
                 // check if the object responds to the selector
                 try {
-                    return target.$msgSend("respondsToSelector:", NobjcMethodNameToObjcSelector(p.toString()));
+                    return target.$respondsToSelector(NobjcMethodNameToObjcSelector(p.toString()));
                 }
                 catch (e) {
                     return false;
@@ -50,53 +74,68 @@ class NobjcObject {
                 if (methodName === NATIVE_OBJC_OBJECT) {
                     return target;
                 }
+                // Handle customInspectSymbol in get trap instead of mutating native object
+                // (avoids hidden class transition that deoptimizes V8 inline caches)
+                if (methodName === customInspectSymbol) {
+                    return () => proxy.toString();
+                }
                 // guard against symbols
                 if (typeof methodName === "symbol") {
                     return Reflect.get(object, methodName, receiver);
                 }
-                // handle toString separately
+                // handle toString separately (cached to avoid repeated closure allocation and FFI check)
                 if (methodName === "toString") {
-                    // if the receiver has a UTF8String method, use it to get the string representation
-                    if ("UTF8String" in receiver) {
-                        return () => String(object.$msgSend("UTF8String"));
+                    let cache = methodCache.get(object);
+                    if (!cache) {
+                        cache = new Map();
+                        methodCache.set(object, cache);
+                    }
+                    let fn = cache.get("toString");
+                    if (!fn) {
+                        // Check directly on native object to avoid triggering proxy has trap
+                        const hasUTF8 = target.$respondsToSelector("UTF8String");
+                        fn = (hasUTF8
+                            ? () => String(object.$msgSend("UTF8String"))
+                            : () => String(wrapObjCObjectIfNeeded(object.$msgSend("description"))));
+                        cache.set("toString", fn);
                     }
-                    // Otherwise, use the description method
-                    return () => String(wrapObjCObjectIfNeeded(object.$msgSend("description")));
+                    return fn;
                 }
-                // handle other built-in Object.prototype properties
-                const builtInProps = [
-                    "constructor",
-                    "valueOf",
-                    "hasOwnProperty",
-                    "isPrototypeOf",
-                    "propertyIsEnumerable",
-                    "toLocaleString",
-                    "__proto__",
-                    "__defineGetter__",
-                    "__defineSetter__",
-                    "__lookupGetter__",
-                    "__lookupSetter__"
-                ];
-                if (builtInProps.includes(methodName)) {
+                // handle other built-in Object.prototype properties (O(1) Set lookup)
+                if (BUILT_IN_PROPS.has(methodName)) {
                     return Reflect.get(target, methodName);
                 }
-                if (!(methodName in receiver)) {
-                    throw new Error(`Method ${methodName} not found on object ${receiver}`);
+                // Return cached method proxy if available, otherwise create and cache
+                let cache = methodCache.get(object);
+                if (!cache) {
+                    cache = new Map();
+                    methodCache.set(object, cache);
                 }
-                return NobjcMethod(object, methodName);
+                let method = cache.get(methodName);
+                if (!method) {
+                    // Check respondsToSelector on cache miss only, directly on native
+                    // object (avoids triggering proxy 'has' trap which would be a second FFI call)
+                    const selector = NobjcMethodNameToObjcSelector(methodName);
+                    if (!target.$respondsToSelector(selector)) {
+                        throw new Error(`Method ${methodName} not found on object`);
+                    }
+                    method = NobjcMethod(object, methodName);
+                    cache.set(methodName, method);
+                }
+                return method;
             }
         };
         // Create the proxy
         const proxy = new Proxy(object, handler);
-        // This is used to override the default inspect behavior for the object. (console.log)
-        object[customInspectSymbol] = () => proxy.toString();
+        // Store proxy → native mapping in WeakMap for O(1) unwrap (bypasses Proxy traps)
+        nativeObjectMap.set(proxy, object);
         // Return the proxy
         return proxy;
     }
 }
 function unwrapArg(arg) {
-    if (arg && typeof arg === "object" && NATIVE_OBJC_OBJECT in arg) {
-        return arg[NATIVE_OBJC_OBJECT];
+    if (arg && typeof arg === "object") {
+        return nativeObjectMap.get(arg) ?? arg;
     }
     return arg;
 }
@@ -106,17 +145,33 @@ function wrapObjCObjectIfNeeded(result) {
     }
     return result;
 }
-// Note: This is actually a factory function that returns a callable Proxy
+// Note: This is actually a factory function that returns a callable function
 const NobjcMethod = function (object, methodName) {
     const selector = NobjcMethodNameToObjcSelector(methodName);
-    // This cannot be an arrow function because we need to access `arguments`.
-    function methodFunc() {
-        const unwrappedArgs = Array.from(arguments).map(unwrapArg);
-        const result = object.$msgSend(selector, ...unwrappedArgs);
-        return wrapObjCObjectIfNeeded(result);
+    // H2: Cache SEL + method signature natively via $prepareSend.
+    // This avoids re-registering the selector, respondsToSelector:, and
+    // method signature lookup on every call.
+    const handle = object.$prepareSend(selector);
+    // Fast paths for 0-3 args avoid rest param array allocation + spread overhead
+    function methodFunc(...args) {
+        switch (args.length) {
+            case 0:
+                return wrapObjCObjectIfNeeded(object.$msgSendPrepared(handle));
+            case 1:
+                return wrapObjCObjectIfNeeded(object.$msgSendPrepared(handle, unwrapArg(args[0])));
+            case 2:
+                return wrapObjCObjectIfNeeded(object.$msgSendPrepared(handle, unwrapArg(args[0]), unwrapArg(args[1])));
+            case 3:
+                return wrapObjCObjectIfNeeded(object.$msgSendPrepared(handle, unwrapArg(args[0]), unwrapArg(args[1]), unwrapArg(args[2])));
+            default:
+                for (let i = 0; i < args.length; i++) {
+                    args[i] = unwrapArg(args[i]);
+                }
+                return wrapObjCObjectIfNeeded(object.$msgSendPrepared(handle, ...args));
+        }
     }
-    const handler = {};
-    return new Proxy(methodFunc, handler);
+    // Return the function directly — no Proxy wrapper needed (handler was empty)
+    return methodFunc;
 };
 class NobjcProtocol {
     static implement(protocolName, methodImplementations) {
@@ -126,11 +181,11 @@ class NobjcProtocol {
             const selector = NobjcMethodNameToObjcSelector(methodName);
             // Wrap the implementation to wrap args and unwrap return values
             convertedMethods[selector] = function (...args) {
-                // Wrap native ObjcObject arguments in NobjcObject proxies
-                const wrappedArgs = args.map((arg) => {
-                    return wrapObjCObjectIfNeeded(arg);
-                });
-                const result = impl(...wrappedArgs);
+                // Wrap native ObjcObject arguments in NobjcObject proxies (in-place to avoid allocation)
+                for (let i = 0; i < args.length; i++) {
+                    args[i] = wrapObjCObjectIfNeeded(args[i]);
+                }
+                const result = impl(...args);
                 // If the result is already a NobjcObject, unwrap it to get the native object
                 return unwrapArg(result);
             };
@@ -157,9 +212,9 @@ class NobjcProtocol {
  * ```
  */
 function getPointer(obj) {
-    // Unwrap the NobjcObject to get the native ObjcObject
-    if (obj && typeof obj === "object" && NATIVE_OBJC_OBJECT in obj) {
-        const nativeObj = obj[NATIVE_OBJC_OBJECT];
+    // Unwrap the NobjcObject to get the native ObjcObject via WeakMap
+    const nativeObj = nativeObjectMap.get(obj);
+    if (nativeObj) {
         return GetPointer(nativeObj);
     }
     throw new TypeError("Argument must be a NobjcObject instance");
@@ -256,20 +311,21 @@ class NobjcClass {
                     implementation: (nativeSelf, ...nativeArgs) => {
                         // Wrap self
                         const wrappedSelf = wrapObjCObjectIfNeeded(nativeSelf);
-                        // Wrap args, but preserve out-param objects as-is
-                        const wrappedArgs = nativeArgs.map((arg) => {
-                            // Check if it's an out-param object (has 'set' method)
+                        // Wrap args in-place to avoid allocation (preserve out-param objects)
+                        for (let i = 0; i < nativeArgs.length; i++) {
+                            const arg = nativeArgs[i];
                             if (arg && typeof arg === "object" && typeof arg.set === "function") {
-                                // Keep out-param objects as-is, but wrap the error objects they handle
-                                return {
+                                nativeArgs[i] = {
                                     set: (error) => arg.set(unwrapArg(error)),
                                     get: () => wrapObjCObjectIfNeeded(arg.get())
                                 };
                             }
-                            return wrapObjCObjectIfNeeded(arg);
-                        });
+                            else {
+                                nativeArgs[i] = wrapObjCObjectIfNeeded(arg);
+                            }
+                        }
                         // Call the user's implementation
-                        const result = methodDef.implementation(wrappedSelf, ...wrappedArgs);
+                        const result = methodDef.implementation(wrappedSelf, ...nativeArgs);
                         // Unwrap the return value
                         return unwrapArg(result);
                     }
@@ -308,9 +364,216 @@ class NobjcClass {
     static super(self, selector, ...args) {
         const normalizedSelector = NobjcMethodNameToObjcSelector(selector);
         const nativeSelf = unwrapArg(self);
-        const unwrappedArgs = args.map(unwrapArg);
-        const result = CallSuper(nativeSelf, normalizedSelector, ...unwrappedArgs);
+        // Mutate args in-place to avoid allocation
+        for (let i = 0; i < args.length; i++) {
+            args[i] = unwrapArg(args[i]);
+        }
+        const result = CallSuper(nativeSelf, normalizedSelector, ...args);
         return wrapObjCObjectIfNeeded(result);
     }
 }
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, getPointer, fromPointer };
+/**
+ * Parse a combined type encoding string into individual type encodings.
+ * Handles multi-character encodings: ^v (pointer), {CGRect=dd} (struct), etc.
+ */
+function parseTypeEncodings(typeStr) {
+    const result = [];
+    let i = 0;
+    while (i < typeStr.length) {
+        const start = i;
+        const ch = typeStr[i];
+        if (ch === "{" || ch === "[" || ch === "(") {
+            const close = ch === "{" ? "}" : ch === "[" ? "]" : ")";
+            let depth = 1;
+            i++;
+            while (i < typeStr.length && depth > 0) {
+                if (typeStr[i] === ch)
+                    depth++;
+                else if (typeStr[i] === close)
+                    depth--;
+                i++;
+            }
+        }
+        else if (ch === "^") {
+            i++;
+            if (i < typeStr.length) {
+                if (typeStr[i] === "{" || typeStr[i] === "[" || typeStr[i] === "(") {
+                    // Pointer to compound type — parse the inner type
+                    const inner = parseTypeEncodings(typeStr.substring(i));
+                    i += inner[0]?.length ?? 1;
+                }
+                else {
+                    i++; // pointer to simple type (^v, ^@, etc.)
+                }
+            }
+        }
+        else {
+            i++;
+        }
+        result.push(typeStr.substring(start, i));
+    }
+    return result;
+}
+/**
+ * Infer the ObjC type encoding for a JS argument value.
+ * - NobjcObject / object → "@" (id)
+ * - string → "@" (auto-converted to NSString by native code)
+ * - boolean → "B" (BOOL)
+ * - number → "d" (double/CGFloat)
+ * - null/undefined → "@" (nil)
+ *
+ * Note: numbers always infer as "d" (double). For integer params (NSInteger, etc.),
+ * specify the type explicitly via { args: ["q"] } or { types: "..." }.
+ */
+function inferArgType(arg) {
+    if (arg === null || arg === undefined)
+        return "@";
+    if (typeof arg === "boolean")
+        return "B";
+    if (typeof arg === "number")
+        return "d";
+    return "@";
+}
+/**
+ * Check if a value is a CallFunctionOptions object (not a NobjcObject or struct).
+ */
+function isCallOptions(value) {
+    if (value === null || value === undefined || typeof value !== "object")
+        return false;
+    if (nativeObjectMap.has(value))
+        return false; // It's a NobjcObject proxy
+    return "returns" in value || "types" in value || "args" in value;
+}
+/**
+ * Resolve return type and arg types from options + values.
+ */
+function resolveTypes(options, args) {
+    if (options?.types) {
+        const encodings = parseTypeEncodings(options.types);
+        const returnType = encodings[0] || "v";
+        const explicitArgTypes = encodings.slice(1);
+        return {
+            returnType,
+            argTypes: explicitArgTypes.length > 0 ? explicitArgTypes : args.map(inferArgType)
+        };
+    }
+    return {
+        returnType: options?.returns || "v",
+        argTypes: options?.args || args.map(inferArgType)
+    };
+}
+/**
+ * Call a C function by name.
+ *
+ * The framework containing the function must be loaded first (e.g., via `new NobjcLibrary(...)`).
+ * Uses `dlsym` to look up the function symbol and `libffi` to call it with the correct ABI.
+ *
+ * Argument types are inferred from JS values by default:
+ * - NobjcObject → `@` (id)
+ * - string → `@` (auto-converted to NSString)
+ * - boolean → `B` (BOOL)
+ * - number → `d` (double/CGFloat)
+ * - null → `@` (nil)
+ *
+ * Return type defaults to `"v"` (void). Pass an options object to specify return/arg types.
+ *
+ * @param name - The function name (e.g., "NSLog", "NSHomeDirectory")
+ * @param optionsOrFirstArg - Either a CallFunctionOptions object or the first function argument
+ * @param args - The actual arguments to pass to the function
+ * @returns The return value converted to a JavaScript type, or undefined for void functions
+ *
+ * @example
+ * ```typescript
+ * import { NobjcLibrary, callFunction } from "objc-js";
+ *
+ * const Foundation = new NobjcLibrary(
+ *   "/System/Library/Frameworks/Foundation.framework/Foundation"
+ * );
+ * const NSString = Foundation.NSString;
+ *
+ * // Void function — simplest form, no options needed
+ * const msg = NSString.stringWithUTF8String$("Hello!");
+ * callFunction("NSLog", msg);
+ *
+ * // Function that returns a value — specify { returns }
+ * const homeDir = callFunction("NSHomeDirectory", { returns: "@" });
+ * console.log(homeDir.toString());
+ *
+ * // Explicit arg types when inference isn't enough
+ * const selName = callFunction("NSStringFromSelector", { returns: "@", args: [":"] }, "description");
+ *
+ * // Combined type string shorthand (return + args)
+ * const className = callFunction("NSStringFromClass", { types: "@#" }, NSString);
+ * ```
+ */
+function callFunction(name, ...rest) {
+    let options = null;
+    let args;
+    if (rest.length > 0 && isCallOptions(rest[0])) {
+        options = rest[0];
+        args = rest.slice(1);
+    }
+    else {
+        args = rest;
+    }
+    const { returnType, argTypes } = resolveTypes(options, args);
+    // Unwrap NobjcObject proxies to native objects
+    for (let i = 0; i < args.length; i++) {
+        args[i] = unwrapArg(args[i]);
+    }
+    const result = CallFunction(name, returnType, argTypes, argTypes.length, ...args);
+    return wrapObjCObjectIfNeeded(result);
+}
+/**
+ * Call a variadic C function by name.
+ *
+ * Correctly handles variadic calling conventions (important on Apple Silicon / ARM64
+ * where variadic args go on the stack while fixed args go in registers).
+ *
+ * @param name - The function name (e.g., "NSLog")
+ * @param optionsOrFixedCount - Either a CallFunctionOptions object or the fixedArgCount directly
+ * @param fixedArgCountOrFirstArg - Number of fixed (non-variadic) arguments, or first arg if options were provided
+ * @param args - The actual arguments to pass to the function
+ * @returns The return value converted to a JavaScript type
+ *
+ * @example
+ * ```typescript
+ * import { NobjcLibrary, callVariadicFunction } from "objc-js";
+ *
+ * const Foundation = new NobjcLibrary(
+ *   "/System/Library/Frameworks/Foundation.framework/Foundation"
+ * );
+ * const NSString = Foundation.NSString;
+ *
+ * // Simplest: void return, inferred args, fixedArgCount = 1
+ * const format = NSString.stringWithUTF8String$("Hello, %@!");
+ * const name = NSString.stringWithUTF8String$("World");
+ * callVariadicFunction("NSLog", 1, format, name);
+ *
+ * // With explicit types
+ * callVariadicFunction("NSLog", { returns: "v", args: ["@", "i"] }, 1, format, 42);
+ * ```
+ */
+function callVariadicFunction(name, ...rest) {
+    let options = null;
+    let restIdx = 0;
+    if (rest.length > 0 && isCallOptions(rest[0])) {
+        options = rest[0];
+        restIdx = 1;
+    }
+    // fixedArgCount must be a number
+    if (restIdx >= rest.length || typeof rest[restIdx] !== "number") {
+        throw new Error("callVariadicFunction requires fixedArgCount as a number parameter");
+    }
+    const fixedArgCount = rest[restIdx];
+    restIdx++;
+    const args = rest.slice(restIdx);
+    const { returnType, argTypes } = resolveTypes(options, args);
+    // Unwrap NobjcObject proxies to native objects
+    for (let i = 0; i < args.length; i++) {
+        args[i] = unwrapArg(args[i]);
+    }
+    const result = CallFunction(name, returnType, argTypes, fixedArgCount, ...args);
+    return wrapObjCObjectIfNeeded(result);
+}
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, getPointer, fromPointer, callFunction, callVariadicFunction };

package/dist/native.d.ts

@@ -1,4 +1,4 @@
 import * as _binding from "#nobjc_native";
-declare const LoadLibrary: typeof _binding.LoadLibrary, GetClassObject: typeof _binding.GetClassObject, ObjcObject: typeof _binding.ObjcObject, GetPointer: typeof _binding.GetPointer, FromPointer: typeof _binding.FromPointer, CreateProtocolImplementation: typeof _binding.CreateProtocolImplementation, DefineClass: typeof _binding.DefineClass, CallSuper: typeof _binding.CallSuper;
-export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper };
+declare const LoadLibrary: typeof _binding.LoadLibrary, GetClassObject: typeof _binding.GetClassObject, ObjcObject: typeof _binding.ObjcObject, GetPointer: typeof _binding.GetPointer, FromPointer: typeof _binding.FromPointer, CreateProtocolImplementation: typeof _binding.CreateProtocolImplementation, DefineClass: typeof _binding.DefineClass, CallSuper: typeof _binding.CallSuper, CallFunction: typeof _binding.CallFunction;
+export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction };
 export type { _binding as NobjcNative };

package/dist/native.js

@@ -5,5 +5,5 @@ const require = createRequire(import.meta.url);
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const binding = require("node-gyp-build")(join(__dirname, ".."));
-const { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper } = binding;
-export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper };
+const { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction } = binding;
+export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper, CallFunction };

package/package.json

@@ -36,6 +36,7 @@
     "test:string-lifetime": "bun test tests/test-string-lifetime.test.ts",
     "test:object-arguments": "bun test tests/test-object-arguments.test.ts",
     "test:protocol-implementation": "bun test tests/test-protocol-implementation.test.ts",
+    "bench": "bun run build && bun run benchmarks/bench.ts",
     "make-clangd-config": "node ./scripts/make-clangd-config.js",
     "format": "prettier --write \"**/*.{ts,js,json,md}\"",
     "preinstall-disabled": "npm run build-scripts && npm run make-clangd-config",
@@ -43,7 +44,7 @@
     "prebuild:x64": "prebuildify --napi --strip --arch x64 -r node",
     "prebuild:all": "bun run prebuild:arm64 && bun run prebuild:x64"
   },
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Objective-C bridge for Node.js",
   "main": "dist/index.js",
   "dependencies": {

package/src/native/ObjcObject.h

@@ -1,10 +1,44 @@
+#ifndef OBJCOBJECT_H
+#define OBJCOBJECT_H
+
 #include <napi.h>
 #include <objc/objc.h>
+#include <objc/runtime.h>
 #include <optional>
 #include <variant>
+#include <unordered_map>
+#include <vector>
 
-#ifndef OBJCOBJECT_H
-#define OBJCOBJECT_H
+#ifdef __OBJC__
+@class NSMethodSignature;
+#else
+typedef struct NSMethodSignature NSMethodSignature;
+#endif
+
+// MARK: - Prepared Send Handle
+
+/**
+ * Opaque handle for $prepareSend / $msgSendPrepared.
+ * Caches SEL, method signature, and fast-path eligibility so that
+ * repeated calls skip selector registration, respondsToSelector:,
+ * and method signature lookup entirely.
+ */
+struct PreparedSend {
+  SEL selector;
+  NSMethodSignature *methodSignature;
+  size_t expectedArgCount;    // numberOfArguments - 2 (self + _cmd)
+  const char *returnType;     // simplified return type encoding (interned, lives in sig)
+  bool isStructReturn;
+  bool canUseFastPath;        // true if direct objc_msgSend cast is possible
+  char fastReturnTypeCode;    // first char of simplified return type, for fast dispatch
+
+  // Per-argument info for fast path
+  struct ArgInfo {
+    char typeCode;             // simplified type code
+    bool isStruct;
+  };
+  std::vector<ArgInfo> argInfos;
+};
 
 class ObjcObject : public Napi::ObjectWrap<ObjcObject> {
 public:
@@ -28,7 +62,10 @@ public:
 
 private:
   Napi::Value $MsgSend(const Napi::CallbackInfo &info);
+  Napi::Value $RespondsToSelector(const Napi::CallbackInfo &info);
+  Napi::Value $PrepareSend(const Napi::CallbackInfo &info);
+  Napi::Value $MsgSendPrepared(const Napi::CallbackInfo &info);
   Napi::Value GetPointer(const Napi::CallbackInfo &info);
 };
 
-#endif // OBJCOBJECT_H
+#endif // OBJCOBJECT_H