expo-modules-macros 0.21.0 → 0.23.0

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.
@@ -144,6 +270,12 @@ internal func isTypeLevel(_ modifiers: DeclModifierListSyntax) -> Bool {
   }
 }
 
+/// True for a `lazy` property. A lazy `@JS` property is read-only from JS: its getter stores the
+/// first value as a data property on the JS object, which a setter couldn't write through.
+internal func isLazy(_ modifiers: DeclModifierListSyntax) -> Bool {
+  return modifiers.contains { $0.name.tokenKind == .keyword(.lazy) }
+}
+
 /// 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.
@@ -158,26 +290,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 +318,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 +335,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 +350,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 +362,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 +380,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 +390,7 @@ internal func shouldStampJavaScriptActor(
   on member: DeclSyntaxProtocol,
   enclosedBy enclosing: some DeclGroupSyntax
 ) -> Bool {
-  if isConcurrentJSMember(member) {
+  if isConcurrentJSMember(member) || hasAsyncVariant(member) {
     return false
   }
 
@@ -312,7 +437,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 +470,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
       }
     }
@@ -425,6 +551,7 @@ internal func collectProperties(
   let jsNameOverride = jsNameArgument(of: attribute)
   // A `let` is never settable; only `var` bindings can carry a setter.
   let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
+  let isLazy = isLazy(varDecl.modifiers)
 
   return varDecl.bindings.compactMap { binding in
     guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
@@ -433,7 +560,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 +569,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 && !isLazy && bindingIsSettable(binding),
+      isLazy: isLazy,
       nameToken: ident.identifier
     )
   }