objc-js 0.0.13 → 0.0.15

package/README.md

@@ -21,9 +21,39 @@ const str = NSString.stringWithUTF8String$("Hello, World!");
 console.log(str.toString());
 ```
 
+### Subclassing Objective-C Classes
+
+**objc-js** supports defining new Objective-C classes and subclassing existing ones from JavaScript. This allows you to override methods, implement custom behavior, and integrate deeply with macOS frameworks.
+
+See [Subclassing Documentation](./docs/subclassing.md) for detailed usage and examples.
+
+#### Quick Example
+
+```typescript
+import { NobjcClass } from "objc-js";
+
+const MyClass = NobjcClass.define({
+  name: "MyCustomClass",
+  superclass: "NSObject",
+  methods: {
+    description: {
+      types: "@@:", // returns NSString
+      implementation: (self) => {
+        const superDesc = NobjcClass.super(self, "description");
+        const prefix = NSString.stringWithUTF8String$("Custom: ");
+        return prefix.stringByAppendingString$(superDesc);
+      }
+    }
+  }
+});
+
+const instance = MyClass.alloc().init();
+console.log(instance.description().toString()); // "Custom: <MyCustomClass: 0x...>"
+```
+
 ### 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.
+**objc-js** 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
 
@@ -125,6 +155,31 @@ Wrapper for Objective-C objects. Methods can be called using the `$` notation.
 const result = object.methodName$arg1$arg2$(arg1, arg2);
 ```
 
+#### `NobjcClass`
+
+Static class for defining new Objective-C classes and subclassing existing ones.
+
+```typescript
+NobjcClass.define(definition: ClassDefinition): NobjcObject
+```
+
+**Parameters:**
+
+- `definition.name`: The name of the new Objective-C class (must be unique)
+- `definition.superclass`: The name of the superclass (e.g., "NSObject", "NSView")
+- `definition.protocols`: (Optional) Array of protocol names to conform to
+- `definition.methods`: Object mapping selector names to method definitions
+
+**Returns:** The new class object (can call `.alloc().init()` on it)
+
+See [Subclassing Documentation](./docs/subclassing.md) for more details.
+
+```typescript
+NobjcClass.super(self: NobjcObject, selector: string, ...args: any[]): any
+```
+
+Call the superclass implementation of a method. Supports methods with any number of arguments, including methods with out-parameters (like `NSError**`).
+
 #### `NobjcProtocol`
 
 Static class for creating protocol implementations.

package/binding.gyp

@@ -6,18 +6,23 @@
                 "src/native/nobjc.mm",
                 "src/native/ObjcObject.mm",
                 "src/native/protocol-impl.mm",
-                "src/native/method-forwarding.mm"
+                "src/native/method-forwarding.mm",
+                "src/native/subclass-impl.mm"
             ],
             "defines": [
                 "NODE_ADDON_API_CPP_EXCEPTIONS",
                 "NAPI_VERSION=6"
             ],
             "include_dirs": [
-                "<!@(node -p \"require('node-addon-api').include\")"
+                "<!@(node -p \"require('node-addon-api').include\")",
+                "<!@(pkg-config --cflags-only-I libffi | sed 's/-I//g')"
             ],
             "dependencies": [
                 "<!(node -p \"require('node-addon-api').gyp\")"
             ],
+            "libraries": [
+                "-lffi"
+            ],
             "xcode_settings": {
                 "MACOSX_DEPLOYMENT_TARGET": "13.3",
                 "CLANG_CXX_LIBRARY": "libc++",

package/dist/index.d.ts

@@ -58,4 +58,119 @@ declare function getPointer(obj: NobjcObject): Buffer;
  * (not deallocated) when you call this function.
  */
 declare function fromPointer(pointer: Buffer | bigint): NobjcObject;
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, getPointer, fromPointer };
+/**
+ * Method definition for defining a class method.
+ */
+interface MethodDefinition {
+    /**
+     * Objective-C type encoding string.
+     * Common encodings:
+     * - @ = id (object)
+     * - : = SEL (selector)
+     * - v = void
+     * - B = BOOL
+     * - q = long long / NSInteger (64-bit)
+     * - Q = unsigned long long / NSUInteger (64-bit)
+     * - ^@ = id* (pointer to object, e.g., NSError**)
+     * - @? = block
+     *
+     * Example: "@@:@^@" means:
+     * - Return: @ (id)
+     * - self: @ (id)
+     * - _cmd: : (SEL)
+     * - arg1: @ (NSArray*)
+     * - arg2: ^@ (NSError**)
+     */
+    types: string;
+    /**
+     * The JavaScript implementation.
+     * Receives (self, ...args) where self is the instance.
+     * For NSError** out-params, the arg is an object with { set(error), get() } methods.
+     */
+    implementation: (self: NobjcObject, ...args: any[]) => any;
+}
+/**
+ * Class definition for creating a new Objective-C class.
+ */
+interface ClassDefinition {
+    /** Name of the new Objective-C class (must be unique in the runtime) */
+    name: string;
+    /** Superclass - either a class name string or a NobjcObject representing a Class */
+    superclass: string | NobjcObject;
+    /** Optional: protocols to conform to */
+    protocols?: string[];
+    /** Instance methods to implement/override */
+    methods?: Record<string, MethodDefinition>;
+    /** Optional: class methods */
+    classMethods?: Record<string, MethodDefinition>;
+}
+/**
+ * API for defining new Objective-C classes at runtime.
+ *
+ * @example
+ * ```typescript
+ * // Define a subclass of NSObject
+ * const MyClass = NobjcClass.define({
+ *   name: "MyClass",
+ *   superclass: "NSObject",
+ *   protocols: ["NSCopying"],
+ *   methods: {
+ *     "init": {
+ *       types: "@@:",
+ *       implementation: (self) => {
+ *         return NobjcClass.super(self, "init");
+ *       }
+ *     },
+ *     "myMethod:": {
+ *       types: "@@:@",
+ *       implementation: (self, arg) => {
+ *         console.log("myMethod called with", arg);
+ *         return arg;
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Create an instance
+ * const instance = MyClass.alloc().init();
+ * instance.myMethod$(someArg);
+ * ```
+ */
+declare class NobjcClass {
+    /**
+     * Define a new Objective-C class at runtime.
+     *
+     * @param definition The class definition
+     * @returns A NobjcObject representing the new Class (can be used to alloc/init instances)
+     *
+     * @warning For private methods (like _requestContextWithRequests:error:), you must provide
+     * the correct type encoding manually since it cannot be introspected from protocols.
+     */
+    static define(definition: ClassDefinition): NobjcObject;
+    /**
+     * Call the superclass implementation of a method.
+     * Use this inside a method implementation to invoke super.
+     *
+     * @param self The instance (the first argument to your implementation)
+     * @param selector The selector string (e.g., "init" or "_requestContextWithRequests:error:")
+     * @param args Additional arguments to pass to super
+     * @returns The result of the super call
+     *
+     * @example
+     * ```typescript
+     * methods: {
+     *   "init": {
+     *     types: "@@:",
+     *     implementation: (self) => {
+     *       // Call [super init]
+     *       const result = NobjcClass.super(self, "init");
+     *       // Do additional setup...
+     *       return result;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    static super(self: NobjcObject, selector: string, ...args: any[]): any;
+}
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, getPointer, fromPointer };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation } from "./native.js";
+import { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper } from "./native.js";
 const customInspectSymbol = Symbol.for("nodejs.util.inspect.custom");
 const NATIVE_OBJC_OBJECT = Symbol("nativeObjcObject");
 class NobjcLibrary {
@@ -198,4 +198,119 @@ function fromPointer(pointer) {
     }
     return new NobjcObject(nativeObj);
 }
-export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, getPointer, fromPointer };
+/**
+ * API for defining new Objective-C classes at runtime.
+ *
+ * @example
+ * ```typescript
+ * // Define a subclass of NSObject
+ * const MyClass = NobjcClass.define({
+ *   name: "MyClass",
+ *   superclass: "NSObject",
+ *   protocols: ["NSCopying"],
+ *   methods: {
+ *     "init": {
+ *       types: "@@:",
+ *       implementation: (self) => {
+ *         return NobjcClass.super(self, "init");
+ *       }
+ *     },
+ *     "myMethod:": {
+ *       types: "@@:@",
+ *       implementation: (self, arg) => {
+ *         console.log("myMethod called with", arg);
+ *         return arg;
+ *       }
+ *     }
+ *   }
+ * });
+ *
+ * // Create an instance
+ * const instance = MyClass.alloc().init();
+ * instance.myMethod$(someArg);
+ * ```
+ */
+class NobjcClass {
+    /**
+     * Define a new Objective-C class at runtime.
+     *
+     * @param definition The class definition
+     * @returns A NobjcObject representing the new Class (can be used to alloc/init instances)
+     *
+     * @warning For private methods (like _requestContextWithRequests:error:), you must provide
+     * the correct type encoding manually since it cannot be introspected from protocols.
+     */
+    static define(definition) {
+        // Convert method implementations to wrap args and unwrap returns
+        const nativeDefinition = {
+            name: definition.name,
+            superclass: typeof definition.superclass === "string" ? definition.superclass : unwrapArg(definition.superclass),
+            protocols: definition.protocols
+        };
+        if (definition.methods) {
+            nativeDefinition.methods = {};
+            for (const [selector, methodDef] of Object.entries(definition.methods)) {
+                const normalizedSelector = NobjcMethodNameToObjcSelector(selector);
+                nativeDefinition.methods[normalizedSelector] = {
+                    types: methodDef.types,
+                    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)
+                            if (arg && typeof arg === "object" && typeof arg.set === "function") {
+                                // Keep out-param objects as-is, but wrap the error objects they handle
+                                return {
+                                    set: (error) => arg.set(unwrapArg(error)),
+                                    get: () => wrapObjCObjectIfNeeded(arg.get())
+                                };
+                            }
+                            return wrapObjCObjectIfNeeded(arg);
+                        });
+                        // Call the user's implementation
+                        const result = methodDef.implementation(wrappedSelf, ...wrappedArgs);
+                        // Unwrap the return value
+                        return unwrapArg(result);
+                    }
+                };
+            }
+        }
+        // Call native DefineClass
+        const nativeClass = DefineClass(nativeDefinition);
+        // Return wrapped Class object
+        return new NobjcObject(nativeClass);
+    }
+    /**
+     * Call the superclass implementation of a method.
+     * Use this inside a method implementation to invoke super.
+     *
+     * @param self The instance (the first argument to your implementation)
+     * @param selector The selector string (e.g., "init" or "_requestContextWithRequests:error:")
+     * @param args Additional arguments to pass to super
+     * @returns The result of the super call
+     *
+     * @example
+     * ```typescript
+     * methods: {
+     *   "init": {
+     *     types: "@@:",
+     *     implementation: (self) => {
+     *       // Call [super init]
+     *       const result = NobjcClass.super(self, "init");
+     *       // Do additional setup...
+     *       return result;
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    static super(self, selector, ...args) {
+        const normalizedSelector = NobjcMethodNameToObjcSelector(selector);
+        const nativeSelf = unwrapArg(self);
+        const unwrappedArgs = args.map(unwrapArg);
+        const result = CallSuper(nativeSelf, normalizedSelector, ...unwrappedArgs);
+        return wrapObjCObjectIfNeeded(result);
+    }
+}
+export { NobjcLibrary, NobjcObject, NobjcMethod, NobjcProtocol, NobjcClass, 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, GetPointer: typeof _binding.GetPointer, FromPointer: typeof _binding.FromPointer, CreateProtocolImplementation: typeof _binding.CreateProtocolImplementation;
-export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, 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, DefineClass: typeof _binding.DefineClass, CallSuper: typeof _binding.CallSuper;
+export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper };
 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, GetPointer, FromPointer, CreateProtocolImplementation } = binding;
-export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation };
+const { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper } = binding;
+export { LoadLibrary, GetClassObject, ObjcObject, GetPointer, FromPointer, CreateProtocolImplementation, DefineClass, CallSuper };

package/package.json

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

package/src/native/bridge.h

@@ -173,6 +173,10 @@ template <typename T>
 T ConvertToNativeValue(const Napi::Value &value,
                        const ObjcArgumentContext &context) {
   if constexpr (std::is_same_v<T, id>) {
+    // Handle null/undefined as nil
+    if (value.IsNull() || value.IsUndefined()) {
+      return nil;
+    }
     // is value an ObjcObject instance?
     if (value.IsObject()) {
       Napi::Object obj = value.As<Napi::Object>();
@@ -183,6 +187,10 @@ T ConvertToNativeValue(const Napi::Value &value,
     }
   }
   if constexpr (std::is_same_v<T, SEL>) {
+    // Handle null/undefined as NULL selector
+    if (value.IsNull() || value.IsUndefined()) {
+      return nullptr;
+    }
     if (!value.IsString()) {
       throw Napi::TypeError::New(value.Env(),
                                  CONVERT_ARG_ERROR_MSG("Expected a string"));
@@ -191,18 +199,30 @@ T ConvertToNativeValue(const Napi::Value &value,
     return sel_registerName(selName.c_str());
   }
   if constexpr (std::is_same_v<T, bool>) {
+    // Handle null/undefined as false
+    if (value.IsNull() || value.IsUndefined()) {
+      return false;
+    }
     if (!value.IsBoolean()) {
       throw Napi::TypeError::New(value.Env(),
                                  CONVERT_ARG_ERROR_MSG("Expected a boolean"));
     }
     return value.As<Napi::Boolean>().Value();
   } else if constexpr (std::is_same_v<T, std::string>) {
+    // Handle null/undefined as empty string
+    if (value.IsNull() || value.IsUndefined()) {
+      return std::string();
+    }
     if (!value.IsString()) {
       throw Napi::TypeError::New(value.Env(),
                                  CONVERT_ARG_ERROR_MSG("Expected a string"));
     }
     return value.As<Napi::String>().Utf8Value();
   } else if constexpr (std::is_arithmetic_v<T>) {
+    // Handle null/undefined as 0
+    if (value.IsNull() || value.IsUndefined()) {
+      return static_cast<T>(0);
+    }
     if (value.IsNumber()) {
       return ConvertJSNumberToNativeValue<T>(value, context);
     } else if (value.IsBigInt()) {

package/src/native/debug.h

@@ -0,0 +1,19 @@
+#ifndef DEBUG_H
+#define DEBUG_H
+
+#define NOBJC_DEBUG 0
+
+// Conditional logging macro - only logs when NOBJC_DEBUG is 1
+#if NOBJC_DEBUG
+  #define NOBJC_LOG(fmt, ...) NSLog(@"" fmt, ##__VA_ARGS__)
+#else
+  #define NOBJC_LOG(fmt, ...) do { } while(0)
+#endif
+
+// Always-on error logging
+#define NOBJC_ERROR(fmt, ...) NSLog(@"ERROR: " fmt, ##__VA_ARGS__)
+
+// Always-on warning logging
+#define NOBJC_WARN(fmt, ...) NSLog(@"WARNING: " fmt, ##__VA_ARGS__)
+
+#endif // DEBUG_H