@expo/expo-modules-macros-plugin 0.2.0 → 0.2.2

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -0,0 +1,297 @@
+import SwiftSyntax
+
+/**
+ A `@JS func` collected for **direct JSI binding**. Instead of describing the function with a
+ `Function(...)` / `AsyncFunction(...)` DSL entry that the runtime interprets per call,
+ `@ExpoModule` synthesizes a `_decorateModule` that binds each such function into the module's JS object
+ via the closure-taking `JavaScriptObject.setProperty(_:)`, with the decode-call-encode body
+ inlined into the closure. This omits the `[Any]`/`toTuple` dynamic-call path: every argument is
+ decoded individually by its static type.
+
+ The receiver is the module's real `self` (a module is a singleton instance), so the body calls
+ `self.<name>(...)` directly and ignores the JS `this`. An `async` `@JS func` produces an `async`
+ closure body and is installed through the async `setProperty(_:)` overload (so JS gets a promise).
+ */
+internal struct JSFunction {
+  let swiftName: String
+  let jsName: String
+  let parameters: [FunctionParameterSyntax]
+  /// The declared return type as written, or `nil` when the function returns `Void`/nothing.
+  let returnType: String?
+  let isThrowing: Bool
+  let isAsync: Bool
+
+  init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
+    self.swiftName = funcDecl.name.text
+    self.jsName = jsNameArgument(of: attribute) ?? funcDecl.name.text
+    self.parameters = Array(funcDecl.signature.parameterClause.parameters)
+
+    let declaredReturnType = funcDecl.signature.returnClause?.type
+    self.returnType = isVoidType(declaredReturnType) ? nil : declaredReturnType?.trimmedDescription
+
+    let effectSpecifiers = funcDecl.signature.effectSpecifiers
+    self.isThrowing = effectSpecifiers?.throwsClause?.throwsSpecifier != nil
+    self.isAsync = effectSpecifiers?.asyncSpecifier != nil
+  }
+
+  /// The decode-call-encode statements that form the host-function body, indented with the given
+  /// prefix. Arity guard, then per-argument decode (primitives via a direct typed accessor like
+  /// `asDouble()` on a zero-copy `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`),
+  /// the `self.<name>(...)` call, and the
+  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`).
+  private func bodyStatements(indent: String) -> String {
+    var lines: [String] = []
+
+    lines.append(
+      """
+      guard arguments.count == \(parameters.count) else {
+        throw Exception(name: "InvalidArgumentCount", description: "Function '\(jsName)' expects \(parameters.count) argument(s), but got \\(arguments.count)")
+      }
+      """)
+
+    var callArguments: [String] = []
+    for (index, parameter) in parameters.enumerated() {
+      let type = parameter.type.trimmedDescription
+
+      // Primitives decode through a direct typed accessor (`asDouble()`, etc.) on a borrowed
+      // `JavaScriptUnownedValue` — no owning `JavaScriptValue` allocation, no `jsi::Value` copy, no
+      // `getDynamicType()` allocation, no `Any` boxing, no force-cast — while still validating and
+      // throwing `TypeError` on a mismatch. Other types fall back to the dynamic converter, which
+      // needs an owning value, so they index the buffer directly.
+      if let accessor = fastDecodeAccessor(for: type) {
+        lines.append("let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()")
+      } else {
+        lines.append(
+          "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)")
+      }
+
+      let label = parameter.firstName.text
+      callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")
+    }
+
+    let tryKeyword = (isThrowing || isAsync) ? "try " : ""
+    let awaitKeyword = isAsync ? "await " : ""
+    let callExpression =
+      "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
+
+    if let returnType {
+      lines.append("let result = \(callExpression)")
+      // Primitives encode through `toJavaScriptValue(in:)` (the typed `JavaScriptRepresentable`
+      // conversion) — no `Any`, no dynamic-type allocation. Others go through the dynamic converter.
+      if fastDecodeAccessor(for: returnType) != nil {
+        lines.append("return result.toJavaScriptValue(in: runtime)")
+      } else {
+        lines.append("return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)")
+      }
+    } else {
+      lines.append(callExpression)
+      lines.append("return .undefined")
+    }
+
+    return lines
+      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
+      .map { indent + $0 }
+      .joined(separator: "\n")
+  }
+
+  /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode
+  /// body is inlined directly into the closure passed to the closure-taking `setProperty` overload
+  /// (which creates the host function under the hood) — no separate named binding. For an `async`
+  /// function the body `await`s the call, which selects the async `setProperty` overload (so JS
+  /// receives a promise).
+  ///
+  /// Capture mirrors core's `SyncFunctionDefinition.build`: `self` (the module) is captured
+  /// **strong** — the host-function closure is what keeps the native callable alive for as long as
+  /// JS can invoke it; its lifetime is bounded by the JS VM's garbage collection of the object.
+  /// `appContext` is captured **weak** (and guarded) so it doesn't form a real retain cycle through
+  /// the app context. When no argument or return value goes through the dynamic-type converter the
+  /// body never references `appContext`, so the capture and guard are omitted to avoid the
+  /// unused-capture warning.
+  var decorateStatements: String {
+    if usesAppContext {
+      return """
+          object.setProperty("\(jsName)") { [weak appContext, self] this, arguments in
+            guard let appContext else {
+              throw Exceptions.AppContextLost()
+            }
+        \(bodyStatements(indent: "    "))
+          }
+        """
+    }
+    return """
+        object.setProperty("\(jsName)") { [self] this, arguments in
+      \(bodyStatements(indent: "    "))
+        }
+      """
+  }
+
+  /// True when the host-function body references `appContext` — i.e. some parameter or the return
+  /// type lacks a fast accessor and decodes/encodes through `getDynamicType()`, which threads
+  /// `appContext` in.
+  private var usesAppContext: Bool {
+    if parameters.contains(where: { fastDecodeAccessor(for: $0.type.trimmedDescription) == nil }) {
+      return true
+    }
+    if let returnType, fastDecodeAccessor(for: returnType) == nil {
+      return true
+    }
+    return false
+  }
+}
+
+/// A `@JS var` collected for **direct JSI binding**. Instead of describing the property with a
+/// `Property(...)` DSL entry, `@ExpoModule` synthesizes a get/set accessor into the module's JS
+/// object inside `_decorateModule`: it builds a descriptor object (`enumerable` + `get`, and `set`
+/// when the property is settable) and installs it with `object.defineProperty(name, descriptor:)`,
+/// mirroring core's `PropertyDefinition.buildDescriptor`. The `get`/`set` host functions are
+/// installed the same way `@JS func`s are — the closure-taking `setProperty(_:)` overload, with the
+/// read/write body inlined into the closure.
+///
+/// The receiver is the module's real `self`, so the getter reads `self.<name>` and the setter writes
+/// `self.<name> = …` directly, ignoring the JS `this`. Decode/encode of the value reuse the same
+/// static-type fast path as functions (primitives through a direct typed accessor / `toJavaScriptValue`,
+/// other types through the `getDynamicType()` converter).
+internal struct JSProperty {
+  let swiftName: String
+  let jsName: String
+  /// The property's value type as written, or `nil` when it couldn't be inferred (no annotation and
+  /// no literal default). When `nil` the getter still works (the encode infers from `self.<name>`)
+  /// but the setter uses an untyped closure parameter.
+  let valueType: String?
+  /// Whether the property is settable from JS: `true` for a stored `var` or a computed `var` with an
+  /// explicit `set` accessor; `false` for a getter-only computed `var` or a `let`.
+  let isSettable: Bool
+
+  /// The statements that install this property's accessor on the JS object, indented for the
+  /// `_decorateModule` body. Builds a descriptor object (`enumerable` + `get`, and `set` when
+  /// settable) via the closure-taking `setProperty(_:)` overload — with the read/write body inlined
+  /// into each closure — and installs it with `object.defineProperty(name, descriptor:)`. Capture
+  /// matches the function bindings: `self` strong, `appContext` weak + guarded — and, like functions,
+  /// the `appContext` capture + guard are omitted from an accessor whose body never references it (a
+  /// primitive value, decoded/encoded without the dynamic converter), to avoid the unused-capture
+  /// warning. Getter and setter are gated independently.
+  var decorateStatements: String {
+    let descriptorName = "\(swiftName)Descriptor"
+    // A primitive value type encodes/decodes without `getDynamicType()`, so its accessor body never
+    // references `appContext`. `nil` (untyped) goes through the dynamic-less `toJavaScriptValue`
+    // getter, which also doesn't use it.
+    let usesAppContext = valueType.map { fastDecodeAccessor(for: $0) == nil } ?? false
+    var lines: [String] = []
+
+    lines.append("let \(descriptorName) = runtime.createObject()")
+    lines.append("\(descriptorName).setProperty(\"enumerable\", value: true)")
+
+    // Getter: read `self.<name>` and encode the result back to JS.
+    let getEncode: String
+    if let valueType, fastDecodeAccessor(for: valueType) != nil {
+      getEncode = "return self.\(swiftName).toJavaScriptValue(in: runtime)"
+    } else if let valueType {
+      getEncode =
+        "return try \(valueType).getDynamicType().castToJS(self.\(swiftName), appContext: appContext, in: runtime)"
+    } else {
+      // No known type: fall back to converting whatever `self.<name>` is. This only happens when the
+      // declaration has neither an annotation nor a literal default, which is rare for a stored var.
+      getEncode = "return self.\(swiftName).toJavaScriptValue(in: runtime)"
+    }
+    lines.append(accessorClosure(descriptorName, "get", usesAppContext: usesAppContext, body: getEncode))
+
+    // Setter: decode argument 0 by the static type and write `self.<name>`. A typed setter needs a
+    // known value type; when the type couldn't be inferred the property is bound getter-only (a
+    // settable var with neither an annotation nor a literal default is rare and can't be decoded).
+    if isSettable, let valueType {
+      let setDecode: String
+      if let accessor = fastDecodeAccessor(for: valueType) {
+        setDecode = "self.\(swiftName) = try arguments.unownedValue(at: 0).\(accessor)()"
+      } else {
+        setDecode =
+          "self.\(swiftName) = try \(valueType).getDynamicType().cast(jsValue: arguments[0], appContext: appContext) as! \(valueType)"
+      }
+      lines.append(
+        accessorClosure(descriptorName, "set", usesAppContext: usesAppContext, body: "\(setDecode)\nreturn .undefined"))
+    }
+
+    lines.append("object.defineProperty(\"\(jsName)\", descriptor: \(descriptorName))")
+
+    return lines
+      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
+      .map { "  " + $0 }
+      .joined(separator: "\n")
+  }
+
+  /// One `descriptor.setProperty("get"/"set") { … }` accessor entry. Captures `self` strong and, when
+  /// `usesAppContext`, `appContext` weak + guarded (matching the function bindings); otherwise the
+  /// capture and guard are omitted so a primitive accessor doesn't warn on an unused capture.
+  private func accessorClosure(
+    _ descriptorName: String, _ key: String, usesAppContext: Bool, body: String
+  ) -> String {
+    // Indent each line of a (possibly multi-line) body to sit one level inside the closure, aligned
+    // with the `guard`; a bare `\(body)` interpolation would only indent the first line.
+    let indentedBody = body
+      .split(separator: "\n", omittingEmptySubsequences: false)
+      .map { "  \($0)" }
+      .joined(separator: "\n")
+    if usesAppContext {
+      return """
+        \(descriptorName).setProperty("\(key)") { [weak appContext, self] this, arguments in
+          guard let appContext else {
+            throw Exceptions.AppContextLost()
+          }
+        \(indentedBody)
+        }
+        """
+    }
+    return """
+      \(descriptorName).setProperty("\(key)") { [self] this, arguments in
+      \(indentedBody)
+      }
+      """
+  }
+}
+
+/// The single generated function that decorates the module's JS object. Core supplies the object;
+/// this binds every `@JS func` (via an inlined `setProperty` closure) and every `@JS var` (via a
+/// `defineProperty` accessor) into it. Mirrors core's `ObjectDefinition.decorate(object:)`, including
+/// its `borrowing` object parameter (it mutates through the reference without reassigning or taking
+/// ownership). Named `_decorateModule` with the leading-underscore convention for synthesized members
+/// the **runtime calls by name**; the `ExpoModule` suffix names the `@ExpoModule` macro it came from (a
+/// shared object's counterpart is `_decorateSharedObject`).
+internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties: [JSProperty]) -> DeclSyntax {
+  let functionBody = functions.map { $0.decorateStatements }
+  let propertyBody = properties.map { $0.decorateStatements }
+  let body = (functionBody + propertyBody).joined(separator: "\n")
+  return """
+    @JavaScriptActor
+    public func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime, appContext: AppContext) throws {
+    \(raw: body)
+    }
+    """
+}
+
+/// The throwing `JavaScriptUnownedValue` accessor that decodes the given primitive type directly,
+/// bypassing the dynamic-type converter (`asDouble()` for `Double`, etc.). Returns `nil` for
+/// types without a dedicated accessor — arrays, records, optionals, shared objects, other numeric
+/// widths — which decode through `getDynamicType().cast(...)`.
+private func fastDecodeAccessor(for type: String) -> String? {
+  switch type {
+  case "Bool":
+    return "asBool"
+  case "Int":
+    return "asInt"
+  case "Double":
+    return "asDouble"
+  case "String":
+    return "asString"
+  default:
+    return nil
+  }
+}
+
+/// True when a return clause is absent or written as `Void` / `()` — i.e. the function returns
+/// nothing JS-visible, so the binding returns `.undefined`.
+private func isVoidType(_ type: TypeSyntax?) -> Bool {
+  guard let type else {
+    return true
+  }
+  let text = type.trimmedDescription
+  return text == "Void" || text == "()"
+}

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -42,11 +42,11 @@ public struct ExpoModuleMacro: MemberMacro {
     let moduleName = jsNameArgument(of: node) ?? classDecl.name.text
     var entries: [String] = ["Name(\"\(moduleName)\")"]
 
-    // `@JS func`s (sync and async) are bound directly into the JS object by the synthesized
-    // `_decorateModule` rather than described with a `Function(...)` / `AsyncFunction(...)` DSL entry,
-    // so they're collected here instead of appended to `entries`. Properties still go through
-    // the DSL for now.
+    // `@JS func`s (sync and async) and `@JS var`s are bound directly into the JS object by the
+    // synthesized `_decorateModule` rather than described with a `Function(...)` / `Property(...)`
+    // DSL entry, so they're collected here instead of appended to `entries`.
     var functions: [JSFunction] = []
+    var properties: [JSProperty] = []
 
     for typeName in classListArgument(of: node, label: "classes") {
       entries.append("\(typeName)._synthesizedClassDefinition()")
@@ -63,7 +63,7 @@ public struct ExpoModuleMacro: MemberMacro {
 
       if let varDecl = decl.as(VariableDeclSyntax.self),
         let attribute = varDecl.attributes.firstAttribute(named: "JS") {
-        entries.append(contentsOf: buildPropertyEntries(varDecl: varDecl, attribute: attribute))
+        properties.append(contentsOf: collectProperties(varDecl: varDecl, attribute: attribute))
       }
     }
 
@@ -100,11 +100,11 @@ public struct ExpoModuleMacro: MemberMacro {
       """
     emitted.append(method)
 
-    // Direct JSI binding: one `_decorateModule` that binds each `@JS func` into the module's JS object,
-    // with the decode-call-encode body inlined into each closure. Only emitted when there are
-    // functions to bind.
-    if !functions.isEmpty {
-      emitted.append(buildDecorateJavaScriptObject(functions: functions))
+    // Direct JSI binding: one `_decorateModule` that binds each `@JS func` (inlined `setProperty`
+    // closure) and each `@JS var` (a `defineProperty` get/set accessor) into the module's JS object.
+    // Only emitted when there's at least one member to bind.
+    if !functions.isEmpty || !properties.isEmpty {
+      emitted.append(buildDecorateJavaScriptObject(functions: functions, properties: properties))
     }
 
     return emitted
@@ -228,19 +228,52 @@ private func hasAppContextInitializer(_ classDecl: ClassDeclSyntax) -> Bool {
 
 // MARK: - Member builders
 
-private func buildPropertyEntries(
+private func collectProperties(
   varDecl: VariableDeclSyntax,
   attribute: AttributeSyntax
-) -> [String] {
+) -> [JSProperty] {
   let jsNameOverride = jsNameArgument(of: attribute)
+  // A `let` is never settable; only `var` bindings can carry a setter.
+  let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
 
   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) }"
+    // 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
+      ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
+    return JSProperty(
+      swiftName: swiftName,
+      jsName: jsNameOverride ?? swiftName,
+      valueType: valueType,
+      isSettable: isVar && bindingIsSettable(binding)
+    )
+  }
+}
+
+/// Whether a `var` binding is settable from JS. A stored property (no accessor block) is settable;
+/// a computed property is settable only when it declares an explicit `set` accessor. A getter-only
+/// computed property (`{ get }` or a single getter body) stays read-only. `willSet`/`didSet`
+/// observers imply stored storage, which is also settable.
+private func bindingIsSettable(_ binding: PatternBindingSyntax) -> Bool {
+  guard let accessorBlock = binding.accessorBlock else {
+    return true
+  }
+  switch accessorBlock.accessors {
+  case .accessors(let accessors):
+    return accessors.contains { accessor in
+      switch accessor.accessorSpecifier.tokenKind {
+      case .keyword(.set), .keyword(.willSet), .keyword(.didSet):
+        return true
+      default:
+        return false
+      }
+    }
+  case .getter:
+    return false
   }
 }
 

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -1,29 +1,93 @@
 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" }
- */
+/// Marker macro applied to module / shared-object members that should be exposed to JavaScript.
+/// `@ExpoModule` and `@SharedObject` discover declarations carrying this attribute and generate the
+/// corresponding `Function` / `AsyncFunction` / `Property` / `Constructor` registrations; that part
+/// of the expansion lives in those macros.
+///
+/// On its own, `@JS` emits one thing: a never-called peer that asserts every type crossing the JS
+/// boundary is JS-convertible. Because it's a **peer** of the marked member, a non-conforming type
+/// produces a compile error located on the user's own `@JS` declaration rather than on the enclosing
+/// `@ExpoModule`. The assertion mechanism itself is shared (see `typeConformanceAssertion`); `@JS`
+/// only supplies the boundary types it reads off the declaration.
+///
+/// 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 []
+    guard let member = boundaryMember(of: declaration),
+      let assertion = typeConformanceAssertion(
+        for: ConformanceAssertion(name: member.name, types: member.types),
+        isStatic: member.isStatic
+      ) else {
+      return []
+    }
+    return [assertion]
+  }
+}
+
+/// What an assertion peer needs about the `@JS` member it sits beside: a name (to keep the peer
+/// unique among siblings), the types crossing the JS boundary, and whether the member is type-level.
+private struct BoundaryMember {
+  let name: String
+  /// Boundary types as written. Composed types (`[Int]`, `String?`, …) are kept verbatim — their
+  /// conditional conformances transitively constrain the elements.
+  let types: [String]
+  /// True for `static`/`class` members, so the peer is emitted in the same metatype context.
+  let isStatic: Bool
+}
+
+/// Reads the boundary member off a `@JS` declaration. A function contributes its parameter types
+/// plus the return type (when non-Void); a property contributes its declared type. Returns `nil` for
+/// declaration kinds `@JS` doesn't read types from, or a property whose type isn't spelled out (a
+/// syntactic macro can't recover it), so no assertion is emitted there.
+private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> BoundaryMember? {
+  if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
+    var types = funcDecl.signature.parameterClause.parameters.map { $0.type.trimmedDescription }
+    if let returnType = funcDecl.signature.returnClause?.type, !isVoidType(returnType) {
+      types.append(returnType.trimmedDescription)
+    }
+    return BoundaryMember(name: funcDecl.name.text, types: types, isStatic: isTypeLevel(funcDecl.modifiers))
   }
+
+  if let varDecl = declaration.as(VariableDeclSyntax.self),
+    let binding = varDecl.bindings.first,
+    let identifier = binding.pattern.as(IdentifierPatternSyntax.self),
+    let type = binding.typeAnnotation?.type {
+    return BoundaryMember(
+      name: identifier.identifier.text,
+      types: [type.trimmedDescription],
+      isStatic: isTypeLevel(varDecl.modifiers)
+    )
+  }
+
+  return nil
+}
+
+/// True when the modifiers make the member type-level (`static` or `class`), so its assertion peer
+/// must be emitted in the same metatype context rather than as an instance member.
+private func isTypeLevel(_ modifiers: DeclModifierListSyntax) -> Bool {
+  return modifiers.contains {
+    $0.name.tokenKind == .keyword(.static) || $0.name.tokenKind == .keyword(.class)
+  }
+}
+
+/// 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 {
+  let text = type.trimmedDescription
+  return text == "Void" || text == "()"
 }

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -155,6 +155,27 @@ private func hasGlobalActorShape(_ element: AttributeListSyntax.Element) -> Bool
   return name.hasSuffix("Actor")
 }
 
+/// The Swift default type of a literal expression — `String`, `Double`, `Int`, or `Bool` — or `nil`
+/// when the expression isn't one of those literals. Used to recover a property's type when it has no
+/// annotation but does have a literal default (`var name = "foo"` → `String`). This matches the type
+/// Swift itself would infer for the same un-annotated declaration; expressions whose type a syntactic
+/// macro can't know (function calls, collection literals, member access) return `nil`.
+internal func inferredLiteralType(of expression: ExprSyntax) -> String? {
+  if expression.is(StringLiteralExprSyntax.self) {
+    return "String"
+  }
+  if expression.is(FloatLiteralExprSyntax.self) {
+    return "Double"
+  }
+  if expression.is(IntegerLiteralExprSyntax.self) {
+    return "Int"
+  }
+  if expression.is(BooleanLiteralExprSyntax.self) {
+    return "Bool"
+  }
+  return nil
+}
+
 extension AttributeListSyntax {
   internal func firstAttribute(named name: String) -> AttributeSyntax? {
     for element in self {

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -59,6 +59,18 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
     let existingInitLabels = initializerParameterLabels(of: declaration)
 
     var members: [DeclSyntax] = []
+
+    // A single never-called member that makes the compiler verify each property type is
+    // JS-convertible (the conversions below go through its dynamic-type API). Each property keeps its
+    // own named assertion inside, so the compiler's conformance diagnostic names the offending
+    // property (see `typeConformanceAssertions`). Emitted first so that, for a non-conforming type,
+    // this clear "requires that '…' conform to '…'" error is reported ahead of the noisier
+    // "no member 'getDynamicType'" errors from the conversion code below.
+    let assertions = properties.map { ConformanceAssertion(name: $0.name, types: [$0.type]) }
+    if let assertionMember = typeConformanceAssertions(for: assertions) {
+      members.append(assertionMember)
+    }
+
     if !existingInitLabels.contains([]) {
       if let defaultInit = defaultInit(properties: properties, isClass: isClass) {
         members.append(defaultInit)
@@ -441,29 +453,6 @@ private func isExcludedByModifier(_ modifiers: DeclModifierListSyntax) -> Bool {
   return false
 }
 
-/**
- The Swift default type of a literal expression — `String`, `Double`, `Int`, or `Bool` — or `nil`
- when the expression isn't one of those literals. Used to recover a property's type when it has no
- annotation but does have a literal default (`var name = "foo"` → `String`). This matches the type
- Swift itself would infer for the same un-annotated declaration; expressions whose type a syntactic
- macro can't know (function calls, collection literals, member access) return `nil`.
- */
-private func inferredLiteralType(of expression: ExprSyntax) -> String? {
-  if expression.is(StringLiteralExprSyntax.self) {
-    return "String"
-  }
-  if expression.is(FloatLiteralExprSyntax.self) {
-    return "Double"
-  }
-  if expression.is(IntegerLiteralExprSyntax.self) {
-    return "Int"
-  }
-  if expression.is(BooleanLiteralExprSyntax.self) {
-    return "Bool"
-  }
-  return nil
-}
-
 /**
  True if the type syntax is optional: `T?`, `T!`, or the spelled-out `Optional<T>`.
  */

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -0,0 +1,105 @@
+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 every macro that
+/// asserts the conformance (`@JS`, `@Record`, …).
+internal let jsConvertibleProtocolName = "AnyArgument"
+
+/// Types we never assert because they're statically known to conform and never reach the dynamic
+/// converter: the JS primitives. Asserting them would only add noise to the expansion. Kept here
+/// (rather than reusing the decode-path's `fastDecodeAccessor`) because "known-to-conform" is a
+/// concept that belongs with the assertion logic, not with how a value is decoded.
+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]
+}
+
+/// A single conformance-assertion peer for a `@JS` member: a never-called `private func` whose body
+/// statically asserts the member's boundary types conform. The assertion is compile-time only — the
+/// function is never invoked, but Swift still type-checks its body, so a non-conforming type becomes
+/// a compile error. Emitted as a **peer** of the user's declaration, so that error lands on the
+/// user's own member rather than on the enclosing macro.
+///
+/// `isStatic` makes the peer `static`, mirroring a `static`/`class` member so it's emitted in the
+/// right metatype context (a peer of a type-level member can't be an instance method). `class func`
+/// members collapse to `static` here too: the peer is private and never called or overridden, so
+/// `static` is always sufficient.
+///
+/// Returns `nil` when nothing is left to assert (every type was a known-conforming primitive, or the
+/// list was empty), so the caller emits nothing in that case.
+internal func typeConformanceAssertion(for assertion: ConformanceAssertion, isStatic: Bool) -> DeclSyntax? {
+  guard let body = conformanceAssertionBody(assertion) else {
+    return nil
+  }
+  let staticKeyword = isStatic ? "static " : ""
+  return """
+    private \(raw: staticKeyword)func _assertTypesConformance_\(raw: assertion.name)() {
+    \(raw: body)
+    }
+    """
+}
+
+/// 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]) -> DeclSyntax? {
+  let bodies = assertions.compactMap(conformanceAssertionBody)
+  guard !bodies.isEmpty else {
+    return nil
+  }
+  return """
+    private func _assertTypesConformance() {
+    \(raw: bodies.joined(separator: "\n"))
+    }
+    """
+}
+
+/// 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) -> String? {
+  // Unwrap top-level optionals to the core type, then dedup so each type is asserted once even when
+  // it appears more than once; skip known primitives.
+  var seen: Set<String> = []
+  var distinct: [String] = []
+  for type in assertion.types.map(unwrappedOptional)
+  where !knownConformingPrimitives.contains(type) && seen.insert(type).inserted {
+    distinct.append(type)
+  }
+  guard !distinct.isEmpty else {
+    return nil
+  }
+
+  var lines = ["func \(assertion.name)<T: \(jsConvertibleProtocolName)>(_: T.Type) {}"]
+  lines.append(contentsOf: distinct.map { "\(assertion.name)(\($0).self)" })
+  return lines.joined(separator: "\n")
+}
+
+/// 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)
+}

package/package.json

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

package/apple/Sources/ExpoModulesMacros/DecorateFunctionBuilder.swift

@@ -1,174 +0,0 @@
-import SwiftSyntax
-
-/**
- A `@JS func` collected for **direct JSI binding**. Instead of describing the function with a
- `Function(...)` / `AsyncFunction(...)` DSL entry that the runtime interprets per call,
- `@ExpoModule` synthesizes a `_decorateModule` that binds each such function into the module's JS object
- via the closure-taking `JavaScriptObject.setProperty(_:)`, with the decode-call-encode body
- inlined into the closure. This omits the `[Any]`/`toTuple` dynamic-call path: every argument is
- decoded individually by its static type.
-
- The receiver is the module's real `self` (a module is a singleton instance), so the body calls
- `self.<name>(...)` directly and ignores the JS `this`. An `async` `@JS func` produces an `async`
- closure body and is installed through the async `setProperty(_:)` overload (so JS gets a promise).
- */
-internal struct JSFunction {
-  let swiftName: String
-  let jsName: String
-  let parameters: [FunctionParameterSyntax]
-  /// The declared return type as written, or `nil` when the function returns `Void`/nothing.
-  let returnType: String?
-  let isThrowing: Bool
-  let isAsync: Bool
-
-  init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
-    self.swiftName = funcDecl.name.text
-    self.jsName = jsNameArgument(of: attribute) ?? funcDecl.name.text
-    self.parameters = Array(funcDecl.signature.parameterClause.parameters)
-
-    let declaredReturnType = funcDecl.signature.returnClause?.type
-    self.returnType = isVoidType(declaredReturnType) ? nil : declaredReturnType?.trimmedDescription
-
-    let effectSpecifiers = funcDecl.signature.effectSpecifiers
-    self.isThrowing = effectSpecifiers?.throwsClause?.throwsSpecifier != nil
-    self.isAsync = effectSpecifiers?.asyncSpecifier != nil
-  }
-
-  /**
-   The `#name` host-function body: a `@JavaScriptActor private func` matching the
-   `createFunction` closure shape `(this, arguments) throws -> JavaScriptValue`, threading
-   `appContext`/`runtime` in as parameters. It checks arity, decodes each argument by its static
-   type — primitives through a direct typed accessor (`asDouble()`, …) on a borrowed
-   `JavaScriptUnownedValue`, other types through the
-   `T.getDynamicType()` converter — calls `self.<name>(...)`, and converts the result back to JS.
-   */
-  /// The decode-call-encode statements that form the host-function body, indented with the given
-  /// prefix. Arity guard, then per-argument decode (primitives via a direct typed accessor like
-  /// `asDouble()` on a zero-copy `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`),
-  /// the `self.<name>(...)` call, and the
-  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`).
-  private func bodyStatements(indent: String) -> String {
-    var lines: [String] = []
-
-    lines.append(
-      """
-      guard arguments.count == \(parameters.count) else {
-        throw Exception(name: "InvalidArgumentCount", description: "Function '\(jsName)' expects \(parameters.count) argument(s), but got \\(arguments.count)")
-      }
-      """)
-
-    var callArguments: [String] = []
-    for (index, parameter) in parameters.enumerated() {
-      let type = parameter.type.trimmedDescription
-
-      // Primitives decode through a direct typed accessor (`asDouble()`, etc.) on a borrowed
-      // `JavaScriptUnownedValue` — no owning `JavaScriptValue` allocation, no `jsi::Value` copy, no
-      // `getDynamicType()` allocation, no `Any` boxing, no force-cast — while still validating and
-      // throwing `TypeError` on a mismatch. Other types fall back to the dynamic converter, which
-      // needs an owning value, so they index the buffer directly.
-      if let accessor = fastDecodeAccessor(for: type) {
-        lines.append("let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()")
-      } else {
-        lines.append(
-          "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)")
-      }
-
-      let label = parameter.firstName.text
-      callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")
-    }
-
-    let tryKeyword = (isThrowing || isAsync) ? "try " : ""
-    let awaitKeyword = isAsync ? "await " : ""
-    let callExpression =
-      "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
-
-    if let returnType {
-      lines.append("let result = \(callExpression)")
-      // Primitives encode through `toJavaScriptValue(in:)` (the typed `JavaScriptRepresentable`
-      // conversion) — no `Any`, no dynamic-type allocation. Others go through the dynamic converter.
-      if fastDecodeAccessor(for: returnType) != nil {
-        lines.append("return result.toJavaScriptValue(in: runtime)")
-      } else {
-        lines.append("return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)")
-      }
-    } else {
-      lines.append(callExpression)
-      lines.append("return .undefined")
-    }
-
-    return lines
-      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
-      .map { indent + $0 }
-      .joined(separator: "\n")
-  }
-
-  /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode
-  /// body is inlined directly into the closure passed to the closure-taking `setProperty` overload
-  /// (which creates the host function under the hood) — no separate named binding. For an `async`
-  /// function the body `await`s the call, which selects the async `setProperty` overload (so JS
-  /// receives a promise).
-  ///
-  /// Capture mirrors core's `SyncFunctionDefinition.build`: `self` (the module) is captured
-  /// **strong** — the host-function closure is what keeps the native callable alive for as long as
-  /// JS can invoke it; its lifetime is bounded by the JS VM's garbage collection of the object.
-  /// `appContext` is captured **weak** (and guarded) so it doesn't form a real retain cycle through
-  /// the app context.
-  var decorateStatements: String {
-    return """
-        object.setProperty("\(jsName)") { [weak appContext, self] this, arguments in
-          guard let appContext else {
-            throw Exceptions.AppContextLost()
-          }
-      \(bodyStatements(indent: "    "))
-        }
-      """
-  }
-}
-
-/**
- The single generated function that decorates the module's JS object. Core supplies the object;
- this binds every `@JS func` into it via one inlined `setProperty` closure per function. Mirrors
- core's `ObjectDefinition.decorate(object:)`, including its `borrowing` object parameter (it
- mutates through the reference without reassigning or taking ownership). Named `_decorateModule`
- with the leading-underscore convention for synthesized members the **runtime calls by name**; the
- `ExpoModule` suffix names the `@ExpoModule` macro it came from (a shared object's counterpart is
- `_decorateSharedObject`).
- */
-internal func buildDecorateJavaScriptObject(functions: [JSFunction]) -> DeclSyntax {
-  let body = functions.map { $0.decorateStatements }.joined(separator: "\n")
-  return """
-    @JavaScriptActor
-    public func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime, appContext: AppContext) throws {
-    \(raw: body)
-    }
-    """
-}
-
-/// The throwing `JavaScriptUnownedValue` accessor that decodes the given primitive type directly,
-/// bypassing the dynamic-type converter (`asDouble()` for `Double`, etc.). Returns `nil` for
-/// types without a dedicated accessor — arrays, records, optionals, shared objects, other numeric
-/// widths — which decode through `getDynamicType().cast(...)`.
-private func fastDecodeAccessor(for type: String) -> String? {
-  switch type {
-  case "Bool":
-    return "asBool"
-  case "Int":
-    return "asInt"
-  case "Double":
-    return "asDouble"
-  case "String":
-    return "asString"
-  default:
-    return nil
-  }
-}
-
-/// True when a return clause is absent or written as `Void` / `()` — i.e. the function returns
-/// nothing JS-visible, so the binding returns `.undefined`.
-private func isVoidType(_ type: TypeSyntax?) -> Bool {
-  guard let type else {
-    return true
-  }
-  let text = type.trimmedDescription
-  return text == "Void" || text == "()"
-}