expo-modules-macros 0.21.0 → 0.22.0

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -35,6 +35,7 @@ public struct JSMacro: PeerMacro {
     diagnoseFreeFormTypes(in: declaration, in: context)
     diagnoseClosureTypes(in: declaration, in: context)
     diagnoseConcurrentOption(of: node, on: declaration, in: context)
+    diagnoseAsyncVariantOption(of: node, on: declaration, in: context)
 
     guard let member = boundaryMember(of: declaration),
       let assertion = directionalConformanceAssertion(
@@ -43,7 +44,8 @@ public struct JSMacro: PeerMacro {
         encodableType: member.encodableType,
         callbackArgumentTypes: member.callbackArgumentTypes,
         isStatic: member.isStatic
-      ) else {
+      )
+    else {
       return []
     }
     return [assertion]
@@ -74,7 +76,9 @@ private func diagnoseConcurrentOption(
           id: "js-concurrent-requires-async",
           severity: .error
         ),
-        fixIts: [insertAsyncFixIt(for: funcDecl)]))
+        fixIts: [insertAsyncFixIt(for: funcDecl)]
+      )
+    )
     return
   }
   context.diagnose(
@@ -84,7 +88,108 @@ private func diagnoseConcurrentOption(
         "'.concurrent' applies only to an 'async' @JS function, not to a property or initializer.",
         id: "js-concurrent-requires-function",
         severity: .error
-      )))
+      )
+    )
+  )
+}
+
+/// Emits the diagnostics for `@JS(.withAsync("name"))` on a member that can't take it. The option
+/// adds a promise-returning variant that calls the function on the concurrent pool, so it needs a
+/// synchronous function without a global actor, and the variant's JavaScript name as a string literal.
+private func diagnoseAsyncVariantOption(
+  of node: AttributeSyntax,
+  on declaration: some DeclSyntaxProtocol,
+  in context: some MacroExpansionContext
+) {
+  guard let option = asyncVariantOption(of: node) else {
+    return
+  }
+  guard let funcDecl = declaration.as(FunctionDeclSyntax.self) else {
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "'.withAsync' applies only to a synchronous @JS function, not to a property or initializer.",
+          id: "js-async-variant-requires-function",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  if funcDecl.signature.effectSpecifiers?.asyncSpecifier != nil {
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          "'.withAsync' adds a promise-returning variant to a synchronous function, and this function is already 'async'. Remove '.withAsync', and use '.concurrent' to run the function off the JavaScript thread.",
+          id: "js-async-variant-on-async-function",
+          severity: .error
+        )
+      )
+    )
+    return
+  }
+  for duplicate in asyncVariantOptions(of: node).dropFirst() {
+    context.diagnose(
+      Diagnostic(
+        node: duplicate,
+        message: JSDiagnosticMessage(
+          "'.withAsync' can be listed only once: a function gets one promise-returning variant.",
+          id: "js-async-variant-duplicate",
+          severity: .error
+        )
+      )
+    )
+  }
+  if asyncVariantName(of: option) == nil {
+    context.diagnose(
+      Diagnostic(
+        node: option,
+        message: JSDiagnosticMessage(
+          "'.withAsync' takes the JavaScript name of the variant as a string literal, for example '.withAsync(\"loadAsync\")'.",
+          id: "js-async-variant-name",
+          severity: .error
+        )
+      )
+    )
+  }
+  if let isolation = globalActorIsolation(of: funcDecl, in: context) {
+    context.diagnose(
+      Diagnostic(
+        node: node,
+        message: JSDiagnosticMessage(
+          isolation.enclosingTypeName.map {
+            "'.withAsync' calls the function on the concurrent thread pool, so the function can't inherit '\(isolation.attribute)' from '\($0)'. Mark the function 'nonisolated'."
+          }
+            ?? "'.withAsync' calls the function on the concurrent thread pool, so the function can't be isolated to '\(isolation.attribute)'.",
+          id: "js-async-variant-isolated",
+          severity: .error
+        )
+      )
+    )
+  }
+}
+
+/// The global actor a function is isolated to, written on the function itself or inherited from its
+/// enclosing type, or `nil` when it has none or is `nonisolated`. `enclosingTypeName` is set when the
+/// isolation is inherited.
+private func globalActorIsolation(
+  of funcDecl: FunctionDeclSyntax,
+  in context: some MacroExpansionContext
+) -> (attribute: String, enclosingTypeName: String?)? {
+  if let attribute = funcDecl.attributes.first(where: hasGlobalActorShape) {
+    return (attribute.trimmedDescription, nil)
+  }
+  if funcDecl.modifiers.contains(where: { $0.name.text == "nonisolated" }) {
+    return nil
+  }
+  guard let enclosing = context.lexicalContext.first,
+    let attribute = enclosing.asProtocol(WithAttributesSyntax.self)?.attributes.first(where: hasGlobalActorShape)
+  else {
+    return nil
+  }
+  return (attribute.trimmedDescription, enclosing.asProtocol(NamedDeclSyntax.self)?.name.text)
 }
 
 /// The fix-it offered alongside the synchronous-function diagnostic: insert `async` into the
@@ -144,7 +249,9 @@ private func diagnoseParameterSpecifiers(
           "A @JS parameter can't be '\(specifier)': its argument is a value decoded from JavaScript, which can't be written back or carry an isolation.",
           id: "js-parameter-specifier",
           severity: .error
-        )))
+        )
+      )
+    )
   }
 }
 
@@ -173,14 +280,16 @@ private func diagnoseFreeFormTypes(
     // A constructor decodes its arguments exactly like a function and has no return value.
     types = initDecl.signature.parameterClause.parameters.map { SpecifiedType($0.type).type }
   } else if let varDecl = declaration.as(VariableDeclSyntax.self),
-    let type = varDecl.bindings.first?.typeAnnotation?.type {
+    let type = varDecl.bindings.first?.typeAnnotation?.type
+  {
     types = [type]
   }
 
   for type in types
   where mentionsFreeFormAny(type) && !isConvertibleFreeFormType(type) && !containsFunctionType(type) {
     context.diagnose(
-      Diagnostic(node: type, message: unconvertibleFreeFormError(for: type.trimmedDescription)))
+      Diagnostic(node: type, message: unconvertibleFreeFormError(for: type.trimmedDescription))
+    )
   }
 }
 
@@ -234,61 +343,49 @@ private struct BoundaryMember {
 
 /// Reads the boundary member off a `@JS` declaration, splitting its types by conversion direction. A
 /// function contributes its parameter types (decodable) and its return type when non-Void (encodable);
-/// a property contributes its value type as encodable (the getter) and also as decodable when settable
-/// (the setter). Composed types (`[Int]`, `String?`, …) are kept verbatim, their conditional
-/// conformances transitively constraining the elements. A type that mentions `Any` is left out: it
-/// converts through the free-form methods, or is diagnosed by `diagnoseFreeFormTypes`. Returns `nil`
-/// for declaration kinds `@JS` doesn't read types from, a property whose type isn't spelled out (a
-/// syntactic macro can't recover it), or one whose type mentions `Any`.
+/// an initializer contributes its parameter types; a property contributes its value type as encodable
+/// (the getter) and also as decodable when settable (the setter). Composed types (`[Int]`, `String?`,
+/// …) are kept verbatim, their conditional conformances transitively constraining the elements. A type
+/// that mentions `Any` is left out: it converts through the free-form methods, or is diagnosed by
+/// `diagnoseFreeFormTypes`. Returns `nil` for declaration kinds `@JS` doesn't read types from, a
+/// property whose type isn't spelled out (a syntactic macro can't recover it), or one whose type
+/// mentions `Any`.
 private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> BoundaryMember? {
   if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
-    // 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 {
-      // The specifier isn't part of the asserted type, and a parameter with one the binding can't honor
-      // is reported by `diagnoseParameterSpecifiers` and not asserted.
-      let specified = SpecifiedType(parameter.type)
-      guard specified.unsupportedSpecifier == nil else {
-        continue
-      }
-      guard let closure = JSClosureType(specified.type) else {
-        if !containsFunctionType(specified.type) && !mentionsFreeFormAny(specified.type) {
-          decodableTypes.append(specified.type.trimmedDescription)
-        }
-        continue
-      }
-      // A closure type that mentions `Any` is reported by `diagnoseClosureTypes` instead.
-      for parameter in closure.parameters
-      where !containsFunctionType(parameter.type) && !mentionsFreeFormAny(parameter.type) {
-        callbackArgumentTypes.append(parameter.type.trimmedDescription)
-      }
-      let closureReturnType = closure.functionType.returnClause.type
-      if let returnType = closure.returnType,
-        !containsFunctionType(closureReturnType) && !mentionsFreeFormAny(closureReturnType) {
-        decodableTypes.append(returnType)
-      }
-    }
+    let argumentTypes = argumentBoundaryTypes(of: funcDecl.signature.parameterClause.parameters)
     let returnType = funcDecl.signature.returnClause?.type
     let encodableType = returnType.flatMap {
       isVoidType($0) || containsFunctionType($0) || mentionsFreeFormAny($0) ? nil : $0.trimmedDescription
     }
     return BoundaryMember(
       name: funcDecl.name.text,
-      decodableTypes: decodableTypes,
+      decodableTypes: argumentTypes.decodable,
       encodableType: encodableType,
-      callbackArgumentTypes: callbackArgumentTypes,
+      callbackArgumentTypes: argumentTypes.callbackArguments,
       isStatic: isTypeLevel(funcDecl.modifiers)
     )
   }
 
+  if let initDecl = declaration.as(InitializerDeclSyntax.self) {
+    // A constructor decodes its arguments like a function does, and the instance it returns isn't
+    // encoded. The name is escaped because it also names the assertion's nested helper, and `init` is
+    // a keyword.
+    let argumentTypes = argumentBoundaryTypes(of: initDecl.signature.parameterClause.parameters)
+    return BoundaryMember(
+      name: "`init`",
+      decodableTypes: argumentTypes.decodable,
+      encodableType: nil,
+      callbackArgumentTypes: argumentTypes.callbackArguments,
+      isStatic: false
+    )
+  }
+
   if let varDecl = declaration.as(VariableDeclSyntax.self),
     let binding = varDecl.bindings.first,
     let identifier = binding.pattern.as(IdentifierPatternSyntax.self),
     let type = binding.typeAnnotation?.type,
-    !containsFunctionType(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. A type that mentions `Any`
     // converts through the free-form methods instead, so it isn't asserted at all.
@@ -309,6 +406,45 @@ private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> Boundary
   return nil
 }
 
+/// The boundary types of a function's or constructor's arguments: an argument is decoded from JS, and
+/// a closure argument instead contributes its parameter types (encoded when native code calls it) and
+/// its return type (decoded).
+private func argumentBoundaryTypes(
+  of parameters: FunctionParameterListSyntax
+) -> (decodable: [String], callbackArguments: [String]) {
+  // 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 parameters {
+    // The specifier isn't part of the asserted type, and a parameter with one the binding can't honor
+    // is reported by `diagnoseParameterSpecifiers` and not asserted.
+    let specified = SpecifiedType(parameter.type)
+    guard specified.unsupportedSpecifier == nil else {
+      continue
+    }
+    guard let closure = JSClosureType(specified.type) else {
+      if !containsFunctionType(specified.type) && !mentionsFreeFormAny(specified.type) {
+        decodableTypes.append(specified.type.trimmedDescription)
+      }
+      continue
+    }
+    // A closure type that mentions `Any` is reported by `diagnoseClosureTypes` instead.
+    for parameter in closure.parameters
+    where !containsFunctionType(parameter.type) && !mentionsFreeFormAny(parameter.type) {
+      callbackArgumentTypes.append(parameter.type.trimmedDescription)
+    }
+    let closureReturnType = closure.functionType.returnClause.type
+    if let returnType = closure.returnType,
+      !containsFunctionType(closureReturnType) && !mentionsFreeFormAny(closureReturnType)
+    {
+      decodableTypes.append(returnType)
+    }
+  }
+  return (decodableTypes, callbackArgumentTypes)
+}
+
 /// True when a return clause is written as `Void` / `()` — nothing crosses the boundary, so it needs
 /// no conformance assertion. (A missing return clause never reaches here: `returnClause` is `nil`.)
 private func isVoidType(_ type: TypeSyntax) -> Bool {

package/apple/Sources/ExpoModulesMacros/JSNameCollisions.swift

@@ -13,9 +13,7 @@ internal func diagnoseJSNameCollisions(
   // 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(jsName: $0.jsName, kind: "function", nameToken: $0.nameToken) }
-    + properties.map { BoundMember(jsName: $0.jsName, kind: "property", nameToken: $0.nameToken) }
+  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 }) {
@@ -23,25 +21,47 @@ internal func diagnoseJSNameCollisions(
       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 @JS \(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 @JS(\"...\")."
+          "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"))
+            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 {