objcjs-types 0.6.3 → 0.7.0

package/README.md

@@ -108,6 +108,39 @@ if (isKindOfClass<_ASAuthorizationAppleIDCredential>(cred, ASAuthorizationAppleI
 
 Both `instanceof` and `isKindOfClass` cache results per (object, class) pair so repeated checks skip the native boundary.
 
+### Subclassing
+
+`defineSubclass` wraps `NobjcClass.define()` with type safety — `self` is typed as the superclass, protocol method names get autocomplete, and the returned class supports `alloc`/`init` and `instanceof`:
+
+```ts
+import { NSObject } from "objcjs-types/Foundation";
+import { defineSubclass, callSuper } from "objcjs-types/subclass";
+
+const MyDelegate = defineSubclass(NSObject, {
+  name: "MyDelegate",
+  protocols: ["NSWindowDelegate"],
+  methods: {
+    windowDidResize$: {
+      types: "v@:@",
+      implementation(self, notification) {
+        console.log("Resized!");
+      }
+    },
+    init: {
+      types: "@@:",
+      implementation(self) {
+        return callSuper(self, "init");
+      }
+    }
+  }
+});
+
+const instance = MyDelegate.alloc().init();
+window.setDelegate$(instance);
+```
+
+Use `callSuper` inside method implementations to invoke the superclass version of a method.
+
 ### NS_OPTIONS
 
 Use `options()` to combine bitmask flags with type safety:
@@ -175,14 +208,15 @@ const nsStr = NSStringFromString("hello");
 
 ## Subpath exports
 
-| Import path                | Contents                                               |
-| -------------------------- | ------------------------------------------------------ |
-| `objcjs-types`             | Structs, `createDelegate`, barrel re-exports           |
-| `objcjs-types/helpers`     | `NSStringFromString`, `options`, `isKindOfClass`, etc. |
-| `objcjs-types/nsdata`      | NSData/Buffer conversion utilities                     |
-| `objcjs-types/osversion`   | macOS version detection and comparison                 |
-| `objcjs-types/delegates`   | `createDelegate` and `ProtocolMap` type                |
-| `objcjs-types/<Framework>` | Framework exports (e.g. `objcjs-types/AppKit`)         |
+| Import path                | Contents                                                 |
+| -------------------------- | -------------------------------------------------------- |
+| `objcjs-types`             | Structs, `createDelegate`, `defineSubclass`, `callSuper` |
+| `objcjs-types/helpers`     | `NSStringFromString`, `options`, `isKindOfClass`, etc.   |
+| `objcjs-types/subclass`    | `defineSubclass`, `callSuper`                            |
+| `objcjs-types/nsdata`      | NSData/Buffer conversion utilities                       |
+| `objcjs-types/osversion`   | macOS version detection and comparison                   |
+| `objcjs-types/delegates`   | `createDelegate` and `ProtocolMap` type                  |
+| `objcjs-types/<Framework>` | Framework exports (e.g. `objcjs-types/AppKit`)           |
 
 ## ObjC selector naming
 

package/dist/subclass.d.ts

@@ -10,6 +10,17 @@ import type { NobjcObject } from "objc-js";
 import type { ProtocolMap } from "./delegates.js";
 /** Converts a union type to an intersection type. */
 type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * Extracts only explicitly declared (non-index-signature) string keys from a type.
+ *
+ * Generated ObjC classes extend `NobjcObject` which has `[key: string]: NobjcMethod`.
+ * Plain `keyof T` includes `string` from that index signature, defeating autocomplete
+ * and generic key constraints. This type filters it out, keeping only the known
+ * literal method names like `"init"`, `"description"`, `"setTitle$"`, etc.
+ */
+type DeclaredKeys<T> = Extract<keyof {
+    [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K]: T[K];
+}, string>;
 /**
  * A method definition for a subclass.
  *
@@ -42,14 +53,12 @@ type ProtocolMethodKeys<TProtocols extends keyof ProtocolMap> = Extract<keyof Un
 /**
  * Methods record for a subclass definition.
  *
- * Provides autocomplete for method names from the specified protocols
- * while allowing arbitrary method names for custom methods or
- * superclass overrides.
+ * Provides autocomplete for method names from the superclass and any
+ * specified protocols, while still allowing arbitrary method names for
+ * custom methods via `(string & {})`.
  */
 type SubclassMethods<TSelf, TProtocols extends keyof ProtocolMap> = {
-    [key: string]: SubclassMethodDef<TSelf> | undefined;
-} & {
-    [K in ProtocolMethodKeys<TProtocols>]?: SubclassMethodDef<TSelf>;
+    [K in ProtocolMethodKeys<TProtocols> | DeclaredKeys<TSelf> | (string & {})]?: SubclassMethodDef<TSelf>;
 };
 /**
  * Define a new Objective-C subclass at runtime with TypeScript type safety.
@@ -103,20 +112,27 @@ export declare function defineSubclass<TClass extends abstract new (...args: any
  * Call the superclass implementation of a method from within a subclass
  * method implementation.
  *
+ * The selector is constrained to method names on the `self` type, giving
+ * autocomplete and validating that a super implementation exists. Arguments
+ * and return type are inferred from the superclass method signature.
+ *
+ * For dynamic selectors not known at compile time, use `NobjcClass.super()`
+ * from `objc-js` directly.
+ *
  * @param self - The instance (`self`, the first argument of your implementation)
- * @param selector - The method selector (e.g. `"init"`, `"viewDidLoad"`)
- * @param args - Arguments to forward to the super implementation
- * @returns The result of the super call
+ * @param selector - The method name to call on super (e.g. `"init"`, `"viewDidLoad"`)
+ * @param args - Arguments matching the superclass method's parameter types
+ * @returns The return type of the superclass method
  *
  * @example
  * ```ts
  * init: {
  *   types: "@@:",
  *   implementation(self) {
- *     return callSuper(self, "init");
+ *     return callSuper(self, "init"); // returns _NSObject
  *   },
  * }
  * ```
  */
-export declare function callSuper(self: NobjcObject, selector: string, ...args: unknown[]): any;
+export declare function callSuper<TSelf, K extends DeclaredKeys<TSelf>>(self: TSelf, selector: K, ...args: TSelf[K] extends (...a: infer A) => any ? A : any[]): TSelf[K] extends (...a: any[]) => infer R ? R : any;
 export {};

package/dist/subclass.js

@@ -79,17 +79,24 @@ export function defineSubclass(superclass, definition) {
  * Call the superclass implementation of a method from within a subclass
  * method implementation.
  *
+ * The selector is constrained to method names on the `self` type, giving
+ * autocomplete and validating that a super implementation exists. Arguments
+ * and return type are inferred from the superclass method signature.
+ *
+ * For dynamic selectors not known at compile time, use `NobjcClass.super()`
+ * from `objc-js` directly.
+ *
  * @param self - The instance (`self`, the first argument of your implementation)
- * @param selector - The method selector (e.g. `"init"`, `"viewDidLoad"`)
- * @param args - Arguments to forward to the super implementation
- * @returns The result of the super call
+ * @param selector - The method name to call on super (e.g. `"init"`, `"viewDidLoad"`)
+ * @param args - Arguments matching the superclass method's parameter types
+ * @returns The return type of the superclass method
  *
  * @example
  * ```ts
  * init: {
  *   types: "@@:",
  *   implementation(self) {
- *     return callSuper(self, "init");
+ *     return callSuper(self, "init"); // returns _NSObject
  *   },
  * }
  * ```

package/generator/templates/subclass.ts

@@ -15,6 +15,19 @@ import type { ProtocolMap } from "./delegates.js";
 /** Converts a union type to an intersection type. */
 type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 
+/**
+ * Extracts only explicitly declared (non-index-signature) string keys from a type.
+ *
+ * Generated ObjC classes extend `NobjcObject` which has `[key: string]: NobjcMethod`.
+ * Plain `keyof T` includes `string` from that index signature, defeating autocomplete
+ * and generic key constraints. This type filters it out, keeping only the known
+ * literal method names like `"init"`, `"description"`, `"setTitle$"`, etc.
+ */
+type DeclaredKeys<T> = Extract<
+  keyof { [K in keyof T as string extends K ? never : number extends K ? never : symbol extends K ? never : K]: T[K] },
+  string
+>;
+
 /**
  * A method definition for a subclass.
  *
@@ -52,13 +65,13 @@ type ProtocolMethodKeys<TProtocols extends keyof ProtocolMap> = Extract<
 /**
  * Methods record for a subclass definition.
  *
- * Provides autocomplete for method names from the specified protocols
- * while allowing arbitrary method names for custom methods or
- * superclass overrides.
+ * Provides autocomplete for method names from the superclass and any
+ * specified protocols, while still allowing arbitrary method names for
+ * custom methods via `(string & {})`.
  */
 type SubclassMethods<TSelf, TProtocols extends keyof ProtocolMap> = {
-  [key: string]: SubclassMethodDef<TSelf> | undefined;
-} & { [K in ProtocolMethodKeys<TProtocols>]?: SubclassMethodDef<TSelf> };
+  [K in ProtocolMethodKeys<TProtocols> | DeclaredKeys<TSelf> | (string & {})]?: SubclassMethodDef<TSelf>;
+};
 
 /**
  * Define a new Objective-C subclass at runtime with TypeScript type safety.
@@ -150,21 +163,32 @@ export function defineSubclass<
  * Call the superclass implementation of a method from within a subclass
  * method implementation.
  *
+ * The selector is constrained to method names on the `self` type, giving
+ * autocomplete and validating that a super implementation exists. Arguments
+ * and return type are inferred from the superclass method signature.
+ *
+ * For dynamic selectors not known at compile time, use `NobjcClass.super()`
+ * from `objc-js` directly.
+ *
  * @param self - The instance (`self`, the first argument of your implementation)
- * @param selector - The method selector (e.g. `"init"`, `"viewDidLoad"`)
- * @param args - Arguments to forward to the super implementation
- * @returns The result of the super call
+ * @param selector - The method name to call on super (e.g. `"init"`, `"viewDidLoad"`)
+ * @param args - Arguments matching the superclass method's parameter types
+ * @returns The return type of the superclass method
  *
  * @example
  * ```ts
  * init: {
  *   types: "@@:",
  *   implementation(self) {
- *     return callSuper(self, "init");
+ *     return callSuper(self, "init"); // returns _NSObject
  *   },
  * }
  * ```
  */
-export function callSuper(self: NobjcObject, selector: string, ...args: unknown[]): any {
-  return NobjcClass.super(self, selector, ...args);
+export function callSuper<TSelf, K extends DeclaredKeys<TSelf>>(
+  self: TSelf,
+  selector: K,
+  ...args: TSelf[K] extends (...a: infer A) => any ? A : any[]
+): TSelf[K] extends (...a: any[]) => infer R ? R : any {
+  return NobjcClass.super(self as any, selector as string, ...args);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objcjs-types",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "Auto-generated TypeScript type declarations for macOS Objective-C frameworks that supplement objc-js",
   "type": "module",
   "sideEffects": false,