objcjs-types 0.6.4 → 0.7.1

package/generator/emitter.ts

@@ -546,7 +546,7 @@ function getMergedProtocols(
   interface Sig {
     returnType: string;
     paramTypes: string[];
-    /** Whether this signature came from a protocol (optional in TS) vs a class body (non-optional). */
+    /** Whether this signature is optional in TypeScript. */
     isOptional: boolean;
   }
   const inherited = new Map<string, Sig>();
@@ -684,7 +684,7 @@ function collectProtocolSignatures(
       sigs.set(jsName, {
         returnType: mapReturnType(method.returnType, containingClass),
         paramTypes: method.parameters.map((p) => mapParamType(p.type, containingClass)),
-        isOptional: true
+        isOptional: method.isOptional
       });
     }
   }
@@ -695,7 +695,7 @@ function collectProtocolSignatures(
       sigs.set(prop.name, {
         returnType: mapReturnType(prop.type, containingClass),
         paramTypes: [],
-        isOptional: true
+        isOptional: prop.isOptional
       });
     }
     if (!prop.readonly) {
@@ -708,7 +708,7 @@ function collectProtocolSignatures(
         sigs.set(setterName, {
           returnType: "void",
           paramTypes: [paramType],
-          isOptional: true
+          isOptional: prop.isOptional
         });
       }
     }
@@ -745,10 +745,8 @@ function checkProtocolConflicts(
     const retType = mapReturnType(method.returnType, containingClass);
     if (retType !== parentSig.returnType) return true;
 
-    // Protocol methods are emitted as optional (foo?()) but class methods are
-    // non-optional (foo()). TypeScript considers these "not identical" in an
-    // interface extends clause, producing TS2320.
-    if (!parentSig.isOptional) return true;
+    // TypeScript interface merging requires optionality to match.
+    if (method.isOptional !== parentSig.isOptional) return true;
 
     const paramTypes = method.parameters.map((p) => mapParamType(p.type, containingClass));
     if (paramTypes.length === parentSig.paramTypes.length) {
@@ -765,13 +763,13 @@ function checkProtocolConflicts(
     if (parentSig) {
       const tsType = mapReturnType(prop.type, containingClass);
       if (tsType !== parentSig.returnType) return true;
-      if (!parentSig.isOptional) return true;
+      if (prop.isOptional !== parentSig.isOptional) return true;
     }
     if (!prop.readonly) {
       const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
       const parentSetterSig = inherited.get(setterName);
       if (parentSetterSig) {
-        if (!parentSetterSig.isOptional) return true;
+        if (prop.isOptional !== parentSetterSig.isOptional) return true;
         let paramType = mapParamType(prop.type, containingClass);
         if (prop.nullResettable && !paramType.includes("| null")) {
           paramType = `${paramType} | null`;
@@ -1483,7 +1481,7 @@ export function emitProtocolFile(
   // Split properties into class and instance
   const instanceProps = proto.properties.filter((p) => !p.isClassProperty);
 
-  // Emit instance methods (all optional with ? syntax)
+  // Emit instance methods
   const instancePropertyNames = new Set(instanceProps.map((p) => p.name));
   const regularMethods = proto.instanceMethods.filter((m) => !instancePropertyNames.has(m.selector));
 
@@ -1512,11 +1510,12 @@ export function emitProtocolFile(
         selector: method.selector
       });
       if (jsdoc.length > 0) lines.push(...jsdoc);
-      lines.push(`  ${jsName}?(${params.join(", ")}): ${returnType};`);
+      const optional = method.isOptional ? "?" : "";
+      lines.push(`  ${jsName}${optional}(${params.join(", ")}): ${returnType};`);
     }
   }
 
-  // Emit instance properties (as optional getter methods)
+  // Emit instance properties
   if (instanceProps.length > 0) {
     if (regularMethods.length > 0) lines.push("");
     lines.push("  // Properties");
@@ -1528,7 +1527,8 @@ export function emitProtocolFile(
         deprecationMessage: prop.deprecationMessage
       });
       if (jsdoc.length > 0) lines.push(...jsdoc);
-      lines.push(`  ${prop.name}?(): ${tsType};`);
+      const optional = prop.isOptional ? "?" : "";
+      lines.push(`  ${prop.name}${optional}(): ${tsType};`);
       if (!prop.readonly) {
         const setterName = `set${prop.name[0]!.toUpperCase()}${prop.name.slice(1)}$`;
         let paramType = mapParamType(prop.type, proto.name);
@@ -1536,7 +1536,7 @@ export function emitProtocolFile(
         if (prop.nullResettable && !paramType.includes("| null")) {
           paramType = `${paramType} | null`;
         }
-        lines.push(`  ${setterName}?(value: ${paramType}): void;`);
+        lines.push(`  ${setterName}${optional}(value: ${paramType}): void;`);
       }
     }
   }
@@ -1641,6 +1641,8 @@ export function emitStringEnumFile(enumDef: ObjCStringEnum, _currentFrameworkNam
   const lines: string[] = [];
   lines.push(AUTOGEN_HEADER);
   lines.push("");
+  lines.push(`import type { NSStringLiteral } from "../helpers.js";`);
+  lines.push("");
 
   // Filter to values that were successfully resolved
   const resolvedValues = enumDef.values.filter((v) => v.value !== null);
@@ -1657,7 +1659,8 @@ export function emitStringEnumFile(enumDef: ObjCStringEnum, _currentFrameworkNam
     lines.push(`} as const;`);
 
     lines.push(`export type ${enumDef.name} =`);
-    lines.push(`  typeof ${enumDef.name}[keyof typeof ${enumDef.name}];`);
+    lines.push(`  | NSStringLiteral<(typeof ${enumDef.name})[keyof typeof ${enumDef.name}]>`);
+    lines.push(`  | (typeof ${enumDef.name})[keyof typeof ${enumDef.name}];`);
   } else {
     // Fallback: if no values could be resolved, emit short names as a JSDoc comment
     // and a type alias that accepts any string (for forward compatibility)
@@ -1668,7 +1671,7 @@ export function emitStringEnumFile(enumDef: ObjCStringEnum, _currentFrameworkNam
       lines.push(` * Values could not be resolved from the framework binary.`);
       lines.push(` */`);
     }
-    lines.push(`export type ${enumDef.name} = string;`);
+    lines.push(`export type ${enumDef.name} = NSStringLiteral<string>;`);
   }
 
   lines.push("");

package/generator/templates/helpers.ts

@@ -8,17 +8,27 @@ import {
   type _NSString
 } from "./Foundation/index.js";
 
+declare const NS_STRING_LITERAL: unique symbol;
+/**
+ * NSString subtype that preserves the originating string literal in the type system.
+ *
+ * This is a compile-time brand only. At runtime it is still just an NSString.
+ */
+export interface NSStringLiteral<T extends string = string> extends _NSString {
+  readonly [NS_STRING_LITERAL]?: T;
+}
+
 /**
  * Create NSString from a JavaScript string
  * @param str The string object
  * @returns An NSString object
  */
-export function NSStringFromString(str: string): _NSString {
+export function NSStringFromString<T extends string>(str: T): NSStringLiteral<T> {
   const nsString = NSString.stringWithUTF8String$(str);
   if (!nsString) {
     throw new Error(`Failed to create NSString from string: ${str}`);
   }
-  return nsString;
+  return nsString as NSStringLiteral<T>;
 }
 
 /**

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/generator/type-mapper.ts

@@ -465,6 +465,31 @@ function mapTypeInner(
   return "NobjcObject";
 }
 
+/**
+ * Check whether a type should be represented as an NSString object when used
+ * as a parameter at runtime.
+ *
+ * Certain NSString typedef aliases should still be represented as NSString
+ * objects in parameter position. String enums are handled via their own
+ * branded enum types, so they are intentionally excluded here.
+ */
+function isNSStringRuntimeParamType(cleaned: string, resolving?: Set<string>): boolean {
+  if (cleaned in DIRECT_MAPPINGS) {
+    return DIRECT_MAPPINGS[cleaned] === "_NSString";
+  }
+
+  if (knownTypedefs.has(cleaned)) {
+    const seen = resolving ?? new Set<string>();
+    if (!seen.has(cleaned)) {
+      seen.add(cleaned);
+      const underlying = knownTypedefs.get(cleaned)!;
+      return isNSStringRuntimeParamType(cleanQualType(underlying), seen);
+    }
+  }
+
+  return false;
+}
+
 /**
  * Map a return type, handling instancetype specially.
  *
@@ -872,5 +897,9 @@ export function mapParamType(qualType: string, containingClass: string, blockPar
     const nullable = isNullableType(qualType);
     return nullable ? "Uint8Array | null" : "Uint8Array";
   }
+  if (isNSStringRuntimeParamType(cleaned)) {
+    const nullable = isNullableType(qualType);
+    return nullable ? "_NSString | null" : "_NSString";
+  }
   return mapType(qualType, containingClass, false, blockParamNames);
 }

package/package.json

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