@expo/expo-modules-macros-plugin 0.0.8 → 0.0.9

package/apple/Package.swift

@@ -25,6 +25,7 @@ let package = Package(
       dependencies: [
         "ExpoModulesMacros",
         .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),
+        .product(name: "SwiftSyntaxMacrosGenericTestSupport", package: "swift-syntax"),
       ]
     ),
   ]

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -0,0 +1,95 @@
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/**
+ Member macro applied to a `Module` subclass. Scans the class body for declarations
+ marked with `@JS` and synthesizes a framework-internal `_exposedDefinition()`
+ method returning `[AnyDefinition]`. `expo-modules-core` calls it automatically
+ and merges the result into the module's definition.
+
+   @ExpoModule
+   public final class MyModule: Module {
+     public func definition() -> ModuleDefinition {
+       Name("MyModule")
+     }
+
+     @JS
+     func greet(name: String) -> String { "Hi, \(name)" }
+   }
+ */
+public struct ExpoModuleMacro: MemberMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingMembersOf declaration: some DeclGroupSyntax,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    guard let classDecl = declaration.as(ClassDeclSyntax.self) else {
+      throw MacroExpansionErrorMessage("@ExpoModule can only be applied to a class")
+    }
+
+    let moduleName = jsNameArgument(of: node) ?? classDecl.name.text
+    var entries: [String] = ["Name(\"\(moduleName)\")"]
+
+    for typeName in classListArgument(of: node, label: "classes") {
+      entries.append("\(typeName)._exposedClassDefinition()")
+    }
+
+    for member in classDecl.memberBlock.members {
+      let decl = member.decl
+
+      if let funcDecl = decl.as(FunctionDeclSyntax.self),
+        let attribute = funcDecl.attributes.firstAttribute(named: "JS") {
+        entries.append(buildFunctionEntry(funcDecl: funcDecl, attribute: attribute))
+        continue
+      }
+
+      if let varDecl = decl.as(VariableDeclSyntax.self),
+        let attribute = varDecl.attributes.firstAttribute(named: "JS") {
+        entries.append(contentsOf: buildPropertyEntries(varDecl: varDecl, attribute: attribute))
+      }
+    }
+
+    let lines = entries.map { "    \($0)" }.joined(separator: ",\n")
+    let body = "  return [\n\(lines)\n  ]"
+
+    let method: DeclSyntax = """
+      public func _exposedDefinition() -> [AnyDefinition] {
+      \(raw: body)
+      }
+      """
+
+    return [method]
+  }
+}
+
+// MARK: - Member builders
+
+private func buildFunctionEntry(
+  funcDecl: FunctionDeclSyntax,
+  attribute: AttributeSyntax
+) -> String {
+  let swiftName = funcDecl.name.text
+  let jsName = jsNameArgument(of: attribute) ?? swiftName
+  let isAsync = funcDecl.signature.effectSpecifiers?.asyncSpecifier != nil
+  let dslEntry = isAsync ? "AsyncFunction" : "Function"
+  return "\(dslEntry)(\"\(jsName)\", \(swiftName))"
+}
+
+private func buildPropertyEntries(
+  varDecl: VariableDeclSyntax,
+  attribute: AttributeSyntax
+) -> [String] {
+  let jsNameOverride = jsNameArgument(of: attribute)
+
+  return varDecl.bindings.compactMap { binding in
+    guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
+      return nil
+    }
+    let swiftName = ident.identifier.text
+    let jsName = jsNameOverride ?? swiftName
+    return "Property(\"\(jsName)\") { self.\(swiftName) }"
+  }
+}
+

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -0,0 +1,29 @@
+import SwiftSyntax
+import SwiftSyntaxMacros
+
+/**
+ Marker macro applied to module / shared-object members that should be exposed to JavaScript.
+ Expands to nothing on its own; `@ExpoModule` and `@SharedObject` discover declarations
+ carrying this attribute and generate the corresponding `Function` / `AsyncFunction` /
+ `Property` / `Constructor` registrations.
+
+ Usage:
+
+   @JS
+   func greet(name: String) -> String { ... }
+
+   @JS("doWork")
+   func performWork() async throws { ... }
+
+   @JS
+   var status: String { "ok" }
+ */
+public struct JSMacro: PeerMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingPeersOf declaration: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    return []
+  }
+}

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -0,0 +1,52 @@
+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.
+ */
+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 {
+    return nil
+  }
+  return segment.content.text
+}
+
+/**
+ 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 []
+  }
+  for arg in args where arg.label?.text == label {
+    guard let array = arg.expression.as(ArrayExprSyntax.self) else {
+      return []
+    }
+    return array.elements.compactMap { element -> String? in
+      guard let memberAccess = element.expression.as(MemberAccessExprSyntax.self),
+        memberAccess.declName.baseName.text == "self",
+        let base = memberAccess.base?.as(DeclReferenceExprSyntax.self) else {
+        return nil
+      }
+      return base.baseName.text
+    }
+  }
+  return []
+}
+
+extension AttributeListSyntax {
+  internal func firstAttribute(named name: String) -> AttributeSyntax? {
+    for element in self {
+      if let attr = element.as(AttributeSyntax.self),
+        attr.attributeName.trimmedDescription == name {
+        return attr
+      }
+    }
+    return nil
+  }
+}

package/apple/Sources/ExpoModulesMacros/Plugin.swift

@@ -5,5 +5,9 @@ import SwiftSyntaxMacros
 struct ExpoModulesMacrosPlugin: CompilerPlugin {
   let providingMacros: [Macro.Type] = [
     OptimizedFunctionAttachedMacro.self,
+    JSMacro.self,
+    ExpoModuleMacro.self,
+    SharedObjectMacro.self,
+    RecordMacro.self,
   ]
 }

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -0,0 +1,234 @@
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/**
+ Member macro applied to a `Record` type. Scans the body for `@Field`-annotated
+ stored properties and synthesizes `_recordFields(of:)`, returning each field
+ paired with its compile-time key. This replaces the runtime `Mirror` walk in
+ `fieldsOf(_:)` and lets the framework drop the lazy keying that today protects
+ the field's options with a `Mutex`.
+
+   @Record
+   struct Options: Record {
+     @Field var name: String = ""
+     @Field(.required) var count: Int = 0
+     @Field(.keyed("custom_key")) var flag: Bool = false
+   }
+
+ Expansion:
+
+   public static func _recordFields(of instance: Self) -> [RecordFieldDescriptor] {
+     var fields: [RecordFieldDescriptor] = []
+     fields.append(RecordFieldDescriptor(key: "name",       isRequired: false, field: instance._name))
+     fields.append(RecordFieldDescriptor(key: "count",      isRequired: true,  field: instance._count))
+     fields.append(RecordFieldDescriptor(key: "custom_key", isRequired: false, field: instance._flag))
+     return fields
+   }
+
+ `isRequired` is computed from the `@Field` attribute arguments at compile time so the
+ framework can avoid a `Mutex.withLock` per field per call.
+
+ For classes that inherit from another `@Record`-annotated class, the macro
+ prepends `super._recordFields(of: instance)` so inherited fields appear first.
+ */
+public struct RecordMacro: MemberMacro, ExtensionMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingMembersOf declaration: some DeclGroupSyntax,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    let isClass = declaration.is(ClassDeclSyntax.self)
+    guard declaration.is(StructDeclSyntax.self) || isClass else {
+      throw MacroExpansionErrorMessage("@Record can only be applied to a struct or class")
+    }
+
+    var entries: [(propertyName: String, key: String, isRequired: Bool)] = []
+
+    for member in declaration.memberBlock.members {
+      guard let varDecl = member.decl.as(VariableDeclSyntax.self),
+        let attribute = varDecl.attributes.firstAttribute(named: "Field") else {
+        continue
+      }
+      for binding in varDecl.bindings {
+        guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
+          continue
+        }
+        let propertyName = ident.identifier.text
+        let key = explicitKeyArgument(of: attribute) ?? propertyName
+        let isRequired = hasRequiredArgument(of: attribute)
+        entries.append((propertyName, key, isRequired))
+      }
+    }
+
+    let inheritsRecord = isClass && classHasInheritance(declaration)
+    let overrideKeyword = inheritsRecord ? "override " : ""
+
+    var lines: [String] = []
+    if inheritsRecord {
+      lines.append("  var fields: [RecordFieldDescriptor] = super._recordFields(of: instance)")
+    } else {
+      lines.append("  var fields: [RecordFieldDescriptor] = []")
+    }
+    for entry in entries {
+      let requiredLiteral = entry.isRequired ? "true" : "false"
+      lines.append("  fields.append(RecordFieldDescriptor(key: \"\(entry.key)\", isRequired: \(requiredLiteral), field: instance._\(entry.propertyName)))")
+    }
+    lines.append("  return fields")
+
+    let body = lines.joined(separator: "\n")
+
+    let method: DeclSyntax = """
+      public \(raw: overrideKeyword)class func _recordFields(of instance: Self) -> [RecordFieldDescriptor] {
+      \(raw: body)
+      }
+      """
+
+    let staticMethod: DeclSyntax = """
+      public static func _recordFields(of instance: Self) -> [RecordFieldDescriptor] {
+      \(raw: body)
+      }
+      """
+
+    return [isClass ? method : staticMethod]
+  }
+
+  /**
+   Adds `Record` and `_RecordFieldsProvider` conformances. Each is only added when the type
+   doesn't already declare it — Swift rejects redundant conformances, so the macro must check
+   the inheritance clause syntactically.
+
+   For class subclasses (which inherit conformance from a `@Record`-annotated parent), no
+   extension is emitted at all. The user can write either `@Record struct Options { ... }`
+   or `@Record struct Options: Record { ... }`; both work.
+   */
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingExtensionsOf type: some TypeSyntaxProtocol,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [ExtensionDeclSyntax] {
+    if declaration.is(ClassDeclSyntax.self) && classHasInheritance(declaration) {
+      return []
+    }
+    guard declaration.is(StructDeclSyntax.self) || declaration.is(ClassDeclSyntax.self) else {
+      return []
+    }
+
+    var conformances: [String] = []
+    if !inheritsProtocol(named: "Record", in: declaration) {
+      conformances.append("Record")
+    }
+    if !inheritsProtocol(named: "_RecordFieldsProvider", in: declaration) {
+      conformances.append("_RecordFieldsProvider")
+    }
+    if conformances.isEmpty {
+      return []
+    }
+
+    let ext: DeclSyntax = """
+      extension \(type.trimmed): \(raw: conformances.joined(separator: ", ")) {}
+      """
+    guard let extDecl = ext.as(ExtensionDeclSyntax.self) else {
+      return []
+    }
+    return [extDecl]
+  }
+}
+
+/**
+ 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`). Typealiases can't be resolved syntactically, so a
+ user who refers to `Record` via a typealias will get a redundant-conformance error from
+ the macro-emitted extension and should drop the alias for the inheritance clause.
+ */
+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 `_recordFields(of:)`.
+ The macro emits an `override` in this case; if the superclass is not a `Record`,
+ the user gets a clear compiler error pointing at the missing override target.
+ */
+private func classHasInheritance(_ declaration: some DeclGroupSyntax) -> Bool {
+  guard let classDecl = declaration.as(ClassDeclSyntax.self),
+    let inherited = classDecl.inheritanceClause?.inheritedTypes,
+    !inherited.isEmpty else {
+    return false
+  }
+  return true
+}
+
+/**
+ True if the `@Field` attribute has `.required` as one of its arguments. The check is purely
+ syntactic — it matches the literal member-access expression `.required`. Variants like
+ `FieldOption.required` or aliased identifiers won't be detected; the framework still falls
+ back to the field's runtime `isRequired` for correctness in those cases (see `Record.swift`).
+ */
+private func hasRequiredArgument(of attribute: AttributeSyntax) -> Bool {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return false
+  }
+  for arg in args {
+    if let member = arg.expression.as(MemberAccessExprSyntax.self),
+      member.declName.baseName.text == "required" {
+      return true
+    }
+  }
+  return false
+}
+
+/**
+ Extracts the dictionary key from a `@Field` attribute. Recognizes both forms:
+ a bare string literal (`@Field("custom_key")`, relying on
+ `FieldOption: ExpressibleByStringLiteral`) and the explicit factory call
+ (`@Field(.keyed("custom_key"))`). Returns nil if neither is present; other
+ `FieldOption` cases (`.required`, etc.) are ignored.
+ */
+private func explicitKeyArgument(of attribute: AttributeSyntax) -> String? {
+  guard let args = attribute.arguments?.as(LabeledExprListSyntax.self) else {
+    return nil
+  }
+  for arg in args {
+    if let str = arg.expression.as(StringLiteralExprSyntax.self),
+      let segment = str.segments.first?.as(StringSegmentSyntax.self) {
+      return segment.content.text
+    }
+    if let call = arg.expression.as(FunctionCallExprSyntax.self),
+      let member = call.calledExpression.as(MemberAccessExprSyntax.self),
+      member.declName.baseName.text == "keyed",
+      let firstArg = call.arguments.first,
+      let str = firstArg.expression.as(StringLiteralExprSyntax.self),
+      let segment = str.segments.first?.as(StringSegmentSyntax.self) {
+      return segment.content.text
+    }
+  }
+  return nil
+}

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -0,0 +1,191 @@
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/**
+ Member macro applied to a `SharedObject` subclass. Scans the class body for
+ declarations marked with `@JS` and synthesizes `_exposedClassDefinition()`,
+ returning a `ClassDefinition` ready to drop into a module's `Class { ... }` slot.
+
+   @SharedObject
+   final class Cache: SharedObject {
+     @JS
+     init(name: String) { self.name = name }
+
+     @JS
+     func get(_ key: String) -> String? { ... }
+
+     @JS
+     var size: Int { 42 }
+   }
+
+ The companion `@ExpoModule(classes: [Cache.self])` wires the resulting
+ definition into the module's exposed surface.
+ */
+public struct SharedObjectMacro: MemberMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingMembersOf declaration: some DeclGroupSyntax,
+    conformingTo protocols: [TypeSyntax],
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    guard let classDecl = declaration.as(ClassDeclSyntax.self) else {
+      throw MacroExpansionErrorMessage("@SharedObject can only be applied to a class")
+    }
+
+    guard inheritsFromSharedObject(classDecl) else {
+      throw MacroExpansionErrorMessage(
+        "@SharedObject class must inherit from SharedObject. Add `: SharedObject` to the class declaration.")
+    }
+
+    let typeName = classDecl.name.text
+    let jsName = jsNameArgument(of: node) ?? typeName
+
+    var entries: [String] = []
+    var sawConstructor = false
+
+    for member in classDecl.memberBlock.members {
+      let decl = member.decl
+
+      if let initDecl = decl.as(InitializerDeclSyntax.self),
+        initDecl.attributes.firstAttribute(named: "JS") != nil {
+        if sawConstructor {
+          throw MacroExpansionErrorMessage(
+            "@SharedObject classes can have at most one @JS initializer; JavaScript classes have a single constructor.")
+        }
+        sawConstructor = true
+        entries.append(buildConstructorEntry(initDecl: initDecl, typeName: typeName))
+        continue
+      }
+
+      if let funcDecl = decl.as(FunctionDeclSyntax.self),
+        let attribute = funcDecl.attributes.firstAttribute(named: "JS") {
+        entries.append(
+          buildClassFunctionEntry(funcDecl: funcDecl, attribute: attribute, typeName: typeName))
+        continue
+      }
+
+      if let varDecl = decl.as(VariableDeclSyntax.self),
+        let attribute = varDecl.attributes.firstAttribute(named: "JS") {
+        entries.append(
+          contentsOf: buildClassPropertyEntries(
+            varDecl: varDecl, attribute: attribute, typeName: typeName))
+      }
+    }
+
+    let lines = entries.map { "    \($0)" }.joined(separator: "\n")
+    let body = entries.isEmpty
+      ? "  return Class(\"\(jsName)\", \(typeName).self) {\n  }"
+      : "  return Class(\"\(jsName)\", \(typeName).self) {\n\(lines)\n  }"
+
+    let method: DeclSyntax = """
+      public static func _exposedClassDefinition() -> ClassDefinition {
+      \(raw: body)
+      }
+      """
+
+    return [method]
+  }
+}
+
+// MARK: - Inheritance check
+
+private func inheritsFromSharedObject(_ classDecl: ClassDeclSyntax) -> Bool {
+  guard let inherited = classDecl.inheritanceClause?.inheritedTypes else {
+    return false
+  }
+  for entry in inherited {
+    if baseIdentifier(of: entry.type) == "SharedObject" {
+      return true
+    }
+  }
+  return false
+}
+
+private func baseIdentifier(of type: TypeSyntax) -> String? {
+  if let identifier = type.as(IdentifierTypeSyntax.self) {
+    return identifier.name.text
+  }
+  if let member = type.as(MemberTypeSyntax.self) {
+    return member.name.text
+  }
+  return nil
+}
+
+// MARK: - Class-scope entry builders
+
+private func buildClassFunctionEntry(
+  funcDecl: FunctionDeclSyntax,
+  attribute: AttributeSyntax,
+  typeName: String
+) -> String {
+  let swiftName = funcDecl.name.text
+  let jsName = jsNameArgument(of: attribute) ?? swiftName
+  let effects = funcDecl.signature.effectSpecifiers
+  let isAsync = effects?.asyncSpecifier != nil
+  let isThrowing = effects?.throwsClause?.throwsSpecifier != nil
+  let dslEntry = isAsync ? "AsyncFunction" : "Function"
+
+  let params = funcDecl.signature.parameterClause.parameters
+  let closureParamList: String
+  let callArgList: String
+  if params.isEmpty {
+    closureParamList = "(this: \(typeName))"
+    callArgList = ""
+  } else {
+    let typedParams = params.enumerated().map { index, param in
+      "_ arg\(index): \(param.type.trimmedDescription)"
+    }.joined(separator: ", ")
+    closureParamList = "(this: \(typeName), \(typedParams))"
+
+    callArgList = params.enumerated().map { index, param in
+      let label = param.firstName.text
+      return label == "_" ? "arg\(index)" : "\(label): arg\(index)"
+    }.joined(separator: ", ")
+  }
+
+  let awaitKeyword = isAsync ? "await " : ""
+  let tryKeyword = (isAsync || isThrowing) ? "try " : ""
+  let callExpr = "\(tryKeyword)\(awaitKeyword)this.\(swiftName)(\(callArgList))"
+
+  return "\(dslEntry)(\"\(jsName)\") { \(closureParamList) in \(callExpr) }"
+}
+
+private func buildClassPropertyEntries(
+  varDecl: VariableDeclSyntax,
+  attribute: AttributeSyntax,
+  typeName: String
+) -> [String] {
+  let jsNameOverride = jsNameArgument(of: attribute)
+
+  return varDecl.bindings.compactMap { binding in
+    guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
+      return nil
+    }
+    let swiftName = ident.identifier.text
+    let jsName = jsNameOverride ?? swiftName
+    return "Property(\"\(jsName)\") { (this: \(typeName)) in this.\(swiftName) }"
+  }
+}
+
+private func buildConstructorEntry(
+  initDecl: InitializerDeclSyntax,
+  typeName: String
+) -> String {
+  let params = initDecl.signature.parameterClause.parameters
+
+  if params.isEmpty {
+    return "Constructor { \(typeName)() }"
+  }
+
+  let argList = params.enumerated().map { index, param in
+    "_ arg\(index): \(param.type.trimmedDescription)"
+  }.joined(separator: ", ")
+
+  let callArgs = params.enumerated().map { index, param in
+    let label = param.firstName.text
+    return label == "_" ? "arg\(index)" : "\(label): arg\(index)"
+  }.joined(separator: ", ")
+
+  return "Constructor { (\(argList)) in \(typeName)(\(callArgs)) }"
+}

package/package.json

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