expo-modules-macros 0.20.0 → 0.22.0

package/apple/Sources/ExpoModulesMacros/JSNameCollisions.swift

@@ -0,0 +1,84 @@
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxMacros
+
+/// Reports each `@JS` member whose JavaScript name an earlier `@JS` member already binds on the same
+/// JavaScript object. Pass the members of one object only: a shared object's static members bind onto
+/// the constructor and its instance members onto the prototype, so the two sets are checked separately.
+internal func diagnoseJSNameCollisions(
+  functions: [JSFunction],
+  properties: [JSProperty],
+  in context: some MacroExpansionContext
+) {
+  // Each member binds with its own `setProperty` or `defineProperty` call, so of two members with one
+  // name, JavaScript would reach only one. Members are compared in source order, so the error lands on
+  // every member after the first, whichever kind each one is.
+  let members = functions.map(BoundMember.init(function:)) + properties.map(BoundMember.init(property:))
+  var firstMembers: [String: BoundMember] = [:]
+
+  for member in members.sorted(by: { $0.nameToken.position < $1.nameToken.position }) {
+    guard let first = firstMembers[member.jsName] else {
+      firstMembers[member.jsName] = member
+      continue
+    }
+    let renaming =
+      first.renaming == member.renaming ? first.renaming : "\(first.renaming) or \(member.renaming)"
+    context.diagnose(
+      Diagnostic(
+        node: member.nameToken,
+        message: JSNameCollisionMessage(
+          "The JavaScript name '\(member.jsName)' is already bound by an earlier \(first.kind). A JavaScript object holds one member per name, so JavaScript could reach only one of them. Give one of them another name with \(renaming)."
+        ),
+        notes: [
+          Note(
+            node: Syntax(first.nameToken),
+            message: JSNameCollisionNote("'\(member.jsName)' is first bound here")
+          )
+        ]
+      )
+    )
+  }
+}
+
+private struct BoundMember {
+  let jsName: String
+  /// How the message names the member, such as `@JS function`.
+  let kind: String
+  /// The spelling that gives the member another JavaScript name.
+  let renaming: String
+  let nameToken: TokenSyntax
+
+  init(function: JSFunction) {
+    // A `.withAsync` variant takes its JavaScript name from the option, not from `@JS("...")`.
+    self.jsName = function.jsName
+    self.kind = function.isAsyncVariant ? "'.withAsync' variant" : "@JS function"
+    self.renaming = function.isAsyncVariant ? ".withAsync(\"...\")" : "@JS(\"...\")"
+    self.nameToken = function.nameToken
+  }
+
+  init(property: JSProperty) {
+    self.jsName = property.jsName
+    self.kind = "@JS property"
+    self.renaming = "@JS(\"...\")"
+    self.nameToken = property.nameToken
+  }
+}
+
+private struct JSNameCollisionMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID = MessageID(domain: "ExpoModulesMacros", id: "js-name-collision")
+  let severity: DiagnosticSeverity = .error
+
+  init(_ message: String) {
+    self.message = message
+  }
+}
+
+private struct JSNameCollisionNote: NoteMessage {
+  let message: String
+  let noteID = MessageID(domain: "ExpoModulesMacros", id: "js-name-collision-first")
+
+  init(_ message: String) {
+    self.message = message
+  }
+}

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -1,23 +1,20 @@
 import SwiftSyntax
 
-/**
- Reads the first string-literal argument of an attribute, e.g. `@JS("doWork")` -> "doWork".
- Returns nil if the attribute has no arguments or the first argument is not a string literal.
- */
+/// Reads the first string-literal argument of an attribute, e.g. `@JS("doWork")` -> "doWork".
+/// Returns nil if the attribute has no arguments or the first argument is not a string literal.
 internal func jsNameArgument(of attribute: AttributeSyntax) -> String? {
   guard let args = attribute.arguments?.as(LabeledExprListSyntax.self),
     let first = args.first,
     let str = first.expression.as(StringLiteralExprSyntax.self),
-    let segment = str.segments.first?.as(StringSegmentSyntax.self) else {
+    let segment = str.segments.first?.as(StringSegmentSyntax.self)
+  else {
     return nil
   }
   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.
- */
+/// 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
@@ -44,7 +41,8 @@ internal func hasJSOption(_ attribute: AttributeSyntax, named option: String) ->
       return true
     }
     if let array = arg.expression.as(ArrayExprSyntax.self),
-      array.elements.contains(where: { namesOption($0.expression, option) }) {
+      array.elements.contains(where: { namesOption($0.expression, option) })
+    {
       return true
     }
   }
@@ -69,6 +67,64 @@ internal func isConcurrentJSMember(_ decl: DeclSyntaxProtocol) -> Bool {
   return hasJSOption(attribute, named: "concurrent")
 }
 
+/// The `.withAsync("name")` option of a `@JS` attribute, e.g. `@JS(.withAsync("loadAsync"))` or
+/// `@JS("load", [.withAsync("loadAsync")])`, or `nil` when the attribute doesn't list it. When the
+/// option is listed more than once, the first one counts and `@JS` reports the others.
+internal func asyncVariantOption(of attribute: AttributeSyntax) -> FunctionCallExprSyntax? {
+  return asyncVariantOptions(of: attribute).first
+}
+
+/// Every `.withAsync(...)` option of a `@JS` attribute, in source order. Like `hasJSOption`, it scans
+/// the arguments and the elements of an array literal.
+internal func asyncVariantOptions(of attribute: AttributeSyntax) -> [FunctionCallExprSyntax] {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return []
+  }
+  return args.flatMap { arg -> [FunctionCallExprSyntax] in
+    if let array = arg.expression.as(ArrayExprSyntax.self) {
+      return array.elements.compactMap { asyncOptionCall($0.expression) }
+    }
+    return asyncOptionCall(arg.expression).map { [$0] } ?? []
+  }
+}
+
+/// The expression as a `.withAsync(...)` call (or `JSOptions.withAsync(...)`), or `nil` for anything
+/// else.
+private func asyncOptionCall(_ expression: ExprSyntax) -> FunctionCallExprSyntax? {
+  guard let call = expression.as(FunctionCallExprSyntax.self),
+    let member = call.calledExpression.as(MemberAccessExprSyntax.self),
+    member.declName.baseName.text == "withAsync"
+  else {
+    return nil
+  }
+  return call
+}
+
+/// The JavaScript name a `.withAsync("name")` option gives the promise-returning variant, with the
+/// token of its string literal, where a name collision is reported. `nil` when the argument isn't a
+/// single plain string literal, which `@JS` reports.
+internal func asyncVariantName(of option: FunctionCallExprSyntax) -> (name: String, token: TokenSyntax)? {
+  guard option.arguments.count == 1,
+    let argument = option.arguments.first,
+    argument.label == nil,
+    let literal = argument.expression.as(StringLiteralExprSyntax.self),
+    literal.segments.count == 1,
+    let segment = literal.segments.first?.as(StringSegmentSyntax.self)
+  else {
+    return nil
+  }
+  return (segment.content.text, segment.content)
+}
+
+/// True if the `@JS`-marked declaration lists `.withAsync("name")`. Such a function is left
+/// unstamped, because its promise-returning variant calls it on the concurrent pool.
+internal func hasAsyncVariant(_ decl: DeclSyntaxProtocol) -> Bool {
+  guard let attribute = memberAttributes(of: decl).firstAttribute(named: "JS") else {
+    return false
+  }
+  return asyncVariantOption(of: attribute) != 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 {
@@ -129,12 +185,82 @@ internal func optionalWrappedType(_ type: TypeSyntax) -> TypeSyntax? {
   if let identifier = type.as(IdentifierTypeSyntax.self),
     identifier.name.text == "Optional",
     let argument = identifier.genericArgumentClause?.arguments.first,
-    case .type(let wrapped) = argument.argument {
+    case .type(let wrapped) = argument.argument
+  {
     return wrapped
   }
   return nil
 }
 
+/// The element type of `[T]` or `Array<T>`, or `nil` for any other type.
+internal func arrayElementType(_ type: TypeSyntax) -> TypeSyntax? {
+  if let array = type.as(ArrayTypeSyntax.self) {
+    return array.element
+  }
+  guard let arguments = genericArguments(of: type, named: "Array"), arguments.count == 1 else {
+    return nil
+  }
+  return arguments[0]
+}
+
+/// The value type of `[String: V]` or `Dictionary<String, V>`, or `nil` for any other type, including a
+/// dictionary with a different key type.
+internal func stringKeyedDictionaryValueType(_ type: TypeSyntax) -> TypeSyntax? {
+  if let dictionary = type.as(DictionaryTypeSyntax.self) {
+    return isStringType(dictionary.key) ? dictionary.value : nil
+  }
+  guard let arguments = genericArguments(of: type, named: "Dictionary"), arguments.count == 2 else {
+    return nil
+  }
+  return isStringType(arguments[0]) ? arguments[1] : nil
+}
+
+/// The element type of `Set<T>`, or `nil` for any other type.
+internal func setElementType(_ type: TypeSyntax) -> TypeSyntax? {
+  guard let arguments = genericArguments(of: type, named: "Set"), arguments.count == 1 else {
+    return nil
+  }
+  return arguments[0]
+}
+
+/// The type arguments of a generic type spelled `<name><…>` (or `Swift.<name><…>`), or `nil` when the
+/// type has another name or no type arguments.
+private func genericArguments(of type: TypeSyntax, named name: String) -> [TypeSyntax]? {
+  let clause: GenericArgumentClauseSyntax?
+  if let identifier = type.as(IdentifierTypeSyntax.self), identifier.name.text == name {
+    clause = identifier.genericArgumentClause
+  } else if let member = type.as(MemberTypeSyntax.self),
+    member.name.text == name,
+    member.baseType.as(IdentifierTypeSyntax.self)?.name.text == "Swift"
+  {
+    clause = member.genericArgumentClause
+  } else {
+    return nil
+  }
+  guard let clause else {
+    return nil
+  }
+  var types: [TypeSyntax] = []
+  for argument in clause.arguments {
+    guard case .type(let type) = argument.argument else {
+      return nil
+    }
+    types.append(type)
+  }
+  return types
+}
+
+/// True when the type is `String` or `Swift.String`.
+private func isStringType(_ type: TypeSyntax) -> Bool {
+  if let identifier = type.as(IdentifierTypeSyntax.self) {
+    return identifier.name.text == "String" && identifier.genericArgumentClause == nil
+  }
+  if let member = type.as(MemberTypeSyntax.self), member.name.text == "String" {
+    return member.baseType.as(IdentifierTypeSyntax.self)?.name.text == "Swift"
+  }
+  return false
+}
+
 /// True when the modifiers make the member type-level (`static` or `class`). A shared object routes
 /// such members to its constructor (JS-static) and instance members to its prototype; the `@JS`
 /// conformance assertion also uses this to emit its peer in the matching metatype context.
@@ -158,26 +284,23 @@ 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.
- */
+/// 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 {
+    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
- `<TypeName>.self` member-access expression; non-conforming elements are skipped silently.
- */
+/// 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
+/// `<TypeName>.self` member-access expression; non-conforming elements are skipped silently.
 internal func classListArgument(of attribute: AttributeSyntax, label: String) -> [String] {
   guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
     return []
@@ -189,7 +312,8 @@ internal func classListArgument(of attribute: AttributeSyntax, label: String) ->
     return array.elements.compactMap { element -> String? in
       guard let memberAccess = element.expression.as(MemberAccessExprSyntax.self),
         memberAccess.declName.baseName.text == "self",
-        let base = memberAccess.base else {
+        let base = memberAccess.base
+      else {
         return nil
       }
       // A bare `CardView.self` has a `DeclReferenceExprSyntax` base; a qualified
@@ -205,11 +329,9 @@ internal func classListArgument(of attribute: AttributeSyntax, label: String) ->
   return []
 }
 
-/**
- Returns true if the class's inheritance clause names any of the given identifiers.
- Matches by base identifier only, so `Module`, `ExpoModulesCore.Module`, and
- `Module<Foo>` all match an entry of "Module".
- */
+/// Returns true if the class's inheritance clause names any of the given identifiers.
+/// Matches by base identifier only, so `Module`, `ExpoModulesCore.Module`, and
+/// `Module<Foo>` all match an entry of "Module".
 internal func inheritsFromAny(_ classDecl: ClassDeclSyntax, names: Set<String>) -> Bool {
   guard let inherited = classDecl.inheritanceClause?.inheritedTypes else {
     return false
@@ -222,10 +344,8 @@ internal func inheritsFromAny(_ classDecl: ClassDeclSyntax, names: Set<String>)
   return false
 }
 
-/**
- Returns the rightmost identifier of a type, e.g. `Foo` for `Foo`, `Foo` for
- `Module.Foo`, and nil for composed or generic shapes the macro doesn't need to handle.
- */
+/// Returns the rightmost identifier of a type, e.g. `Foo` for `Foo`, `Foo` for
+/// `Module.Foo`, and nil for composed or generic shapes the macro doesn't need to handle.
 internal func baseIdentifier(of type: TypeSyntax) -> String? {
   if let identifier = type.as(IdentifierTypeSyntax.self) {
     return identifier.name.text
@@ -236,10 +356,8 @@ internal func baseIdentifier(of type: TypeSyntax) -> String? {
   return nil
 }
 
-/**
- True if the declaration carries a `@JS` attribute. Works for functions, properties, and inits;
- returns false for any other decl kind.
- */
+/// True if the declaration carries a `@JS` attribute. Works for functions, properties, and inits;
+/// returns false for any other decl kind.
 internal func memberHasJSAttribute(_ decl: DeclSyntaxProtocol) -> Bool {
   if let funcDecl = decl.as(FunctionDeclSyntax.self) {
     return funcDecl.attributes.firstAttribute(named: "JS") != nil
@@ -256,6 +374,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 member lists `@JS(.withAsync("name"))`, whose variant runs it on the concurrent pool
 /// - 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
@@ -265,7 +384,7 @@ internal func shouldStampJavaScriptActor(
   on member: DeclSyntaxProtocol,
   enclosedBy enclosing: some DeclGroupSyntax
 ) -> Bool {
-  if isConcurrentJSMember(member) {
+  if isConcurrentJSMember(member) || hasAsyncVariant(member) {
     return false
   }
 
@@ -312,7 +431,7 @@ internal func memberAttributes(of decl: DeclSyntaxProtocol) -> AttributeListSynt
   return AttributeListSyntax()
 }
 
-private func hasGlobalActorShape(_ element: AttributeListSyntax.Element) -> Bool {
+internal func hasGlobalActorShape(_ element: AttributeListSyntax.Element) -> Bool {
   guard let attribute = element.as(AttributeSyntax.self) else {
     return false
   }
@@ -345,7 +464,8 @@ extension AttributeListSyntax {
   internal func firstAttribute(named name: String) -> AttributeSyntax? {
     for element in self {
       if let attr = element.as(AttributeSyntax.self),
-        attr.attributeName.trimmedDescription == name {
+        attr.attributeName.trimmedDescription == name
+      {
         return attr
       }
     }
@@ -433,7 +553,8 @@ internal func collectProperties(
     let swiftName = ident.identifier.text
     // Prefer the explicit annotation; recover the type from a literal default (`var x = false`)
     // when there's none. `nil` falls back to inference at the use site.
-    let valueType = binding.typeAnnotation?.type.trimmedDescription
+    let valueType =
+      binding.typeAnnotation?.type.trimmedDescription
       ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
     return JSProperty(
       swiftName: swiftName,
@@ -441,7 +562,8 @@ internal func collectProperties(
       valueType: valueType,
       // A literal-inferred type never mentions `Any`, so only an explicit annotation can be free-form.
       freeForm: binding.typeAnnotation.flatMap { freeFormConversion(of: $0.type) },
-      isSettable: isVar && bindingIsSettable(binding)
+      isSettable: isVar && bindingIsSettable(binding),
+      nameToken: ident.identifier
     )
   }
 }