expo-modules-macros 0.17.0 → 0.19.0

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -72,6 +72,9 @@ internal func isConcurrentJSMember(_ decl: DeclSyntaxProtocol) -> Bool {
 /// True if the type is written as an optional: `T?`, `T!`, or the explicit `Optional<T>`. Used to
 /// decide argument requiredness (an optional parameter may be omitted) and record-field nullability.
 internal func isOptionalType(_ type: TypeSyntax) -> Bool {
+  if let attributed = type.as(AttributedTypeSyntax.self) {
+    return isOptionalType(attributed.baseType)
+  }
   if type.is(OptionalTypeSyntax.self) || type.is(ImplicitlyUnwrappedOptionalTypeSyntax.self) {
     return true
   }
@@ -81,6 +84,39 @@ internal func isOptionalType(_ type: TypeSyntax) -> Bool {
   return false
 }
 
+/// A parameter's type split from the specifiers written in front of it (`borrowing`, `consuming`,
+/// `sending`, `inout`, `isolated`, ...). The specifiers aren't part of the type: the decode call and
+/// the conformance assertion need the bare type (`borrowing Point.decode(...)` isn't valid Swift), and
+/// a decoded argument is a fresh owned value, so it can be passed under any ownership convention.
+internal struct SpecifiedType {
+  /// The type without its specifiers.
+  let type: TypeSyntax
+  /// The specifiers written before the type, in source order.
+  let specifiers: [String]
+
+  init(_ type: TypeSyntax) {
+    if let attributed = type.as(AttributedTypeSyntax.self), !attributed.specifiers.isEmpty {
+      self.specifiers = attributed.specifiers.map(\.trimmedDescription)
+      self.type =
+        attributed.attributes.isEmpty
+        ? attributed.baseType : TypeSyntax(attributed.with(\.specifiers, []))
+    } else {
+      self.specifiers = []
+      self.type = type
+    }
+  }
+
+  /// The first specifier a decoded argument can't honor: `inout` (JavaScript can't observe a write
+  /// back) or `isolated` (the argument doesn't carry an isolation).
+  var unsupportedSpecifier: String? {
+    return specifiers.first { !ownershipSpecifiers.contains($0) }
+  }
+}
+
+/// The ownership specifiers a parameter may carry. They only change how the argument is passed, which
+/// a fresh decoded value satisfies either way.
+internal let ownershipSpecifiers: Set<String> = ["borrowing", "consuming", "sending", "__shared", "__owned"]
+
 /// The type wrapped by one optional layer (`T?`, `T!` or `Optional<T>`), or `nil` when the type isn't
 /// optional.
 internal func optionalWrappedType(_ type: TypeSyntax) -> TypeSyntax? {
@@ -330,17 +366,53 @@ 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
+/// backticks in every identifier position, but a name JavaScript sees (a JS member name, an event
+/// name, a record key) is the bare name.
+internal func withoutBackticks(_ name: String) -> String {
+  var name = Substring(name)
+  while name.first == "`" {
+    name.removeFirst()
+  }
+  while name.last == "`" {
+    name.removeLast()
+  }
+  return String(name)
+}
+
+/// A generated identifier built from a member's name, such as `countDescriptor` from `count`. The
+/// affixes join the bare name, and an escaped name keeps the backticks around the whole result
+/// (`` `class` `` gives `` `classDescriptor` ``), since the bare name may not be an identifier on
+/// its own.
+internal func derivedIdentifier(from name: String, prefix: String = "", suffix: String = "") -> String {
+  let bareName = withoutBackticks(name)
+  let identifier = prefix + bareName + suffix
+  return bareName == name ? identifier : "`\(identifier)`"
+}
+
 // MARK: - @JS property collection
 
 /// Collects the `@JS var` bindings of a declaration into `JSProperty` values for direct JSI binding.
@@ -365,8 +437,10 @@ internal func collectProperties(
       ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
     return JSProperty(
       swiftName: swiftName,
-      jsName: jsNameOverride ?? 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

@@ -95,7 +95,7 @@ public struct RecordMacro: MemberMacro, ExtensionMacro {
         members.append(defaultInit)
       }
     }
-    if !existingInitLabels.contains(properties.map { $0.name }) {
+    if !existingInitLabels.contains(properties.map { $0.key }) {
       members.append(memberwiseInit(properties: properties))
     }
     members.append(fromJSObjectFactory(properties: properties))
@@ -143,62 +143,13 @@ 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 (also the JS key), its written type, and how the
- source may omit it.
+ conversions need: its property name, its written type, and how the source may omit it.
  */
 private struct RecordProperty {
+  /// The property name as written, backticks included for an escaped name (`` `default` ``), since
+  /// every identifier position in the generated code needs them.
   let name: String
   /// The property's declared type, verbatim (e.g. `String`, `Int`, `String?`). Used to build the
   /// memberwise-init parameter and as the receiver of the per-property `decode`/`encode` (and, on the
@@ -222,6 +173,12 @@ private struct RecordProperty {
   var isRequired: Bool {
     return !hasDefault && !isOptional
   }
+
+  /// The key the property reads from and writes to, in both the JS object and the dictionary: the
+  /// name without escaping backticks.
+  var key: String {
+    return withoutBackticks(name)
+  }
 }
 
 /**
@@ -414,7 +371,7 @@ private func factoryBody(properties: [RecordProperty], readLines: [String]) -> S
 private func jsObjectReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
   for property in properties {
-    let valueVar = "\(property.name)JSValue"
+    let valueVar = derivedIdentifier(from: property.name, suffix: "JSValue")
     let exprType = expressionType(property.type)
     let decode: String
     switch property.freeForm {
@@ -426,10 +383,10 @@ private func jsObjectReadLines(properties: [RecordProperty]) -> [String] {
     case nil:
       decode = "try \(exprType).decode(\(valueVar), in: runtime)"
     }
-    lines.append("  let \(valueVar) = object.getProperty(\"\(property.name)\")")
+    lines.append("  let \(valueVar) = object.getProperty(\"\(property.key)\")")
     if property.isRequired {
       lines.append("  guard !\(valueVar).isUndefined() else {")
-      lines.append("    throw RecordPropertyRequiredException(\"\(property.name)\")")
+      lines.append("    throw RecordPropertyRequiredException(\"\(property.key)\")")
       lines.append("  }")
       lines.append("  let \(property.name) = \(decode)")
     } else if property.isOptional {
@@ -449,16 +406,16 @@ private func jsObjectReadLines(properties: [RecordProperty]) -> [String] {
 private func dictionaryReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
   for property in properties {
-    let valueVar = "\(property.name)Value"
+    let valueVar = derivedIdentifier(from: property.name, suffix: "Value")
     let exprType = expressionType(property.type)
     let isBareAny = property.freeForm?.isBareAny == true
     let cast = isBareAny
       ? valueVar
       : "try \(exprType).getDynamicType().cast(\(valueVar), appContext: appContext) as! \(exprType)"
-    lines.append("  let \(valueVar) = dictionary[\"\(property.name)\"]")
+    lines.append("  let \(valueVar) = dictionary[\"\(property.key)\"]")
     if property.isRequired {
       lines.append("  guard let \(valueVar) else {")
-      lines.append("    throw RecordPropertyRequiredException(\"\(property.name)\")")
+      lines.append("    throw RecordPropertyRequiredException(\"\(property.key)\")")
       lines.append("  }")
       lines.append("  let \(property.name) = \(cast)")
     } else if property.isOptional {
@@ -483,7 +440,7 @@ private func toDictionaryMethod(properties: [RecordProperty], inheritsRecord: Bo
     lines.append("  var dictionary: [String: Any] = [:]")
   }
   for property in properties {
-    lines.append("  dictionary[\"\(property.name)\"] = self.\(property.name)")
+    lines.append("  dictionary[\"\(property.key)\"] = self.\(property.name)")
   }
   lines.append("  return dictionary")
   let body = lines.joined(separator: "\n")
@@ -537,7 +494,7 @@ private func toObjectMethod(properties: [RecordProperty], inheritsRecord: Bool)
     case nil:
       encode = "try \(exprType).encode(self.\(property.name), in: runtime)"
     }
-    lines.append("  object.setProperty(\"\(property.name)\", value: \(encode))")
+    lines.append("  object.setProperty(\"\(property.key)\", value: \(encode))")
   }
   lines.append("  return object")
   let body = lines.joined(separator: "\n")
@@ -567,7 +524,7 @@ private func initializerParameterLabels(of declaration: some DeclGroupSyntax) ->
     }
     let labels = initDecl.signature.parameterClause.parameters.map { parameter in
       // `firstName` is the external label (or `_`); fall back to the internal name when omitted.
-      let label = parameter.firstName.text
+      let label = withoutBackticks(parameter.firstName.text)
       return label == "_" ? "" : label
     }
     signatures.append(labels)

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -39,7 +39,7 @@ public struct SharedObjectMacro: MemberMacro {
     }
 
     let typeName = classDecl.name.text
-    let jsName = jsNameArgument(of: node) ?? typeName
+    let jsName = jsNameArgument(of: node) ?? withoutBackticks(typeName)
 
     // `@JS func`s/`var`s and the `@JS init` are bound directly into the shared object's JS object by
     // the synthesized `_decorateSharedObject(prototype:)` / `_decorateSharedObject(constructor:)` / `_constructSharedObject`

package/apple/Sources/ExpoModulesMacros/TypeConformanceAssertion.swift

@@ -111,8 +111,9 @@ internal func directionalConformanceAssertion(
   let helper = "func \(name)<\(parameters.joined(separator: ", "))>(\(typeParameters.joined(separator: ", "))) {}"
   let call = "\(name)(\(arguments.joined(separator: ", ")))"
   let staticKeyword = isStatic ? "static " : ""
+  let peerName = derivedIdentifier(from: name, prefix: "_assertTypesConformance_")
   return """
-    private \(raw: staticKeyword)func _assertTypesConformance_\(raw: name)() {
+    private \(raw: staticKeyword)func \(raw: peerName)() {
     \(raw: helper)
     \(raw: call)
     }
@@ -142,10 +143,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

package/apple/Sources/ExpoModulesMacros/ViewPropsMacro.swift

@@ -251,18 +251,6 @@ private struct ViewProp {
   }
 }
 
-/// `name` without the backticks that escape it: `` `default` `` becomes `default`.
-private func withoutBackticks(_ name: String) -> String {
-  var name = Substring(name)
-  while name.first == "`" {
-    name.removeFirst()
-  }
-  while name.last == "`" {
-    name.removeLast()
-  }
-  return String(name)
-}
-
 private struct ViewPropsModel {
   /// Value props, in declaration order. The order is the bit order, so it is part of the ABI
   /// between a compiled view and the runtime that fills the mask.

package/apple/Sources/ExpoModulesScanner/Exports/ExportedSurface.swift

@@ -158,7 +158,8 @@ struct ExportedEvent: Encodable, Equatable {
 
 /// A `@ExpoModule` type and its `@JS` surface.
 struct ExportedModule: Encodable, Equatable {
-  /// The Swift class name.
+  /// The Swift class name. A module is always declared at file scope, since autolinking registers no
+  /// other.
   let name: String
 
   /// The JS module name: `@ExpoModule("Foo")` override, else the class name.
@@ -178,7 +179,9 @@ struct ExportedModule: Encodable, Equatable {
 
 /// One entry of `@ExpoModule(classes: [...])`.
 struct ExportedClass: Encodable, Equatable {
-  /// The Swift name as spelled in the argument, e.g. `Database` or `Outer.Statement`.
+  /// The `name` of the matching `@SharedObject`, which is qualified when the class is nested
+  /// (`Outer.Statement`). The Swift name as spelled in the argument when the scan found no
+  /// `@SharedObject` with this name.
   let name: String
 
   /// The name of the module member JS reads the class from: the matching `@SharedObject`'s `jsName`.
@@ -189,10 +192,11 @@ struct ExportedClass: Encodable, Equatable {
 
 /// A `@SharedObject` type: a JS class with an optional `@JS init` constructor plus its `@JS` members.
 struct ExportedSharedObject: Encodable, Equatable {
-  /// The Swift class name.
+  /// The Swift class name, qualified with the types it is nested in (`Outer.Player`).
   let name: String
 
-  /// The JS class name: `@SharedObject("Foo")` override, else the class name.
+  /// The JS class name: `@SharedObject("Foo")` override, else the class name without the enclosing
+  /// types.
   let jsName: String
 
   /// The `@JS init` parameters, or `nil` when there's none. A shared object has at most one.
@@ -207,7 +211,8 @@ struct ExportedSharedObject: Encodable, Equatable {
 
 /// A `@Record` type and its properties (data only: no functions, accessors, or constructor).
 struct ExportedRecord: Encodable, Equatable {
-  /// The Swift type name (struct or class).
+  /// The Swift type name (struct or class), qualified with the types it is nested in
+  /// (`Outer.Options`).
   let name: String
 
   let properties: [ExportedRecordProperty]
@@ -247,8 +252,9 @@ struct ExportedEnumCase: Encodable, Equatable {
 /// Detected by conformance, not by a macro attribute, because core converts it through its
 /// `RawRepresentable`/`Enumerable` conformance (`Coding/…+Enumerable`) with no macro involved.
 struct ExportedEnum: Encodable, Equatable {
-  /// The Swift enum name. No `jsName`: an enum carries no macro to spell an override on, and it
-  /// reaches JS as its raw values, not under a bound name.
+  /// The Swift enum name, qualified with the types it is nested in (`Options.Encoding`). No `jsName`:
+  /// an enum carries no macro to spell an override on, and it reaches JS as its raw values, not under
+  /// a bound name.
   let name: String
 
   /// The raw value type as written (`String`, `Int`, …), or `nil` for a bare `Enumerable` conformance
@@ -296,8 +302,9 @@ struct ExportedUnionMember: Encodable, Equatable {
 /// `Double`, two compatible records) the earlier case wins. Reordering them describes a different
 /// union than the one the module runs.
 struct ExportedUnion: Encodable, Equatable {
-  /// The Swift enum name. No `jsName`: `@Union` takes no arguments, and a union reaches JS as its
-  /// payload types rather than under a bound name.
+  /// The Swift enum name, qualified with the types it is nested in (`Options.Value`). No `jsName`:
+  /// `@Union` takes no arguments, and a union reaches JS as its payload types rather than under a bound
+  /// name.
   let name: String
 
   let members: [ExportedUnionMember]
@@ -320,8 +327,9 @@ struct ExportedSurface: Encodable, Equatable {
 /// Versioned independently of `scanModulesSchemaVersion`: the two commands serve different consumers
 /// and change for different reasons. Version 2 added `events` to modules and shared objects; version 3
 /// added `enums`; version 4 added `unions`; version 5 resolves refs, adding `refKind` and correcting
-/// an enum ref's `typeof`; version 6 added `classes` to modules.
-let scanExportsSchemaVersion = 6
+/// an enum ref's `typeof`; version 6 added `classes` to modules; version 7 reports nested types under
+/// qualified names and gives a resolved ref the name of its declaration.
+let scanExportsSchemaVersion = 7
 
 /// The `scan-exports` result: the surface plus the run's stats. A distinct envelope from
 /// `ScanModulesResult` (different consumer: TS generation vs. autolinking).