objc-js 0.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iamEvan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,144 @@
+# objc-js
+
+> [!WARNING]
+> This is not production ready.
+
+**objc-js** is an Objective-C bridge for Node.js. This is a fork of [nobjc](https://github.com/nmggithub/nobjc) by [Noah Gregory](https://github.com/nmggithub).
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { NobjcLibrary } from "objc-js";
+
+// Load a framework
+const foundation = new NobjcLibrary("/System/Library/Frameworks/Foundation.framework/Foundation");
+
+// Get a class and call methods
+const NSString = foundation["NSString"];
+const str = NSString.stringWithUTF8String$("Hello, World!");
+console.log(str.toString());
+```
+
+### Protocol Implementation
+
+**objc-js** now supports creating Objective-C protocol implementations from JavaScript. This allows you to create delegate objects that can be passed to Objective-C APIs.
+
+#### Creating a Protocol Implementation
+
+Use `NobjcProtocol.implement()` to create an object that implements a protocol:
+
+```typescript
+import { NobjcProtocol } from "objc-js";
+
+const delegate = NobjcProtocol.implement("ASAuthorizationControllerDelegate", {
+  authorizationController$didCompleteWithAuthorization$: (controller, authorization) => {
+    console.log("Authorization completed successfully!");
+    console.log("Authorization:", authorization);
+  },
+  authorizationController$didCompleteWithError$: (controller, error) => {
+    console.error("Authorization failed:", error);
+  }
+});
+
+// Pass the delegate to an Objective-C API
+authController.setDelegate$(delegate);
+```
+
+#### Method Naming Convention
+
+Method names use the `$` notation to represent colons in Objective-C selectors:
+
+- Objective-C: `authorizationController:didCompleteWithAuthorization:`
+- JavaScript: `authorizationController$didCompleteWithAuthorization$`
+
+#### Argument and Return Value Marshalling
+
+Arguments are automatically converted between JavaScript and Objective-C:
+
+- **Primitives**: Numbers, booleans, and strings are automatically converted
+- **Objects**: Objective-C objects are wrapped in `NobjcObject` instances
+- **null/nil**: JavaScript `null` maps to Objective-C `nil` and vice versa
+
+#### Memory Management
+
+Memory is automatically managed:
+
+- JavaScript callbacks are kept alive as long as the delegate object exists
+- When the Objective-C object is deallocated, the callbacks are automatically released
+- No manual cleanup is required
+
+#### Example: WebAuthn/Passkeys with AuthenticationServices
+
+```typescript
+import { NobjcLibrary, NobjcProtocol } from "objc-js";
+
+const authServices = new NobjcLibrary(
+  "/System/Library/Frameworks/AuthenticationServices.framework/AuthenticationServices"
+);
+
+// Create authorization requests
+const ASAuthorizationController = authServices["ASAuthorizationController"];
+const controller = ASAuthorizationController.alloc().initWithAuthorizationRequests$(requests);
+
+// Create a delegate
+const delegate = NobjcProtocol.implement("ASAuthorizationControllerDelegate", {
+  authorizationController$didCompleteWithAuthorization$: (controller, authorization) => {
+    // Handle successful authorization
+    const credential = authorization.credential();
+    console.log("Credential:", credential);
+  },
+  authorizationController$didCompleteWithError$: (controller, error) => {
+    // Handle error
+    console.error("Authorization error:", error.localizedDescription());
+  }
+});
+
+// Set the delegate and perform requests
+controller.setDelegate$(delegate);
+controller.performRequests();
+```
+
+#### Notes
+
+- Protocol implementations are created at runtime using the Objective-C runtime APIs
+- If a protocol is not found, a class is still created (useful for informal protocols)
+- Method signatures are inferred from the protocol or from the method name
+- Thread safety: Currently assumes single-threaded (main thread) usage
+
+### API Reference
+
+#### `NobjcLibrary`
+
+Creates a proxy for accessing Objective-C classes from a framework.
+
+```typescript
+const framework = new NobjcLibrary(path: string);
+```
+
+#### `NobjcObject`
+
+Wrapper for Objective-C objects. Methods can be called using the `$` notation.
+
+```typescript
+const result = object.methodName$arg1$arg2$(arg1, arg2);
+```
+
+#### `NobjcProtocol`
+
+Static class for creating protocol implementations.
+
+```typescript
+NobjcProtocol.implement(
+  protocolName: string,
+  methodImplementations: Record<string, (...args: any[]) => any>
+): NobjcObject
+```
+
+**Parameters:**
+
+- `protocolName`: The name of the Objective-C protocol (e.g., "NSCopying", "ASAuthorizationControllerDelegate")
+- `methodImplementations`: An object mapping method names (using `$` notation) to JavaScript functions
+
+**Returns:** A `NobjcObject` that can be passed to Objective-C APIs expecting the protocol

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+import { NobjcNative } from "./native.js";
+declare class NobjcLibrary {
+    [key: string]: NobjcObject;
+    constructor(library: string);
+}
+declare class NobjcObject {
+    [key: string]: NobjcMethod;
+    constructor(object: NobjcNative.ObjcObject);
+}
+declare class NobjcMethod {
+    constructor(object: NobjcNative.ObjcObject, methodName: string);
+}
+declare class NobjcProtocol {
+    static implement(protocolName: string, methodImplementations: Record<string, (...args: any[]) => any>): NobjcObject;
+}
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol };

package/dist/index.js

@@ -0,0 +1,112 @@
+import { LoadLibrary, GetClassObject, ObjcObject, CreateProtocolImplementation } from "./native.js";
+const NATIVE_OBJC_OBJECT = Symbol("nativeObjcObject");
+class NobjcLibrary {
+    constructor(library) {
+        const handler = {
+            wasLoaded: false,
+            get(_, className) {
+                if (!this.wasLoaded) {
+                    LoadLibrary(library);
+                    this.wasLoaded = true;
+                }
+                return new NobjcObject(GetClassObject(className));
+            }
+        };
+        return new Proxy({}, handler);
+    }
+}
+function NobjcMethodNameToObjcSelector(methodName) {
+    return methodName.replace(/\$/g, ":");
+}
+// unused, might be useful for codegen later
+function ObjcSelectorToNobjcMethodName(selector) {
+    return selector.replace(/:/g, "$");
+}
+class NobjcObject {
+    constructor(object) {
+        const handler = {
+            has(target, p) {
+                // Return true for the special Symbol to enable unwrapping
+                if (p === NATIVE_OBJC_OBJECT)
+                    return true;
+                // guard against other symbols
+                if (typeof p === "symbol")
+                    return Reflect.has(target, p);
+                // toString is always present
+                if (p === "toString")
+                    return true;
+                // check if the object responds to the selector
+                return target.$msgSend("respondsToSelector:", NobjcMethodNameToObjcSelector(p.toString()));
+            },
+            get(target, methodName, receiver) {
+                // Return the underlying native object when Symbol is accessed
+                if (methodName === NATIVE_OBJC_OBJECT) {
+                    return target;
+                }
+                // guard against symbols
+                if (typeof methodName === "symbol") {
+                    return Reflect.get(object, methodName, receiver);
+                }
+                // handle toString separately
+                if (methodName === "toString") {
+                    return () => String(object.$msgSend("description"));
+                }
+                if (!(methodName in receiver)) {
+                    throw new Error(`Method ${methodName} not found on object ${receiver}`);
+                }
+                return new NobjcMethod(object, methodName);
+            }
+        };
+        return new Proxy(object, handler);
+    }
+}
+function unwrapArg(arg) {
+    if (arg && typeof arg === "object" && NATIVE_OBJC_OBJECT in arg) {
+        return arg[NATIVE_OBJC_OBJECT];
+    }
+    return arg;
+}
+class NobjcMethod {
+    constructor(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);
+            if (typeof result == "object" && result instanceof ObjcObject) {
+                return new NobjcObject(result);
+            }
+            return result;
+        }
+        const handler = {};
+        return new Proxy(methodFunc, handler);
+    }
+}
+class NobjcProtocol {
+    static implement(protocolName, methodImplementations) {
+        // Convert method names from $ notation to : notation
+        const convertedMethods = {};
+        for (const [methodName, impl] of Object.entries(methodImplementations)) {
+            const selector = NobjcMethodNameToObjcSelector(methodName);
+            // Wrap the implementation to unwrap args and wrap return values
+            convertedMethods[selector] = function (...args) {
+                const unwrappedArgs = args.map(unwrapArg);
+                const result = impl(...unwrappedArgs);
+                // If the result is already a NobjcObject, unwrap it to get the native object
+                if (result && typeof result === "object" && NATIVE_OBJC_OBJECT in result) {
+                    return result[NATIVE_OBJC_OBJECT];
+                }
+                // If the result is a native ObjcObject, return it as-is
+                if (typeof result === "object" && result instanceof ObjcObject) {
+                    return result;
+                }
+                return result;
+            };
+        }
+        // Call native implementation
+        const nativeObj = CreateProtocolImplementation(protocolName, convertedMethods);
+        // Wrap in NobjcObject proxy
+        return new NobjcObject(nativeObj);
+    }
+}
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol };

package/dist/native.d.ts

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

package/dist/native.js

@@ -0,0 +1,5 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+const binding = require("#nobjc_native");
+const { LoadLibrary, GetClassObject, ObjcObject, CreateProtocolImplementation } = binding;
+export { LoadLibrary, GetClassObject, ObjcObject, CreateProtocolImplementation };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "objc-js",
+  "private": false,
+  "access": "public",
+  "type": "module",
+  "os": [
+    "darwin"
+  ],
+  "repository": "https://github.com/iamEvanYT/objc-js",
+  "author": "iamEvan",
+  "imports": {
+    "#nobjc_native": "./build/Release/nobjc_native.node"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./native": "./build/Release/nobjc_native.node"
+  },
+  "files": [
+    "dist/",
+    "build/Release/nobjc_native.node"
+  ],
+  "scripts": {
+    "build-native": "node-gyp build",
+    "build-scripts": "tsc --project scripts/tsconfig.json",
+    "build-source": "tsc --project src/ts/tsconfig.json",
+    "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: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",
+    "test:object-arguments": "bun test tests/test-object-arguments.test.ts",
+    "test:protocol-implementation": "bun test tests/test-protocol-implementation.test.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"
+  },
+  "version": "0.0.4",
+  "description": "Objective-C bridge for Node.js",
+  "main": "dist/index.js",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^20.0.0",
+    "node-addon-api": "^8.5.0",
+    "node-gyp": "^11.4.2",
+    "prettier": "^3.7.4",
+    "typescript": "^5.9.3"
+  },
+  "gypfile": true
+}