objc-js 0.0.5 → 0.0.6

package/README.md

@@ -142,3 +142,116 @@ NobjcProtocol.implement(
 - `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
+
+#### `getPointer()`
+
+Get the raw native pointer for a NobjcObject as a Node Buffer. This is useful for passing Objective-C objects to native APIs that expect raw pointers, such as Electron's native window handles.
+
+```typescript
+function getPointer(obj: NobjcObject): Buffer;
+```
+
+**Parameters:**
+
+- `obj`: The NobjcObject to get the pointer from
+
+**Returns:** A Buffer containing the pointer address in little-endian format (8 bytes on 64-bit macOS)
+
+**Example: Getting an NSView pointer**
+
+```typescript
+import { NobjcLibrary, getPointer } from "objc-js";
+
+// Load AppKit framework
+const appKit = new NobjcLibrary("/System/Library/Frameworks/AppKit.framework/AppKit");
+
+// Get an NSWindow and its content view
+const NSApplication = appKit["NSApplication"];
+const app = NSApplication.sharedApplication();
+const window = app.mainWindow();
+const view = window.contentView();
+
+// Get the raw pointer as a Buffer
+const pointerBuffer = getPointer(view);
+
+// Read the pointer as a BigInt (64-bit unsigned integer)
+const pointer = pointerBuffer.readBigUInt64LE(0);
+console.log(`NSView pointer: 0x${pointer.toString(16)}`);
+
+// Use with Electron or other native APIs
+// const { BrowserWindow } = require('electron');
+// const win = BrowserWindow.fromId(pointer);
+```
+
+**Note:** The pointer is returned as a Buffer in little-endian format. Use `readBigUInt64LE(0)` to read it as a 64-bit unsigned integer, which is the standard pointer size on macOS.
+
+#### `fromPointer()`
+
+Create a NobjcObject from a raw native pointer. This is the inverse of `getPointer()` and allows you to reconstruct an Objective-C object from a pointer address.
+
+```typescript
+function fromPointer(pointer: Buffer | bigint): NobjcObject;
+```
+
+**Parameters:**
+
+- `pointer`: A Buffer (8 bytes in little-endian format) or BigInt containing the pointer address
+
+**Returns:** A NobjcObject wrapping the native Objective-C object
+
+**Example: Round-trip pointer conversion**
+
+```typescript
+import { NobjcLibrary, getPointer, fromPointer } from "objc-js";
+
+const foundation = new NobjcLibrary("/System/Library/Frameworks/Foundation.framework/Foundation");
+const NSString = foundation["NSString"];
+
+// Create an original object
+const original = NSString.stringWithUTF8String$("Hello, World!");
+console.log(original.toString()); // "Hello, World!"
+
+// Get the pointer
+const pointerBuffer = getPointer(original);
+const pointer = pointerBuffer.readBigUInt64LE(0);
+console.log(`Pointer: 0x${pointer.toString(16)}`);
+
+// Reconstruct the object from the pointer
+const reconstructed = fromPointer(pointer);
+// or: const reconstructed = fromPointer(pointerBuffer);
+
+console.log(reconstructed.toString()); // "Hello, World!"
+
+// Both objects reference the same underlying Objective-C object
+const ptr1 = getPointer(original).readBigUInt64LE(0);
+const ptr2 = getPointer(reconstructed).readBigUInt64LE(0);
+console.log(ptr1 === ptr2); // true
+```
+
+**Example: Using with external native APIs**
+
+```typescript
+// Receive a pointer from an external API
+const externalPointer = 0x12345678n; // Example pointer from native code
+
+// Convert it to a NobjcObject
+const nsObject = fromPointer(externalPointer);
+
+// Now you can call Objective-C methods on it
+console.log(nsObject.description());
+```
+
+**⚠️ Safety Warning:**
+
+This function is **inherently unsafe** and should be used with extreme caution:
+
+- **Invalid pointers will crash your program**: The pointer must point to a valid Objective-C object
+- **Dangling pointers**: The object must still be alive (not deallocated). Accessing a deallocated object will crash
+- **No type checking**: There's no way to verify the pointer points to the expected type of object
+- **Memory management**: Be aware of Objective-C reference counting. The object must remain valid for the lifetime of your usage
+
+Only use this function when:
+
+- You received the pointer from `getPointer()` and the object is still alive
+- You received the pointer from a trusted native API that guarantees the object's validity
+- You're interfacing with external native code that provides valid Objective-C object pointers

package/dist/index.d.ts

@@ -7,10 +7,55 @@ declare class NobjcObject {
     [key: string]: NobjcMethod;
     constructor(object: NobjcNative.ObjcObject);
 }
-declare class NobjcMethod {
-    constructor(object: NobjcNative.ObjcObject, methodName: string);
+interface NobjcMethod {
+    (...args: any[]): any;
 }
+declare const NobjcMethod: (object: NobjcNative.ObjcObject, methodName: string) => NobjcMethod;
 declare class NobjcProtocol {
     static implement(protocolName: string, methodImplementations: Record<string, (...args: any[]) => any>): NobjcObject;
 }
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol };
+/**
+ * Get the raw native pointer for a NobjcObject as a Node Buffer.
+ * The pointer is stored in little-endian format (8 bytes on 64-bit macOS).
+ *
+ * @param obj - The NobjcObject to get the pointer from
+ * @returns A Buffer containing the pointer address
+ *
+ * @example
+ * ```typescript
+ * const view = window.contentView();
+ * const pointerBuffer = getPointer(view);
+ * const pointer = pointerBuffer.readBigUInt64LE(0);
+ * console.log(`NSView pointer: 0x${pointer.toString(16)}`);
+ * ```
+ */
+declare function getPointer(obj: NobjcObject): Buffer;
+/**
+ * Create a NobjcObject from a raw native pointer.
+ *
+ * @param pointer - A Buffer or BigInt containing the pointer address
+ * @returns A NobjcObject wrapping the native object
+ *
+ * @example
+ * ```typescript
+ * // From a Buffer
+ * const pointerBuffer = getPointer(originalObject);
+ * const reconstructed = fromPointer(pointerBuffer);
+ *
+ * // From a BigInt
+ * const pointer = 0x12345678n;
+ * const obj = fromPointer(pointer);
+ *
+ * // Round-trip example
+ * const original = NSString.stringWithUTF8String$("Hello");
+ * const ptr = getPointer(original).readBigUInt64LE(0);
+ * const restored = fromPointer(ptr);
+ * console.log(restored.toString()); // "Hello"
+ * ```
+ *
+ * @warning This is unsafe! The pointer must point to a valid Objective-C object.
+ * Using an invalid pointer will cause a crash. The object must still be alive
+ * (not deallocated) when you call this function.
+ */
+declare function fromPointer(pointer: Buffer | bigint): NobjcObject;
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, getPointer, fromPointer };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { LoadLibrary, GetClassObject, ObjcObject, CreateProtocolImplementation } from "./native.js";
+import { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation } from "./native.js";
 const NATIVE_OBJC_OBJECT = Symbol("nativeObjcObject");
 class NobjcLibrary {
     constructor(library) {
@@ -54,7 +54,7 @@ class NobjcObject {
                 if (!(methodName in receiver)) {
                     throw new Error(`Method ${methodName} not found on object ${receiver}`);
                 }
-                return new NobjcMethod(object, methodName);
+                return NobjcMethod(object, methodName);
             }
         };
         return new Proxy(object, handler);
@@ -66,22 +66,21 @@ function unwrapArg(arg) {
     }
     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;
+// Note: This is actually a factory function that returns a callable Proxy
+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);
+        if (typeof result == "object" && result instanceof ObjcObject) {
+            return new NobjcObject(result);
         }
-        const handler = {};
-        return new Proxy(methodFunc, handler);
+        return result;
     }
-}
+    const handler = {};
+    return new Proxy(methodFunc, handler);
+};
 class NobjcProtocol {
     static implement(protocolName, methodImplementations) {
         // Convert method names from $ notation to : notation
@@ -109,4 +108,61 @@ class NobjcProtocol {
         return new NobjcObject(nativeObj);
     }
 }
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol };
+/**
+ * Get the raw native pointer for a NobjcObject as a Node Buffer.
+ * The pointer is stored in little-endian format (8 bytes on 64-bit macOS).
+ *
+ * @param obj - The NobjcObject to get the pointer from
+ * @returns A Buffer containing the pointer address
+ *
+ * @example
+ * ```typescript
+ * const view = window.contentView();
+ * const pointerBuffer = getPointer(view);
+ * const pointer = pointerBuffer.readBigUInt64LE(0);
+ * console.log(`NSView pointer: 0x${pointer.toString(16)}`);
+ * ```
+ */
+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];
+        return GetPointer(nativeObj);
+    }
+    throw new TypeError("Argument must be a NobjcObject instance");
+}
+/**
+ * Create a NobjcObject from a raw native pointer.
+ *
+ * @param pointer - A Buffer or BigInt containing the pointer address
+ * @returns A NobjcObject wrapping the native object
+ *
+ * @example
+ * ```typescript
+ * // From a Buffer
+ * const pointerBuffer = getPointer(originalObject);
+ * const reconstructed = fromPointer(pointerBuffer);
+ *
+ * // From a BigInt
+ * const pointer = 0x12345678n;
+ * const obj = fromPointer(pointer);
+ *
+ * // Round-trip example
+ * const original = NSString.stringWithUTF8String$("Hello");
+ * const ptr = getPointer(original).readBigUInt64LE(0);
+ * const restored = fromPointer(ptr);
+ * console.log(restored.toString()); // "Hello"
+ * ```
+ *
+ * @warning This is unsafe! The pointer must point to a valid Objective-C object.
+ * Using an invalid pointer will cause a crash. The object must still be alive
+ * (not deallocated) when you call this function.
+ */
+function fromPointer(pointer) {
+    const nativeObj = FromPointer(pointer);
+    if (nativeObj === null) {
+        throw new Error("Cannot create object from null pointer");
+    }
+    return new NobjcObject(nativeObj);
+}
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, getPointer, fromPointer };

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, CreateProtocolImplementation: typeof _binding.CreateProtocolImplementation;
-export { LoadLibrary, GetClassObject, ObjcObject, CreateProtocolImplementation };
+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;
+export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation };
 export type { _binding as NobjcNative };

package/dist/native.js

@@ -1,5 +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 };
+const { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation } = binding;
+export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation };

package/package.json

@@ -36,7 +36,7 @@
     "format": "prettier --write \"**/*.{ts,js,json,md}\"",
     "preinstall-disabled": "npm run build-scripts && npm run make-clangd-config"
   },
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Objective-C bridge for Node.js",
   "main": "dist/index.js",
   "devDependencies": {