RFC: Native ES classes — constructors that always run, interop.initializer, and real Objective-C hierarchies

[edusperoni]

RFC: Native ES classes — constructors that always run, interop.initializer, and real Objective-C hierarchies

Status	Proposed — iOS implemented, Android pending
Supersedes	ios#403 (native ES classes with lazy registration)
Implementation	iOS: feat/es-classes-construction — ios#403's lazy registration (@NathanWalker) rebased on main, then the Objective-C hierarchy and the construction contract

Summary

NativeScript lets you subclass native types. ios#403 made that work with plain ES classes — class MyView extends UIView {} with no decorator and no ES5 downleveling, registered with the Objective-C runtime lazily on first use. That makes extending native classes cheap: unlike .extend() and @NativeClass, which register every subclass when its module loads, a class costs nothing native until it's actually used. This RFC builds on that and proposes the contract for how those classes are constructed, which NativeScript/ios#403 left open:

1. The JS constructor runs for every instance, however it was created — new MyView(), MyView.alloc().initWithFrame(f), a storyboard, cell reuse, NSCoding, or an Objective-C factory. Class fields and #private members always exist.
2. A constructor takes one options object. The user's own keys are plain JS data. The runtime adds two symbol-keyed entries: [interop.initializer.args] picks the native initializer, and [interop.initializer.native] is present when Objective-C started the construction. The interop.Args<T> type makes "your keys may be missing because Objective-C created this" a type-checked fact, not a convention.
3. The Objective-C class hierarchy mirrors the JS one. class B extends A extends UIView gives [b isKindOfClass:A] == YES, and an ES class may extend a legacy .extend() class.

Android is pending; the API is designed to carry over (see Android).

Motivation

Extending a native class should cost nothing until it's used. Today both ways of subclassing register the Objective-C class when the class is defined: .extend() allocates and registers it on the call, and the TypeScript __extends path (what @NativeClass downlevels to) does the same as soon as the class body evaluates. In practice that's module load, i.e. app startup. Every delegate, data source and view subclass an app or @nativescript/core defines pays for objc_allocateClassPair/objc_registerClassPair up front, whether or not that screen is ever opened, and a registered class can never be unregistered. Plain ES classes register lazily instead: defining class X extends UIView {} touches nothing native, the class is registered the first time it's constructed, allocated, called statically, or handed to Objective-C, and a class that's never used never reaches the Objective-C runtime. Code that needs the class to exist up front under its own name (storyboards, NSClassFromString) opts in with NativeClass({ name, eager: true }). Making these classes the first-class way to extend native types — instead of an ES5-downleveled special case — is only worth it if their construction is as reliable as the legacy paths, which is what the rest of this RFC is about.

Two different objects depending on who created them. Objects Objective-C creates itself (alloc]/init, cell reuse, storyboards, NSCoding) reached JS as a bare object with the class prototype grafted on. They never ran [[Construct]], so class fields were undefined, #private access threw, and constructor logic was skipped. new MyView() and MyView.alloc().init() produced objects that looked the same and behaved differently.

Constructor arguments that mean two things. new NSFoo(a, b) picks a native initializer by matching JS value shapes against initializer signatures — initWithInt: and initWithDouble: are indistinguishable, and null matches anything. In a subclass, the same positional arguments also had to carry the class's own data. The generated .d.ts already only types the token form (constructor(o: { frame: CGRect })).

The static-factory workaround. Because constructors don't reliably run, @nativescript/core is full of:

static initWithOwner(owner: WeakRef<ListView>): UITableViewDelegateImpl {
  const delegate = <UITableViewDelegateImpl>UITableViewDelegateImpl.new();
  delegate._owner = owner;
  return delegate;
}

We want new UITableViewDelegateImpl({ owner }) to just work.

A flattened hierarchy. NativeScript/ios#403 registered B extends A extends UIView as two sibling Objective-C classes under UIView, copying A's methods into B. b instanceof A was true in JS and [b isKindOfClass:A] false in Objective-C — breaking UIAppearance, class-keyed registration and KVO.

Guide-level explanation

1. The constructor always runs

class BadgeCell extends UITableViewCell {
  count = 0;
  #dot = CAShapeLayer.new();

  constructor(args: interop.Args<{ count?: number }> = {}) {
    super(args);
    if (!args[interop.initializer.native]) {
      this.count = args.count ?? 0;
    }
    this.contentView.layer.addSublayer(this.#dot);
  }
}

new BadgeCell({ count: 3 });                                         // JS creates it
BadgeCell.alloc().initWithFrame(rect);                               // an Objective-C initializer, sent from JS
tableView.registerClassForCellReuseIdentifier(BadgeCell, 'badge');   // UIKit creates them on dequeue

In every case, the order is the same as for any ES class: native initializer → class fields → constructor body. super(...) is where the native initializer runs, so this exists (and is fully initialized natively) after it, exactly like plain JS.

2. One options object, with honest types

interop.Args<T> is a union of the two ways a constructor can be reached:

type Args<T extends object = {}, I = object> =
  | (T & { [interop.initializer.args]?: I; [interop.initializer.native]?: undefined })  // `new X({...})`
  | { [interop.initializer.args]: I; [interop.initializer.native]: interop.NativeInit }; // Objective-C created it

• Call sites stay flat and keep required keys required: new Delegate({ owner, list }) compiles, new Delegate({ owner }) does not.

• Inside the constructor you must pick a path before reading your data — args.owner without narrowing is a type error:

  constructor(args: interop.Args<{ owner: Owner; list: ListView }>) {
    super(args);
    if (args[interop.initializer.native]) {
      return;                                   // a storyboard, cell reuse, … — no JS data
    }
    this.owner = args.owner;                    // Owner, not Owner | undefined
  }

• Union shapes work: interop.Args<{ owner: Owner; style: number } | { owner: Owner; nib: string }> narrows with in (or a kind tag, which also makes TypeScript reject a literal mixing both variants' keys).

• Classes with no data of their own just write constructor(args: interop.Args = {}), or no constructor at all.

3. Choosing the native initializer

The initializer is named by its constructor tokens — the same keys the generated .d.ts uses — under [interop.initializer.args]:

class Cell extends UITableViewCell {
  constructor(args: interop.Args<{ id: string }, UITableViewCellInit> = {}) {
    super({ [interop.initializer.args]: { style: UITableViewCellStyle.Subtitle, reuseIdentifier: 'cell' }, ...args });
  }
}

• No [interop.initializer.args] → init.
• Keys match as a set: { reuseIdentifier, style } and { style, reuseIdentifier } both pick initWithStyle:reuseIdentifier:. Order only breaks a tie between two initializers taking the same set.
• Error-out initializers never expose their NSError** as a token: { parameter1, parameter2 } runs initWithParameter1:parameter2:error:.
• A parameterless initializer is named by its token alone: { empty: undefined } runs initWithEmpty (the generated .d.ts already types it { empty: void }).
• The class's own keys never pick an initializer, so { frame } as user data is just data.

4. When Objective-C starts the construction

When Objective-C sends an initializer ([[Cell alloc] initWithStyle:… reuseIdentifier:…], a storyboard's initWithCoder:, MyView.alloc().initWithFrame(f) from JS), the runtime calls the constructor with:

{
  [interop.initializer.native]: { selector: 'initWithStyle:reuseIdentifier:', args: [3, 'cell'] }, // frozen
  [interop.initializer.args]: { style: 3, reuseIdentifier: 'cell' },                              // prefilled
}

super(args) then runs that initializer with Objective-C's original arguments, exactly once. The prefilled tokens object is frozen: to change an argument, pass a new object ({ ...args, [interop.initializer.args]: { frame: inset(frame) } }), which runs the initializer with the JS values instead. Because the runtime prefills [interop.initializer.args], spread order decides who wins, on both paths:

// Default: used only when the creator didn't choose (`new X()`, or Objective-C sent init)
super({ [interop.initializer.args]: { style: UITableViewStyle.Grouped }, ...args });

// Force — like ObjC's  -init { return [super initWithStyle:UITableViewStyleGrouped]; }
super({ ...args, [interop.initializer.args]: { style: UITableViewStyle.Grouped } });

// Force, but keep a storyboard's decoding
if (args[interop.initializer.native]?.selector === 'initWithCoder:') super(args);
else super({ ...args, [interop.initializer.args]: { style: UITableViewStyle.Grouped } });

The same spread order gives JS subclasses of JS subclasses the usual override semantics: a parent that defaults lets its subclass choose; a parent that forces doesn't.

5. Initializers the runtime never sees: construction on first use

The runtime hooks every initializer the metadata lists for the native base class. Some objects are created through initializers the metadata doesn't list — typically a public class factory that runs a private initializer:

// SomeKit (Objective-C): the initializer is not in any header
@implementation SKWidget
+ (instancetype)widgetWithStyle:(SKStyle)style { return [[self alloc] initPrivatelyWithStyle:style]; }
@end

class FancyWidget extends SKWidget {
  ripple = new Ripple();
  constructor(args: interop.Args = {}) {
    super(args);
  }
}

const widget = FancyWidget.widgetWithStyle(SKStyle.Plain); // -initPrivatelyWithStyle: is never seen
widget.ripple;                                              // constructed: the instance was adopted

Such an object is constructed the first time it reaches JS — as a return value, an argument, or this in the first overridden method Objective-C calls on it. The constructor receives { [interop.initializer.native]: { selector: null, args: [] } } and no [interop.initializer.args]: the object is already initialized, so super(args) binds it as is and no initializer runs.

Two consequences worth knowing:

• If an override is called during that unseen initializer, construction happens there, before the initializer finished.
• If the object never reaches JS, its constructor never runs.

6. Subclassing ES classes — and legacy classes

class Base extends UIView { layoutSubviews() { super.layoutSubviews(); /* … */ } }
class Fancy extends Base  { layoutSubviews() { super.layoutSubviews(); /* … */ } }

const f = new Fancy();
f.isKindOfClass(Base);          // true — Fancy's Objective-C class is a subclass of Base's
Fancy.superclass() === Base;    // true

Objective-C dispatch reaches each JS level, and every super.foo() lands one level up. An ES class may also extend a legacy .extend() class (previously refused); the legacy class's this.super keeps working. Extending an .extend() class with .extend() is still not supported.

7. Errors

You write	You get
super(7), super(a, b), super(someClassInstance)	error: takes no arguments or a single options object
super({ frame }) (the old token spelling)	error pointing at { [interop.initializer.args]: { frame } } — it would otherwise silently run init
{ [interop.initializer.args]: { frme } }	No initializer of X takes { frme }. Available: { frame }, { coder }, {}
an init() / initWithFrame() method in an ES class	error at registration: the constructor already runs for every initializer
passing [interop.initializer.native] to an unrelated super(...)	error: it belongs to the construction Objective-C started
a constructor that throws when Objective-C started the construction	reported through the uncaught-error pipeline (error event / __onUncaughtError); the initializer returns nil. Thrown normally for new.
an initializer that raises an NSException	a JS Error with the exception's name/reason and nativeException, like any other native call

Reference-level details

Registration. class X extends Native {} registers lazily (first construction, alloc, static call, or when passed where a Class/id is expected), or eagerly via NativeClass({ name, eager }) (NativeScript/ios#403). A JS-defined parent is registered first and becomes the superclass. Only the class's own prototype level is exposed; inherited members come through Objective-C inheritance.

Initializer hooks. On the first ES class above a native (or legacy) base, the runtime installs a hook for every initializer the metadata lists that the base actually implements (optional protocol initializers the base lacks are skipped, so respondsToSelector: doesn't change; variadic ones are skipped). ES subclasses inherit the hooks. A hook either:

• passes straight through to the superclass implementation, when JS is already constructing that object (new X(), or a nested initializer like init → initWithFrame:), or
• calls the JS constructor of the object's class with the options above, and returns what super(...) produced.

super(...). Accepts nothing, undefined, or one plain object (object literal or spread; a class instance is rejected). It reads only the two symbol keys. On the native path it claims the pending construction only if the class matches and any [interop.initializer.native] value is the one the runtime created — so a nested new Other() evaluated in the constructor's arguments can't steal it. (A constructor that constructs its own class before calling super() is the one case that can; the inner instance claims the native object and the outer super() fails with a clear error.)

Dynamic subclasses. An instance whose runtime class is a dynamic subclass of an ES class (KVO's NSKVONotifying_…) is constructed as that ES class.

Binding before init. this is bound to the native object before the initializer runs, on both paths, so overrides the initializer calls (setFrame:, traitCollectionDidChange: …) see the instance under construction. As in any JS class whose base constructor calls an overridden method, fields aren't initialized yet at that point. If the initializer returns a different object, this is rebound; if it returns an already-wrapped object (a singleton), that object becomes the result of super(...).

Ownership. The JS instance holds its own reference; the Objective-C caller keeps the one the initializer returned. On a failing construction started by Objective-C, the caller's allocation is released (as a failing initializer does) and nil returned.

super.method() reaching a native method dispatches to the superclass of the rootmost JS-defined class in the receiver's chain, not the receiver's immediate superclass — every JS-defined class in between would call back into JS and recurse.

Symbols. interop.initializer.args / .native come from V8's API symbol registry: one pair per isolate, shared by its contexts, and not reachable through Symbol.for.

Workers. Unchanged from NativeScript/ios#403: classes are isolate-scoped, eager registration no-ops on workers.

TypeScript

declare namespace interop {
  const initializer: { readonly args: unique symbol; readonly native: unique symbol };

  /** What the runtime passes when Objective-C started the construction. Opaque: cannot be constructed in user code. */
  class NativeInit {
    private constructor();
    readonly selector: string | null;   // null when adopted on first use
    readonly args: readonly unknown[];
  }

  type Args<T extends object = {}, I = object> =
    | (T & { readonly [initializer.args]?: I; readonly [initializer.native]?: undefined })
    | { readonly [initializer.args]: I; readonly [initializer.native]: NativeInit };
}

• The metadata generator would emit, per class, the union of its initializers' token objects (e.g. UITableViewControllerInit = { style } | { coder } | { nibName; bundle }) and a constructor(args: interop.Args<{}, XInit>) overload, so [interop.initializer.args] is checked against the base class's real initializers (a misspelled token is a compile error).
• @NativeClass can enforce the contract with a conditional-type check: the object the runtime passes on the native path must be assignable to the constructor's parameter. That accepts Args<…>, no-argument and implicit constructors, and rejects (owner: Owner), (a: { owner: Owner }), and a JS-only (a: T & {…}) that forgot the native case. Undecorated classes rely on the runtime checks.
• All of the above was verified with TypeScript 5.7 under both legacy and standard decorators. One known limit: TypeScript's excess-property check is loose for non-discriminated unions, so { owner, something, somethingElse } is accepted by Args<A | B> unless the variants carry a tag.

Drawbacks

• User code runs inside native initializers (storyboard decoding, cell dequeue). It can't throw into Objective-C, so failures there are reported and the initializer returns nil, rather than surfacing at a JS call site.
• init*() overrides are rejected in ES classes. Code using the earlier workaround (init() { const self = super.init(); … }) must move to the constructor. Legacy .extend() classes are unaffected.
• First-use construction is lazy for initializers outside the metadata: it can run mid-initializer, or never.
• One FFI closure per hooked initializer per ES root class (UIView's chain: a handful).
• Constructor data is absent for Objective-C-created instances. That's inherent — a storyboard can't hand you an owner — but the types now say so.

Alternatives considered

• Adopt on first sight only (feat: support native ES classes with lazy registration, including static usage before construction ios#403's latest commit). Runs the constructor whenever JS first sees the object: possibly mid-initializer, possibly never (a storyboard view gets the subviews its constructor adds only once JS touches it), always with zero arguments, ignoring super's arguments. Its single pending slot was consumed by any construct, so super({ url: new NSURL(…) }) bound the NSURL wrapper to the wrong object. Kept here only as the fallback for initializers the runtime can't hook.
• Override init() as the one shared hook. Doesn't give class fields or #private to Objective-C-created instances.
• No-argument super(), creator picks the initializer (X.alloc().initWithFrame(f) only). Forces JS data back into static factories — the pattern this RFC wants to retire.
• Positional arguments / bare token keys (super({ frame })). Ambiguous, and collides with the class's own data.
• Partial<T> options. Lets { owner } compile when something is required for every JS caller.
• Nested { data: T }. Works, but every call site gets noisier and args.data?.owner never acknowledges the native path.
• A branded first parameter (constructor(init: interop.NativeInit, owner?: Owner)). Enforceable, but every call site becomes new X(interop.init(), owner).

Android

The Android runtime has the same problem in a different shape: the framework instantiates Activity, Fragment, View (from XML), Service… reflectively, through specific Java constructors, and a JS constructor either never runs or runs without its data. The proposal for Android is to keep the same JS-facing contract — one options object, interop.Args<T>, [interop.initializer.native] present when the platform created the object (with the Java constructor's signature and arguments), [interop.initializer.args] choosing the super constructor — so a class's constructor reads the same on both platforms. Mapping details (static binding generator, constructor signatures as tokens) are pending and will be added here.

Adoption plan

1. Land the iOS implementation behind the existing "native ES classes" work (feat: support native ES classes with lazy registration, including static usage before construction ios#403 is superseded by it).
2. Ship the interop typings and the generator's per-class initializer unions.
3. Android implementation of the same contract.
4. Docs: a "Subclassing native types" guide built from the cases above; migrate core's static initWithOwner(...) factories to constructors once both platforms ship.

Unresolved questions

1. Names. interop.initializer.args / interop.initializer.native — better spellings?
2. Where the typings live. interop is typed in @nativescript/types-ios, NativeClass in @nativescript/core's global-types.d.ts, and the per-class unions come from the runtime's metadata generator.
3. Old spelling. super({ frame }) currently throws (always). Throw only in debug builds?
4. First-use construction. Always on, or opt-in per class?
5. Late prototype changes (X.prototype.foo = … after registration) still don't reach Objective-C.

[farfromrefug]

User code runs inside native initializers: what is happening today with current runtime? Wondering what i means for like UIcollectionView or RecyclerView. for example in RecyclerView where we are supposed to return an item view. if it throws on the JS side it means on the native side the view will be null?

[edusperoni]

Right now, native does: [[YourClass alloc] init] which means it doesn't touch any JS. Under the new flow it'll call constructor and setup any properties that you set on it. A throw inside the constructor would make [[YourClass alloc] init] return null and likely propagate a native error. If your class doesn't have any properties to construct there's no error to throw

[farfromrefug]

@edusperoni i was more thinking in the current runtime if my JS extended native class throws from JS constructor/init will it propagate to native?
in RecyclerView for example in getItemView(dont remember the name right now) you cant return null value. So it it was to return null from JS extended class in NEW runtime we would get null in native => throw in native, but we wouldnt know why? Or maybe we would still get a JS error on the side even if it returns null? Thinking sentry for example and issue reporting