expo-modules-macros 0.18.0 → 0.19.1

package/apple/Sources/ExpoModulesMacros/ClosureArguments.swift

@@ -93,7 +93,8 @@ internal func argumentDecodeStatements(
   // A specifier such as `borrowing` belongs to the parameter, not to the type that decodes.
   let type = SpecifiedType(type).type
   guard let closure = JSClosureType(type) else {
-    return ["let \(name) = try \(decodeCall(type.trimmedDescription, from: valueExpression))"]
+    let decode = decodeCall(type.trimmedDescription, freeForm: freeFormConversion(of: type), from: valueExpression)
+    return ["let \(name) = try \(decode)"]
   }
   return closureArgumentStatements(closure, into: name, from: valueExpression)
 }
@@ -279,7 +280,7 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
   }
 
   // The closure's parameters are encoded and its result is decoded, so neither can be another
-  // closure or a free-form type.
+  // closure or a type that mentions `Any`, in any shape.
   let returnType = functionType.returnClause.type
   for type in closure.parameters.map(\.type) + [returnType] {
     if let nested = firstFunctionType(in: type) {
@@ -290,7 +291,7 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
             "A @JS closure argument can't take or return another closure.",
             id: "js-closure-nested"
           )))
-    } else if isFreeFormBoundaryType(type.trimmedDescription) {
+    } else if mentionsFreeFormAny(type) {
       context.diagnose(
         Diagnostic(
           node: type,

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -19,6 +19,8 @@ internal struct JSFunction {
   let parameters: [FunctionParameterSyntax]
   /// The declared return type as written, or `nil` when the function returns `Void`/nothing.
   let returnType: String?
+  /// How the return value encodes when its type mentions `Any`, or `nil` for any other type.
+  let returnFreeForm: FreeFormConversion?
   let isThrowing: Bool
   let isAsync: Bool
 
@@ -29,6 +31,7 @@ internal struct JSFunction {
 
     let declaredReturnType = funcDecl.signature.returnClause?.type
     self.returnType = isVoidType(declaredReturnType) ? nil : declaredReturnType?.trimmedDescription
+    self.returnFreeForm = declaredReturnType.flatMap(freeFormConversion(of:))
 
     let effectSpecifiers = funcDecl.signature.effectSpecifiers
     self.isThrowing = effectSpecifiers?.throwsClause?.throwsSpecifier != nil
@@ -220,9 +223,10 @@ internal struct JSFunction {
     return lines
   }
 
-  /// Encode the `result` local back to JS and return it through `JavaScriptEncodable.encode`, the same
-  /// for every type. Unlike the decode side there's no primitive fast path: `encode` produces the same
-  /// value as the primitive's `toJavaScriptValue(in:)` except for `Int`/`UInt`, where it range-checks
+  /// Encode the `result` local back to JS and return it through `JavaScriptEncodable.encode` (or, for a
+  /// type that mentions `Any`, the matching `JavaScriptValue` free-form method). Unlike the decode side
+  /// there's no primitive fast path: `encode` produces the same value as the primitive's
+  /// `toJavaScriptValue(in:)` except for `Int`/`UInt`, where it range-checks
   /// and throws instead of silently encoding an out-of-safe-range value as a lossy number — the
   /// catchable error is the right behavior, and matches how non-primitive integers already encode. A
   /// no-return function returns `.undefined()` instead.
@@ -237,7 +241,7 @@ internal struct JSFunction {
     guard let returnType else {
       return ["return .undefined()"]
     }
-    let encode = "try \(expressionType(returnType)).encode(result, in: runtime)"
+    let encode = "try \(encodeCall(returnType, freeForm: returnFreeForm, of: "result"))"
     if isAsync {
       return [
         "return try await runtime.execute {",
@@ -290,7 +294,8 @@ internal struct JSFunction {
 /// The receiver (see `Receiver`) is the module's `self` for a module binding, or the per-call `_self`
 /// unwrapped from the JS `this` for a shared object. The getter reads `<callee>.<name>` and the setter
 /// writes `<callee>.<name> = …`. Decode/encode of the value go through `JavaScriptDecodable.decode` /
-/// `JavaScriptEncodable.encode`, the same uniform path as functions.
+/// `JavaScriptEncodable.encode` (or the free-form methods for a type that mentions `Any`), the same
+/// path as functions.
 internal struct JSProperty {
   let swiftName: String
   let jsName: String
@@ -298,6 +303,8 @@ internal struct JSProperty {
   /// 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?
+  /// How the value converts when its type mentions `Any`, or `nil` for any other type.
+  let freeForm: FreeFormConversion?
   /// 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
@@ -325,7 +332,7 @@ internal struct JSProperty {
     // no static type to call `encode` on, so the value's own `toJavaScriptValue(in:)` is the fallback.
     let getEncode: String
     if let valueType {
-      getEncode = "return try \(expressionType(valueType)).encode(\(callee).\(swiftName), in: runtime)"
+      getEncode = "return try \(encodeCall(valueType, freeForm: freeForm, of: "\(callee).\(swiftName)"))"
     } else {
       getEncode = "return \(callee).\(swiftName).toJavaScriptValue(in: runtime)"
     }
@@ -337,7 +344,8 @@ internal struct JSProperty {
     // 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 = "\(callee).\(swiftName) = try \(decodeCall(valueType, from: "arguments.unownedValue(at: 0)"))"
+      let decode = decodeCall(valueType, freeForm: freeForm, from: "arguments.unownedValue(at: 0)")
+      let setDecode = "\(callee).\(swiftName) = try \(decode)"
       lines.append(
         accessorClosure(
           descriptorName, "set", receiver: receiver, body: "\(unwrap)\(setDecode)\nreturn .undefined()"))

package/apple/Sources/ExpoModulesMacros/FreeFormTypes.swift

@@ -1,74 +1,123 @@
 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.
+/// Recognition of the free-form (`Any`-bearing) boundary types and the conversions the macros emit 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. They convert through
+/// the `JavaScriptValue` free-form methods instead: the three free-form shapes (`Any`, `[Any]` and
+/// `[String: Any]`), optionally wrapped in one optional, use the dedicated `decodeAny…` and
+/// `encodeAny…` methods, and every other type built from `Any`, arrays, `String`-keyed dictionaries and
+/// optionals uses the generic `decodeAny(_:as:in:)` and `encodeAny(_:in:)`.
 ///
-/// 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:)`.
+/// Shared across the macro pipeline: `@Record` properties and `@JS` arguments, return values and
+/// properties convert through `FreeFormConversion` (the `@JS` bindings by way of
+/// `MacroHelpers.decodeCall` and `encodeCall`), `TypeConformanceAssertion` skips the free-form shapes,
+/// and `JSMacro` uses them for its diagnostics.
 
 /// 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 JS wrapper of the same shape
-/// (`JavaScriptArray` for an array, `JavaScriptObject` for a dictionary, `JavaScriptValue` for an
-/// untyped value). The wrappers conform to the codable protocols and keep the value unconverted; a
-/// non-copyable `JavaScriptValue` cannot be an element of a Swift array or dictionary, so the container
-/// shapes map to a wrapper rather than to a container of values. Keyed by the free-form type's
-/// normalized spelling.
-private let typedFreeFormReplacements: [String: String] = [
-  "Any": "JavaScriptValue",
-  "[Any]": "JavaScriptArray",
-  "[String:Any]": "JavaScriptObject",
-]
-
-/// 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.
+/// True when a boundary type (as written) is exactly one of the free-form shapes, ignoring internal
+/// whitespace so `[String: Any]` and `[String :Any]` both match. An optional or nested free-form type
+/// doesn't match; `freeFormConversion(of:)` recognizes those.
 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 (the JS wrapper of the same shape),
-/// 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 }
 }
 
+/// How a type that mentions `Any` converts on the JS-value paths. Such a type can't conform to the JS
+/// codable protocols, so it converts through the `JavaScriptValue` free-form methods.
+internal enum FreeFormConversion {
+  /// `Any`, `[Any]` or `[String: Any]`, wrapped in at most one optional: the dedicated methods for
+  /// that shape, named by `decodeMethod` and `encodeMethod`. The optional is handled around them.
+  case shape(decodeMethod: String, encodeMethod: String, isOptional: Bool, isBareAny: Bool)
+  /// Any other type that mentions `Any`: the generic `decodeAny(_:as:in:)` and `encodeAny(_:in:)`.
+  case generic
+
+  /// Classifies a type that mentions `Any`; the caller checks `isConvertibleFreeFormType` first.
+  init(type: TypeSyntax) {
+    let wrapped = optionalWrappedType(type)
+    switch freeFormShape(of: wrapped ?? type) {
+    case .any:
+      self = .shape(
+        decodeMethod: "decodeAny",
+        encodeMethod: "encodeAny",
+        isOptional: wrapped != nil,
+        isBareAny: true
+      )
+    case .array:
+      self = .shape(
+        decodeMethod: "decodeAnyArray",
+        encodeMethod: "encodeAnyArray",
+        isOptional: wrapped != nil,
+        isBareAny: false
+      )
+    case .dictionary:
+      self = .shape(
+        decodeMethod: "decodeAnyDictionary",
+        encodeMethod: "encodeAnyDictionary",
+        isOptional: wrapped != nil,
+        isBareAny: false
+      )
+    case nil:
+      self = .generic
+    }
+  }
+
+  /// True for `Any` itself, optional or not.
+  var isBareAny: Bool {
+    guard case .shape(_, _, _, let isBareAny) = self else {
+      return false
+    }
+    return isBareAny
+  }
+
+  /// The decode expression, as it appears after `try`, for a `@JS` value read from `valueExpression`
+  /// (a `JavaScriptUnownedValue`) into `type` (spelled in expression position). For an optional
+  /// free-form shape, `undefined` and `null` map to `nil` around the dedicated method, just like
+  /// `Optional.decode`. The generic method takes an owning value, so the borrowed one is copied first.
+  func decodeExpression(of valueExpression: String, as type: String) -> String {
+    switch self {
+    case .shape(let decodeMethod, _, let isOptional, _):
+      let call = "JavaScriptValue.\(decodeMethod)(\(valueExpression), in: runtime)"
+      return isOptional ? "\(valueExpression).isUndefined() || \(valueExpression).isNull() ? nil : \(call)" : call
+    case .generic:
+      return "JavaScriptValue.decodeAny(\(valueExpression).copied(in: runtime), as: \(type).self, in: runtime)"
+    }
+  }
+
+  /// The encode expression, as it appears after `try`, for the `@JS` value `valueExpression`. An
+  /// optional free-form shape encodes through the generic `encodeAny(_:in:)`, which encodes `nil` as
+  /// `null` and unwraps any other value, so the expression (which may call a computed getter) is
+  /// evaluated only once.
+  func encodeExpression(of valueExpression: String) -> String {
+    switch self {
+    case .shape(_, let encodeMethod, false, _):
+      return "JavaScriptValue.\(encodeMethod)(\(valueExpression), in: runtime)"
+    case .shape(_, _, true, _), .generic:
+      // The explicit `as Any` keeps an optional value from warning about its implicit coercion.
+      return "JavaScriptValue.encodeAny(\(valueExpression) as Any, in: runtime)"
+    }
+  }
+}
+
+/// The conversion for a boundary type that mentions `Any`, or `nil` when the type doesn't mention
+/// `Any`, or holds it in a shape the free-form methods can't convert (see `isConvertibleFreeFormType`),
+/// which the caller diagnoses.
+internal func freeFormConversion(of type: TypeSyntax) -> FreeFormConversion? {
+  guard mentionsFreeFormAny(type), isConvertibleFreeFormType(type) else {
+    return nil
+  }
+  return FreeFormConversion(type: type)
+}
+
 /// 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.

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -148,99 +148,46 @@ private func diagnoseParameterSpecifiers(
   }
 }
 
-/// Emits the free-form (`Any` / `[Any]` / `[String: Any]`) diagnostics for a `@JS` declaration.
+/// Emits the free-form (`Any`-bearing) diagnostics for a `@JS` declaration.
 ///
-/// A free-form type is only supported crossing the boundary as an **argument**, decoded through
-/// `JavaScriptValue.decodeAny…`; there is no free-form encode, so any position that encodes is a hard
-/// error. That means:
-/// - a function/constructor **parameter** typed free-form gets a warning steering to
-///   `JavaScriptValue` (the type-safe alternative), but compiles;
-/// - a function **return** typed free-form is an error (it would need to encode);
-/// - a **property** typed free-form is an error regardless of settability, because its getter always
-///   encodes.
+/// A type built from `Any`, arrays, `String`-keyed dictionaries and optionals converts through the
+/// `JavaScriptValue` free-form methods in every position (see `FreeFormConversion`). That means:
+/// - a free-form argument, return value or property needs no diagnostic: it decodes through
+///   `decodeAny…` and encodes through `encodeAny…`;
+/// - a type that holds `Any` in any other shape (`[Int: Any]`, `Set<[String: Any]>`) is an error in
+///   every position, since the free-form methods never produce or accept it.
 ///
-/// Types are matched by their written spelling on the type node, so the diagnostic points at the
-/// offending type in the user's source.
+/// Types are matched on the type node, so the diagnostic points at the offending type in the user's
+/// source. A closure type is left to `diagnoseClosureTypes`.
 private func diagnoseFreeFormTypes(
   in declaration: some DeclSyntaxProtocol,
   in context: some MacroExpansionContext
 ) {
+  var types: [TypeSyntax] = []
   if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
-    warnFreeFormArguments(funcDecl.signature.parameterClause.parameters, in: context)
-    if let returnType = funcDecl.signature.returnClause?.type,
-      isFreeFormBoundaryType(returnType.trimmedDescription) {
-      context.diagnose(
-        Diagnostic(node: returnType, message: freeFormReturnError(for: returnType.trimmedDescription)))
+    types = funcDecl.signature.parameterClause.parameters.map { SpecifiedType($0.type).type }
+    if let returnType = funcDecl.signature.returnClause?.type {
+      types.append(returnType)
     }
-    return
-  }
-
-  // A constructor decodes its arguments exactly like a function; it has no return value to encode, so
-  // only the argument warning applies.
-  if let initDecl = declaration.as(InitializerDeclSyntax.self) {
-    warnFreeFormArguments(initDecl.signature.parameterClause.parameters, in: context)
-    return
-  }
-
-  if let varDecl = declaration.as(VariableDeclSyntax.self),
-    let type = varDecl.bindings.first?.typeAnnotation?.type,
-    isFreeFormBoundaryType(type.trimmedDescription) {
-    context.diagnose(
-      Diagnostic(node: type, message: freeFormPropertyError(for: type.trimmedDescription)))
+  } else if let initDecl = declaration.as(InitializerDeclSyntax.self) {
+    // A constructor decodes its arguments exactly like a function and has no return value.
+    types = initDecl.signature.parameterClause.parameters.map { SpecifiedType($0.type).type }
+  } else if let varDecl = declaration.as(VariableDeclSyntax.self),
+    let type = varDecl.bindings.first?.typeAnnotation?.type {
+    types = [type]
   }
-}
 
-/// The tail of a free-form encode error: the typed wrapper of the same shape (`JavaScriptArray`,
-/// `JavaScriptObject`) when there is one, otherwise the plain `JavaScriptValue` passthrough suggestion.
-private func suggestedAlternative(for freeFormType: String) -> String {
-  if let reshaped = typedFreeFormReplacement(for: freeFormType), reshaped != "JavaScriptValue" {
-    return "Use '\(reshaped)', or 'JavaScriptValue' to pass a JS value through unchanged."
-  }
-  return "Use a concrete type, or 'JavaScriptValue' to pass a JS value through unchanged."
-}
-
-/// Emits the steering warning for each free-form parameter in a list. Shared by the function and
-/// constructor cases, which both decode their arguments through the same path.
-private func warnFreeFormArguments(
-  _ parameters: FunctionParameterListSyntax,
-  in context: some MacroExpansionContext
-) {
-  for parameter in parameters {
-    // Matched on the bare type: `borrowing [String: Any]` decodes as free-form too.
-    let type = SpecifiedType(parameter.type).type.trimmedDescription
-    guard let suggested = typedFreeFormReplacement(for: type) else {
-      continue
-    }
+  for type in types
+  where mentionsFreeFormAny(type) && !isConvertibleFreeFormType(type) && !containsFunctionType(type) {
     context.diagnose(
-      Diagnostic(
-        node: parameter.type,
-        message: freeFormArgumentWarning(for: type, suggesting: suggested)))
+      Diagnostic(node: type, message: unconvertibleFreeFormError(for: type.trimmedDescription)))
   }
 }
 
-private func freeFormArgumentWarning(
-  for freeFormType: String,
-  suggesting suggestedType: String
-) -> JSDiagnosticMessage {
+private func unconvertibleFreeFormError(for type: String) -> JSDiagnosticMessage {
   return JSDiagnosticMessage(
-    "Prefer '\(suggestedType)' over the free-form '\(freeFormType)' for a @JS argument. Free-form decoding boxes every value as 'Any' (slower, no static typing); '\(suggestedType)' keeps the JS value inspectable without converting it.",
-    id: "js-free-form-argument",
-    severity: .warning
-  )
-}
-
-private func freeFormReturnError(for freeFormType: String) -> JSDiagnosticMessage {
-  return JSDiagnosticMessage(
-    "A @JS function can't return the free-form '\(freeFormType)': there's no way to encode an untyped value back to JavaScript. \(suggestedAlternative(for: freeFormType))",
-    id: "js-free-form-return",
-    severity: .error
-  )
-}
-
-private func freeFormPropertyError(for freeFormType: String) -> JSDiagnosticMessage {
-  return JSDiagnosticMessage(
-    "A @JS property can't have the free-form '\(freeFormType)': its getter would have to encode an untyped value back to JavaScript, which isn't supported. \(suggestedAlternative(for: freeFormType))",
-    id: "js-free-form-property",
+    "A @JS member can't use the type '\(type)': a type holding 'Any' converts to and from JavaScript only when it's built from 'Any', arrays, String-keyed dictionaries and optionals. Use one of those shapes, such as '[String: Any]', or 'JavaScriptValue' to keep the JavaScript value unconverted.",
+    id: "js-free-form-unsupported",
     severity: .error
   )
 }
@@ -289,9 +236,10 @@ private struct BoundaryMember {
 /// function contributes its parameter types (decodable) and its return type when non-Void (encodable);
 /// a property contributes its value type as encodable (the getter) and also as decodable when settable
 /// (the setter). Composed types (`[Int]`, `String?`, …) are kept verbatim, their conditional
-/// conformances transitively constraining the elements. 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).
+/// conformances transitively constraining the elements. A type that mentions `Any` is left out: it
+/// converts through the free-form methods, or is diagnosed by `diagnoseFreeFormTypes`. Returns `nil`
+/// for declaration kinds `@JS` doesn't read types from, a property whose type isn't spelled out (a
+/// syntactic macro can't recover it), or one whose type mentions `Any`.
 private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> BoundaryMember? {
   if let funcDecl = declaration.as(FunctionDeclSyntax.self) {
     // A closure argument moves data the other way: JS receives its parameters and returns its result.
@@ -307,21 +255,25 @@ private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> Boundary
         continue
       }
       guard let closure = JSClosureType(specified.type) else {
-        if !containsFunctionType(specified.type) {
+        if !containsFunctionType(specified.type) && !mentionsFreeFormAny(specified.type) {
           decodableTypes.append(specified.type.trimmedDescription)
         }
         continue
       }
-      for parameter in closure.parameters where !containsFunctionType(parameter.type) {
+      // A closure type that mentions `Any` is reported by `diagnoseClosureTypes` instead.
+      for parameter in closure.parameters
+      where !containsFunctionType(parameter.type) && !mentionsFreeFormAny(parameter.type) {
         callbackArgumentTypes.append(parameter.type.trimmedDescription)
       }
-      if let returnType = closure.returnType, !containsFunctionType(closure.functionType.returnClause.type) {
+      let closureReturnType = closure.functionType.returnClause.type
+      if let returnType = closure.returnType,
+        !containsFunctionType(closureReturnType) && !mentionsFreeFormAny(closureReturnType) {
         decodableTypes.append(returnType)
       }
     }
     let returnType = funcDecl.signature.returnClause?.type
     let encodableType = returnType.flatMap {
-      isVoidType($0) || containsFunctionType($0) ? nil : $0.trimmedDescription
+      isVoidType($0) || containsFunctionType($0) || mentionsFreeFormAny($0) ? nil : $0.trimmedDescription
     }
     return BoundaryMember(
       name: funcDecl.name.text,
@@ -338,7 +290,11 @@ private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> Boundary
     let type = binding.typeAnnotation?.type,
     !containsFunctionType(type) {
     // A `let`, or a `var` with no setter, is read-only (encodable only). A settable `var` is also
-    // decoded on write, so its value type is asserted in both directions.
+    // decoded on write, so its value type is asserted in both directions. A type that mentions `Any`
+    // converts through the free-form methods instead, so it isn't asserted at all.
+    guard !mentionsFreeFormAny(type) else {
+      return nil
+    }
     let typeText = type.trimmedDescription
     let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
     let isSettable = isVar && bindingIsSettable(binding)

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -366,17 +366,27 @@ internal func expressionType(_ type: String) -> String {
 }
 
 /// The decode expression for a boundary type read from `valueExpression` (a `JavaScriptUnownedValue`),
-/// as it appears after `try`. A free-form type (`Any`, `[Any]`, `[String: Any]`) can't conform to
-/// `JavaScriptDecodable`, so it decodes through the dedicated `JavaScriptValue.decodeAny…` entry point
-/// keyed to its shape; every other type decodes through its own static `decode`, spelled in expression
-/// position (`T!` rewritten to `T?`).
-internal func decodeCall(_ type: String, from valueExpression: String) -> String {
-  if let method = freeFormDecodeMethod(for: type) {
-    return "JavaScriptValue.\(method)(\(valueExpression), in: runtime)"
+/// as it appears after `try`. A type that mentions `Any` can't conform to `JavaScriptDecodable`, so it
+/// decodes through the `JavaScriptValue` free-form methods its `freeForm` conversion names; every other
+/// type decodes through its own static `decode`, spelled in expression position (`T!` rewritten to
+/// `T?`).
+internal func decodeCall(_ type: String, freeForm: FreeFormConversion?, from valueExpression: String) -> String {
+  if let freeForm {
+    return freeForm.decodeExpression(of: valueExpression, as: expressionType(type))
   }
   return "\(expressionType(type)).decode(\(valueExpression), in: runtime)"
 }
 
+/// The encode expression for the native value `valueExpression` of a boundary type, as it appears
+/// after `try`. The counterpart of `decodeCall`: a type that mentions `Any` encodes through the
+/// `JavaScriptValue` free-form methods, and every other type through its own static `encode`.
+internal func encodeCall(_ type: String, freeForm: FreeFormConversion?, of valueExpression: String) -> String {
+  if let freeForm {
+    return freeForm.encodeExpression(of: valueExpression)
+  }
+  return "\(expressionType(type)).encode(\(valueExpression), in: runtime)"
+}
+
 // MARK: - Escaped names
 
 /// `name` without the backticks that escape it: `` `default` `` becomes `default`. Swift needs the
@@ -429,6 +439,8 @@ internal func collectProperties(
       swiftName: swiftName,
       jsName: jsNameOverride ?? withoutBackticks(swiftName),
       valueType: valueType,
+      // A literal-inferred type never mentions `Any`, so only an explicit annotation can be free-form.
+      freeForm: binding.typeAnnotation.flatMap { freeFormConversion(of: $0.type) },
       isSettable: isVar && bindingIsSettable(binding)
     )
   }

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -143,56 +143,6 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
 
 // MARK: - Property model
 
-/**
- How a property whose type mentions `Any` converts on the JS-value paths. Such a type can't conform to
- the JS codable protocols, so the property converts through the `JavaScriptValue` free-form methods.
- */
-private enum FreeFormConversion {
-  /// `Any`, `[Any]` or `[String: Any]`, wrapped in at most one optional: the dedicated methods for
-  /// that shape, named by `decodeMethod` and `encodeMethod`. The optional is handled around them.
-  case shape(decodeMethod: String, encodeMethod: String, isOptional: Bool, isBareAny: Bool)
-  /// Any other type that mentions `Any`: the generic `decodeAny(_:as:in:)` and `encodeAny(_:in:)`.
-  case generic
-
-  /// Classifies a type that mentions `Any`; the caller checks `isConvertibleFreeFormType` first.
-  init(type: TypeSyntax) {
-    let wrapped = optionalWrappedType(type)
-    switch freeFormShape(of: wrapped ?? type) {
-    case .any:
-      self = .shape(
-        decodeMethod: "decodeAny",
-        encodeMethod: "encodeAny",
-        isOptional: wrapped != nil,
-        isBareAny: true
-      )
-    case .array:
-      self = .shape(
-        decodeMethod: "decodeAnyArray",
-        encodeMethod: "encodeAnyArray",
-        isOptional: wrapped != nil,
-        isBareAny: false
-      )
-    case .dictionary:
-      self = .shape(
-        decodeMethod: "decodeAnyDictionary",
-        encodeMethod: "encodeAnyDictionary",
-        isOptional: wrapped != nil,
-        isBareAny: false
-      )
-    case nil:
-      self = .generic
-    }
-  }
-
-  /// True for `Any` itself, optional or not.
-  var isBareAny: Bool {
-    guard case .shape(_, _, _, let isBareAny) = self else {
-      return false
-    }
-    return isBareAny
-  }
-}
-
 /**
  A single record property discovered on the type, paired with everything the synthesized
  conversions need: its property name, its written type, and how the source may omit it.

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -88,22 +88,23 @@ internal func directionalConformanceAssertion(
   // Build the generic parameter list and the matching call arguments in lockstep: one `A0…` slot
   // constrained `JavaScriptDecodable` per argument, one `E0…` slot constrained `JavaScriptEncodable`
   // per closure-argument parameter, and a single `Return` slot constrained `JavaScriptEncodable` for
-  // the return/getter value (there's only ever one, so it isn't indexed).
+  // the return/getter value (there's only ever one, so it isn't indexed). Every slot suppresses
+  // `Copyable`, so a non-copyable boundary type such as `JavaScriptValue` can fill it.
   var parameters: [String] = []
   var typeParameters: [String] = []
   var arguments: [String] = []
   for (index, type) in decodables.enumerated() {
-    parameters.append("A\(index): \(javaScriptDecodableProtocolName)")
+    parameters.append("A\(index): \(javaScriptDecodableProtocolName) & ~Copyable")
     typeParameters.append("_: A\(index).Type")
     arguments.append("\(type).self")
   }
   for (index, type) in callbackArguments.enumerated() {
-    parameters.append("E\(index): \(javaScriptEncodableProtocolName)")
+    parameters.append("E\(index): \(javaScriptEncodableProtocolName) & ~Copyable")
     typeParameters.append("_: E\(index).Type")
     arguments.append("\(type).self")
   }
   if let encodable {
-    parameters.append("Return: \(javaScriptEncodableProtocolName)")
+    parameters.append("Return: \(javaScriptEncodableProtocolName) & ~Copyable")
     typeParameters.append("_: Return.Type")
     arguments.append("\(encodable).self")
   }
@@ -143,10 +144,11 @@ internal func typeConformanceAssertions(
 }
 
 /// 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`.
+/// exactly-free-form type (converted through the `JavaScriptValue` free-form methods) and a
+/// known-conforming primitive both return `nil`; everything else is unwrapped of trailing optionals
+/// and asserted. Shared with `@Event`, where an *optional* free-form type (`[String: Any]?`) is kept
+/// and asserted for a clean diagnostic. `@JS` leaves out every type that mentions `Any` before it gets
+/// here.
 internal func assertableBoundaryType(_ type: String) -> String? {
   guard !isFreeFormBoundaryType(type) else {
     return nil