@expo/expo-modules-macros-plugin 0.9.0 → 0.10.0

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -151,6 +151,13 @@ extension ExpoModuleMacro: MemberAttributeMacro {
       attributes.append("@JavaScriptActor")
     }
 
+    // `@JS(.concurrent)` is the inverse: instead of the JS-thread stamp the member gets
+    // `@concurrent`, so its body runs on the concurrent pool. `shouldStampJavaScriptActor` already
+    // skipped the stamp above, leaving the two mutually exclusive.
+    if isConcurrentJSMember(member) {
+      attributes.append("@concurrent")
+    }
+
     // Apply the result builder to `definition()` so the user doesn't have to. Skipped if
     // they already wrote `@ModuleDefinitionBuilder` themselves, which would otherwise be
     // a duplicate attribute.

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)
+    diagnoseConcurrentOption(of: node, on: declaration, in: context)
 
     guard let member = boundaryMember(of: declaration),
       let assertion = directionalConformanceAssertion(
@@ -46,6 +47,71 @@ public struct JSMacro: PeerMacro {
   }
 }
 
+/// Emits the diagnostic for `@JS(.concurrent)` on a member that can't take it. The option maps to
+/// Swift's `@concurrent`, which requires an `async` function: a synchronous member has nowhere to
+/// suspend, and a property or initializer can't be async at all. Diagnosing here points at the
+/// user's own `@JS` attribute rather than at the `@concurrent` the module macro would attach.
+private func diagnoseConcurrentOption(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  guard hasJSOption(node, named: "concurrent") else {
+    return
+  }
+  if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
+    guard funcDecl.signature.effectSpecifiers?.asyncSpecifier == nil else {
+      return
+    }
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "'.concurrent' needs an 'async' function: a synchronous @JS member runs on the JavaScript thread by definition. Mark the function 'async' to run its body off that thread.",
+          id: "js-concurrent-requires-async",
+          severity: .error
+        ),
+        fixIts: [insertAsyncFixIt(for: funcDecl)]))
+    return
+  }
+  context.diagnose(
+    Diagnostic(
+      node: node,
+      message: JSDiagnosticMessage(
+        "'.concurrent' applies only to an 'async' @JS function, not to a property or initializer.",
+        id: "js-concurrent-requires-function",
+        severity: .error
+      )))
+}
+
+/// The fix-it offered alongside the synchronous-function diagnostic: insert `async` into the
+/// signature so `@JS(.concurrent)` becomes valid. The macro can't add the keyword itself (no macro
+/// role rewrites the declaration it's attached to), but Xcode can apply this in one click.
+///
+/// `async` goes at the front of the effect specifiers, ahead of any `throws`, which is the only
+/// order Swift accepts. When the signature has no effect specifiers yet, the new clause inherits
+/// what the parameter clause had trailing it and the parameter clause is left with a single space,
+/// so `() -> Int` becomes `() async -> Int` rather than `() async-> Int`.
+private func insertAsyncFixIt(for funcDecl: FunctionDeclSyntax) -> FixIt {
+  let signature = funcDecl.signature
+  var newSignature = signature
+
+  if var effectSpecifiers = signature.effectSpecifiers {
+    effectSpecifiers.asyncSpecifier = .keyword(.async, trailingTrivia: .space)
+    newSignature.effectSpecifiers = effectSpecifiers
+  } else {
+    newSignature.effectSpecifiers = FunctionEffectSpecifiersSyntax(
+      asyncSpecifier: .keyword(.async, trailingTrivia: signature.parameterClause.trailingTrivia)
+    )
+    newSignature.parameterClause.trailingTrivia = .space
+  }
+
+  return FixIt(
+    message: JSFixItMessage("Mark the function 'async'", id: "js-concurrent-insert-async"),
+    changes: [.replace(oldNode: Syntax(signature), newNode: Syntax(newSignature))]
+  )
+}
+
 /// Emits the free-form (`Any` / `[Any]` / `[String: Any]`) diagnostics for a `@JS` declaration.
 ///
 /// A free-form type is only supported crossing the boundary as an **argument**, decoded through
@@ -155,6 +221,16 @@ private struct JSDiagnosticMessage: DiagnosticMessage {
   }
 }
 
+private struct JSFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
 /// What an assertion peer needs about the `@JS` member it sits beside: a name (to keep the peer unique
 /// among siblings), the boundary types split by conversion direction, and whether the member is
 /// type-level. Arguments (and a settable property's incoming value) are decoded; return values (and a

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -31,6 +31,44 @@ internal func boolArgument(of attribute: AttributeSyntax, label: String) -> Bool
   return nil
 }
 
+/// True if the attribute lists the given `JSOptions` member, e.g. `@JS(.concurrent)` or
+/// `@JS("name", [.concurrent])` -> true for "concurrent". Options are written as member-access
+/// expressions (`.concurrent`), optionally inside an array literal when more than one is combined, so
+/// both spellings are scanned. The leading string literal, when present, is the JS name and is skipped.
+internal func hasJSOption(_ attribute: AttributeSyntax, named option: String) -> Bool {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return false
+  }
+  for arg in args {
+    if namesOption(arg.expression, option) {
+      return true
+    }
+    if let array = arg.expression.as(ArrayExprSyntax.self),
+      array.elements.contains(where: { namesOption($0.expression, option) }) {
+      return true
+    }
+  }
+  return false
+}
+
+/// True when the expression is the member access `.<option>` (or `JSOptions.<option>`).
+private func namesOption(_ expression: ExprSyntax, _ option: String) -> Bool {
+  guard let member = expression.as(MemberAccessExprSyntax.self) else {
+    return false
+  }
+  return member.declName.baseName.text == option
+}
+
+/// True if the `@JS`-marked declaration opted into running off the JavaScript thread with
+/// `@JS(.concurrent)`. Such a member is left unstamped and gets `@concurrent` instead, so its body
+/// runs on the concurrent pool rather than inheriting the JS thread.
+internal func isConcurrentJSMember(_ decl: DeclSyntaxProtocol) -> Bool {
+  guard let attribute = memberAttributes(of: decl).firstAttribute(named: "JS") else {
+    return false
+  }
+  return hasJSOption(attribute, named: "concurrent")
+}
+
 /// True if the type is written as an optional: `T?`, `T!`, or the explicit `Optional<T>`. Used to
 /// decide argument requiredness (an optional parameter may be omitted) and record-field nullability.
 internal func isOptionalType(_ type: TypeSyntax) -> Bool {
@@ -156,6 +194,7 @@ internal func memberHasJSAttribute(_ decl: DeclSyntaxProtocol) -> Bool {
 
 /// Decides whether the macro should stamp `@JavaScriptActor` on a `@JS`-marked member.
 /// The macro defers to the user when they've already chosen an isolation:
+/// - the member opted out with `@JS(.concurrent)`
 /// - the `nonisolated` modifier is present on the member
 /// - any attribute whose name matches a known global actor (`@MainActor`, `@JavaScriptActor`)
 ///   or follows the `*Actor` naming convention is present on the member or its enclosing type
@@ -165,6 +204,10 @@ internal func shouldStampJavaScriptActor(
   on member: DeclSyntaxProtocol,
   enclosedBy enclosing: some DeclGroupSyntax
 ) -> Bool {
+  if isConcurrentJSMember(member) {
+    return false
+  }
+
   let modifiers = memberModifiers(of: member)
   if modifiers.contains(where: { $0.name.text == "nonisolated" }) {
     return false
@@ -326,3 +369,25 @@ internal func bindingIsSettable(_ binding: PatternBindingSyntax) -> Bool {
     return false
   }
 }
+
+/// True if the type's inheritance clause already lists a protocol with the given name. Matches
+/// either the bare identifier (`Record`) or a qualified member access ending in the name
+/// (`ExpoModulesCore.Record`). Used by the extension macros to skip a conformance the author already
+/// spelled out. Works for `struct`, `class`, and `enum` declarations; any other declaration kind has no
+/// inheritance clause to read and reports `false`.
+internal func inheritsProtocol(named name: String, in declaration: some DeclGroupSyntax) -> Bool {
+  let inheritanceClause: InheritanceClauseSyntax?
+  if let structDecl = declaration.as(StructDeclSyntax.self) {
+    inheritanceClause = structDecl.inheritanceClause
+  } else if let classDecl = declaration.as(ClassDeclSyntax.self) {
+    inheritanceClause = classDecl.inheritanceClause
+  } else if let enumDecl = declaration.as(EnumDeclSyntax.self) {
+    inheritanceClause = enumDecl.inheritanceClause
+  } else {
+    return false
+  }
+  guard let inherited = inheritanceClause?.inheritedTypes else {
+    return false
+  }
+  return inherited.contains { baseIdentifier(of: $0.type) == name }
+}

package/apple/Sources/ExpoModulesMacros/Plugin.swift

@@ -11,6 +11,7 @@ struct ExpoModulesMacrosPlugin: CompilerPlugin {
     ExpoModuleMacro.self,
     SharedObjectMacro.self,
     RecordMacro.self,
+    UnionMacro.self,
   ]
 }
 

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -478,37 +478,6 @@ private func isExcludedByModifier(_ modifiers: DeclModifierListSyntax) -> Bool {
   return false
 }
 
-/**
- True if the type's inheritance clause already lists a protocol with the given name.
- Matches either the bare identifier (`Record`) or a qualified member access ending in
- the name (`ExpoModulesCore.Record`).
- */
-private func inheritsProtocol(named name: String, in declaration: some DeclGroupSyntax) -> Bool {
-  let inheritanceClause: InheritanceClauseSyntax?
-  if let structDecl = declaration.as(StructDeclSyntax.self) {
-    inheritanceClause = structDecl.inheritanceClause
-  } else if let classDecl = declaration.as(ClassDeclSyntax.self) {
-    inheritanceClause = classDecl.inheritanceClause
-  } else {
-    return false
-  }
-  guard let inherited = inheritanceClause?.inheritedTypes else {
-    return false
-  }
-  for entry in inherited {
-    let typeSyntax = entry.type
-    if let identifier = typeSyntax.as(IdentifierTypeSyntax.self),
-      identifier.name.text == name {
-      return true
-    }
-    if let member = typeSyntax.as(MemberTypeSyntax.self),
-      member.name.text == name {
-      return true
-    }
-  }
-  return false
-}
-
 /**
  True if the class declaration has any inheritance clause. Used as a heuristic for
  whether the superclass also conforms to `Record` and provides the synthesized methods;

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -141,8 +141,14 @@ extension SharedObjectMacro: MemberAttributeMacro {
     // `@Event(sync: true)` members are stamped alongside `@JS` ones: a sync event dispatches
     // inline, so the isolation forces its call site onto the JS thread. Async events (the
     // default) stay unstamped — their `emit` schedules onto the JS thread itself.
-    guard memberHasJSAttribute(member) || isSyncEventMember(member),
-      shouldStampJavaScriptActor(on: member, enclosedBy: declaration) else {
+    guard memberHasJSAttribute(member) || isSyncEventMember(member) else {
+      return []
+    }
+    // `@JS(.concurrent)` opts the member out of the JS-thread stamp and onto the concurrent pool.
+    if isConcurrentJSMember(member) {
+      return ["@concurrent"]
+    }
+    guard shouldStampJavaScriptActor(on: member, enclosedBy: declaration) else {
       return []
     }
     return ["@JavaScriptActor"]

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -21,6 +21,12 @@ internal let javaScriptEncodableProtocolName = "JavaScriptEncodable"
 /// support both directions, so the assertion requires the intersection.
 internal let recordFieldProtocolName = "AnyArgument & JavaScriptDecodable & JavaScriptEncodable"
 
+/// The constraint a `@Union` case payload type must satisfy: the union decodes by trying each payload's
+/// `decode` and encodes through the matching payload's `encode`, so every alternative must convert in
+/// both directions. Unlike a `@Record` field, a union never crosses the native-`Any` dictionary path, so
+/// `AnyArgument` is not required.
+internal let unionPayloadProtocolName = "JavaScriptDecodable & JavaScriptEncodable"
+
 /// The protocol a type must conform to for `self.emit(event:…)` to resolve; core conforms
 /// `BaseModule` and `SharedObject` to it. Asserted by `@Event` so attaching it to a type that can't
 /// emit fails with a conformance diagnostic instead of an opaque "no member 'emit'" error.

package/apple/Sources/ExpoModulesMacros/UnionMacro.swift

@@ -0,0 +1,365 @@
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/// Member + extension macro applied to an `enum` whose cases each carry one associated value: a typed
+/// union of the payload types (`A | B | C` in TypeScript). The enum is a tagged union at the Swift
+/// 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:
+///
+/// - `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.
+/// - `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
+///   by type without naming the case and throws `Exceptions.UnionCaseMismatch` when the union holds a
+///   different case. Since a payload type may appear only once, each overload is unambiguous, and asking
+///   for a type the union doesn't carry is a compile error.
+///
+/// The type is auto-conformed to `JavaScriptDecodable` and `JavaScriptEncodable`, so it can be a `@JS`
+/// argument or return value, an `@Event` payload, or nested inside an optional, array, or dictionary.
+/// Author-facing shape:
+///
+///   @Union
+///   enum Source {
+///     case text(String)
+///     case options(SourceOptions)   // a @Record
+///   }
+///
+/// Discrimination is structural and order-dependent: the first case whose payload decodes wins. When
+/// two payload shapes overlap (two records with compatible fields, `Int` and `Double`), the earlier
+/// case matches; the author orders the more specific case first. A case may not repeat another case's
+/// payload type, since it could never be chosen.
+///
+/// The named-union counterpart of core's `Either`: any number of named cases instead of two anonymous
+/// slots, no `Any?` box, and an exhaustive `switch` as the primary way to read it (`as(_:)` covers the
+/// one-type lookup `Either.as(_:)` offered, with the same throwing shape).
+public struct UnionMacro: MemberMacro, ExtensionMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingMembersOf declaration: some DeclGroupSyntax,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    let union = try validatedUnion(of: declaration)
+
+    var members: [DeclSyntax] = []
+
+    // A single never-called member that makes the compiler verify each payload type converts both
+    // ways. Each case keeps its own named assertion inside, so the conformance diagnostic names the
+    // offending case (see `typeConformanceAssertions`). Emitted first so a non-conforming payload
+    // reports the clear "requires that '…' conform to …" error ahead of the noisier "no member
+    // 'decode'"/"'encode'" errors from the conversion code below.
+    let assertions = union.cases.map { ConformanceAssertion(name: $0.name, types: [$0.payloadType]) }
+    if let assertionMember = typeConformanceAssertions(for: assertions, constraint: unionPayloadProtocolName) {
+      members.append(assertionMember)
+    }
+
+    members.append(decodeMethod(union: union))
+    members.append(encodeMethod(union: union))
+    members.append(contentsOf: accessorMethods(union: union))
+    members.append(payloadTypeNameProperty(union: union))
+    return members
+  }
+
+  /// Auto-conforms the enum to `JavaScriptDecodable` and `JavaScriptEncodable`, the protocols whose
+  /// requirements are exactly the `decode`/`encode` members synthesized above. A conformance the author
+  /// already spelled out in the inheritance clause is not repeated.
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingExtensionsOf type: some TypeSyntaxProtocol,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [ExtensionDeclSyntax] {
+    // Diagnostics are owned by the member expansion; an invalid declaration silently emits no extension
+    // here, so each error is reported once and no witness-less conformance piles "does not conform"
+    // errors on top of it.
+    guard (try? validatedUnion(of: declaration)) != nil else {
+      return []
+    }
+    // The compiler hands over only the conformances the type still lacks; the test harness passes the
+    // declared list verbatim, so filter against the inheritance clause here as well.
+    let missing = protocols.filter { protocolType in
+      guard let name = baseIdentifier(of: protocolType) else {
+        return true
+      }
+      return !inheritsProtocol(named: name, in: declaration)
+    }
+    guard !missing.isEmpty else {
+      return []
+    }
+
+    let conformances = missing.map { $0.trimmedDescription }.joined(separator: ", ")
+    let ext: DeclSyntax = """
+      extension \(type.trimmed): \(raw: conformances) {}
+      """
+    guard let extDecl = ext.as(ExtensionDeclSyntax.self) else {
+      return []
+    }
+    return [extDecl]
+  }
+}
+
+// MARK: - Union model
+
+/// A validated `@Union` enum: its spelled name (for the mismatch error) and its cases in declaration
+/// order (the decode order).
+private struct UnionType {
+  let name: String
+  let cases: [UnionCase]
+}
+
+/// One alternative of the union: the case name, its single payload type as written, and the payload's
+/// argument label when the author gave it one (`case id(value: Int)`), needed to construct the case.
+private struct UnionCase {
+  let name: String
+  let payloadType: String
+  let payloadLabel: String?
+
+  /// The expression constructing this case from a `payload` local: `.id(payload)`, or
+  /// `.id(value: payload)` for a labeled associated value.
+  var construction: String {
+    if let payloadLabel {
+      return ".\(name)(\(payloadLabel): payload)"
+    }
+    return ".\(name)(payload)"
+  }
+
+  /// The pattern binding this case's payload to a `payload` local in a `switch`.
+  var pattern: String {
+    return ".\(name)(let payload)"
+  }
+}
+
+/// Reads and validates the union off the attached declaration. Every check is a compile error located
+/// on the offending node: the macro must be on a non-generic `enum` with at least one case, and every
+/// case must carry exactly one associated value, its payload type distinct from every earlier case's.
+private func validatedUnion(of declaration: some DeclGroupSyntax) throws -> UnionType {
+  guard let enumDecl = declaration.as(EnumDeclSyntax.self) else {
+    throw MacroExpansionErrorMessage("@Union can only be applied to an enum")
+  }
+  if let genericParameterClause = enumDecl.genericParameterClause {
+    throw DiagnosticsError(diagnostics: [
+      Diagnostic(
+        node: genericParameterClause,
+        message: UnionDiagnosticMessage(
+          "@Union cannot be applied to a generic enum: each case's payload type must be concrete so the macro can select its converter.",
+          id: "union-generic-enum"
+        ))
+    ])
+  }
+
+  var cases: [UnionCase] = []
+  var seenPayloadTypes: [String: String] = [:]
+  var diagnostics: [Diagnostic] = []
+
+  for member in enumDecl.memberBlock.members {
+    guard let caseDecl = member.decl.as(EnumCaseDeclSyntax.self) else {
+      continue
+    }
+    for element in caseDecl.elements {
+      let name = element.name.text
+      guard let parameters = element.parameterClause?.parameters, !parameters.isEmpty else {
+        diagnostics.append(
+          Diagnostic(
+            node: element,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' must carry exactly one associated value: the type this alternative decodes from. A payload-less enum is not a union; make it a raw-value enum conforming to 'Enumerable' instead.",
+              id: "union-case-without-payload"
+            )))
+        continue
+      }
+      guard parameters.count == 1, let parameter = parameters.first else {
+        diagnostics.append(
+          Diagnostic(
+            node: element,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' must carry exactly one associated value, but has \(parameters.count). Group them in a @Record type and use it as the single payload.",
+              id: "union-case-with-multiple-payloads"
+            )))
+        continue
+      }
+
+      // A default on the associated value can never apply: the macro constructs the case from the
+      // decoded JS value every time, and there is no "omitted" slot the way a `@Record` property has.
+      // Left in place it would read as a JS-side default that doesn't exist, so it's rejected with a
+      // fix-it that removes it.
+      if let defaultValue = parameter.defaultValue {
+        diagnostics.append(defaultValueDiagnostic(for: parameter, defaultValue: defaultValue, caseName: name))
+        continue
+      }
+
+      let payloadType = parameter.type.trimmedDescription
+      // Alternatives decode in declaration order and the first success wins, so a case whose payload
+      // type repeats an earlier case's is unreachable: an exact-spelling duplicate is an error. (An
+      // overlap between *different* types, like `Int` and `Double`, is the author's ordering call and
+      // isn't checked here.)
+      let normalizedType = payloadType.filter { !$0.isWhitespace }
+      if let earlierCase = seenPayloadTypes[normalizedType] {
+        diagnostics.append(
+          Diagnostic(
+            node: element,
+            message: UnionDiagnosticMessage(
+              "@Union case '\(name)' repeats the payload type '\(payloadType)' of case '\(earlierCase)' and can never be decoded: alternatives are tried in declaration order and the first match wins.",
+              id: "union-duplicate-payload-type"
+            )))
+        continue
+      }
+      seenPayloadTypes[normalizedType] = name
+
+      // `firstName` is the associated value's label (`case id(value: Int)`); a `_` label is the same as
+      // none for construction purposes.
+      let label = parameter.firstName.flatMap { $0.text == "_" ? nil : $0.text }
+      cases.append(UnionCase(name: name, payloadType: payloadType, payloadLabel: label))
+    }
+  }
+
+  if !diagnostics.isEmpty {
+    throw DiagnosticsError(diagnostics: diagnostics)
+  }
+  if cases.isEmpty {
+    throw MacroExpansionErrorMessage("@Union requires at least one case carrying an associated value")
+  }
+  return UnionType(name: enumDecl.name.text, cases: cases)
+}
+
+// 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
+/// 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.
+private func decodeMethod(union: UnionType) -> DeclSyntax {
+  var lines: [String] = []
+  for unionCase in union.cases {
+    let payloadType = expressionType(unionCase.payloadType)
+    lines.append("  if 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)])"
+  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 {
+    \(raw: body)
+    }
+    """
+}
+
+/// `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.
+private func encodeMethod(union: UnionType) -> DeclSyntax {
+  var lines: [String] = ["  switch value {"]
+  for unionCase in union.cases {
+    lines.append("  case \(unionCase.pattern):")
+    lines.append("    return try \(expressionType(unionCase.payloadType)).encode(payload, in: runtime)")
+  }
+  lines.append("  }")
+  let body = lines.joined(separator: "\n")
+  return """
+    @JavaScriptActor
+    public static func encode(_ value: Self, in runtime: borrowing JavaScriptRuntime) throws -> JavaScriptValue {
+    \(raw: body)
+    }
+    """
+}
+
+/// `as(_:)`: a typed accessor per case, selected by the payload's metatype rather than the case name,
+/// so a caller that only knows the type it wants writes `try value.as(String.self)` and gets a `String`.
+/// When
+/// the union holds a different case it throws `Exceptions.UnionCaseMismatch`, the same error `decode`
+/// throws, with the held case's payload type as `received` and the requested type as `expected`. The
+/// overloads can't collide because a payload type appears in at most one case (enforced above), and a
+/// metatype the union doesn't carry fails to resolve at compile time. `as` is a keyword, so the
+/// declaration is backticked; a call site after a dot (`value.as(…)`) needs no backticks. The parameter
+/// is spelled in expression form (`T!` rewritten to `T?`), since `T!.Type` isn't valid.
+private func accessorMethods(union: UnionType) -> [DeclSyntax] {
+  return union.cases.map { unionCase in
+    let payloadType = expressionType(unionCase.payloadType)
+    let mismatch = "(unionName: \"\(union.name)\", received: _payloadTypeName, expected: [\"\(unionCase.payloadType)\"])"
+    return """
+      public func `as`(_ type: \(raw: payloadType).Type) throws -> \(raw: payloadType) {
+        if case \(raw: unionCase.pattern) = self {
+          return payload
+        }
+        throw Exceptions.UnionCaseMismatch(\(raw: mismatch))
+      }
+      """
+  }
+}
+
+/// `_payloadTypeName`: the spelled payload type of the case the union currently holds, as written in the
+/// declaration, so every `as(_:)` overload reports the actual type in its mismatch error through one
+/// shared `switch` instead of each overload enumerating the other cases.
+private func payloadTypeNameProperty(union: UnionType) -> DeclSyntax {
+  var lines: [String] = ["  switch self {"]
+  for unionCase in union.cases {
+    lines.append("  case .\(unionCase.name):")
+    lines.append("    return \"\(unionCase.payloadType)\"")
+  }
+  lines.append("  }")
+  let body = lines.joined(separator: "\n")
+  return """
+    private var _payloadTypeName: String {
+    \(raw: body)
+    }
+    """
+}
+
+// MARK: - Diagnostics
+
+/// The error for a default value on a case's associated value, attached to the `= …` clause and carrying
+/// a fix-it that deletes it (trimming the space the type carried before the `=`).
+private func defaultValueDiagnostic(
+  for parameter: EnumCaseParameterSyntax,
+  defaultValue: InitializerClauseSyntax,
+  caseName: String
+) -> Diagnostic {
+  let fixIt = FixIt(
+    message: UnionFixItMessage("Remove the default value", id: "union-remove-default-value"),
+    changes: [
+      .replace(
+        oldNode: Syntax(parameter),
+        newNode: Syntax(
+          parameter
+            .with(\.type, parameter.type.with(\.trailingTrivia, []))
+            .with(\.defaultValue, nil))
+      )
+    ]
+  )
+  let message = UnionDiagnosticMessage(
+    "@Union case '\(caseName)' cannot give its associated value a default: the payload is always decoded from the JavaScript value, so the default would never apply. Remove '\(defaultValue.trimmedDescription)'.",
+    id: "union-case-default-value"
+  )
+  return Diagnostic(node: defaultValue, message: message, fixIts: [fixIt])
+}
+
+private struct UnionDiagnosticMessage: 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 UnionFixItMessage: 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/ExpoModulesScanner/Core/SourceScan.swift

@@ -100,11 +100,21 @@ func mightContainMacro(in source: String, prefilter: NSRegularExpression) -> Boo
 
 // MARK: - File discovery
 
-/// Directory names skipped during the recursive walk. These hold build products, dependencies, and
-/// git internals — never source worth scanning — and pruning them keeps the walk from descending
-/// into the bulk of a monorepo's files. `node_modules` makes any npm package root safe to pass as a
-/// scan path: nested dependencies are separate packages and get scanned on their own.
-private let prunedDirectoryNames: Set<String> = [".build", "Pods", ".git", "node_modules"]
+/// Directory names skipped during the recursive walk, in two groups:
+/// - Build products, dependencies, and git internals (`.build`, `Pods`, `.git`, `node_modules`) are
+///   never source worth scanning, and pruning them keeps the walk from descending into the bulk of
+///   a monorepo's files. `node_modules` also makes any npm package root safe to pass as a scan
+///   path: nested dependencies are separate packages and get scanned on their own.
+/// - Test and example directories, by the layout conventions of Expo module packages (`Tests`,
+///   `UITests`, `__tests__`, `__mocks__`, `example(s)`, `e2e`). Their sources are not compiled into the
+///   package's product (they belong to a `test_spec` or a standalone example app), so a declaration
+///   found there would name a type the consumer can't reference. This is a name-based heuristic;
+///   a package keeping product sources in such a directory can declare its modules in
+///   `expo-module.config.json` instead.
+private let prunedDirectoryNames: Set<String> = [
+  ".build", "Pods", ".git", "node_modules",
+  "Tests", "UITests", "__tests__", "__mocks__", "example", "examples", "e2e",
+]
 
 /// Expands the given paths into the list of `.swift` files to parse: a file path passes through,
 /// a directory is enumerated recursively (skipping `prunedDirectoryNames`). Order is deterministic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/expo-modules-macros-plugin",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Swift macro plugin for Expo modules",
   "license": "MIT",
   "author": "650 Industries, Inc.",