expo-modules-macros 0.14.0 → 0.16.0

package/README.md

@@ -18,7 +18,7 @@ This package is not meant to be installed directly. It is a dependency of `expo-
 # Macros
 
 - **`@ExpoModule(_ name: String? = nil, classes: [Any.Type] = [])`** on a class. Turns the class into a module: binds its `@JS` members into the module's JavaScript object and resolves the module name from the argument, falling back to the class name. It also synthesizes everything inheriting from `Module` used to provide, so a module class can carry any superclass, or none.
-- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it.
+- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
 - **`@Event(_ name: String? = nil, sync: Bool = false)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. `sync: true` dispatches inline instead of asynchronously.
 - **`@SharedObject(_ name: String? = nil)`** on a `SharedObject` subclass. Collects the class's `@JS` members into a class definition that a module exposes through `@ExpoModule(classes:)`.
 - **`@Record()`** on a record type. Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.

package/apple/Sources/ExpoModulesMacros/ClosureArguments.swift

@@ -0,0 +1,405 @@
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxMacros
+
+/// A closure parameter of a `@JS` function or initializer, read from its declared type. JS passes a
+/// function for it, and the binding wraps that function in a native closure of the declared type.
+///
+/// A function type can't conform to `JavaScriptDecodable`, so a closure parameter doesn't decode
+/// through `decode` like other arguments. The data also moves the other way: the closure's parameters
+/// are encoded when native code calls it, and its return value is decoded from what the JS function
+/// returns.
+internal struct JSClosureType {
+  /// The function type as written, under any attributes, parentheses and optional wrapper.
+  let functionType: FunctionTypeSyntax
+  /// The attributes written on the function type, such as `@escaping` or `@Sendable`.
+  let attributes: [AttributeSyntax]
+  /// The closure's parameters. Each one is encoded to JS when the closure is called.
+  let parameters: [Parameter]
+  /// The return type as written, or `nil` for `Void`. It is decoded from the JS function's result.
+  let returnType: String?
+  let isAsync: Bool
+  let isThrowing: Bool
+  /// True for an optional closure (`((Int) -> Void)?`): JS `null` and `undefined` become `nil`.
+  let isOptional: Bool
+
+  /// Returns `nil` when the type isn't a closure, or is a closure nested in another type such as an
+  /// array. One optional layer is accepted around the function type.
+  init?(_ type: TypeSyntax) {
+    var type = unparenthesized(type)
+    var isOptional = false
+    if let wrapped = optionalWrappedType(type) {
+      isOptional = true
+      type = unparenthesized(wrapped)
+    }
+    var attributes: [AttributeSyntax] = []
+    if let attributed = type.as(AttributedTypeSyntax.self) {
+      attributes = attributed.attributes.compactMap { $0.as(AttributeSyntax.self) }
+      type = unparenthesized(attributed.baseType)
+    }
+    guard let functionType = type.as(FunctionTypeSyntax.self) else {
+      return nil
+    }
+    self.functionType = functionType
+    self.attributes = attributes
+    self.parameters = functionType.parameters.map(Parameter.init)
+    let returnType = functionType.returnClause.type
+    self.returnType = isVoidReturnType(returnType) ? nil : returnType.trimmedDescription
+    self.isAsync = functionType.effectSpecifiers?.asyncSpecifier != nil
+    self.isThrowing = functionType.effectSpecifiers?.throwsClause != nil
+    self.isOptional = isOptional
+  }
+
+  /// The type of the wrapper closure as the binding declares it. `@escaping` is left out, since it is
+  /// only valid on a parameter.
+  var wrapperTypeText: String {
+    let kept = attributes.filter { attributeName($0) != "escaping" }.map { $0.trimmedDescription + " " }
+    let text = kept.joined() + functionType.trimmedDescription
+    return isOptional ? "(\(text))?" : text
+  }
+
+  /// One parameter of the closure type.
+  struct Parameter {
+    /// The parameter's type without its specifiers, such as `borrowing` or `inout`.
+    let type: TypeSyntax
+    /// The specifiers written before the type, such as `borrowing`, `sending` or `inout`.
+    let specifiers: [String]
+    /// True for a variadic parameter (`Int...`).
+    let isVariadic: Bool
+
+    init(_ element: TupleTypeElementSyntax) {
+      if let attributed = element.type.as(AttributedTypeSyntax.self), !attributed.specifiers.isEmpty {
+        self.specifiers = attributed.specifiers.map(\.trimmedDescription)
+        self.type =
+          attributed.attributes.isEmpty
+          ? attributed.baseType : TypeSyntax(attributed.with(\.specifiers, []))
+      } else {
+        self.specifiers = []
+        self.type = element.type
+      }
+      self.isVariadic = element.ellipsis != nil
+    }
+
+    /// The first specifier the wrapper can't support, such as `inout` or `isolated`.
+    var unsupportedSpecifier: String? {
+      return specifiers.first { !supportedParameterSpecifiers.contains($0) }
+    }
+  }
+}
+
+/// The ownership specifiers a closure parameter may carry. The wrapper passes each parameter on to the
+/// callback, so the ownership convention doesn't change what it does.
+private let supportedParameterSpecifiers: Set<String> = ["borrowing", "consuming", "sending", "__shared", "__owned"]
+
+/// The statements that bind `name` to the native value of a `@JS` argument read from
+/// `valueExpression` (a `JavaScriptUnownedValue`). A closure gets a wrapper around the JS function,
+/// and every other type decodes through `decodeCall`.
+internal func argumentDecodeStatements(
+  type: TypeSyntax,
+  into name: String,
+  from valueExpression: String
+) -> [String] {
+  guard let closure = JSClosureType(type) else {
+    return ["let \(name) = try \(decodeCall(type.trimmedDescription, from: valueExpression))"]
+  }
+  return closureArgumentStatements(closure, into: name, from: valueExpression)
+}
+
+/// Binds `name` to a closure that calls the JS function in `valueExpression`. The
+/// `JavaScriptCallback` keeps the JS function alive and does the thread hops, so the closure can be
+/// stored and called from any thread.
+private func closureArgumentStatements(
+  _ closure: JSClosureType,
+  into name: String,
+  from valueExpression: String
+) -> [String] {
+  let callback = "\(name)Callback"
+  let wrapper = closureLiteralLines(closure, callback: callback)
+
+  guard closure.isOptional else {
+    var lines = ["let \(callback) = try JavaScriptCallback.decode(\(valueExpression), in: runtime)"]
+    lines.append("let \(name): \(closure.wrapperTypeText) = " + wrapper[0])
+    lines.append(contentsOf: wrapper.dropFirst())
+    return lines
+  }
+
+  var lines = [
+    "let \(name): \(closure.wrapperTypeText)",
+    "if let \(callback) = try JavaScriptCallback.decodeIfPresent(\(valueExpression), in: runtime) {",
+    "  \(name) = " + wrapper[0],
+  ]
+  lines.append(contentsOf: wrapper.dropFirst().map { "  " + $0 })
+  lines.append("} else {")
+  lines.append("  \(name) = nil")
+  lines.append("}")
+  return lines
+}
+
+/// The closure literal `{ p0, p1 in … }` that passes its parameters to the `JavaScriptCallback`,
+/// which encodes them, calls the function and decodes the result. The closure's effects pick the
+/// method:
+/// - a non-throwing `Void` closure doesn't wait for JS (`invokeDetached`);
+/// - a sync closure that throws blocks until JS returns (`invokeBlocking`);
+/// - an `async` closure suspends instead (`invokeAsync`), and the callback awaits a returned promise.
+private func closureLiteralLines(_ closure: JSClosureType, callback: String) -> [String] {
+  // `@Sendable` keeps the literal from taking the binding's `@JavaScriptActor` isolation: native code
+  // may call it from any thread, and it captures only the callback.
+  let parameters = closure.parameters.indices.map { "p\($0)" }
+  let header = parameters.isEmpty ? "{ @Sendable in" : "{ @Sendable \(parameters.joined(separator: ", ")) in"
+
+  var arguments = parameters
+  if let returnType = closure.returnType {
+    arguments.append("returning: \(expressionType(returnType)).self")
+  }
+  let argumentList = arguments.joined(separator: ", ")
+
+  let call: String
+  if closure.isAsync {
+    call = "try await \(callback).invokeAsync(\(argumentList))"
+  } else if closure.isThrowing || closure.returnType != nil {
+    call = "try \(callback).invokeBlocking(\(argumentList))"
+  } else {
+    call = "\(callback).invokeDetached(\(argumentList))"
+  }
+
+  guard closure.isAsync && !closure.isThrowing else {
+    return [header, "  " + call, "}"]
+  }
+  // The closure can't throw, so an error from JS goes to the callback's error reporting.
+  return [
+    header,
+    "  do {",
+    "    " + call,
+    "  } catch {",
+    "    \(callback).reportError(error)",
+    "  }",
+    "}",
+  ]
+}
+
+// MARK: - Diagnostics
+
+/// Emits the closure diagnostics for a `@JS` declaration. A closure is supported only as a parameter
+/// of a function or initializer, where JS passes a function in. Every other position would need a
+/// native closure encoded to a JS function, which isn't supported.
+internal func diagnoseClosureTypes(
+  in declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
+    diagnoseClosureParameters(funcDecl.signature.parameterClause.parameters, in: context)
+    if let returnType = funcDecl.signature.returnClause?.type, let nested = firstFunctionType(in: returnType) {
+      context.diagnose(
+        Diagnostic(
+          node: nested,
+          message: ClosureDiagnosticMessage(
+            "A @JS function can't return a closure: a native closure can't be encoded to a JavaScript function.",
+            id: "js-closure-return"
+          )))
+    }
+    return
+  }
+  if let initDecl = declaration.as(InitializerDeclSyntax.self) {
+    diagnoseClosureParameters(initDecl.signature.parameterClause.parameters, in: context)
+    return
+  }
+  if let varDecl = declaration.as(VariableDeclSyntax.self),
+    let type = varDecl.bindings.first?.typeAnnotation?.type,
+    let nested = firstFunctionType(in: type) {
+    context.diagnose(
+      Diagnostic(
+        node: nested,
+        message: ClosureDiagnosticMessage(
+          "A @JS property can't have a closure type: a native closure can't be encoded to a JavaScript function.",
+          id: "js-closure-property"
+        )))
+  }
+}
+
+private func diagnoseClosureParameters(
+  _ parameters: FunctionParameterListSyntax,
+  in context: some MacroExpansionContext
+) {
+  for parameter in parameters {
+    guard let closure = JSClosureType(parameter.type) else {
+      if let nested = firstFunctionType(in: parameter.type) {
+        context.diagnose(
+          Diagnostic(
+            node: nested,
+            message: ClosureDiagnosticMessage(
+              "A closure in a @JS argument must be the argument's own type, optionally wrapped in an optional. Closures inside other types, such as arrays or dictionaries, aren't supported.",
+              id: "js-closure-nested-in-type"
+            )))
+      }
+      continue
+    }
+    diagnoseClosure(closure, in: context)
+  }
+}
+
+private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExpansionContext) {
+  let functionType = closure.functionType
+
+  for attribute in closure.attributes {
+    let name = attributeName(attribute)
+    guard name != "escaping" && name != "Sendable" else {
+      continue
+    }
+    context.diagnose(
+      Diagnostic(
+        node: attribute,
+        message: ClosureDiagnosticMessage(
+          "'@\(name)' isn't supported on a @JS closure argument. The closure calls JavaScript through its own thread hop, so only '@escaping' and '@Sendable' are allowed.",
+          id: "js-closure-attribute"
+        )))
+  }
+
+  if let throwsClause = functionType.effectSpecifiers?.throwsClause, throwsClause.type != nil {
+    context.diagnose(
+      Diagnostic(
+        node: throwsClause,
+        message: ClosureDiagnosticMessage(
+          "A @JS closure argument can't use typed throws: the error from JavaScript can be any error. Write 'throws' without a type.",
+          id: "js-closure-typed-throws"
+        )))
+  }
+
+  for parameter in closure.parameters {
+    if let specifier = parameter.unsupportedSpecifier {
+      context.diagnose(
+        Diagnostic(
+          node: parameter.type,
+          message: ClosureDiagnosticMessage(
+            "A @JS closure argument can't take an '\(specifier)' parameter: its value is encoded and sent to JavaScript, which can't write it back or share its isolation.",
+            id: "js-closure-parameter-specifier"
+          )))
+    }
+    if parameter.isVariadic {
+      context.diagnose(
+        Diagnostic(
+          node: parameter.type,
+          message: ClosureDiagnosticMessage(
+            "A @JS closure argument can't take a variadic parameter. Use an array instead.",
+            id: "js-closure-variadic-parameter"
+          )))
+    }
+  }
+
+  // The closure's parameters are encoded and its result is decoded, so neither can be another
+  // closure or a free-form type.
+  let returnType = functionType.returnClause.type
+  for type in closure.parameters.map(\.type) + [returnType] {
+    if let nested = firstFunctionType(in: type) {
+      context.diagnose(
+        Diagnostic(
+          node: nested,
+          message: ClosureDiagnosticMessage(
+            "A @JS closure argument can't take or return another closure.",
+            id: "js-closure-nested"
+          )))
+    } else if isFreeFormBoundaryType(type.trimmedDescription) {
+      context.diagnose(
+        Diagnostic(
+          node: type,
+          message: ClosureDiagnosticMessage(
+            "A @JS closure argument can't use the free-form '\(type.trimmedDescription)'. Use a concrete type, or 'JavaScriptValue' to pass a JS value through unchanged.",
+            id: "js-closure-free-form"
+          )))
+    }
+  }
+
+  if closure.returnType != nil && !closure.isThrowing {
+    context.diagnose(
+      Diagnostic(
+        node: functionType,
+        message: ClosureDiagnosticMessage(
+          "A @JS closure argument that returns a value must be 'throws': when the JavaScript function throws, the closure has no value to return.",
+          id: "js-closure-requires-throws"
+        ),
+        fixIts: [insertThrowsFixIt(for: functionType)]))
+  }
+}
+
+/// The fix-it for a non-throwing closure that returns a value: insert `throws` after the parameter
+/// list, or after `async` when the type has it. The inserted keyword takes over the trivia that
+/// followed the token before it, so `(Int) -> Int` becomes `(Int) throws -> Int`.
+private func insertThrowsFixIt(for functionType: FunctionTypeSyntax) -> FixIt {
+  var newType = functionType
+  if var effectSpecifiers = functionType.effectSpecifiers, let asyncSpecifier = effectSpecifiers.asyncSpecifier {
+    effectSpecifiers.throwsClause = ThrowsClauseSyntax(
+      throwsSpecifier: .keyword(.throws, trailingTrivia: asyncSpecifier.trailingTrivia))
+    effectSpecifiers.asyncSpecifier = asyncSpecifier.with(\.trailingTrivia, .space)
+    newType.effectSpecifiers = effectSpecifiers
+  } else {
+    newType.effectSpecifiers = TypeEffectSpecifiersSyntax(
+      throwsClause: ThrowsClauseSyntax(
+        throwsSpecifier: .keyword(.throws, trailingTrivia: functionType.rightParen.trailingTrivia)))
+    newType.rightParen = functionType.rightParen.with(\.trailingTrivia, .space)
+  }
+  return FixIt(
+    message: ClosureFixItMessage("Mark the closure 'throws'", id: "js-closure-insert-throws"),
+    changes: [.replace(oldNode: Syntax(functionType), newNode: Syntax(newType))]
+  )
+}
+
+// MARK: - Helpers
+
+/// True when `type` is a function type or has one anywhere inside it.
+internal func containsFunctionType(_ type: TypeSyntax) -> Bool {
+  return firstFunctionType(in: type) != nil
+}
+
+/// The first function type in `type` or anywhere inside it, in source order.
+private func firstFunctionType(in type: some SyntaxProtocol) -> FunctionTypeSyntax? {
+  if let functionType = type.as(FunctionTypeSyntax.self) {
+    return functionType
+  }
+  for child in type.children(viewMode: .sourceAccurate) {
+    if let found = firstFunctionType(in: child) {
+      return found
+    }
+  }
+  return nil
+}
+
+/// The type inside any number of single-element, unlabeled parentheses: `((Int) -> Void)` is the
+/// same type as `(Int) -> Void`.
+private func unparenthesized(_ type: TypeSyntax) -> TypeSyntax {
+  if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
+    let element = tuple.elements.first, element.firstName == nil {
+    return unparenthesized(element.type)
+  }
+  return type
+}
+
+/// True when a closure's return type is `Void`, `()` or `Swift.Void`, also inside parentheses.
+private func isVoidReturnType(_ type: TypeSyntax) -> Bool {
+  let type = unparenthesized(type)
+  let text = type.trimmedDescription
+  return text == "Void" || text == "()" || text == "Swift.Void"
+}
+
+private func attributeName(_ attribute: AttributeSyntax) -> String {
+  return attribute.attributeName.trimmedDescription
+}
+
+private struct ClosureDiagnosticMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID: MessageID
+  let severity: DiagnosticSeverity = .error
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+private struct ClosureFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -86,7 +86,7 @@ internal struct JSFunction {
     // Decode the required prefix once — these slots are present in every accepted arity, so the
     // decode is shared rather than repeated per branch.
     for index in 0..<required {
-      lines.append(decodeStatement(at: index))
+      lines.append(contentsOf: decodeLines(at: index))
     }
 
     if required == maximum {
@@ -95,7 +95,7 @@ internal struct JSFunction {
       // body; a sync one calls and encodes directly.
       if isAsync {
         for index in required..<maximum {
-          lines.append(decodeStatement(at: index))
+          lines.append(contentsOf: decodeLines(at: index))
         }
         lines.append(contentsOf: asyncBodyLines(receiver: receiver, arity: maximum))
       } else {
@@ -110,7 +110,7 @@ internal struct JSFunction {
         let label = arity == maximum ? "default:" : "case \(arity):"
         lines.append(label)
         for index in required..<arity {
-          lines.append("  " + decodeStatement(at: index))
+          lines.append(contentsOf: decodeLines(at: index).map { "  " + $0 })
         }
         lines.append(contentsOf: asyncBodyLines(receiver: receiver, arity: arity).map { "  " + $0 })
       }
@@ -127,7 +127,7 @@ internal struct JSFunction {
         let label = arity == maximum ? "default:" : "case \(arity):"
         lines.append(label)
         for index in required..<arity {
-          lines.append("  " + decodeStatement(at: index))
+          lines.append(contentsOf: decodeLines(at: index).map { "  " + $0 })
         }
         let assignment = returnType != nil ? "result = " : ""
         lines.append("  \(assignment)\(callExpression(receiver: receiver, arity: arity))")
@@ -160,14 +160,17 @@ internal struct JSFunction {
     return lines
   }
 
-  /// `let arg<index> = …` decoding the slot at `index` by its static type through
+  /// The lines binding `arg<index>`: a decode of the slot at `index` by its static type through
   /// `JavaScriptDecodable.decode` on the borrowed `JavaScriptUnownedValue` — no owning value, no
   /// `jsi::Value` copy, no `Any` boxing, no force-cast; it returns the concrete type directly. A
   /// primitive's `decode` is `@inlinable` and lowers to the same direct accessor a hand-rolled fast
-  /// path would use.
-  private func decodeStatement(at index: Int) -> String {
-    let type = parameters[index].type.trimmedDescription
-    return "let arg\(index) = try \(decodeCall(type, from: "arguments.unownedValue(at: \(index))"))"
+  /// path would use. A closure parameter takes several lines instead, wrapping the JS function.
+  private func decodeLines(at index: Int) -> [String] {
+    return argumentDecodeStatements(
+      type: parameters[index].type,
+      into: "arg\(index)",
+      from: "arguments.unownedValue(at: \(index))"
+    )
   }
 
   /// The `<callee>.<name>(...)` call for the given arity. Slots `0..<arity` are passed their decoded
@@ -205,7 +208,7 @@ internal struct JSFunction {
   private func callAndEncodeLines(receiver: Receiver, arity: Int, decodingFrom: Int) -> [String] {
     var lines: [String] = []
     for index in decodingFrom..<arity {
-      lines.append(decodeStatement(at: index))
+      lines.append(contentsOf: decodeLines(at: index))
     }
     if returnType != nil {
       lines.append("let result = \(callExpression(receiver: receiver, arity: arity))")

package/apple/Sources/ExpoModulesMacros/JSConstructor.swift

@@ -14,7 +14,7 @@ internal struct JSConstructor {
 
   /// The body statements, indented with `indent`: arity guard, per-argument decode through
   /// `JavaScriptDecodable.decode` on a zero-copy `arguments.unownedValue(at:)` (the arity guard proves
-  /// each index is in bounds), then `return <Type>(label: arg0, …)`.
+  /// each index is in bounds) or a wrapper for a closure argument, then `return <Type>(label: arg0, …)`.
   private func bodyStatements(typeName: String, indent: String) -> String {
     var lines: [String] = []
 
@@ -27,8 +27,12 @@ internal struct JSConstructor {
 
     var callArguments: [String] = []
     for (index, parameter) in parameters.enumerated() {
-      let type = parameter.type.trimmedDescription
-      lines.append("let arg\(index) = try \(decodeCall(type, from: "arguments.unownedValue(at: \(index))"))")
+      lines.append(
+        contentsOf: argumentDecodeStatements(
+          type: parameter.type,
+          into: "arg\(index)",
+          from: "arguments.unownedValue(at: \(index))"
+        ))
 
       let label = parameter.firstName.text
       callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -32,6 +32,7 @@ public struct JSMacro: PeerMacro {
     in context: some MacroExpansionContext
   ) throws -> [DeclSyntax] {
     diagnoseFreeFormTypes(in: declaration, in: context)
+    diagnoseClosureTypes(in: declaration, in: context)
     diagnoseConcurrentOption(of: node, on: declaration, in: context)
 
     guard let member = boundaryMember(of: declaration),
@@ -39,6 +40,7 @@ public struct JSMacro: PeerMacro {
         name: member.name,
         decodableTypes: member.decodableTypes,
         encodableType: member.encodableType,
+        callbackArgumentTypes: member.callbackArgumentTypes,
         isStatic: member.isStatic
       ) else {
       return []
@@ -237,11 +239,14 @@ private struct JSFixItMessage: FixItMessage {
 /// property's outgoing value) are encoded, so each is asserted against the protocol for its direction.
 private struct BoundaryMember {
   let name: String
-  /// Types decoded from JS: function/constructor arguments, and a settable property's value type.
+  /// Types decoded from JS: function/constructor arguments, a settable property's value type, and the
+  /// return types of closure arguments.
   let decodableTypes: [String]
   /// The single type encoded to JS: a function's return type, or a property's value type on read;
   /// `nil` when the member produces nothing JS-visible (a `Void` function).
   let encodableType: String?
+  /// The parameter types of closure arguments, encoded to JS when native code calls the closure.
+  var callbackArgumentTypes: [String] = []
   /// True for `static`/`class` members, so the peer is emitted in the same metatype context.
   let isStatic: Bool
 }
@@ -255,13 +260,34 @@ private struct BoundaryMember {
 /// recover it).
 private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> BoundaryMember? {
   if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
-    let decodableTypes = funcDecl.signature.parameterClause.parameters.map { $0.type.trimmedDescription }
+    // A closure argument moves data the other way: JS receives its parameters and returns its result.
+    // A closure in any other position is diagnosed by `diagnoseClosureTypes` and left out here, since
+    // its metatype isn't a valid expression in the assertion.
+    var decodableTypes: [String] = []
+    var callbackArgumentTypes: [String] = []
+    for parameter in funcDecl.signature.parameterClause.parameters {
+      guard let closure = JSClosureType(parameter.type) else {
+        if !containsFunctionType(parameter.type) {
+          decodableTypes.append(parameter.type.trimmedDescription)
+        }
+        continue
+      }
+      for parameter in closure.parameters where !containsFunctionType(parameter.type) {
+        callbackArgumentTypes.append(parameter.type.trimmedDescription)
+      }
+      if let returnType = closure.returnType, !containsFunctionType(closure.functionType.returnClause.type) {
+        decodableTypes.append(returnType)
+      }
+    }
     let returnType = funcDecl.signature.returnClause?.type
-    let encodableType = returnType.flatMap { isVoidType($0) ? nil : $0.trimmedDescription }
+    let encodableType = returnType.flatMap {
+      isVoidType($0) || containsFunctionType($0) ? nil : $0.trimmedDescription
+    }
     return BoundaryMember(
       name: funcDecl.name.text,
       decodableTypes: decodableTypes,
       encodableType: encodableType,
+      callbackArgumentTypes: callbackArgumentTypes,
       isStatic: isTypeLevel(funcDecl.modifiers)
     )
   }
@@ -269,7 +295,8 @@ private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> Boundary
   if let varDecl = declaration.as(VariableDeclSyntax.self),
     let binding = varDecl.bindings.first,
     let identifier = binding.pattern.as(IdentifierPatternSyntax.self),
-    let type = binding.typeAnnotation?.type {
+    let type = binding.typeAnnotation?.type,
+    !containsFunctionType(type) {
     // A `let`, or a `var` with no setter, is read-only (encodable only). A settable `var` is also
     // decoded on write, so its value type is asserted in both directions.
     let typeText = type.trimmedDescription

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -66,24 +66,29 @@ internal struct ConformanceAssertion {
 /// direction.
 ///
 /// `decodableTypes` are the argument types (and a settable property's value type); `encodableType` is
-/// the single return type (or a property's value type on read), or `nil` when there's none. Primitives
-/// are dropped from each; when nothing is left in either, returns `nil` so the caller emits no peer.
-/// `isStatic` mirrors a `static`/`class` member so the peer sits in the right metatype context.
+/// the single return type (or a property's value type on read), or `nil` when there's none.
+/// `callbackArgumentTypes` are the parameter types of closure arguments, which are encoded when native
+/// code calls the closure. Primitives are dropped from each; when nothing is left in any of them,
+/// returns `nil` so the caller emits no peer. `isStatic` mirrors a `static`/`class` member so the peer
+/// sits in the right metatype context.
 internal func directionalConformanceAssertion(
   name: String,
   decodableTypes: [String],
   encodableType: String?,
+  callbackArgumentTypes: [String] = [],
   isStatic: Bool
 ) -> DeclSyntax? {
   let decodables = distinctAssertableTypes(decodableTypes)
+  let callbackArguments = distinctAssertableTypes(callbackArgumentTypes)
   let encodable = encodableType.flatMap(assertableBoundaryType)
-  guard !decodables.isEmpty || encodable != nil else {
+  guard !decodables.isEmpty || !callbackArguments.isEmpty || encodable != nil else {
     return nil
   }
 
   // Build the generic parameter list and the matching call arguments in lockstep: one `A0…` slot
-  // constrained `JavaScriptDecodable` per argument, and a single `Return` slot constrained
-  // `JavaScriptEncodable` for the return/getter value (there's only ever one, so it isn't indexed).
+  // constrained `JavaScriptDecodable` per argument, one `E0…` slot constrained `JavaScriptEncodable`
+  // per closure-argument parameter, and a single `Return` slot constrained `JavaScriptEncodable` for
+  // the return/getter value (there's only ever one, so it isn't indexed).
   var parameters: [String] = []
   var typeParameters: [String] = []
   var arguments: [String] = []
@@ -92,6 +97,11 @@ internal func directionalConformanceAssertion(
     typeParameters.append("_: A\(index).Type")
     arguments.append("\(type).self")
   }
+  for (index, type) in callbackArguments.enumerated() {
+    parameters.append("E\(index): \(javaScriptEncodableProtocolName)")
+    typeParameters.append("_: E\(index).Type")
+    arguments.append("\(type).self")
+  }
   if let encodable {
     parameters.append("Return: \(javaScriptEncodableProtocolName)")
     typeParameters.append("_: Return.Type")

package/apple/Sources/ExpoModulesMacros/UnionMacro.swift

@@ -8,9 +8,13 @@ import SwiftSyntaxMacros
 /// level, so the author switches over it exhaustively with each payload keeping its static type, and
 /// the macro synthesizes the conversion surface that makes it a JS boundary type:
 ///
+/// - `decodableKinds`: the union of the payloads' `decodableKinds`, the JS kinds the union can decode.
 /// - `decode(_:in:)`: an ordered decode that tries each case's payload converter in declaration order
 ///   and returns the first case that decodes; when none does, it throws
 ///   `Exceptions.UnionCaseMismatch` naming the union, the JS kind received, and the alternatives.
+///   Only the overload taking a borrowed `JavaScriptUnownedValue` is emitted. The overload taking an
+///   owning `JavaScriptValue` comes from the `JavaScriptDecodable` default, which borrows the value
+///   and calls this one.
 /// - `encode(_:in:)`: a `switch` over the cases, encoding the payload through its own type.
 /// - `as(_:)`: one throwing overload per case, keyed by the payload's metatype, returning that payload
 ///   (`try source.as(String.self)` is `String`; `try? source.as(String.self)` is `String?`). It unwraps
@@ -57,6 +61,7 @@ public struct UnionMacro: MemberMacro, ExtensionMacro {
       members.append(assertionMember)
     }
 
+    members.append(decodableKindsProperty(union: union))
     members.append(decodeMethod(union: union))
     members.append(encodeMethod(union: union))
     members.append(contentsOf: accessorMethods(union: union))
@@ -229,31 +234,50 @@ private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> Unio
 // MARK: - Synthesized members
 
 /// `decode(_:in:)`: tries each case's payload converter in declaration order and returns the first
-/// case that decodes. `try?` turns a candidate's failure into "try the next one" without erasing the
+/// case that decodes. Only the overload taking a borrowed `JavaScriptUnownedValue` is emitted; the
+/// overload taking an owning `JavaScriptValue` comes from the `JavaScriptDecodable` default, which
+/// borrows the value and calls this one. Each payload decode receives the same borrowed value. The
+/// value's kind is read once, and each candidate is gated on its payload's `decodableKinds`, so a case
+/// that can't accept that kind is skipped with a mask test instead of a thrown and discarded error. `try?` turns a candidate's failure into "try the next one" without erasing the
 /// payload (each `payload` local keeps its concrete type); the candidate's own error is discarded, since
 /// with several alternatives there is no single failure to surface. When no alternative accepts the
 /// value the factory throws `Exceptions.UnionCaseMismatch`, naming the union, the JS kind of the value
-/// received, and every payload type the union accepts.
+/// received, and every payload type the union accepts. `JavaScriptUnownedValue` has no `kind`, so the
+/// error reads it from an owning copy; the copy is made only on this failure path.
 private func decodeMethod(union: UnionType) -> DeclSyntax {
-  var lines: [String] = []
+  var lines: [String] = ["  let kind = JavaScriptValueKinds(of: value)"]
   for unionCase in union.cases {
     let payloadType = expressionType(unionCase.payloadType)
-    lines.append("  if let payload = try? \(payloadType).decode(value, in: runtime) {")
+    lines.append("  if \(payloadType).decodableKinds.contains(kind), let payload = try? \(payloadType).decode(value, in: runtime) {")
     lines.append("    return \(unionCase.construction)")
     lines.append("  }")
   }
   let expected = union.cases.map { "\"\($0.payloadType)\"" }.joined(separator: ", ")
-  let mismatch = "(unionName: \"\(union.name)\", received: value.kind.rawValue, expected: [\(expected)])"
+  let mismatch = "(unionName: \"\(union.name)\", received: value.copied(in: runtime).kind.rawValue, expected: [\(expected)])"
   lines.append("  throw Exceptions.UnionCaseMismatch(\(mismatch))")
   let body = lines.joined(separator: "\n")
   return """
     @JavaScriptActor
-    public static func decode(_ value: borrowing JavaScriptValue, in runtime: borrowing JavaScriptRuntime) throws -> Self {
+    public static func decode(_ value: borrowing JavaScriptUnownedValue, in runtime: borrowing JavaScriptRuntime) throws -> Self {
     \(raw: body)
     }
     """
 }
 
+/// `decodableKinds`: the union of the payloads' kinds, so a union nested in another union, or wrapped
+/// in an optional, is skipped as precisely as its payloads are.
+private func decodableKindsProperty(union: UnionType) -> DeclSyntax {
+  let kinds = union.cases.map { "\(expressionType($0.payloadType)).decodableKinds" }
+  // An option set's array literal is the union of its elements, which reads like the case list. The
+  // optimizer folds it to a constant after specialization, the same as a chain of `union(_:)` calls.
+  let expression = kinds.count == 1 ? kinds[0] : "[\(kinds.joined(separator: ", "))]"
+  return """
+    public static var decodableKinds: JavaScriptValueKinds {
+      return \(raw: expression)
+    }
+    """
+}
+
 /// `encode(_:in:)`: a `switch` over the cases, each encoding its payload through the payload type's
 /// own `encode`. Exhaustive by construction, so a case added later without re-expansion can't slip
 /// through silently.

package/apple/Sources/ExpoModulesScanner/Exports/ExportedSurface.swift

@@ -170,10 +170,25 @@ struct ExportedModule: Encodable, Equatable {
   let properties: [ExportedProperty]
   let events: [ExportedEvent]
 
+  /// The classes listed in `@ExpoModule(classes: [...])`, in source order. Each is reachable from JS
+  /// as a member of the module.
+  let classes: [ExportedClass]
+
   /// Absolute source path, matching `scan-modules`.
   let file: String
 }
 
+/// One entry of `@ExpoModule(classes: [...])`.
+struct ExportedClass: Encodable, Equatable {
+  /// The Swift name as spelled in the argument, e.g. `Database` or `Outer.Statement`.
+  let name: String
+
+  /// The name of the module member JS reads the class from: the matching `@SharedObject`'s `jsName`.
+  /// `nil` when the scan found no `@SharedObject` with this name, for example a class defined
+  /// outside the scanned paths.
+  let jsName: String?
+}
+
 /// A `@SharedObject` type: a JS class with an optional `@JS init` constructor plus its `@JS` members.
 struct ExportedSharedObject: Encodable, Equatable {
   /// The Swift class name.
@@ -307,8 +322,8 @@ struct ExportedSurface: Encodable, Equatable {
 /// Versioned independently of `scanModulesSchemaVersion`: the two commands serve different consumers
 /// and change for different reasons. Version 2 added `events` to modules and shared objects; version 3
 /// added `enums`; version 4 added `unions`; version 5 resolves refs, adding `refKind` and correcting
-/// an enum ref's `typeof`.
-let scanExportsSchemaVersion = 5
+/// an enum ref's `typeof`; version 6 added `classes` to modules.
+let scanExportsSchemaVersion = 6
 
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).

package/apple/Sources/ExpoModulesScanner/Exports/ResolveRefs.swift

@@ -23,12 +23,16 @@ struct RefIndex {
   /// `name` -> the kind declaring it, plus the JS category a ref to it crosses as.
   private var entries: [String: (kind: RefKind, jsType: JSType)] = [:]
 
+  /// A `@SharedObject`'s Swift name -> its JS name.
+  private var sharedObjectJSNames: [String: String] = [:]
+
   init(surface: ExportedSurface) {
     for record in surface.records {
       entries[record.name] = (.record, .object)
     }
     for sharedObject in surface.sharedObjects {
       entries[sharedObject.name] = (.sharedObject, .object)
+      sharedObjectJSNames[sharedObject.name] = sharedObject.jsName
     }
     for union in surface.unions {
       // A union crosses as whichever alternative matched, so its category is only meaningful per
@@ -42,18 +46,28 @@ struct RefIndex {
 
   /// How a ref to `name` should be reported, or `nil` when the scan declares no such type.
   func lookup(_ name: String) -> (kind: RefKind, jsType: JSType)? {
-    if let entry = entries[name] {
-      return entry
-    }
-    // A qualified use site (`Media.Status`) names the same type a bare declaration did. Fall back to
-    // the trailing component, which is how the conformance and raw-type checks already match names.
-    guard let trailing = name.split(separator: ".").last.map(String.init), trailing != name else {
-      return nil
-    }
-    return entries[trailing]
+    lookupQualified(name, in: entries)
+  }
+
+  /// The JS name of the `@SharedObject` declared as `name`, or `nil` when the scan declares none.
+  func sharedObjectJSName(_ name: String) -> String? {
+    lookupQualified(name, in: sharedObjectJSNames)
   }
 }
 
+/// The value for `name` in `table`, falling back to its trailing component. A qualified use site
+/// (`Media.Status`) names the same type a bare declaration did, which is how the conformance and
+/// raw-type checks already match names.
+private func lookupQualified<Value>(_ name: String, in table: [String: Value]) -> Value? {
+  if let value = table[name] {
+    return value
+  }
+  guard let trailing = name.split(separator: ".").last.map(String.init), trailing != name else {
+    return nil
+  }
+  return table[trailing]
+}
+
 /// The JS category a raw-value enum crosses as: its raw value's. A bare `Enumerable` conformance with
 /// no raw type has nothing to go on, so it stays an object.
 private func jsType(ofRawType rawType: TypeNode?) -> JSType {
@@ -114,6 +128,9 @@ extension ExportedSurface {
           functions: module.functions.map { $0.resolvingRefs(using: index) },
           properties: module.properties.map { $0.resolvingRefs(using: index) },
           events: module.events.map { $0.resolvingRefs(using: index) },
+          classes: module.classes.map {
+            ExportedClass(name: $0.name, jsName: index.sharedObjectJSName($0.name))
+          },
           file: module.file
         )
       },

package/apple/Sources/ExpoModulesScanner/Exports/SurfaceVisitor.swift

@@ -78,6 +78,11 @@ final class SurfaceVisitor: SyntaxVisitor {
           functions: functions,
           properties: properties,
           events: events,
+          // `jsName` is filled in by `ExportedSurface.resolvingRefs()`, since the `@SharedObject` can
+          // be declared in another file.
+          classes: classListArgument(of: attribute, label: "classes").map {
+            ExportedClass(name: $0, jsName: nil)
+          },
           file: file
         ))
       return
@@ -590,6 +595,25 @@ extension AttributeListSyntax {
   }
 }
 
+/// The type names in an attribute's `label: [A.self, B.self]` argument, in source order. A qualified
+/// `Outer.A.self` keeps its full spelling. Returns an empty array when the argument is absent or isn't
+/// an array literal. A local copy of the macros' helper (the macro target can't be imported here).
+private func classListArgument(of attribute: AttributeSyntax, label: String) -> [String] {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
+    let array = args.first(where: { $0.label?.text == label })?.expression.as(ArrayExprSyntax.self) else {
+    return []
+  }
+  return array.elements.compactMap { element in
+    guard let memberAccess = element.expression.as(MemberAccessExprSyntax.self),
+      memberAccess.declName.baseName.text == "self",
+      let base = memberAccess.base,
+      base.is(DeclReferenceExprSyntax.self) || base.is(MemberAccessExprSyntax.self) else {
+      return nil
+    }
+    return base.trimmedDescription
+  }
+}
+
 /// The node for a property/field value type: the annotation, else the literal default's inferred
 /// primitive (`var n = 1` -> `Int`), else `nil`.
 private func valueTypeNode(annotation: TypeSyntax?, initializer: ExprSyntax?) -> TypeNode? {

package/apple/Sources/ExpoModulesScanner/Exports/TypeNode.swift

@@ -8,8 +8,8 @@ import SwiftSyntax
 /// never silently dropped.
 
 /// The runtime category mirroring JavaScript's `typeof`. A coarse companion to `TypeNode.kind`: every
-/// structured object kind (array, dictionary, promise, ref) reports `object`. `bigint`/`symbol` are
-/// included for completeness; the scanner doesn't produce them.
+/// structured object kind (array, dictionary, promise, ref) reports `object`. `symbol` is included for
+/// completeness; the scanner doesn't produce it.
 enum JSType: String, Encodable {
   case undefined
   case object
@@ -37,8 +37,8 @@ enum RefKind: String, Encodable {
 }
 
 indirect enum TypeNode: Equatable {
-  /// `Bool`, `Int`, `Double`, `String`: the types core fast-decodes. `name` is the Swift spelling;
-  /// `jsType` is `boolean`/`number`/`string`.
+  /// A Swift type that crosses as a JS primitive: `Bool`, `String`, or a numeric type. `name` is the
+  /// Swift spelling; `jsType` is `boolean`/`number`/`bigint`/`string`.
   case primitive(name: String, jsType: JSType)
 
   /// `T?` / `T!` / `Optional<T>`.
@@ -148,13 +148,27 @@ extension TypeNode: Encodable {
   }
 }
 
-/// The primitive Swift types with a dedicated JS mapping (the set core fast-decodes), each paired with
-/// its JS primitive. A bare name here is a `.primitive`; anything else is a `.ref`.
+/// The Swift types that cross as a JS primitive, each paired with that primitive. A bare name here is
+/// a `.primitive`; anything else is a `.ref`.
 private let primitiveJSTypes: [String: JSType] = [
   "Bool": .boolean,
+  "String": .string,
+  // These numeric types encode to a JS `number`.
   "Int": .number,
+  "Int8": .number,
+  "Int16": .number,
+  "Int32": .number,
+  "UInt": .number,
+  "UInt8": .number,
+  "UInt16": .number,
+  "UInt32": .number,
   "Double": .number,
-  "String": .string,
+  "Float": .number,
+  "CGFloat": .number,
+  // The 64-bit fixed-width integers decode from a `number` or a `bigint`, and always encode to a
+  // `bigint`. The reported category is the encoded one.
+  "Int64": .bigint,
+  "UInt64": .bigint,
 ]
 
 /// Parses a `TypeSyntax` into a `TypeNode`: the single place Swift type syntax is interpreted.
@@ -183,6 +197,11 @@ func typeNode(from type: TypeSyntax) -> TypeNode {
   if let attributed = type.as(AttributedTypeSyntax.self) {
     return typeNode(from: attributed.baseType)
   }
+  // `(T)`: one unlabeled element in parentheses is the same type as `T`, as in `((Int) -> Void)?`.
+  if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
+    let element = tuple.elements.first, element.firstName == nil {
+    return typeNode(from: element.type)
+  }
   // A nominal type, possibly generic: `Int`, `Point`, `Optional<T>`, `Array<T>`, `Promise<T>`.
   if let identifier = type.as(IdentifierTypeSyntax.self) {
     return nominalNode(name: identifier.name.text, generics: identifier.genericArgumentClause)

package/build/types.d.ts

@@ -112,9 +112,25 @@ export interface ExportedModule {
     functions: ExportedFunction[];
     properties: ExportedProperty[];
     events: ExportedEvent[];
+    /**
+     * The classes listed in `@ExpoModule(classes: [...])`, in source order. Each is reachable from JS
+     * as a member of the module.
+     */
+    classes: ExportedClass[];
     /** Absolute source path. */
     file: string;
 }
+/** One entry of `@ExpoModule(classes: [...])`. */
+export interface ExportedClass {
+    /** The Swift name as spelled in the argument, e.g. `Database` or `Outer.Statement`. */
+    name: string;
+    /**
+     * The name of the module member JS reads the class from: the matching shared object's `jsName`.
+     * Absent when the scan found no shared object with this name, for example a class defined outside
+     * the scanned paths.
+     */
+    jsName?: string;
+}
 /** One `@Event var`: a typed event JS listens for by name, rather than calls. */
 export interface ExportedEvent {
     /** The Swift property name, e.g. `onStatusChange`. */
@@ -261,4 +277,4 @@ export interface ScanExportsResult {
  * as a clear error instead of silently misread fields.
  */
 export declare const SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
-export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 5;
+export declare const SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 6;

package/build/types.js

@@ -12,4 +12,4 @@ exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = exports.SUPPORTED_SCAN_MODULES_S
  * as a clear error instead of silently misread fields.
  */
 exports.SUPPORTED_SCAN_MODULES_SCHEMA_VERSION = 2;
-exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 5;
+exports.SUPPORTED_SCAN_EXPORTS_SCHEMA_VERSION = 6;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-modules-macros",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Swift macro plugin for Expo modules",
   "main": "build/index.js",
   "types": "build/index.d.ts",