RFC: Swift interop — calling Swift-only APIs from JavaScript through generated thunks (ns:swift)

[NathanWalker]

RFC: Swift interop — calling Swift-only APIs from JavaScript through generated thunks (ns:swift)

Status	Proposed — iOS implemented (draft PR stack), Android counterpart open
Implementation	iOS: a stack of seven PRs, reviewed bottom-up — ios#518 generator · ios#519 runtime core · ios#520 modules, generics, protocols, Observation, SwiftUI · ios#521 app builds · ios#522 more values · ios#523 lifetime, cancellation, subscripts, Combine, operators · ios#517 Any, performance, docs
Docs	docs/swift-interop.md on the top branch

Summary

NativeScript reaches iOS through Objective-C metadata. That covers UIKit and most of the SDK, but Apple's newer frameworks and nearly every modern Swift package are Swift-only: WeatherKit, SwiftUI, SwiftData, Observation, Swift structs and enums, async functions, generics. Today the only way to use them is to hand-write an @objc bridge for each API. This RFC proposes making them callable directly:

1. The metadata generator reads Swift symbol graphs for the modules an app names, classifies every declaration, has the Swift compiler verify the result, and writes two things: Swift thunks that call each declaration with full static types, and TypeScript declarations for exactly that surface.
2. A new builtin, ns:swift, loads the thunks at runtime. require("ns:swift/WeatherKit") or import { WeatherService } from "ns:swift/WeatherKit" gives JS classes that mirror the Swift types.
3. Swift values map to idiomatic JS values. async becomes a Promise (cancellable with AbortSignal), closures take JS functions, protocols take plain JS objects, AsyncSequence becomes an async iterator, and enums with payloads become tagged unions TypeScript can narrow.
4. Apps opt in with one build setting, NS_SWIFT_MODULES, and the existing link step does the rest. No CLI change is needed, and Objective-C interop is untouched.

Motivation

Swift-only APIs are invisible. NativeScript's metadata is generated from Objective-C headers. A Swift declaration reaches it only if it is @objc, which rules out structs, enums with associated values, generics, async functions (except as completion handlers), protocols with Swift-only types, and every API Apple ships Swift-first. WeatherKit has no Objective-C API at all. SwiftUI and SwiftData can't be expressed in Objective-C. Neither can most of the Swift Package ecosystem.

The workaround is a hand-written bridge per API. Every Swift API an app wants needs an @objc wrapper that flattens Swift types into Objective-C ones:

@objc public class WeatherBridge: NSObject {
    @objc public func forecast(_ city: String, completion: @escaping (NSDictionary?, NSError?) -> Void) {
        Task {
            do {
                let f = try await WeatherClient().forecast(for: city, units: .celsius)
                completion(["city": f.city, "highs": f.highs], nil)
            } catch { completion(nil, error as NSError) }
        }
    }
}

That's boilerplate, and it loses types: JS sees an NSDictionary, TypeScript sees any, and an enum argument becomes a magic string. It also has to be kept in sync with the Swift API by hand. Plugin authors write these bridges over and over, and most app developers can't write them at all.

Apple's direction is Swift-first. New frameworks ship Swift-only, and existing ones gain Swift-only surface (async overloads, Observation, result builders). Without Swift interop, the share of the platform NativeScript can reach shrinks every year.

Guide-level explanation

1. Write Swift, name the module, call it

Put Swift in App_Resources/iOS/src, add a SwiftPM package (ios.SPMPackages), or name an SDK module:

// App_Resources/iOS/src/Weather.swift
public enum Units { case celsius, fahrenheit }

public struct Forecast {
    public let city: String
    public let highs: [Double]
}

public final class WeatherClient {
    public init() {}
    public func forecast(for city: String, units: Units) async throws -> Forecast { ... }
    public func onUpdate(_ handler: @escaping (Forecast) -> Void) { ... }
}

# App_Resources/iOS/build.xcconfig
NS_SWIFT_MODULES = $(PRODUCT_MODULE_NAME) WeatherKit
NS_TYPESCRIPT_DECLARATIONS_PATH = $(SRCROOT)/typescript-declarations

// ES modules / TypeScript
import { WeatherClient, Units } from "ns:swift/MyApp";
import { WeatherService, WeatherQuery } from "ns:swift/WeatherKit";

const client = new WeatherClient();
const forecast = await client.forecast("Lisbon", Units.celsius); // Promise; a Swift throw rejects with SwiftError
forecast.highs;                                                  // [21, 23.5, 19]
client.onUpdate((f) => console.log(f.city));                     // a JS function as a Swift closure

const lisbon = CLLocation.alloc().initWithLatitudeLongitude(38.72, -9.14); // Objective-C objects mix in as usual
const daily = await WeatherService.shared.weather(lisbon, WeatherQuery.daily);

// CommonJS
const { WeatherClient, Units } = require("ns:swift/MyApp");
new WeatherClient().forecast("Lisbon", Units.celsius).then((f) => console.log(f.highs));

ns build ios generates, verifies, compiles and links the thunks. Both import forms survive bundling, because @nativescript/vite already leaves ns: specifiers for the runtime to resolve.

2. Values

Swift	JavaScript
Bool, Double, Float, CGFloat	boolean, number
Int, Int8…UInt64	number (or BigInt in); outside ±(2⁵³−1) throws RangeError rather than lose precision
String, Character, UUID, Decimal	string (Decimal as number)
T?	T or null
class, actor	an instance of the generated JS class, one JS object per Swift object
struct	an instance of the generated JS class holding its own copy (value semantics)
enum without payloads	the case name as a string (Units.celsius === "celsius")
enum with payloads	{ case: "area", width: 3, height: 4 }, a TypeScript union that switch (m.case) narrows
[T], [String: T], Set<T>, tuples	array, plain object, Set, and array or labeled object copies
Date, URL, Data	Date, URL, Uint8Array
Any, [String: Any]	JSON-like JS values (unknown in TypeScript)
Result<S, F>	{ case: "success", value } or { case: "failure", value }
any Error	an Error named SwiftError, with swiftType
CGRect, CGPoint, CLLocationCoordinate2D, …	plain objects; NativeScript's struct values are accepted too
Objective-C classes	NativeScript's ordinary Objective-C wrappers

3. Calls

• Overloads resolve by argument count and JS types. An ambiguous call throws a TypeError naming the candidates, and every overload is also reachable by its Swift signature: square["scale(by: Int)"](2).
• Initializers run through new and also accept one object naming the labels: new Point({ x: 2, y: 3 }).
• Operators become named methods: a.plus(b), a.lessThan(b), v.negated(). Equatable and Comparable types get equals() and compare(), so list.sort((a, b) => a.compare(b)) sorts by Swift's <.
• Subscripts become shelf.subscript("apples") and shelf.setSubscript("apples", 3).
• inout parameters take a reference object: bump(ref) with ref = { value: 41 } leaves ref.value === 42.
• Nested types hang off their parent: Polygon.Style.dashed.

4. Async, actors, cancellation

const controller = new AbortController();
const results = client.search("swift", controller.signal); // trailing AbortSignal on any async call
controller.abort(); // rejects at once and cancels the Swift Task (Task.sleep, URLSession throw CancellationError)

await counter.increment(); // actor members are awaited from outside the actor, as in Swift

An async call runs in a Swift Task and settles on the calling isolate's thread, the main thread or a Worker. @MainActor members run synchronously on the main thread. Called from a Worker, they throw instead of trapping.

5. Closures and protocols: JS implementing Swift

SwiftDemo.transform([1, 2], (n) => "#" + n); // ["#1", "#2"]: closures can return values or throw

uploader.delegate = this.delegate = {         // a plain object implementing a Swift protocol
  progress: (fraction: number) => (this.percent = fraction * 100),
};

• A JS object gets one adapter per protocol, so Swift sees one identity (removeAll { $0 === listener } matches).
• Lifetime follows NativeScript's existing rule for the JS side of Objective-C objects. A strong Swift reference keeps the JS object alive. weak var delegate holds it only as long as JS does, then becomes nil.
• Threading:
  • Closures and protocol members called on the JS thread run before the Swift call returns.
  • Called from another thread, a Void closure is queued to the JS thread.
  • Anything that returns a value waits while it runs on the JS thread.

6. Streams, Observation and SwiftUI

for await (const reading of sensor.readings()) {}  // AsyncStream / AsyncSequence / Combine publisher
                                                   // leaving the loop early ends the Swift stream

const stop = swift.observe(() => thermostat.celsius, () => render(thermostat.celsius)); // @Observable

const controller = new Badge("Inbox", 3).hostingController(); // a SwiftUI View → UIHostingController

7. Generics

• Generic types are bridged through the concrete instantiations the code spells (Forecast<DayWeather>). All instantiations of a type share one JS class, so instanceof holds for each, and a public typealias adds one no API spells.
• Generic functions get one typed overload per concrete stand-in: largest([3, 9]) and largest(["b", "a"]) are both declared. WeatherKit's weather(for:including:) gets eight overloads, one per WeatherQuery instantiation.
• Collection protocols (some Sequence<Int>, C: Collection where C.Element == X, any Sequence<E>) take JS arrays.

8. Swift-only members of Objective-C-visible classes

A Swift UIView or NSObject subclass stays NativeScript's own Objective-C class (CounterView.new()). Its Swift-only members (methods, Swift-typed properties, Swift-only initializers) are added to that class when ns:swift/<Module> loads. They never replace a member NativeScript already provides.

9. Errors

You write	You get
a Swift throw	an Error named SwiftError, with message and swiftType
an argument of the wrong type	TypeError
an integer that doesn't fit	RangeError
an ambiguous overload call	TypeError listing the overloads' keys
a declaration newer than the running OS	an Error naming the required version (TypeScript's @remarks says so too)
a JS protocol object missing a requirement	TypeError naming what's missing
require("ns:swift/Nope")	an error saying the module isn't linked

Reference-level details

Pipeline.

build time (the app's link step)
  swift-symbolgraph-extract              → symbol graphs per module
  objc-metadata-generator --swift-unit
    SymbolGraphLoader + merge            → one Swift IR for all modules (streaming; SwiftUI's graphs in ~1.2 GB)
    instantiateGenerics                  → concrete instantiations and generic-function stand-ins
    CapabilityClassifier                 → one tier + machine-readable reasons per declaration
    ProbeVerifier (--swift-verify)       → swiftc type-checks a probe per declaration and the thunks; demotes what it rejects
    ThunkEmitter                         → <Unit>+NativeScript.swift (compiled and linked into the app)
    SwiftDefinitionWriter                → swift!<Module>.d.ts per module
run time
  ns:swift/<Module>
    dlsym ns_swift_register_<Module>     → types, members, signatures (ABI-versioned)
    per isolate                          → JS classes mirroring Swift inheritance, one per generic family
    call                                 → 24-byte argument slots → thunk → typed Swift call → result entries

Why thunks. Swift's ABI is stable on Apple platforms, but calling it dynamically means reimplementing resilience, value witness tables, generic metadata, async frames and ownership conventions inside the runtime. A thunk is ordinary Swift that the compiler type-checks and optimizes. The runtime only ever sees a small C ABI (NativeScript/runtime/SwiftInterop.h): argument slots in, typed result entries out, an API table for callbacks into the runtime, and completion entries for async results and closures.

Classification and verification. Every declaration gets a tier: objc-direct, swift-generated, swift-specialized, type-only, unsupported or not-applicable. Each tier comes with reasons, and --swift-coverage-output writes them as a report. Symbol graphs don't record every fact a call depends on (~Copyable is often invisible), so --swift-verify compiles everything and demotes what swiftc rejects, repeating until the remainder compiles. Against the iOS 27.1 SDK, every generated thunk file type-checks:

Module	Callable	Of	Compiler-demoted
Foundation	3861	18289	12
SwiftUI	1043	85975	8
WeatherKit	424	1616	9
SwiftData	241	1102	3
Charts	140	10917	4
Observation	24	82	5
RegexBuilder	24	512	1

Generation units. Modules generated together form one unit, so a declaration in one module can take another module's types, and extensions apply across modules. An app generates everything it uses as one unit. SwiftUICore declarations join SwiftUI.

App builds. With NS_SWIFT_MODULES set, the template's nsld.sh runs the generator for each architecture next to the Objective-C metadata step, compiles the thunks and links them (-u per register symbol). The object is cached while the symbol graphs, the generator and the settings stay the same. In a Release build, WeatherKit generation takes about 19 s per architecture the first time. The thunk object for an app module plus WeatherKit (424 callables) plus a SwiftPM package is 0.8 MB, and the first ns:swift import takes 2.7 ms.

Identity and lifetime. A Swift object is retained once by its JS wrapper and released when the wrapper is collected. Returning the same object again yields the same wrapper. Wrappers are isolate-scoped, so each Worker has its own.

Callbacks. A callback that Swift makes on the JS thread converts its arguments straight to JS values through a pooled frame, with no per-argument allocation. Callbacks from other threads are recorded and run on the JS thread.

Performance. One API is implemented twice, in Objective-C (the metadata path) and in Swift (ns:swift), and every result is consumed in JS. Release build, iPhone 17 Pro simulator, Swift time ÷ Objective-C time:

Workload	Ratio
scalar calls (no args, int, 3 doubles, bool)	0.57x – 0.93x
strings (short, 10 KB in, 10 KB round trip)	0.69x / 0.66x / 0.86x
object construct / method / property read	0.41x / 1.16x / 0.92x
1000-int array in / out	0.32x / 0.31x
10-key dictionary in / out	0.36x / 0.39x
1 MB Data in / out	0.12x / 0.68x
build, filter, sort 1000 records, read all	0.28x
async call and await	0.82x
native calls a JS function / JS object 100 times	0.82x / 1.08x

The gains come mostly from collections and strings: Swift values cross as eager copies of plain JS values, while the Objective-C path wraps NSArray/NSDictionary lazily and pays per element read.

ABI. Thunks are stamped with NS_SWIFT_ABI_VERSION (16, unreleased), and the runtime refuses a module generated for another version.

Workers. ns:swift works in Workers. Each isolate builds its own classes, async results settle on the calling isolate, and @MainActor synchronous members throw off the main thread.

TypeScript

The generator writes one ambient module per Swift module:

// swift!SwiftDemo.d.ts (generated)
declare module "ns:swift/SwiftDemo" {
  export class Demo {
    constructor();
    greet(name: string, times: number | bigint): string;
    greet(name: string): string;
    "greet(name:times:)"(name: string, times: number | bigint): string;
    static readonly version: string;
  }

  export type ShapeError =
    | { case: "invalidSide"; value: number }
    | { case: "tooManySides"; count: number; limit: number }
    | { case: "unknown" };

  /** @remarks Requires iOS 17.0; throws on earlier versions. */
  export class Thermostat { /* ... */ }
}

The ns:swift module itself (types/ns-swift.d.ts) types the helpers:

declare module "ns:swift" {
  export const abiVersion: number;
  export function module<Name extends keyof SwiftModules>(name: Name): SwiftModules[Name];
  export function info(name: string): SwiftModuleInfo;
  export function track(read: () => void, onChange: () => void): void;
  export function observe(read: () => void, onChange: () => void): () => void;
}

• Swift-only members of Objective-C-visible classes merge into the class's global declaration.
• A Swift protocol becomes an interface, so a JS implementation is type-checked.
• Generated declarations land in NS_TYPESCRIPT_DECLARATIONS_PATH/swift, next to the Objective-C ones.
• The generator tests compile a usage file against the declarations with tsc, including lines that must fail (@ts-expect-error).

Drawbacks

• Build time. Symbol-graph extraction, generation and compiler verification add seconds to tens of seconds per architecture on a cold build of a large module. The cache makes unchanged rebuilds cheap, but the first build pays the full cost.
• Binary size. Every callable declaration has a thunk. SDK modules should be listed only when JS uses them. Narrowing per declaration isn't supported yet.
• Copies, not views. Collections, structs and enum payloads cross as copies. That's correct for Swift's value types and fast in the benchmarks, but a large [T] read in small pieces would be better served by a Swift-side API.
• Blocking callbacks from other threads. A closure or protocol member that returns a value, called from a background thread, blocks that thread until the JS thread runs it. A Swift thread that holds up the JS thread while waiting on such a call deadlocks. NativeScript's Objective-C path instead runs JS on the calling thread under the V8 lock, so the two models differ, and the difference has to be documented.
• Two generators to keep in step. The thunks and the runtime share a C ABI. A runtime release must ship a generator that emits its ABI version, and apps must rebuild their thunks when the runtime's ABI changes.
• Coverage is not total. Generic methods of generic types, protocols with associated types (beyond collections), static or async protocol requirements, async closures, and the Swift overlay members of SDK Objective-C classes are left out. Each declaration that's left out appears in the coverage report with its reason, and is absent from the JS surface and its TypeScript declarations, so nothing fails at runtime.

Alternatives considered

• Status quo: hand-written @objc bridges. They lose types, have to be kept in sync by hand, and most app developers can't write them.
• Generate @objc wrapper classes automatically. This runs into the same limits as hand-written bridges: no structs, no payload enums, no generics, async only as completion handlers. Every call also pays for objc_msgSend, boxing and lazy collection wrappers. The benchmarks show direct thunks beating the Objective-C path on most workloads.
• Call Swift dynamically from the runtime (libffi with Swift's calling convention plus runtime metadata). It's possible in principle, but the runtime would have to reimplement resilience, generics, witness tables, async and ownership, all of which the compiler already handles in a thunk. It would also lose compile-time verification of the surface.
• Reflection (Mirror, NSClassFromString on Swift classes). Read-only, partial, and not available for structs or functions.
• Ship pre-generated thunks for SDK modules in the runtime. This fixes the SDK version at runtime build time and inflates every app. Generating per app, with caching, keeps size proportional to use.
• A dedicated CLI step. Running generation inside the existing link step (nsld.sh) means no CLI release is needed, and it reuses the per-architecture structure the Objective-C metadata step already has. A nativescript.config.ts key could still feed NS_SWIFT_MODULES later (see the questions below).

Android

Android has a parallel gap. Kotlin compiles to JVM bytecode, so most of it is reachable through NativeScript's Java metadata, but in awkward shapes:

• suspend functions need a hand-built Continuation;
• Flow needs a collector;
• sealed and data classes lose their pattern-matching shape;
• default arguments and inline (value) classes don't map cleanly.

The same approach could carry over: generated Kotlin thunks plus typed declarations behind an ns:kotlin/<module> builtin, mapping suspend to a Promise, Flow to an async iterator and sealed classes to tagged unions. That would give apps one mental model on both platforms. It's out of scope for this RFC's implementation and listed as an open question.

Adoption plan

1. Review and land the iOS stack bottom-up, from ios#518 to ios#517. Each PR builds and passes CI on its own.
2. Freeze and document the thunk ABI for the first release. Decide the compatibility policy (below).
3. Add typings support. ns:swift and generated swift!*.d.ts should resolve in app tsconfigs by default, and @nativescript/types-ios should carry types/ns-swift.d.ts.
4. Write docs: a "Using Swift APIs" guide built from the cases above, plus a plugin-author guide. App builds already find plugins' Swift modules named in NS_SWIFT_MODULES.
5. Validate on physical devices and on visionOS and Mac Catalyst at runtime. So far, runtime validation has been on the iOS simulator, and Catalyst has only been built in CI.
6. Decide the Android question.

Unresolved questions

1. Specifier. Is ns:swift/<Module> right? Should the app's own module have an alias (ns:swift/app) so code doesn't depend on the product module name?
2. Configuration surface. Should apps keep NS_SWIFT_MODULES in build.xcconfig, or should nativescript.config.ts gain an ios.swiftModules key that the CLI forwards?
3. ABI compatibility policy. The runtime currently requires an exact NS_SWIFT_ABI_VERSION match. Should it accept a range, and should the build fail early when the runtime and generator disagree?
4. Toolchain support. Which Xcode and Swift versions should be the minimum? CI uses Xcode 16.4 (Swift 6.1), and the work was developed on Xcode 27, where symbol-graph details differ.
5. SDK coverage defaults. Should common SDK modules (WeatherKit, SwiftData) be opt-in per app as now, or should some ship with declarations pre-generated in @nativescript/types-ios while thunks stay per app?
6. Remaining gaps. Are generic methods of generic types and protocols with associated types worth the generator complexity? The coverage reports from real plugins should decide.
7. Blocking callbacks. Should a value-returning callback from a background thread keep blocking, as Objective-C does, or should there be an opt-in mode that throws instead?
8. Android. Should ns:kotlin with the same mapping be pursued?