expo-modules-macros 0.0.1 → 0.15.0

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -0,0 +1,162 @@
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/**
+ Member macro applied to a `SharedObject` subclass. Scans the class body for
+ declarations marked with `@JS` and synthesizes `_synthesizedClassDefinition()`,
+ 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
+
+    // `@JS func`s/`var`s and the `@JS init` are bound directly into the shared object's JS object by
+    // the synthesized `_decorateSharedObject(prototype:)` / `_decorateSharedObject(constructor:)` / `_constructSharedObject`
+    // rather than described with a `Function(...)` / `Property(...)` / `Constructor { … }` DSL entry, so
+    // they're collected here instead of appended to the `Class` block. The block keeps only non-`@JS`
+    // definitions (none are collected today), so it's empty when every member is `@JS`.
+    //
+    // Members split by the `static`/`class` modifier onto two different JS objects: instance members
+    // decorate the prototype (receiver recovered from JS `this`), static members decorate the
+    // constructor (called on the metatype). A JS instance and static member may share a name without
+    // colliding: they live on different objects.
+    let entries: [String] = []
+    var instanceFunctions: [JSFunction] = []
+    var instanceProperties: [JSProperty] = []
+    var staticFunctions: [JSFunction] = []
+    var staticProperties: [JSProperty] = []
+    var constructor: JSConstructor?
+
+    for member in classDecl.memberBlock.members {
+      let decl = member.decl
+
+      if let initDecl = decl.as(InitializerDeclSyntax.self),
+        initDecl.attributes.firstAttribute(named: "JS") != nil {
+        if constructor != nil {
+          throw MacroExpansionErrorMessage(
+            "@SharedObject classes can have at most one @JS initializer; JavaScript classes have a single constructor.")
+        }
+        constructor = JSConstructor(initDecl: initDecl)
+        continue
+      }
+
+      if let funcDecl = decl.as(FunctionDeclSyntax.self),
+        let attribute = funcDecl.attributes.firstAttribute(named: "JS") {
+        let function = JSFunction(funcDecl: funcDecl, attribute: attribute)
+        if isTypeLevel(funcDecl.modifiers) {
+          staticFunctions.append(function)
+        } else {
+          instanceFunctions.append(function)
+        }
+        continue
+      }
+
+      if let varDecl = decl.as(VariableDeclSyntax.self),
+        let attribute = varDecl.attributes.firstAttribute(named: "JS") {
+        let collected = collectProperties(varDecl: varDecl, attribute: attribute)
+        if isTypeLevel(varDecl.modifiers) {
+          staticProperties.append(contentsOf: collected)
+        } else {
+          instanceProperties.append(contentsOf: collected)
+        }
+      }
+    }
+
+    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  }"
+
+    var emitted: [DeclSyntax] = [
+      """
+      public static func _synthesizedClassDefinition() -> ClassDefinition {
+      \(raw: body)
+      }
+      """
+    ]
+
+    // Direct JSI binding, split by which JS object each member decorates:
+    // `_decorateSharedObject(prototype:)` binds instance `@JS func`/`var`s (unwrapping the per-call receiver from
+    // `this`); `_decorateSharedObject(constructor:)` binds `static`/`class` ones (called on the metatype); and
+    // `_constructSharedObject` builds an instance from the `@JS init` arguments. Each is emitted only
+    // when it has something to bind.
+    if !instanceFunctions.isEmpty || !instanceProperties.isEmpty {
+      emitted.append(
+        buildDecorateSharedObjectPhase(
+          phase: .prototype, functions: instanceFunctions, properties: instanceProperties,
+          typeName: typeName))
+    }
+    if !staticFunctions.isEmpty || !staticProperties.isEmpty {
+      emitted.append(
+        buildDecorateSharedObjectPhase(
+          phase: .constructor, functions: staticFunctions, properties: staticProperties,
+          typeName: typeName))
+    }
+    if let constructor {
+      emitted.append(constructor.buildConstructor(typeName: typeName))
+    }
+
+    return emitted
+  }
+}
+
+extension SharedObjectMacro: MemberAttributeMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    attachedTo declaration: some DeclGroupSyntax,
+    providingAttributesFor member: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [AttributeSyntax] {
+    // `@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) else {
+      return []
+    }
+    // `@JS(.concurrent)` opts the member out of the JS-thread stamp and onto the concurrent pool.
+    if isConcurrentJSMember(member) {
+      return ["@concurrent"]
+    }
+    guard shouldStampJavaScriptActor(on: member, enclosedBy: declaration) else {
+      return []
+    }
+    return ["@JavaScriptActor"]
+  }
+}
+
+// MARK: - Inheritance check
+
+private func inheritsFromSharedObject(_ classDecl: ClassDeclSyntax) -> Bool {
+  return inheritsFromAny(classDecl, names: ["SharedObject"])
+}

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -0,0 +1,190 @@
+import SwiftSyntax
+
+/// The protocol that every type crossing the JS boundary must conform to. Centralized here so the
+/// eventual rename (this is a placeholder name) is a single edit, and shared by the macros whose
+/// generated conversions go through the dynamic-type API (`@Record`, `@Event`).
+internal let jsConvertibleProtocolName = "AnyArgument"
+
+/// The constraint a `@JS` boundary type must satisfy, by direction: an argument (and a settable
+/// property's incoming value) is decoded, so it must be `JavaScriptDecodable`; a return value (and a
+/// property's outgoing value) is encoded, so it must be `JavaScriptEncodable`. Asserting each
+/// direction on its own keeps a decode-only or encode-only type from being over-constrained, and
+/// surfaces a missing conformance as a clear "requires that '…' conform to …" diagnostic on the
+/// member instead of an opaque error inside the generated closure.
+internal let javaScriptDecodableProtocolName = "JavaScriptDecodable"
+internal let javaScriptEncodableProtocolName = "JavaScriptEncodable"
+
+/// The constraint a `@Record` property type must satisfy: it must be both `AnyArgument` (the
+/// `from(dictionary:)` / `toDictionary(appContext:)` paths still convert native `Any` through the
+/// dynamic-type API) and `JavaScriptDecodable & JavaScriptEncodable` (the `from(object:)` /
+/// `toObject(appContext:)` paths convert JS values through `decode`/`encode`). A record field has to
+/// support both directions, so the assertion requires the intersection.
+///
+/// The exception is a property whose type mentions `Any` (`[String: Any]?`, `[Any]`, …): it can't
+/// conform to the JS codable protocols, so the JS-value paths convert it through the `JavaScriptValue`
+/// free-form methods, and it's asserted against `jsConvertibleProtocolName` alone for the dictionary
+/// paths.
+internal let recordFieldProtocolName = "AnyArgument & JavaScriptDecodable & JavaScriptEncodable"
+
+/// The constraint a `@Union` case payload type must satisfy: the union decodes by trying each payload's
+/// `decode` and encodes through the matching payload's `encode`, so every alternative must convert in
+/// both directions. Unlike a `@Record` field, a union never crosses the native-`Any` dictionary path, so
+/// `AnyArgument` is not required.
+internal let unionPayloadProtocolName = "JavaScriptDecodable & JavaScriptEncodable"
+
+/// 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: the JS primitives. Asserting
+/// them would only add noise to the expansion.
+private let knownConformingPrimitives: Set<String> = ["Bool", "Int", "Double", "String"]
+
+/// One member's worth of conformance assertion: a name (the member it stands for) and the declared
+/// types crossing the JS boundary for it. The name surfaces verbatim in the compiler's conformance
+/// diagnostic ("local function '<name>' requires that '<Type>' conform to …"), so it identifies the
+/// offending member in the error message on top of the location pointing at the user's declaration.
+internal struct ConformanceAssertion {
+  let name: String
+  /// Declared types as written. Composed types (`[Int]`, `String?`, …) are kept verbatim — their
+  /// conditional conformances transitively constrain the elements.
+  let types: [String]
+  /// The constraint for this member's types, overriding the one passed to `typeConformanceAssertions`.
+  /// `@Record` uses it to assert only `AnyArgument` for a property that mentions `Any`, which can't be
+  /// `JavaScriptDecodable & JavaScriptEncodable`.
+  var constraint: String? = nil
+}
+
+/// A directional conformance-assertion peer for a `@JS` member: a never-called `private func` whose
+/// body asserts each argument type is `JavaScriptDecodable` and the return/getter type is
+/// `JavaScriptEncodable`, matching how the generated binding converts each (decode on the way in,
+/// encode on the way out). The check is a single member-named nested helper with one `A0…` generic
+/// parameter per non-primitive argument and a single `Return` parameter for the value, called once with
+/// every type's metatype; naming the helper after the member puts the member in the compiler's
+/// diagnostic, and the per-slot constraint reports the offending type against the protocol for *its*
+/// direction.
+///
+/// `decodableTypes` are the argument types (and a settable property's value type); `encodableType` is
+/// the single return type (or a property's value type on read), or `nil` when there's none. Primitives
+/// are dropped from each; when nothing is left in either, returns `nil` so the caller emits no peer.
+/// `isStatic` mirrors a `static`/`class` member so the peer sits in the right metatype context.
+internal func directionalConformanceAssertion(
+  name: String,
+  decodableTypes: [String],
+  encodableType: String?,
+  isStatic: Bool
+) -> DeclSyntax? {
+  let decodables = distinctAssertableTypes(decodableTypes)
+  let encodable = encodableType.flatMap(assertableBoundaryType)
+  guard !decodables.isEmpty || encodable != nil else {
+    return nil
+  }
+
+  // Build the generic parameter list and the matching call arguments in lockstep: one `A0…` slot
+  // constrained `JavaScriptDecodable` per argument, and a single `Return` slot constrained
+  // `JavaScriptEncodable` for the return/getter value (there's only ever one, so it isn't indexed).
+  var parameters: [String] = []
+  var typeParameters: [String] = []
+  var arguments: [String] = []
+  for (index, type) in decodables.enumerated() {
+    parameters.append("A\(index): \(javaScriptDecodableProtocolName)")
+    typeParameters.append("_: A\(index).Type")
+    arguments.append("\(type).self")
+  }
+  if let encodable {
+    parameters.append("Return: \(javaScriptEncodableProtocolName)")
+    typeParameters.append("_: Return.Type")
+    arguments.append("\(encodable).self")
+  }
+
+  let helper = "func \(name)<\(parameters.joined(separator: ", "))>(\(typeParameters.joined(separator: ", "))) {}"
+  let call = "\(name)(\(arguments.joined(separator: ", ")))"
+  let staticKeyword = isStatic ? "static " : ""
+  return """
+    private \(raw: staticKeyword)func _assertTypesConformance_\(raw: name)() {
+    \(raw: helper)
+    \(raw: call)
+    }
+    """
+}
+
+/// One conformance-assertion peer covering several members' assertions at once — used by `@Record`,
+/// which folds every property into a single `_assertTypesConformance()` rather than emitting a peer
+/// per property. Each assertion keeps its own named nested helper, so the per-member naming in the
+/// diagnostic is preserved even though they share one peer.
+///
+/// Returns `nil` when no assertion has anything left to verify (all primitives / empty), so the
+/// caller emits nothing.
+internal func typeConformanceAssertions(
+  for assertions: [ConformanceAssertion],
+  constraint: String = jsConvertibleProtocolName
+) -> DeclSyntax? {
+  let bodies = assertions.compactMap { conformanceAssertionBody($0, constraint: $0.constraint ?? constraint) }
+  guard !bodies.isEmpty else {
+    return nil
+  }
+  return """
+    private func _assertTypesConformance() {
+    \(raw: bodies.joined(separator: "\n"))
+    }
+    """
+}
+
+/// The type to assert for a boundary type as written, or `nil` when nothing needs asserting: an
+/// exactly-free-form type (handled by the binding's `decodeAny…` reroute) and a known-conforming
+/// primitive both return `nil`; everything else is unwrapped of trailing optionals and asserted. An
+/// *optional* free-form (`[String: Any]?`) isn't rerouted and doesn't conform, so it's kept and
+/// asserted for a clean diagnostic. Shared with `@Event`.
+internal func assertableBoundaryType(_ type: String) -> String? {
+  guard !isFreeFormBoundaryType(type) else {
+    return nil
+  }
+  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
+/// puts the member's name in the compiler's conformance diagnostic. Returns `nil` when every type was
+/// a known-conforming primitive or the list was empty.
+private func conformanceAssertionBody(
+  _ assertion: ConformanceAssertion,
+  constraint: String = jsConvertibleProtocolName
+) -> String? {
+  let distinct = distinctAssertableTypes(assertion.types)
+  guard !distinct.isEmpty else {
+    return nil
+  }
+
+  var lines = ["func \(assertion.name)<T: \(constraint)>(_: T.Type) {}"]
+  lines.append(contentsOf: distinct.map { "\(assertion.name)(\($0).self)" })
+  return lines.joined(separator: "\n")
+}
+
+/// The distinct types to assert from a list, mapping each through `assertableBoundaryType` (which
+/// drops what needs no assertion) and deduping in first-seen order.
+private func distinctAssertableTypes(_ types: [String]) -> [String] {
+  var seen: Set<String> = []
+  var distinct: [String] = []
+  for type in types.compactMap(assertableBoundaryType) where seen.insert(type).inserted {
+    distinct.append(type)
+  }
+  return distinct
+}
+
+/// Strips every trailing optional marker (`?`/`!`) so the assertion targets the core wrapped type.
+/// `Optional<W>: AnyArgument` holds exactly when `W: AnyArgument` (and `T!` is just `T?`), so each
+/// layer is conformance-equivalent to its wrapped type. Asserting the core gives a cleaner diagnostic
+/// (the direct `requires that '<type>' conform`, not the conditional-conformance phrasing through
+/// `Optional`) and sidesteps that `T!.self` is invalid in metatype position. Only *trailing* markers
+/// are stripped, so `[Int?]` keeps its inner `?`; a longhand `Optional<W>` isn't peeled but is still
+/// asserted whole, which remains correct.
+private func unwrappedOptional(_ type: String) -> String {
+  var result = Substring(type)
+  while result.hasSuffix("?") || result.hasSuffix("!") {
+    result = result.dropLast()
+  }
+  return String(result)
+}