NodeJS ⇆ Objective-C bridge (experimental)
$ npm install --save objc
const objc = require('objc');
const {
NSDate,
NSDateFormatter
} = objc;
let now = NSDate.date()
let localizedDate = NSDateFormatter.localizedStringFromDate_dateStyle_timeStyle_(now, 2, 2);
console.log(localizedDate); // -> "19. Apr 2017, 22:41:13"
Import an Objective-C framework. Foundation is always imported by default
Convert a JavaScript object to its objc equivalent. Returns null
if the object doesn't have an objc counterpart.
Takes an optional second parameter to specify whether strings should be converted to NSString
objects (default), SEL
or Class
Convert an objc object to its JavaScript equivalent.
Takes an optional second parameter to specify whether it should return null
or the input if the object doesn't have a JS counterpart
When calling Objective-C methods, all you need to do is replace the colons in the selector with underscores.
For example, this Objective-C code:
#import <AppKit/AppKit.h>
NSPasteboard *pasteboard = [NSPasteboard generalPasteboard];
[pasteboard declareTypes:@[NSPasteboardTypeString] owner:nil];
[pasteboard setString:@"44 > 45" forType:NSPasteboardTypeString];
is equivalent to the following JavaScript code:
const objc = require('objc');
objc.import('AppKit');
const {NSPasteboard, NSPasteboardTypeString} = objc;
const pasteboard = NSPasteboard.generalPasteboard();
pasteboard.declareTypes_owner_([NSPasteboardTypeString], null);
pasteboard.setString_forType_("44 > 45", NSPasteboardTypeString);
The objc
module automatically catches all exceptions thrown by Objective-C methods and rethrows them as JavaScript errors.
Example:
const {NSMutableArray} = objc;
const array = NSMutableArray.array();
array.addObject_(null);
// -> throws 'NSInvalidArgumentException *** -[__NSArrayM insertObject:atIndex:]: object cannot be nil'
You can create a block with the objc.Block
helper class:
const block = new objc.Block(() => {
console.log('In the block!');
}, 'v', []);
When creating a block, you need to explicitly declare the type encoding of the block's return value and all its parameters.
Note
If a block takes an Objective-C object as its parameter, you'll need to manually wrap that object in an objc.Proxy
(via the objc.wrap
helper function).
Example: Sort an array by word length, longest to shortest
const {NSArray, Block, wrap} = objc;
const array = NSArray.arrayWithArray_(['I', 'Am', 'The', 'Doctor']);
const block = new Block((arg1, arg2) => {
arg1 = wrap(arg1);
arg2 = wrap(arg2);
return arg1.length() > arg2.length() ? -1 : 1;
}, 'q', ['@', '@']); // NSComparator returns a NSInteger and takes two ids
const sorted = array.sortedArrayUsingComparator_(block);
// => ['Doctor', 'The', 'Am', 'I']
You can load NSString*
constants just like you'd access a class:
const {NSFontAttributeName} = objc;
console.log(NSFontAttributeName); // => 'NSFont'
NSString*
constants are returned as native JavaScript String
objects.
Method swizzling allows you to replace a method's implementation:
const {NSProcessInfo} = objc;
objc.swizzle(NSProcessInfo, 'processorCount', (self, _cmd) => {
return 12;
});
NSProcessInfo.processInfo().processorCount(); // => 12
The method's original implementation is still available, with the xxx__
prefix:
const {NSDate, wrap} = objc;
objc.swizzle(NSDate, 'dateByAddingTimeInterval:', (self, _cmd, timeInterval) => {
self = wrap(self);
return self.xxx__dateByAddingTimeInterval_(timeInterval * 2);
});
const now = NSDate.date();
const a = now.dateByAddingTimeInterval_(2);
const b = now.xxx__dateByAddingTimeInterval_(4);
a.isEqualToDate_(b); // => true
Note
- Just like with blocks, you have to
wrap
all non-primitive parameters - If you want to swizzle a class method, pass
'class'
as theswizzle
function's last parameter objc.swizzle
returns a function that - if called - restores the original implementation of the swizzled method
If a method expects an inout parameter (like NSError**
), you can use the objc.allocRef
function to get a pointer to a nil
objc object that can be passed to a method expecting an id*
:
const {NSAppleScript} = objc;
const script = NSAppleScript.alloc().initWithSource_('foobar');
const error = objc.allocRef();
script.executeAndReturnError_(error); // `executeAndReturnError:` takes a `NSDictionary**`
console.log(error); // `error` is now a `NSDictionary*`
Output:
[objc.InstanceProxy {
NSAppleScriptErrorBriefMessage = "The variable foobar is not defined.";
NSAppleScriptErrorMessage = "The variable foobar is not defined.";
NSAppleScriptErrorNumber = "-2753";
NSAppleScriptErrorRange = "NSRange: {0, 6}";
}]
If you need more advanced inout functionality (using primitive types, etc), simply use the ref
module.
Use the objc.createClass
function to register custom classes with the Objective-C runtime:
const objc = require('objc');
const LKGreeter = objc.createClass('LKGreeter', 'NSObject', {
'greet:': (self, cmd, name) => {
name = objc.wrap(name);
return objc.ns(`Hello, ${name}!`);
},
_encodings: {
'greet:': ['@', ['@', ':', '@']]
}
});
LKGreeter.new().greet('Lukas'); // => 'Hello, Lukas!'
Note: You might have to specify individual offsets in the type encoding, see this example.
In the future, I'd like to add support for:
- structs, c-style arrays, unions as method parameter/return type
- runtime introspection (accessing an object's properties, ivars, methods, etc)
- improved class creation api
- improved support for inout parameters (
id*
)
MIT © Lukas Kollmer