expo-modules-macros 0.0.1 → 0.15.0

package/apple/Sources/ExpoModulesMacros/ExpoModulesOptimizedMacro.swift

@@ -0,0 +1,117 @@
+import Foundation
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+// MARK: - ExpoModulesOptimizedMacro
+
+/// Implementation of the `@OptimizedFunction` attached macro.
+/// Generates a peer function that returns `OptimizedFunctionDescriptor` for use with
+/// the `Function("name", descriptor)` or `AsyncFunction("name", descriptor)` overload.
+///
+/// Usage:
+///
+///     @OptimizedFunction
+///     private func addNumbers(a: Double, b: Double) -> Double {
+///         return a + b
+///     }
+///
+/// generates a peer function:
+///
+///     private func addNumbers() -> OptimizedFunctionDescriptor {
+///         return OptimizedSyncFunctionDefinition.createDescriptor(
+///             typeEncoding: "d@?dd",
+///             argsCount: 2,
+///             block: (addNumbers as @convention(block) (Double, Double) -> Double) as AnyObject
+///         )
+///     }
+///
+/// Then use in definition(): `Function("addNumbers", addNumbers())`
+public struct OptimizedFunctionAttachedMacro: PeerMacro {
+  public static func expansion(
+    of node: AttributeSyntax,
+    providingPeersOf declaration: some DeclSyntaxProtocol,
+    in context: some MacroExpansionContext
+  ) throws -> [DeclSyntax] {
+    guard let funcDecl = declaration.as(FunctionDeclSyntax.self) else {
+      throw MacroExpansionErrorMessage(
+        "@OptimizedFunction can only be attached to function declarations")
+    }
+
+    let functionName = funcDecl.name.text
+
+    var paramTypes: [String] = []
+    for param in funcDecl.signature.parameterClause.parameters {
+      paramTypes.append(param.type.trimmedDescription)
+    }
+
+    let returnType = funcDecl.signature.returnClause?.type.trimmedDescription ?? "Void"
+    let functionThrows = funcDecl.signature.effectSpecifiers?.throwsClause?.throwsSpecifier != nil
+    let typeEncoding = try generateTypeEncoding(returnType: returnType, paramTypes: paramTypes)
+    let implFuncName = funcDecl.name.text
+    let blockParamTypes = paramTypes.joined(separator: ", ")
+    let argNames = (0..<paramTypes.count).map { "arg\($0)" }.joined(separator: ", ")
+
+    let peerFunc: DeclSyntax
+
+    if functionThrows {
+      let isVoid = returnType == "Void" || returnType == "()"
+      let implType =
+        paramTypes.isEmpty
+        ? "() throws -> \(returnType)" : "(\(blockParamTypes)) throws -> \(returnType)"
+      let wrapperType =
+        paramTypes.isEmpty
+        ? "@convention(block) () -> \(returnType)"
+        : "@convention(block) (\(blockParamTypes)) -> \(returnType)"
+      let closureArgs = paramTypes.isEmpty ? "" : " \(argNames) in"
+      let implCall = paramTypes.isEmpty ? "impl()" : "impl(\(argNames))"
+      let tryExpr = isVoid ? "try \(implCall)" : "return try \(implCall)"
+      let unreachable = isVoid ? "" : "\n      fatalError(\"Unreachable\")"
+
+      peerFunc = """
+        private func \(raw: functionName)() -> OptimizedFunctionDescriptor {
+          let impl: \(raw: implType) = \(raw: implFuncName)
+          let wrapper: \(raw: wrapperType) = {\(raw: closureArgs)
+            do {
+              \(raw: tryExpr)
+            } catch {
+              let nsError: NSError
+              if let expoError = error as? Exception {
+                nsError = NSError(domain: "dev.expo.modules", code: 0, userInfo: [
+                  "name": expoError.name,
+                  "code": expoError.code,
+                  "message": expoError.debugDescription,
+                ])
+              } else {
+                nsError = error as NSError
+              }
+              let exception = NSException(
+                name: NSExceptionName(nsError.userInfo["name"] as? String ?? "SwiftError"),
+                reason: nsError.userInfo["message"] as? String ?? nsError.localizedDescription,
+                userInfo: nsError.userInfo
+              )
+              exception.raise()\(raw: unreachable)
+            }
+          }
+          return OptimizedSyncFunctionDefinition.createDescriptor(
+            typeEncoding: "\(raw: typeEncoding)",
+            argsCount: \(raw: String(paramTypes.count)),
+            block: wrapper as AnyObject
+          )
+        }
+        """
+    } else {
+      peerFunc = """
+        private func \(raw: functionName)() -> OptimizedFunctionDescriptor {
+          return OptimizedSyncFunctionDefinition.createDescriptor(
+            typeEncoding: "\(raw: typeEncoding)",
+            argsCount: \(raw: String(paramTypes.count)),
+            block: (\(raw: implFuncName) as @convention(block) (\(raw: blockParamTypes)) -> \(raw: returnType)) as AnyObject
+          )
+        }
+        """
+    }
+
+    return [peerFunc]
+  }
+}

package/apple/Sources/ExpoModulesMacros/ExpoViewMacro.swift

@@ -0,0 +1,259 @@
+import SwiftDiagnostics
+import SwiftSyntax
+import SwiftSyntaxBuilder
+import SwiftSyntaxMacros
+
+/// Member macro applied to an `ExpoView` subclass, binding it to its props type:
+///
+///   @ExpoView<CardProps>
+///   final class CardView: ExpoView {
+///     override func didUpdateProps(_ diff: CardProps.Diff) {
+///       if diff.changed(.color) {
+///         backgroundColor = props.color
+///       }
+///     }
+///   }
+///
+/// The props type is the attribute's **generic argument**, so it sits in type position: no
+/// `.self` metatype to write, and the macro reads it straight off the attribute's
+/// `genericArgumentClause`. Core's declaration constrains the parameter
+/// (`macro ExpoView<Props: AnyViewProps>()`), so passing a type that isn't a props type is a
+/// compile error at the author's own line ("requires that 'X' conform to 'AnyViewProps'")
+/// rather than a macro diagnostic. This macro therefore validates nothing about the props type.
+///
+/// The whole expansion is one line:
+///
+///   public typealias Props = CardProps
+///
+/// That is deliberately all of it. There is **no view definition**: no `ViewDefinition`, no
+/// `View(…) { }` builder, no `Props(_:)` or `Events(_:)` element. `_synthesizedViewDefinition()`
+/// existed only to hand core a DSL value the old registration path could consume, and modules and
+/// shared objects already moved to direct hooks. Core reads the props type from this typealias and
+/// the event names from the props type's own `_eventNames` (synthesized by `@ViewProps`), both
+/// static, neither needing a builder to be evaluated.
+///
+/// Views also get no `_decorateView` hook in its place: `_decorateModule` and `_decorateSharedObject`
+/// exist to bind members into a JS object, and a view has no such object. Props reach a view through
+/// Fabric's mounting layer, not a JS call, so a view's runtime entry point is the props update hook.
+///
+/// `didUpdateProps` is a core-called override, not synthesized here.
+public struct ExpoViewMacro: 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("@ExpoView can only be applied to a class")
+    }
+
+    guard inheritsFromAny(classDecl, names: expoViewBaseClassNames) else {
+      throw DiagnosticsError(diagnostics: [missingBaseClassDiagnostic(for: classDecl)])
+    }
+
+    // A generic view can't be registered: `@ExpoModule(views: [CardView.self])` on a generic type
+    // fails with "generic parameter 'T' could not be inferred", and the props type ignores the
+    // parameter anyway. Reject it here, at the author's line, rather than at the registration site.
+    // `@ViewProps` rejects generic props types for the same reason.
+    if classDecl.genericParameterClause != nil {
+      throw MacroExpansionErrorMessage(
+        "@ExpoView does not support generic classes — a view registered with @ExpoModule(views:) must be concrete"
+      )
+    }
+
+    // The expansion is a `Props` typealias, so a member of that name already on the class collides.
+    // Left alone, the compiler reports "invalid redeclaration of 'Props'" positioned inside the
+    // macro expansion, which is code the author never wrote. Name it here instead.
+    if let existing = existingPropsMemberKind(in: classDecl) {
+      throw MacroExpansionErrorMessage(
+        "@ExpoView synthesizes a `Props` typealias, but this class already declares a \(existing) named 'Props'. Rename it"
+      )
+    }
+
+    // The props type is the attribute's generic argument. Core's declaration is generic, so a bare
+    // `@ExpoView` never reaches expansion: it fails type-checking first with "generic parameter
+    // 'Props' could not be inferred". This diagnostic covers the case where the macro is declared
+    // differently than core declares it, so the author still gets a message naming the attribute.
+    guard let propsType = genericArgument(of: node) else {
+      throw MacroExpansionErrorMessage(
+        "@ExpoView requires its props type as a generic argument, as in `@ExpoView<MyViewProps>`"
+      )
+    }
+
+    return [
+      """
+      public typealias Props = \(raw: propsType)
+      """
+    ]
+  }
+}
+
+// MARK: - Diagnostics
+
+/// The error for a class that doesn't name `ExpoView` in its inheritance clause, carrying a fix-it
+/// that adds it.
+///
+/// The fix-it only applies where the edit is unambiguous. With no inheritance clause at all it
+/// inserts `: ExpoView`; with an existing clause it prepends `ExpoView` as the first entry, since
+/// Swift requires the superclass to come before any protocol. A class that already names some other
+/// superclass gets the diagnostic without a fix-it: replacing that superclass is a decision the macro
+/// can't make (see the indirect-inheritance note on `expoViewBaseClassNames`).
+private func missingBaseClassDiagnostic(for classDecl: ClassDeclSyntax) -> Diagnostic {
+  let message = ExpoViewDiagnosticMessage(
+    "@ExpoView class must inherit from ExpoView. Add `: ExpoView` to the class declaration.",
+    id: "expoview-missing-base-class"
+  )
+  var fixIts: [FixIt] = []
+
+  if classDecl.inheritanceClause == nil {
+    // `class CardView {` → `class CardView: ExpoView {`. The name carries the space before `{` as
+    // trailing trivia, so move it onto the clause to keep the spacing.
+    let name = classDecl.name
+    let clause = InheritanceClauseSyntax(
+      colon: .colonToken(trailingTrivia: .space),
+      inheritedTypes: InheritedTypeListSyntax([
+        InheritedTypeSyntax(type: TypeSyntax(IdentifierTypeSyntax(name: .identifier("ExpoView"))))
+      ])
+    )
+    fixIts.append(
+      FixIt(
+        message: ExpoViewFixItMessage("Inherit from 'ExpoView'", id: "expoview-add-base-class"),
+        changes: [
+          .replace(
+            oldNode: Syntax(classDecl),
+            newNode: Syntax(
+              classDecl
+                .with(\.name, name.with(\.trailingTrivia, []))
+                .with(\.inheritanceClause, clause.with(\.trailingTrivia, name.trailingTrivia))
+            )
+          )
+        ]
+      )
+    )
+  } else if let clause = classDecl.inheritanceClause, inheritsOnlyProtocolsByConvention(clause) {
+    // `class CardView: Identifiable {` → `class CardView: ExpoView, Identifiable {`.
+    var inherited = clause.inheritedTypes
+    if var first = inherited.first {
+      first.trailingComma = .commaToken(trailingTrivia: .space)
+      first.type = TypeSyntax(IdentifierTypeSyntax(name: .identifier("ExpoView")))
+      inherited.insert(first, at: inherited.startIndex)
+    }
+    fixIts.append(
+      FixIt(
+        message: ExpoViewFixItMessage("Inherit from 'ExpoView'", id: "expoview-add-base-class"),
+        changes: [
+          .replace(
+            oldNode: Syntax(clause),
+            newNode: Syntax(clause.with(\.inheritedTypes, inherited))
+          )
+        ]
+      )
+    )
+  }
+
+  return Diagnostic(node: classDecl.name, message: message, fixIts: fixIts)
+}
+
+/// Whether every entry in the clause looks like a protocol rather than a superclass, by the
+/// capitalization-free heuristic that a Swift superclass must come first: if the first entry is one
+/// the macro would be replacing, prepending `ExpoView` would produce two superclasses. A macro can't
+/// resolve names, so this only reports true when the clause is empty of anything that could be a
+/// base class the author chose deliberately. Conservative by design: a wrong guess here would emit a
+/// fix-it that doesn't compile.
+private func inheritsOnlyProtocolsByConvention(_ clause: InheritanceClauseSyntax) -> Bool {
+  // Any entry at all could be a superclass, so only offer the prepend when the author wrote
+  // something that is definitely not one: a known protocol-shaped name from the standard library.
+  let knownProtocols: Set<String> = [
+    "Identifiable", "Equatable", "Hashable", "Codable", "Encodable", "Decodable",
+    "Sendable", "CustomStringConvertible", "ObservableObject",
+  ]
+  return clause.inheritedTypes.allSatisfy { entry in
+    guard let name = baseIdentifier(of: entry.type) else {
+      return false
+    }
+    return knownProtocols.contains(name)
+  }
+}
+
+private struct ExpoViewDiagnosticMessage: DiagnosticMessage {
+  let message: String
+  let diagnosticID: MessageID
+  let severity: DiagnosticSeverity = .error
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.diagnosticID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+private struct ExpoViewFixItMessage: FixItMessage {
+  let message: String
+  let fixItID: MessageID
+
+  init(_ message: String, id: String) {
+    self.message = message
+    self.fixItID = MessageID(domain: "ExpoModulesMacros", id: id)
+  }
+}
+
+/// Describes an existing `Props` member on the class, for the collision diagnostic, or `nil` when the
+/// name is free. Covers the shapes that would clash with the synthesized typealias: another typealias,
+/// and a nested type of any kind.
+private func existingPropsMemberKind(in classDecl: ClassDeclSyntax) -> String? {
+  for member in classDecl.memberBlock.members {
+    let decl = member.decl
+    if let typealiasDecl = decl.as(TypeAliasDeclSyntax.self), typealiasDecl.name.text == "Props" {
+      return "typealias"
+    }
+    if let structDecl = decl.as(StructDeclSyntax.self), structDecl.name.text == "Props" {
+      return "struct"
+    }
+    if let nestedClass = decl.as(ClassDeclSyntax.self), nestedClass.name.text == "Props" {
+      return "class"
+    }
+    if let enumDecl = decl.as(EnumDeclSyntax.self), enumDecl.name.text == "Props" {
+      return "enum"
+    }
+    if let actorDecl = decl.as(ActorDeclSyntax.self), actorDecl.name.text == "Props" {
+      return "actor"
+    }
+  }
+  return nil
+}
+
+/// Base classes an `@ExpoView` may inherit from. The check is syntactic, matching the name in the
+/// class's own inheritance clause: both `: ExpoView` and a qualified `: ExpoModulesCore.ExpoView`
+/// pass, since `baseIdentifier` reads the trailing name.
+///
+/// Indirect inheritance does not: a view whose superclass is itself an `ExpoView` subclass
+/// (`class Base: ExpoView` then `class CardView: Base`) is rejected, because a macro can't resolve
+/// the superclass to check. `@SharedObject` has the same limitation, through the same helper. The
+/// workaround is to apply `@ExpoView` to the class that names `ExpoView` directly.
+private let expoViewBaseClassNames: Set<String> = ["ExpoView"]
+
+/// The attribute's single generic argument, verbatim (`@ExpoView<CardProps>` → `"CardProps"`), or
+/// `nil` when the attribute carries no generic argument clause.
+///
+/// The type is available syntactically, with no type resolution. Two spellings carry it, mirroring
+/// `baseIdentifier`'s handling of the inheritance clause: a bare `@ExpoView<CardProps>` parses as an
+/// `IdentifierTypeSyntax`, and a qualified `@ExpoModulesCore.ExpoView<CardProps>` as a
+/// `MemberTypeSyntax`. Both have a `genericArgumentClause`, and both are legal at the use site, so
+/// reading only the bare form would reject valid code while claiming the author omitted the argument.
+///
+/// Only the first argument is read: core's declaration has exactly one parameter, so a second is
+/// already a compile error at the use site ("specialized with too many type parameters").
+private func genericArgument(of attribute: AttributeSyntax) -> String? {
+  let arguments: GenericArgumentListSyntax?
+  if let identifier = attribute.attributeName.as(IdentifierTypeSyntax.self) {
+    arguments = identifier.genericArgumentClause?.arguments
+  } else if let member = attribute.attributeName.as(MemberTypeSyntax.self) {
+    arguments = member.genericArgumentClause?.arguments
+  } else {
+    arguments = nil
+  }
+  guard let first = arguments?.first, case .type(let type) = first.argument else {
+    return nil
+  }
+  return type.trimmedDescription
+}

package/apple/Sources/ExpoModulesMacros/FreeFormTypes.swift

@@ -0,0 +1,214 @@
+import SwiftSyntax
+
+/// Recognition of the free-form (`Any`-bearing) boundary types and the spellings the macros emit or
+/// suggest for them. None of these types can conform to the JS codable protocols (`Any` can't conform
+/// to a protocol, and the container conditional conformances require the element/value to conform), so
+/// they can't cross the boundary through the usual `T.decode` / `T.encode` path. Instead they're
+/// accepted **only** in decode position (function/constructor arguments), decoded through a dedicated
+/// `JavaScriptValue.decodeAny…` entry point; a free-form return or getter is rejected, since there's
+/// no free-form encode.
+///
+/// Shared across the macro pipeline: `TypeConformanceAssertion` skips them, `MacroHelpers.decodeCall`
+/// reroutes their decode, and `JSMacro` uses them for the steering diagnostics.
+///
+/// `@Record` accepts a property whose type mentions `Any` anywhere (`Any?`, `[String: Any]?`,
+/// `[String: [Any]]`, …) and converts it on the JS-value paths without `decode`/`encode`: the three
+/// free-form shapes, optionally wrapped in one optional, use the dedicated `JavaScriptValue.decodeAny…`
+/// and `encodeAny…` methods, and every other type uses the generic `decodeAny(_:as:in:)` and
+/// `encodeAny(_:in:)`.
+
+/// The free-form boundary types: an untyped value (`Any`), an untyped array (`[Any]`), and an untyped
+/// string-keyed dictionary (`[String: Any]`). Matched by whitespace-normalized spelling so
+/// `[String: Any]` and `[String : Any]` both count.
+private let freeFormBoundaryTypes: Set<String> = ["Any", "[Any]", "[String:Any]"]
+
+/// The `JavaScriptValue.decodeAny…` method the binding calls to decode a free-form argument, keyed by
+/// the free-form type's normalized spelling. `nil` for any non-free-form type.
+private let freeFormDecodeMethods: [String: String] = [
+  "Any": "decodeAny",
+  "[Any]": "decodeAnyArray",
+  "[String:Any]": "decodeAnyDictionary",
+]
+
+/// The type-safe alternative a free-form type's diagnostic steers to: the same shape with the `Any`
+/// element replaced by `JavaScriptValue`, which conforms to the codable protocols. Keyed by the
+/// free-form type's normalized spelling; spelled with conventional spacing for the message.
+private let typedFreeFormReplacements: [String: String] = [
+  "Any": "JavaScriptValue",
+  "[Any]": "[JavaScriptValue]",
+  "[String:Any]": "[String: JavaScriptValue]",
+]
+
+/// True when a boundary type (as written) is one of the free-form spellings, ignoring internal
+/// whitespace so `[String: Any]` and `[String :Any]` both match. Optionals are not free-form here: a
+/// trailing `?` would route through `Optional.decode`, which free-form can't satisfy, so an optional
+/// free-form type isn't recognized and stays a normal (failing) assertion.
+internal func isFreeFormBoundaryType(_ type: String) -> Bool {
+  return freeFormBoundaryTypes.contains(normalizedTypeSpelling(type))
+}
+
+/// The `JavaScriptValue.decodeAny…` method name for a free-form boundary type, or `nil` when the type
+/// isn't free-form. The binding emits `JavaScriptValue.<method>(arguments.unownedValue(at:), in:)` in
+/// place of the type's own `.decode`.
+internal func freeFormDecodeMethod(for type: String) -> String? {
+  return freeFormDecodeMethods[normalizedTypeSpelling(type)]
+}
+
+/// The type-safe alternative to suggest in place of a free-form type (its `Any` element replaced by
+/// `JavaScriptValue`), or `nil` when the type isn't free-form.
+internal func typedFreeFormReplacement(for type: String) -> String? {
+  return typedFreeFormReplacements[normalizedTypeSpelling(type)]
+}
+
+/// A type spelling with all whitespace removed, so spelling variations of the same type
+/// (`[String: Any]` vs `[String :Any]`) compare equal.
+private func normalizedTypeSpelling(_ type: String) -> String {
+  return type.filter { !$0.isWhitespace }
+}
+
+/// True when a type mentions `Any` anywhere in its spelling, at any nesting depth: `Any`, `[Any]?`,
+/// `[String: Any]`, `Dictionary<String, [Any]>`, `[Int: Any]`, and so on. Such a type can't conform to
+/// the JS codable protocols.
+internal func mentionsFreeFormAny(_ type: TypeSyntax) -> Bool {
+  let finder = AnyTypeFinder(viewMode: .sourceAccurate)
+  finder.walk(type)
+  return finder.found
+}
+
+/// True when a type mentioning `Any` is built only from `Any`, arrays, `String`-keyed dictionaries and
+/// optionals, in any nesting (`[String: [Any]]?`, `[[String: Any]]`, …). Those are the only shapes the
+/// free-form conversions produce and accept, so any other type holding `Any` (`[Int: Any]`,
+/// `Set<[String: Any]>`, a user generic `Box<Any>`) could never convert.
+internal func isConvertibleFreeFormType(_ type: TypeSyntax) -> Bool {
+  if isAnyType(type) {
+    return true
+  }
+  if let wrapped = optionalWrappedType(type) {
+    return isConvertibleFreeFormType(wrapped)
+  }
+  if let element = arrayElementType(type) {
+    return isConvertibleFreeFormType(element)
+  }
+  if let value = stringKeyedDictionaryValueType(type) {
+    return isConvertibleFreeFormType(value)
+  }
+  return false
+}
+
+/// The three free-form shapes that have dedicated conversions.
+internal enum FreeFormShape {
+  case any
+  case array
+  case dictionary
+}
+
+/// The free-form shape a type has exactly (`Any`, `[Any]` or `[String: Any]`, in any spelling), or
+/// `nil` for every other type, including nested and optional ones.
+internal func freeFormShape(of type: TypeSyntax) -> FreeFormShape? {
+  if isAnyType(type) {
+    return .any
+  }
+  if let element = arrayElementType(type), isAnyType(element) {
+    return .array
+  }
+  if let value = stringKeyedDictionaryValueType(type), isAnyType(value) {
+    return .dictionary
+  }
+  return nil
+}
+
+/// True when the type is `Any` itself, spelled `Any` or `Swift.Any` (not `AnyObject`, `AnyHashable` or
+/// a generic).
+internal func isAnyType(_ type: some SyntaxProtocol) -> Bool {
+  if let identifier = type.as(IdentifierTypeSyntax.self) {
+    return identifier.name.text == "Any" && identifier.genericArgumentClause == nil
+  }
+  if let member = type.as(MemberTypeSyntax.self),
+    member.name.text == "Any",
+    member.genericArgumentClause == nil,
+    let base = member.baseType.as(IdentifierTypeSyntax.self) {
+    return base.name.text == "Swift"
+  }
+  return false
+}
+
+/// The element type of `[T]` or `Array<T>`, or `nil` for any other type.
+private 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.
+private 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 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
+}
+
+/// Walks a type looking for `Any` (or `Swift.Any`) anywhere inside it.
+private final class AnyTypeFinder: SyntaxVisitor {
+  var found = false
+
+  override func visit(_ node: IdentifierTypeSyntax) -> SyntaxVisitorContinueKind {
+    if isAnyType(node) {
+      found = true
+      return .skipChildren
+    }
+    return .visitChildren
+  }
+
+  override func visit(_ node: MemberTypeSyntax) -> SyntaxVisitorContinueKind {
+    if isAnyType(node) {
+      found = true
+      return .skipChildren
+    }
+    return .visitChildren
+  }
+}

package/apple/Sources/ExpoModulesMacros/JSConstructor.swift

@@ -0,0 +1,55 @@
+import SwiftSyntax
+
+/// A `@JS init` collected for direct JSI binding. A shared-object type has at most one (JS classes
+/// have a single constructor). Instead of a `Constructor { … }` DSL entry, the macro synthesizes an
+/// override of `SharedObject._constructSharedObject(...)` that decodes the JS arguments and returns a
+/// fresh instance; unlike the method/property bindings it produces the native instance rather than
+/// recovering one.
+internal struct JSConstructor {
+  let parameters: [FunctionParameterSyntax]
+
+  init(initDecl: InitializerDeclSyntax) {
+    self.parameters = Array(initDecl.signature.parameterClause.parameters)
+  }
+
+  /// The body statements, indented with `indent`: arity guard, per-argument decode through
+  /// `JavaScriptDecodable.decode` on a zero-copy `arguments.unownedValue(at:)` (the arity guard proves
+  /// each index is in bounds), then `return <Type>(label: arg0, …)`.
+  private func bodyStatements(typeName: String, indent: String) -> String {
+    var lines: [String] = []
+
+    lines.append(
+      """
+      guard arguments.count == \(parameters.count) else {
+        throw Exceptions.ArgumentsRangeMismatch((functionName: "\(typeName)", received: arguments.count, required: \(parameters.count), maximum: \(parameters.count)))
+      }
+      """)
+
+    var callArguments: [String] = []
+    for (index, parameter) in parameters.enumerated() {
+      let type = parameter.type.trimmedDescription
+      lines.append("let arg\(index) = try \(decodeCall(type, from: "arguments.unownedValue(at: \(index))"))")
+
+      let label = parameter.firstName.text
+      callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")
+    }
+
+    lines.append("return \(typeName)(\(callArguments.joined(separator: ", ")))")
+
+    return lines
+      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
+      .map { indent + $0 }
+      .joined(separator: "\n")
+  }
+
+  /// Builds an instance from the JS arguments. Overrides the base `SharedObject` class method; returns
+  /// the concrete instance, which promotes to the base `SharedObject?` return type.
+  func buildConstructor(typeName: String) -> DeclSyntax {
+    return """
+      @JavaScriptActor
+      public override class func _constructSharedObject(this: JavaScriptValue, arguments: borrowing JavaScriptValuesBuffer, in runtime: JavaScriptRuntime) throws -> SharedObject? {
+      \(raw: bodyStatements(typeName: typeName, indent: "  "))
+      }
+      """
+  }
+}