@expo/expo-modules-macros-plugin 0.2.2 → 0.3.0

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -34,64 +34,157 @@ internal struct JSFunction {
     self.isAsync = effectSpecifiers?.asyncSpecifier != nil
   }
 
+  /// The number of leading parameters that must always be supplied: the total minus the maximal
+  /// trailing run of *omittable* parameters (each having a default value or an optional type). A
+  /// non-omittable parameter part-way through stops the run, since arguments are positional — a
+  /// required parameter after an omittable one forces the earlier one to be supplied too.
+  private var requiredArgumentCount: Int {
+    var required = parameters.count
+    for parameter in parameters.reversed() {
+      guard isOmittable(parameter) else {
+        break
+      }
+      required -= 1
+    }
+    return required
+  }
+
   /// The decode-call-encode statements that form the host-function body, indented with the given
-  /// prefix. Arity guard, then per-argument decode (primitives via a direct typed accessor like
-  /// `asDouble()` on a zero-copy `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`),
-  /// the `self.<name>(...)` call, and the
-  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`).
+  /// prefix. An arity guard (an exact check when every parameter is required, otherwise a range
+  /// check) throwing `Exceptions.ArgumentsRangeMismatch`; then the decode of the always-present
+  /// required prefix (primitives via a direct typed accessor like `asDouble()` on a zero-copy
+  /// `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`); then the call and
+  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`). When a
+  /// trailing run of parameters is omittable the call branches on `arguments.count`, decoding only
+  /// the slots that branch actually has — `arguments[i]` traps past `count`, so a slot the caller
+  /// didn't pass is never indexed.
   private func bodyStatements(indent: String) -> String {
+    let required = requiredArgumentCount
+    let maximum = parameters.count
     var lines: [String] = []
 
-    lines.append(
-      """
-      guard arguments.count == \(parameters.count) else {
-        throw Exception(name: "InvalidArgumentCount", description: "Function '\(jsName)' expects \(parameters.count) argument(s), but got \\(arguments.count)")
-      }
-      """)
+    if required == maximum {
+      lines.append(
+        """
+        guard arguments.count == \(maximum) else {
+          throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
+        }
+        """)
+    } else {
+      lines.append(
+        """
+        guard arguments.count >= \(required) && arguments.count <= \(maximum) else {
+          throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
+        }
+        """)
+    }
 
-    var callArguments: [String] = []
-    for (index, parameter) in parameters.enumerated() {
-      let type = parameter.type.trimmedDescription
+    // 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))
+    }
 
-      // Primitives decode through a direct typed accessor (`asDouble()`, etc.) on a borrowed
-      // `JavaScriptUnownedValue` — no owning `JavaScriptValue` allocation, no `jsi::Value` copy, no
-      // `getDynamicType()` allocation, no `Any` boxing, no force-cast — while still validating and
-      // throwing `TypeError` on a mismatch. Other types fall back to the dynamic converter, which
-      // needs an owning value, so they index the buffer directly.
-      if let accessor = fastDecodeAccessor(for: type) {
-        lines.append("let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()")
+    if required == maximum {
+      // No omittable trailing run: a single flat call with every argument decoded.
+      lines.append(contentsOf: callAndEncodeLines(arity: maximum, decodingFrom: required))
+    } else {
+      // One call shape per accepted arity. Each branch decodes only the trailing slots it has and
+      // fills the rest (defaulted params drop their label so Swift applies the default; optional
+      // params are passed `nil`). A value-returning function binds the result from a `switch`
+      // expression and encodes once after it; a no-return one calls inline in a `switch` statement
+      // and returns `.undefined`.
+      if returnType != nil {
+        lines.append("let result = switch arguments.count {")
       } else {
-        lines.append(
-          "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)")
+        lines.append("switch arguments.count {")
+      }
+      for arity in required...maximum {
+        let label = arity == maximum ? "default:" : "case \(arity):"
+        lines.append(label)
+        for index in required..<arity {
+          lines.append("  " + decodeStatement(at: index))
+        }
+        lines.append("  \(callExpression(arity: arity))")
       }
+      lines.append("}")
+      lines.append(contentsOf: encodeResultLines())
+    }
 
-      let label = parameter.firstName.text
-      callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")
+    return lines
+      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
+      .map { indent + $0 }
+      .joined(separator: "\n")
+  }
+
+  /// `let arg<index> = …` decoding the slot at `index` by its static type: a primitive through a
+  /// direct typed accessor on a borrowed `JavaScriptUnownedValue` (no owning value, no `jsi::Value`
+  /// copy, no `getDynamicType()` allocation, no `Any` boxing, no force-cast — still validating and
+  /// throwing `TypeError` on a mismatch), any other type through the dynamic converter (which needs
+  /// an owning value, so it indexes the buffer directly).
+  private func decodeStatement(at index: Int) -> String {
+    let type = parameters[index].type.trimmedDescription
+    if let accessor = fastDecodeAccessor(for: type) {
+      return "let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()"
     }
+    return "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)"
+  }
 
+  /// The `self.<name>(...)` call for the given arity. Slots `0..<arity` are passed their decoded
+  /// `arg<i>`; a trailing optional-without-default slot that this arity omits is passed `nil`; a
+  /// trailing defaulted slot that this arity omits is dropped entirely so Swift applies its default.
+  private func callExpression(arity: Int) -> String {
+    var callArguments: [String] = []
+    for (index, parameter) in parameters.enumerated() {
+      let label = parameter.firstName.text
+      let value: String?
+      if index < arity {
+        value = "arg\(index)"
+      } else if hasDefaultValue(parameter) {
+        // Omitted defaulted slot: drop it from the call so Swift fills in the default.
+        value = nil
+      } else {
+        // Omitted optional-without-default slot: pass `nil`.
+        value = "nil"
+      }
+      guard let value else {
+        continue
+      }
+      callArguments.append(label == "_" ? value : "\(label): \(value)")
+    }
     let tryKeyword = (isThrowing || isAsync) ? "try " : ""
     let awaitKeyword = isAsync ? "await " : ""
-    let callExpression =
-      "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
+    return "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
+  }
 
-    if let returnType {
-      lines.append("let result = \(callExpression)")
-      // Primitives encode through `toJavaScriptValue(in:)` (the typed `JavaScriptRepresentable`
-      // conversion) — no `Any`, no dynamic-type allocation. Others go through the dynamic converter.
-      if fastDecodeAccessor(for: returnType) != nil {
-        lines.append("return result.toJavaScriptValue(in: runtime)")
-      } else {
-        lines.append("return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)")
-      }
+  /// The flat (single-arity) call-and-encode lines used when no trailing parameter is omittable:
+  /// `let result = self.f(...)` then the return encode (or the no-return `self.f(...)` + `.undefined`).
+  private func callAndEncodeLines(arity: Int, decodingFrom: Int) -> [String] {
+    var lines: [String] = []
+    for index in decodingFrom..<arity {
+      lines.append(decodeStatement(at: index))
+    }
+    if returnType != nil {
+      lines.append("let result = \(callExpression(arity: arity))")
+      lines.append(contentsOf: encodeResultLines())
     } else {
-      lines.append(callExpression)
+      lines.append(callExpression(arity: arity))
       lines.append("return .undefined")
     }
-
     return lines
-      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
-      .map { indent + $0 }
-      .joined(separator: "\n")
+  }
+
+  /// Encode the `result` local back to JS and return it: a primitive through `toJavaScriptValue(in:)`
+  /// (the typed `JavaScriptRepresentable` conversion — no `Any`, no dynamic-type allocation), any
+  /// other type through the dynamic converter. A no-return function returns `.undefined` instead.
+  private func encodeResultLines() -> [String] {
+    guard let returnType else {
+      return ["return .undefined"]
+    }
+    if fastDecodeAccessor(for: returnType) != nil {
+      return ["return result.toJavaScriptValue(in: runtime)"]
+    }
+    return ["return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)"]
   }
 
   /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode

package/apple/Sources/ExpoModulesMacros/EventMacro.swift

@@ -0,0 +1,330 @@
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxMacros
+
+/// Accessor macro applied to a function-typed `var` on a module or shared object, turning it into a
+/// typed JavaScript event. A function-typed `var` can't be a stored property without an initializer,
+/// so the macro expands it into a computed getter returning a closure that dispatches by name into
+/// the `EventEmitter` `emit` overloads (core conforms both `BaseModule` and `SharedObject` to that
+/// protocol, so `self.emit` resolves on each):
+///
+///   @Event
+///   var onProgress: (ProgressEvent) -> Void
+///   // expands to:
+///   var onProgress: (ProgressEvent) -> Void {
+///     get {
+///       { [weak self] payload in self?.emit(event: "progress", payload: payload) }
+///     }
+///   }
+///
+/// A no-payload event (`() -> Void`) dispatches through the dedicated `emit(event:)` overload.
+/// The JS event name defaults to the property name with the conventional `on` prefix stripped
+/// (see `defaultEventName(for:)`); `@Event("customName")` overrides it verbatim.
+///
+/// The closure captures `self` **weakly**: it's usually invoked inline (`self.onProgress(…)`), but an
+/// author may store it or hand it to a delegate, and a strong capture would then extend the module's
+/// lifetime. After the emitter deallocates the closure silently no-ops, which matches what `emit`
+/// already does once the runtime is gone.
+///
+/// The synthesized property is deliberately **not** isolated to `@JavaScriptActor`, unlike `@JS`
+/// members: `emit` is itself non-isolated and schedules the dispatch onto the JS thread internally,
+/// so the event is callable from any thread or isolation with no actor hop at the call site. It is
+/// also self-contained: `@ExpoModule`/`@SharedObject` neither collect `@Event` members nor register
+/// their names anywhere.
+///
+/// `@Event(sync: true)` opts into **synchronous dispatch**: the closure calls `emitSync` (inline
+/// conversion + dispatch, no scheduling) instead of `emit`, and `@ExpoModule`/`@SharedObject` stamp
+/// the member `@JavaScriptActor` so the compiler forces the call site onto the JS thread, the
+/// inverse of the async default. The isolation is on the property access, so it guards the inline
+/// `self.onTick(…)` usage; a closure stored or handed off escapes it, after which `emitSync` runs
+/// wherever the caller invokes it.
+///
+/// As a **peer**, the macro emits a never-called conformance assertion (see
+/// `TypeConformanceAssertion.swift`) checking that the payload type is JS-convertible and that the
+/// enclosing type conforms to `EventEmitter`, so both failure modes surface as clear conformance
+/// errors on the user's own declaration.
+public struct EventMacro: AccessorMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingAccessorsOf declaration: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [AccessorDeclSyntax] {
+    let event = try validatedEvent(of: node, on: declaration)
+    // The closure's parameter and return types are inferred from the property's declared type
+    // through the getter, so the body never has to spell the payload type. A sync event calls
+    // `emitSync` (inline dispatch, JS thread only); the default calls the scheduling `emit`.
+    let emitMethod = event.isSync ? "emitSync" : "emit"
+    let closure = event.hasPayload
+      ? "{ [weak self] payload in self?.\(emitMethod)(event: \"\(event.jsName)\", payload: payload) }"
+      : "{ [weak self] in self?.\(emitMethod)(event: \"\(event.jsName)\") }"
+    return [
+      """
+      get {
+        \(raw: closure)
+      }
+      """
+    ]
+  }
+}
+
+extension EventMacro: PeerMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingPeersOf declaration: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    // Diagnostics are owned by the accessor expansion; an invalid declaration silently emits no
+    // peer here so each error is reported once.
+    guard let event = try? validatedEvent(of: node, on: declaration) else {
+      return []
+    }
+    // One nested helper asserts everything in a single call: the payload type is JS-convertible
+    // (the `P` parameter, dropped for no-payload events and known-conforming primitives) and the
+    // enclosing type can emit (the `E` parameter, always present since any `@Event` dispatches
+    // through `self.emit`). Named after the member so the member shows up in either diagnostic,
+    // and asserting the enclosing type by its spelled name so the conformance error names the
+    // user's type rather than 'Self'.
+    let name = event.swiftName
+    let payload = event.payloadType.flatMap(assertableBoundaryType)
+    let owner = enclosingTypeName(in: context) ?? "Self"
+    let helper = payload != nil
+      ? "func \(name)<P: \(jsConvertibleProtocolName), E: \(eventEmitterProtocolName)>(_: P.Type, _: E.Type) {}"
+      : "func \(name)<E: \(eventEmitterProtocolName)>(_: E.Type) {}"
+    let call = payload.map { "\(name)(\($0).self, \(owner).self)" } ?? "\(name)(\(owner).self)"
+    return [
+      """
+      private func _assertTypesConformance_\(raw: name)() {
+      \(raw: helper)
+      \(raw: call)
+      }
+      """
+    ]
+  }
+}
+
+/// What the expansions need to know about a validated `@Event` declaration: the property name, the
+/// JS event name (after an `@Event("…")` override), and the payload type when the function type
+/// takes one.
+private struct EventMember {
+  let swiftName: String
+  let jsName: String
+  /// The payload type as written, or `nil` for a no-payload `() -> Void` event.
+  let payloadType: String?
+  /// Whether the event dispatches synchronously (`@Event(sync: true)`) via `emitSync`.
+  let isSync: Bool
+
+  var hasPayload: Bool {
+    return payloadType != nil
+  }
+}
+
+/// Validates the declaration `@Event` is attached to and reads the event out of it. The checks
+/// mirror what the expansion relies on: a single-binding instance `var` (the macro synthesizes a
+/// computed getter, so `let`, accessors, and initializers are all incompatible) whose type is a
+/// function type returning `Void` with at most one payload parameter.
+private func validatedEvent(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol
+) throws -> EventMember {
+  guard let varDecl = declaration.as(VariableDeclSyntax.self) else {
+    throw MacroExpansionErrorMessage("@Event can only be applied to a property")
+  }
+  if varDecl.attributes.firstAttribute(named: "JS") != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event and @JS cannot be combined on the same property; an event is exposed to JS on its own, so remove one of the attributes")
+  }
+  // The compiler also rejects accessor macros on a `let`, but with a generic message; this one says
+  // what to do instead and carries the fix-it doing it. The synthesized property is getter-only, so
+  // switching to `var` loses nothing.
+  if varDecl.bindingSpecifier.tokenKind == .keyword(.let) {
+    throw letBindingDiagnostic(for: varDecl)
+  }
+  if varDecl.modifiers.contains(where: isTypeLevelModifier) {
+    throw MacroExpansionErrorMessage(
+      "@Event must be an instance property; events are emitted from a module or shared object instance.")
+  }
+  guard varDecl.bindings.count == 1, let binding = varDecl.bindings.first,
+    let identifier = binding.pattern.as(IdentifierPatternSyntax.self) else {
+    throw MacroExpansionErrorMessage(
+      "@Event must be applied to a single named property; declare each event separately")
+  }
+  if binding.initializer != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event property cannot have an initial value; the macro synthesizes the closure")
+  }
+  if binding.accessorBlock != nil {
+    throw MacroExpansionErrorMessage(
+      "@Event property cannot declare its own accessors; the macro synthesizes the getter")
+  }
+  guard let functionType = underlyingFunctionType(of: binding.typeAnnotation?.type) else {
+    throw MacroExpansionErrorMessage(
+      "@Event property must declare a function type, such as '(Payload) -> Void' or '() -> Void'")
+  }
+  guard isVoidReturn(functionType.returnClause.type) else {
+    throw MacroExpansionErrorMessage(
+      "@Event function type must return 'Void'; an event dispatches to JS and has no return value")
+  }
+  guard functionType.parameters.count <= 1 else {
+    throw MacroExpansionErrorMessage(
+      "@Event function type takes at most one payload parameter; combine multiple values into a single record")
+  }
+
+  let swiftName = identifier.identifier.text
+  return EventMember(
+    swiftName: swiftName,
+    jsName: jsNameArgument(of: node) ?? defaultEventName(for: swiftName),
+    payloadType: functionType.parameters.first?.type.trimmedDescription,
+    isSync: boolArgument(of: node, label: "sync") == true
+  )
+}
+
+// MARK: - Default event name
+
+/// The default JS event name for a property: the Swift name with the conventional `on` prefix
+/// stripped and the remainder decapitalized (`onStatusChange` → `statusChange`). The two sides
+/// idiomatically want different names: the Swift property reads as invoking a handler
+/// (`self.onStatusChange(…)`) and the prefix keeps it from colliding with a state property
+/// (`status`), while JS listens by bare name (`addListener("statusChange")`, the Node/DOM idiom
+/// that module and shared-object events follow). Names without the prefix (`statusChange`,
+/// `online`) pass through verbatim, and an explicit `@Event("name")` override is never
+/// transformed — that's also the escape hatch for legacy `onX` wire names.
+private func defaultEventName(for swiftName: String) -> String {
+  guard swiftName.hasPrefix("on") else {
+    return swiftName
+  }
+  let rest = swiftName.dropFirst(2)
+  guard let first = rest.first, first.isUppercase else {
+    return swiftName
+  }
+  return decapitalized(String(rest))
+}
+
+/// Lowercases the leading uppercase run the way Swift's API importer does: a single leading
+/// capital is lowercased (`StatusChange` → `statusChange`); a longer acronym run keeps its last
+/// capital when a lowercase letter follows it, since that capital starts the next word
+/// (`URLChange` → `urlChange`, `URL` → `url`).
+private func decapitalized(_ name: String) -> String {
+  let runEnd = name.firstIndex { !$0.isUppercase } ?? name.endIndex
+  if name[..<runEnd].count > 1 && runEnd != name.endIndex {
+    let lastCapital = name.index(before: runEnd)
+    return name[..<lastCapital].lowercased() + name[lastCapital...]
+  }
+  return name[..<runEnd].lowercased() + name[runEnd...]
+}
+
+// MARK: - The `let` diagnostic
+
+/// The error for `@Event let`, attached to the `let` keyword itself and carrying a fix-it that
+/// replaces it with `var`. Unlike the other checks (plain thrown messages located at the attribute),
+/// this one is a structured `Diagnostic` so Xcode can offer the one-click fix.
+private func letBindingDiagnostic(for varDecl: VariableDeclSyntax) -> DiagnosticsError {
+  let specifier = varDecl.bindingSpecifier
+  let fixIt = FixIt(
+    message: EventFixItMessage("Replace 'let' with 'var'", id: "event-let-to-var"),
+    changes: [
+      // Rewriting just the token's kind keeps its surrounding trivia (indentation, the space
+      // before the property name) intact.
+      .replace(
+        oldNode: Syntax(specifier),
+        newNode: Syntax(specifier.with(\.tokenKind, .keyword(.var)))
+      )
+    ]
+  )
+  let message = EventDiagnosticMessage(
+    "@Event must be applied to a 'var': it expands into a computed property, which a 'let' cannot be. The synthesized property is read-only anyway.",
+    id: "event-on-let"
+  )
+  return DiagnosticsError(diagnostics: [
+    Diagnostic(node: specifier, message: message, fixIts: [fixIt])
+  ])
+}
+
+private struct EventDiagnosticMessage: 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 EventFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+// MARK: - Declaration shape helpers
+
+/// The spelled name of the innermost type declaration enclosing the macro, read from the lexical
+/// context, so the emitter assertion can name the user's type in the conformance diagnostic
+/// ("requires that 'MyModule' conform to 'EventEmitter'" instead of "'Self'"). Returns `nil` (the
+/// caller falls back to `Self`) when there's no enclosing type, or when it's a generic type
+/// declaration: `Foo.self` isn't valid for an unbound generic, while `Self` works anywhere. An
+/// extension can't be detected as generic syntactically (see the extension case below).
+private func enclosingTypeName(in context: some MacroExpansionContext) -> String? {
+  for scope in context.lexicalContext {
+    if let classDecl = scope.as(ClassDeclSyntax.self) {
+      return classDecl.genericParameterClause == nil ? classDecl.name.text : nil
+    }
+    if let structDecl = scope.as(StructDeclSyntax.self) {
+      return structDecl.genericParameterClause == nil ? structDecl.name.text : nil
+    }
+    if let actorDecl = scope.as(ActorDeclSyntax.self) {
+      return actorDecl.genericParameterClause == nil ? actorDecl.name.text : nil
+    }
+    if let extensionDecl = scope.as(ExtensionDeclSyntax.self) {
+      // An extension carries no generic-parameter clause of its own, so a bare extended type
+      // (`extension Box`) is indistinguishable from a non-generic one (`extension Foo`); both read
+      // as a plain identifier here. A written bound form (`extension Box<Int>`) is valid as `.self`,
+      // and the common non-generic case keeps its spelled name in the diagnostic. The unguarded gap
+      // is `extension <Generic>` with the parameters omitted, where the spelled name is an unbound
+      // generic invalid as `.self`; events on generic types in an extension are rare enough that the
+      // resulting compile error is an acceptable price for naming the user's type everywhere else.
+      return extensionDecl.extendedType.trimmedDescription
+    }
+  }
+  return nil
+}
+
+private func isTypeLevelModifier(_ modifier: DeclModifierSyntax) -> Bool {
+  return modifier.name.tokenKind == .keyword(.static) || modifier.name.tokenKind == .keyword(.class)
+}
+
+/// The function type underlying a property's type annotation, unwrapping attributes
+/// (`@Sendable (P) -> Void`) and single-element parentheses (`((P) -> Void)`). Returns `nil` when
+/// the annotation is missing or isn't a function type, including an optional function type:
+/// an event is always present, never `nil`.
+private func underlyingFunctionType(of type: TypeSyntax?) -> FunctionTypeSyntax? {
+  guard let type else {
+    return nil
+  }
+  if let attributed = type.as(AttributedTypeSyntax.self) {
+    return underlyingFunctionType(of: attributed.baseType)
+  }
+  if let tuple = type.as(TupleTypeSyntax.self),
+    tuple.elements.count == 1, let element = tuple.elements.first, element.firstName == nil {
+    return underlyingFunctionType(of: element.type)
+  }
+  return type.as(FunctionTypeSyntax.self)
+}
+
+/// True when the function type's return is written as `Void` / `()`. Function types always carry an
+/// explicit return clause, so unlike a function declaration there's no "absent" case. A module-qualified
+/// `Swift.Void` and redundant parentheses (`(Void)`, `(())`) are accepted too, so a valid void return
+/// written one of those ways isn't rejected with a misleading "must return 'Void'" diagnostic.
+private func isVoidReturn(_ type: TypeSyntax) -> Bool {
+  // Peel single-element, unlabeled parentheses: `(Void)` and `(())` are the same type as their content.
+  if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
+    let element = tuple.elements.first, element.firstName == nil {
+    return isVoidReturn(element.type)
+  }
+  let text = type.trimmedDescription
+  return text == "Void" || text == "()" || text == "Swift.Void"
+}

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -6,11 +6,13 @@ import SwiftSyntaxMacros
  Macro applied to a module class. It plays three roles, each implemented in its own
  extension below:
 
- - `MemberMacro`: scans the class body for `@JS`-marked declarations and synthesizes a
-   framework-internal `_synthesizedDefinition()` returning `[AnyDefinition]`, which
-   `expo-modules-core` calls automatically and merges into the module's definition. When
-   the class doesn't already inherit `Module`/`BaseModule`, it also synthesizes the
-   `appContext` storage and `init(appContext:)` those base classes would have provided.
+ - `MemberMacro`: binds `@JS`-marked members directly into the module's JS object via the
+   synthesized `_decorateModule`, and emits the resolved module name as a non-optional
+   `_jsName` static (no `Name(…)` DSL element). It also synthesizes a
+   framework-internal `_synthesizedDefinition()` returning `[AnyDefinition]` (now carrying
+   only nested `classes` entries) that `expo-modules-core` merges into the module's
+   definition. When the class doesn't already inherit `Module`/`BaseModule`, it also
+   synthesizes the `appContext` storage and `init(appContext:)` those base classes provide.
  - `MemberAttributeMacro`: stamps `@JavaScriptActor` on `@JS` sync members and
    `@ModuleDefinitionBuilder` on a `definition()` method.
  - `ExtensionMacro`: adds the `AnyModule` conformance when the class doesn't inherit it.
@@ -39,8 +41,12 @@ public struct ExpoModuleMacro: MemberMacro {
       throw MacroExpansionErrorMessage("@ExpoModule can only be applied to a class")
     }
 
+    // The module name is fully resolved here (the explicit `@ExpoModule("…")` argument, else the
+    // class name) and emitted as a non-optional `_jsName` static below — so the
+    // macro no longer emits a `Name(…)` DSL entry. Core reads the static for the module name,
+    // ahead of its type-name fallback (which then only applies to non-macro DSL modules).
     let moduleName = jsNameArgument(of: node) ?? classDecl.name.text
-    var entries: [String] = ["Name(\"\(moduleName)\")"]
+    var entries: [String] = []
 
     // `@JS func`s (sync and async) and `@JS var`s are bound directly into the JS object by the
     // synthesized `_decorateModule` rather than described with a `Function(...)` / `Property(...)`
@@ -67,11 +73,21 @@ public struct ExpoModuleMacro: MemberMacro {
       }
     }
 
-    let lines = entries.map { "    \($0)" }.joined(separator: ",\n")
-    let body = "  return [\n\(lines)\n  ]"
+    let body: String
+    if entries.isEmpty {
+      body = "  return []"
+    } else {
+      let lines = entries.map { "    \($0)" }.joined(separator: ",\n")
+      body = "  return [\n\(lines)\n  ]"
+    }
 
     var emitted: [DeclSyntax] = []
 
+    // The fully-resolved module name as a non-optional stored constant. Core reads this
+    // instead of the retired `Name(…)` DSL element; it feeds both native registration and the
+    // JS object name, so they can't diverge.
+    emitted.append("public static let _jsName = \"\(raw: moduleName)\"")
+
     // `Module`/`BaseModule` already provide `appContext` storage and the
     // `init(appContext:)` requirement, so we only synthesize them for classes that
     // inherit from neither. Each is skipped individually if the user wrote their own,
@@ -127,7 +143,10 @@ extension ExpoModuleMacro: MemberAttributeMacro {
     // `@JS` sync members run on the JS thread; stamp `@JavaScriptActor` so isolation is
     // checked at compile time. Skipped when the member already chose an isolation
     // (`async`, `nonisolated`, or another global actor) — see `shouldStampJavaScriptActor`.
-    if memberHasJSAttribute(member),
+    // `@Event(sync: true)` members get the stamp too: a sync event dispatches inline, so the
+    // isolation forces its call site onto the JS thread. Async events (the default) are
+    // deliberately left unstamped — their `emit` schedules onto the JS thread itself.
+    if memberHasJSAttribute(member) || isSyncEventMember(member),
       shouldStampJavaScriptActor(on: member, enclosedBy: declaration) {
       attributes.append("@JavaScriptActor")
     }

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -14,6 +14,64 @@ internal func jsNameArgument(of attribute: AttributeSyntax) -> String? {
   return segment.content.text
 }
 
+/**
+ Reads a labeled boolean-literal argument of an attribute, e.g. `@Event(sync: true)` -> true.
+ Returns nil if the attribute has no argument with that label or its value isn't a boolean literal.
+ */
+internal func boolArgument(of attribute: AttributeSyntax, label: String) -> Bool? {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return nil
+  }
+  for arg in args where arg.label?.text == label {
+    guard let literal = arg.expression.as(BooleanLiteralExprSyntax.self) else {
+      return nil
+    }
+    return literal.literal.tokenKind == .keyword(.true)
+  }
+  return nil
+}
+
+/// 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 {
+  if type.is(OptionalTypeSyntax.self) || type.is(ImplicitlyUnwrappedOptionalTypeSyntax.self) {
+    return true
+  }
+  if let identifier = type.as(IdentifierTypeSyntax.self), identifier.name.text == "Optional" {
+    return true
+  }
+  return false
+}
+
+/// True if a trailing occurrence of this parameter may be omitted by the JS caller: it either has a
+/// default value (Swift applies it) or is an optional type (an absent slot becomes `nil`). The arity
+/// range and the per-arity call branches are derived from this.
+internal func isOmittable(_ parameter: FunctionParameterSyntax) -> Bool {
+  return hasDefaultValue(parameter) || isOptionalType(parameter.type)
+}
+
+/// True if the parameter declares a default value (`b: Int = 5`). An omitted defaulted slot is left
+/// out of the call so Swift fills in the default, distinguishing it from an omitted optional slot
+/// (passed `nil`).
+internal func hasDefaultValue(_ parameter: FunctionParameterSyntax) -> Bool {
+  return parameter.defaultValue != nil
+}
+
+/**
+ True if the declaration is a `@Event(sync: true)` property. A sync event dispatches inline on the
+ JS thread instead of scheduling, so `@ExpoModule`/`@SharedObject` stamp it with `@JavaScriptActor`,
+ making "must be called on the JS thread" a compile-time guarantee at the call site. Async events
+ (the default) are deliberately not stamped: their `emit` schedules onto the JS thread itself, so
+ they stay callable from any thread.
+ */
+internal func isSyncEventMember(_ decl: DeclSyntaxProtocol) -> Bool {
+  guard let varDecl = decl.as(VariableDeclSyntax.self),
+    let attribute = varDecl.attributes.firstAttribute(named: "Event") else {
+    return false
+  }
+  return boolArgument(of: attribute, label: "sync") == true
+}
+
 /**
  Reads a labeled array-literal argument of an attribute, e.g. `@ExpoModule(classes: [Foo.self, Bar.self])`,
  and returns the type names referenced (e.g. `["Foo", "Bar"]`). Each element must be a

package/apple/Sources/ExpoModulesMacros/Plugin.swift

@@ -6,6 +6,7 @@ struct ExpoModulesMacrosPlugin: CompilerPlugin {
   let providingMacros: [Macro.Type] = [
     OptimizedFunctionAttachedMacro.self,
     JSMacro.self,
+    EventMacro.self,
     ExpoModuleMacro.self,
     SharedObjectMacro.self,
     RecordMacro.self,

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -453,19 +453,6 @@ private func isExcludedByModifier(_ modifiers: DeclModifierListSyntax) -> Bool {
   return false
 }
 
-/**
- True if the type syntax is optional: `T?`, `T!`, or the spelled-out `Optional<T>`.
- */
-private func isOptionalType(_ type: TypeSyntax) -> Bool {
-  if type.is(OptionalTypeSyntax.self) || type.is(ImplicitlyUnwrappedOptionalTypeSyntax.self) {
-    return true
-  }
-  if let identifier = type.as(IdentifierTypeSyntax.self), identifier.name.text == "Optional" {
-    return true
-  }
-  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

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -95,7 +95,10 @@ extension SharedObjectMacro: MemberAttributeMacro {
     providingAttributesFor member: some DeclSyntaxProtocol,
     in context: some MacroExpansionContext
   ) throws -> [AttributeSyntax] {
-    guard memberHasJSAttribute(member),
+    // `@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 {
       return []
     }

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -5,6 +5,11 @@ import SwiftSyntax
 /// asserts the conformance (`@JS`, `@Record`, …).
 internal let jsConvertibleProtocolName = "AnyArgument"
 
+/// 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.
+internal let eventEmitterProtocolName = "EventEmitter"
+
 /// Types we never assert because they're statically known to conform and never reach the dynamic
 /// converter: the JS primitives. Asserting them would only add noise to the expansion. Kept here
 /// (rather than reusing the decode-path's `fastDecodeAccessor`) because "known-to-conform" is a
@@ -66,6 +71,15 @@ internal func typeConformanceAssertions(for assertions: [ConformanceAssertion])
     """
 }
 
+/// The type to assert for a boundary type as written: trailing optional markers are unwrapped to the
+/// core type, and a known-conforming primitive returns `nil` (nothing to assert). Shared with
+/// `@Event`, which folds its single payload type into a combined assertion of its own shape rather
+/// than reusing the whole body fragment below.
+internal func assertableBoundaryType(_ type: String) -> String? {
+  let unwrapped = unwrappedOptional(type)
+  return knownConformingPrimitives.contains(unwrapped) ? nil : unwrapped
+}
+
 /// The assertion's body fragment: a nested generic helper named after the member, plus one call per
 /// distinct non-primitive type. Nesting the helper keeps the constraint entirely local — no shared
 /// symbol, nothing to collide, nothing left in the type's namespace — and naming it after the member

package/package.json

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