expo-modules-macros 0.25.0 → 0.27.0

package/apple/Sources/ExpoModulesMacros/Support/TupleTypes.swift

@@ -0,0 +1,272 @@
+import SwiftSyntax
+
+/// Recognition of boundary types that hold a tuple, and the conversions the macros emit for them. A
+/// tuple can't conform to a protocol, so neither it nor an array, optional or dictionary of tuples can
+/// convert through the usual `T.decode` / `T.encode` path. Such a type converts through the
+/// `JavaScriptValue` tuple and container methods instead, which take one closure per element, so the
+/// conversion follows the structure of the type: a tuple, optional, array or `String`-keyed dictionary
+/// that holds a tuple converts through the matching method, and every other type in it through its own
+/// `decode` / `encode`.
+///
+/// An unlabeled tuple maps to a JavaScript array with one value per element, and a labeled tuple to an
+/// object with one property per label. Recognized are tuples of two or more elements where either every
+/// element is labeled or none is. `TypeConformanceAssertion` asserts the types that convert through
+/// their own `decode` / `encode` (see `conformingTypes`) in place of the whole type.
+internal enum TupleConversion {
+  /// A type that holds no tuple, which converts through its own `decode` / `encode`.
+  case conforming(type: String)
+  /// A tuple: the conversion of each element, with one label per element for a labeled tuple.
+  case tuple(elements: [TupleConversion], labels: [String]?)
+  /// An optional of a type that holds a tuple.
+  indirect case optional(wrapped: TupleConversion)
+  /// An array of a type that holds a tuple.
+  indirect case array(element: TupleConversion)
+  /// A `String`-keyed dictionary whose values hold a tuple.
+  indirect case dictionary(value: TupleConversion)
+
+  /// The decode expression, as it appears after `try`, for a value read from `valueExpression` (a
+  /// `JavaScriptUnownedValue`). A tuple whose elements all conform passes the element types; any other
+  /// tuple and every container pass closures, which take the value and the runtime as parameters that
+  /// shadow the outer ones, so a closure captures nothing.
+  func decodeExpression(of valueExpression: String) -> String {
+    switch self {
+    case .conforming(let type):
+      return "\(expressionType(type)).decode(\(valueExpression), in: runtime)"
+    case .tuple(let elements, let labels):
+      if let types = conformingElementTypes(elements) {
+        let metatypes = types.map { "\(expressionType($0)).self" }.joined(separator: ", ")
+        let arguments = [valueExpression] + labelsArgument(labels) + ["as: \(metatypes)", "in: runtime"]
+        return "JavaScriptValue.decodeTuple(\(arguments.joined(separator: ", ")))"
+      }
+      let closures = elements.map { elementClosure(returning: $0.decodeExpression(of: "value")) }
+      let arguments = [valueExpression] + labelsArgument(labels) + ["in: runtime"] + closures
+      return "JavaScriptValue.decodeTuple(\(arguments.joined(separator: ", ")))"
+    case .optional(let wrapped):
+      return containerDecode("decodeOptional", label: "wrapped", inner: wrapped, of: valueExpression)
+    case .array(let element):
+      return containerDecode("decodeArray", label: "element", inner: element, of: valueExpression)
+    case .dictionary(let value):
+      return containerDecode("decodeDictionary", label: "value", inner: value, of: valueExpression)
+    }
+  }
+
+  /// The call, as it appears after `try`, that encodes the value `valueExpression` into the slot named
+  /// `slot`, in the runtime named `runtime`. A tuple whose elements all conform needs no closures. The
+  /// tuple method takes an unlabeled tuple, so a labeled one is coerced to its unlabeled type first.
+  func encodeCall(of valueExpression: String, into slot: String, in runtime: String = "runtime") -> String {
+    switch self {
+    case .conforming(let type):
+      return "\(expressionType(type)).encode(\(valueExpression), into: \(slot), in: \(runtime))"
+    case .tuple(let elements, let labels):
+      let value = labels == nil ? valueExpression : "\(valueExpression) as \(unlabeledType)"
+      let closures =
+        conformingElementTypes(elements) == nil
+        ? elements.map { encoderClosure(encoding: $0.encodeCall(of: "value", into: "slot")) } : []
+      let arguments = [value] + labelsArgument(labels) + ["into: \(slot)", "in: \(runtime)"] + closures
+      return "JavaScriptValue.encodeTuple(\(arguments.joined(separator: ", ")))"
+    case .optional(let wrapped):
+      return containerEncode(
+        "encodeOptional",
+        label: "wrapped",
+        inner: wrapped,
+        of: valueExpression,
+        into: slot,
+        in: runtime
+      )
+    case .array(let element):
+      return containerEncode(
+        "encodeArray",
+        label: "element",
+        inner: element,
+        of: valueExpression,
+        into: slot,
+        in: runtime
+      )
+    case .dictionary(let value):
+      return containerEncode(
+        "encodeDictionary",
+        label: "value",
+        inner: value,
+        of: valueExpression,
+        into: slot,
+        in: runtime
+      )
+    }
+  }
+
+  /// The encode expression, as it appears after `try`, that creates a `JavaScriptValue` from the value
+  /// `valueExpression`, for a place that has no slot to encode into, such as an async result. A type that
+  /// holds a tuple is encoded into the slot of `JavaScriptValue.encoding(in:_:)`.
+  func encodeExpression(of valueExpression: String) -> String {
+    if case .conforming(let type) = self {
+      return "\(expressionType(type)).encode(\(valueExpression), in: runtime)"
+    }
+    return "JavaScriptValue.encoding(in: runtime) { slot in try \(encodeCall(of: valueExpression, into: "slot")) }"
+  }
+
+  /// The JavaScript value kinds the decode accepts, as an expression of type `JavaScriptValueKinds`, for
+  /// a `@Union` that picks a payload by kind. Mirrors the kinds of the matching `JavaScriptCodable`
+  /// conformances: an array decodes a non-array value as a single element.
+  var decodableKindsExpression: String {
+    switch self {
+    case .conforming(let type):
+      return "\(expressionType(type)).decodableKinds"
+    case .tuple:
+      return "JavaScriptValueKinds.object"
+    case .optional(let wrapped):
+      return "\(wrapped.decodableKindsExpression).union([.null, .undefined])"
+    case .array(let element):
+      return "\(element.decodableKindsExpression).union(JavaScriptValueKinds.object)"
+    case .dictionary:
+      return "JavaScriptValueKinds.object"
+    }
+  }
+
+  /// The types in the structure that convert through their own `decode` / `encode`, in order, as
+  /// written.
+  var conformingTypes: [String] {
+    switch self {
+    case .conforming(let type):
+      return [type]
+    case .tuple(let elements, _):
+      return elements.flatMap(\.conformingTypes)
+    case .optional(let inner), .array(let inner), .dictionary(let inner):
+      return inner.conformingTypes
+    }
+  }
+
+  /// The type spelled in expression position, with tuple labels kept for nested tuples.
+  private var spelledType: String {
+    switch self {
+    case .conforming(let type):
+      return expressionType(type)
+    case .tuple(let elements, let labels):
+      let spelled = elements.enumerated().map { index, element in
+        labels.map { "\($0[index]): \(element.spelledType)" } ?? element.spelledType
+      }
+      return "(\(spelled.joined(separator: ", ")))"
+    case .optional(let wrapped):
+      return "\(wrapped.spelledType)?"
+    case .array(let element):
+      return "[\(element.spelledType)]"
+    case .dictionary(let value):
+      return "[String: \(value.spelledType)]"
+    }
+  }
+
+  /// The type of a tuple with its own labels dropped. Labels of nested tuples are kept, since the
+  /// nested conversion handles them.
+  private var unlabeledType: String {
+    guard case .tuple(let elements, _) = self else {
+      return spelledType
+    }
+    return "(\(elements.map(\.spelledType).joined(separator: ", ")))"
+  }
+
+  private func containerDecode(
+    _ method: String,
+    label: String,
+    inner: TupleConversion,
+    of valueExpression: String
+  ) -> String {
+    return
+      "JavaScriptValue.\(method)(\(valueExpression), in: runtime, \(label): \(elementClosure(returning: inner.decodeExpression(of: "value"))))"
+  }
+
+  private func containerEncode(
+    _ method: String,
+    label: String,
+    inner: TupleConversion,
+    of valueExpression: String,
+    into slot: String,
+    in runtime: String
+  ) -> String {
+    let closure = encoderClosure(encoding: inner.encodeCall(of: "value", into: "slot"))
+    return "JavaScriptValue.\(method)(\(valueExpression), into: \(slot), in: \(runtime), \(label): \(closure))"
+  }
+
+  /// The types of a tuple's elements when every element converts through its own `decode` /
+  /// `encode`, so the tuple can use the overloads that take no closures; `nil` otherwise.
+  private func conformingElementTypes(_ elements: [TupleConversion]) -> [String]? {
+    var types: [String] = []
+    for element in elements {
+      guard case .conforming(let type) = element else {
+        return nil
+      }
+      types.append(type)
+    }
+    return types
+  }
+
+  private func labelsArgument(_ labels: [String]?) -> [String] {
+    guard let labels else {
+      return []
+    }
+    return ["labels: [\(labels.map { "\"\($0)\"" }.joined(separator: ", "))]"]
+  }
+}
+
+/// The conversion for a boundary type that holds a tuple, or `nil` when the type holds no tuple the
+/// tuple methods convert (a single parenthesized type, a tuple that labels only some elements, or one
+/// with a variadic element converts as it's written, and fails its conformance assertion).
+internal func tupleConversion(of type: TypeSyntax) -> TupleConversion? {
+  let conversion = structure(of: type)
+  guard case .conforming = conversion else {
+    return conversion
+  }
+  return nil
+}
+
+/// The conversion for a boundary type written as a string. See `tupleConversion(of:)`.
+internal func tupleConversion(of type: String) -> TupleConversion? {
+  return tupleConversion(of: TypeSyntax(stringLiteral: type))
+}
+
+/// The conversion of `type`, which is `.conforming` when the type holds no recognized tuple.
+private func structure(of type: TypeSyntax) -> TupleConversion {
+  let conforming = TupleConversion.conforming(type: type.trimmedDescription)
+  if let tuple = type.as(TupleTypeSyntax.self) {
+    // `(T)` is the same type as `T`.
+    if tuple.elements.count == 1, let only = tuple.elements.first, only.firstName == nil {
+      return structure(of: only.type)
+    }
+    guard tuple.elements.count >= 2,
+      tuple.elements.allSatisfy({ $0.ellipsis == nil && $0.inoutKeyword == nil })
+    else {
+      return conforming
+    }
+    let labels = tuple.elements.compactMap { $0.firstName?.text }
+    guard labels.isEmpty || labels.count == tuple.elements.count else {
+      return conforming
+    }
+    return .tuple(elements: tuple.elements.map { structure(of: $0.type) }, labels: labels.isEmpty ? nil : labels)
+  }
+  let inner: TupleConversion
+  let wrap: (TupleConversion) -> TupleConversion
+  if let wrapped = optionalWrappedType(type) {
+    (inner, wrap) = (structure(of: wrapped), TupleConversion.optional)
+  } else if let element = arrayElementType(type) {
+    (inner, wrap) = (structure(of: element), TupleConversion.array)
+  } else if let value = stringKeyedDictionaryValueType(type) {
+    (inner, wrap) = (structure(of: value), TupleConversion.dictionary)
+  } else {
+    return conforming
+  }
+  // A container that holds no tuple conforms as a whole.
+  if case .conforming = inner {
+    return conforming
+  }
+  return wrap(inner)
+}
+
+/// An element closure that returns `expression`, as it appears after `try`. It takes the value and
+/// the runtime as parameters, which shadow the outer ones, so it captures nothing.
+internal func elementClosure(returning expression: String) -> String {
+  return "{ value, runtime in return try \(expression) }"
+}
+
+/// An element closure that encodes its value into its slot with `call`, as it appears after `try`. It takes
+/// the value, the slot and the runtime as parameters, which shadow the outer ones, so it captures nothing.
+internal func encoderClosure(encoding call: String) -> String {
+  return "{ value, slot, runtime in try \(call) }"
+}

package/apple/Sources/ExpoModulesMacros/Support/TypeAliases.swift

@@ -0,0 +1,75 @@
+import SwiftSyntax
+
+/// The type aliases declared in the body of a class whose aliased type holds a tuple (see
+/// `TupleConversion`), resolved to that type. A macro sees only the declaration it's attached to, so
+/// `@ExpoModule` and `@SharedObject` collect the aliases from their class body, and resolve them in
+/// the `@JS` members they bind before reading the members' types: an alias of a tuple can't convert
+/// through `decode` / `encode` under its own name, because the tuple can't conform.
+///
+/// An alias declared anywhere else (at file level, in an extension or in another type) isn't visible
+/// to the macros, so it converts under its own name and fails its conformance assertion. A generic
+/// alias isn't resolved either.
+internal struct TupleTypeAliases {
+  /// The resolved type of each alias, by name.
+  private let resolved: [String: TypeSyntax]
+
+  init(in memberBlock: MemberBlockSyntax) {
+    var declared: [String: TypeSyntax] = [:]
+    for member in memberBlock.members {
+      guard let alias = member.decl.as(TypeAliasDeclSyntax.self), alias.genericParameterClause == nil else {
+        continue
+      }
+      declared[alias.name.text] = alias.initializer.value
+    }
+    // Aliases may refer to each other, so each one is resolved through the others. An alias that refers
+    // back to itself is invalid Swift, and is left as written after `declared.count` rounds.
+    var resolved = declared
+    for _ in 0..<declared.count {
+      let rewriter = AliasRewriter(aliases: resolved)
+      resolved = resolved.mapValues { rewriter.rewrite($0).cast(TypeSyntax.self) }
+    }
+    self.resolved = resolved.filter { tupleConversion(of: $0.value) != nil }
+  }
+
+  /// True when the class body declares no alias that holds a tuple.
+  var isEmpty: Bool {
+    return resolved.isEmpty
+  }
+
+  /// `node` with each reference to an alias that holds a tuple replaced by the aliased type.
+  func resolving<Node: SyntaxProtocol>(_ node: Node) -> Node {
+    guard !resolved.isEmpty else {
+      return node
+    }
+    return AliasRewriter(aliases: resolved).rewrite(node).cast(Node.self)
+  }
+}
+
+/// Replaces each type reference to an alias by the aliased type: a bare name (`Pair`) or one qualified
+/// with `Self` (`Self.Pair`). A name with generic arguments isn't an alias reference, since the
+/// resolved aliases aren't generic.
+private final class AliasRewriter: SyntaxRewriter {
+  let aliases: [String: TypeSyntax]
+
+  init(aliases: [String: TypeSyntax]) {
+    self.aliases = aliases
+    super.init(viewMode: .sourceAccurate)
+  }
+
+  override func visit(_ node: IdentifierTypeSyntax) -> TypeSyntax {
+    guard node.genericArgumentClause == nil, let aliased = aliases[node.name.text] else {
+      return TypeSyntax(node)
+    }
+    return aliased.with(\.leadingTrivia, node.leadingTrivia).with(\.trailingTrivia, node.trailingTrivia)
+  }
+
+  override func visit(_ node: MemberTypeSyntax) -> TypeSyntax {
+    guard node.baseType.as(IdentifierTypeSyntax.self)?.name.text == "Self",
+      node.genericArgumentClause == nil,
+      let aliased = aliases[node.name.text]
+    else {
+      return super.visit(node)
+    }
+    return aliased.with(\.leadingTrivia, node.leadingTrivia).with(\.trailingTrivia, node.trailingTrivia)
+  }
+}

package/apple/Sources/ExpoModulesMacros/{TypeConformanceAssertion.swift → Support/TypeConformanceAssertion.swift}

@@ -40,57 +40,78 @@ internal struct ConformanceAssertion {
   let types: [String]
 }
 
+/// One type crossing the boundary for a member, as a parameter of the member's assertion helper: the
+/// type as written, the protocol it must conform to for the direction it travels, and the argument label
+/// it's passed under.
+internal struct AssertedType {
+  /// The argument label, or `nil` for an unlabeled parameter.
+  let label: String?
+  /// The type as written.
+  let type: String
+  /// `JavaScriptDecodable` for a type decoded from JavaScript, `JavaScriptEncodable` for one encoded to it.
+  let constraint: String
+}
+
 /// A directional conformance-assertion peer for a `@JS` member: a never-called `private func` whose
-/// body asserts each argument type is `JavaScriptDecodable` and the return/getter type is
+/// body asserts that each argument type is `JavaScriptDecodable` and the return or getter type is
 /// `JavaScriptEncodable`, matching how the generated binding converts each (decode on the way in,
-/// encode on the way out). The check is a single member-named nested helper with one opaque metatype
-/// parameter per asserted type, called once with every type's metatype; naming the helper after the
-/// member puts the member in the compiler's diagnostic, and the per-parameter constraint reports the
-/// offending type against the protocol for *its* direction.
+/// encode on the way out). The body is a local helper named after the member, with one opaque metatype
+/// parameter per asserted type, called once with every type's metatype (see
+/// `memberConformanceAssertion`). Naming the helper after the member and its labels puts the member in
+/// the compiler's diagnostic, and the per-parameter constraint reports the offending type against the
+/// protocol for its direction.
 ///
-/// `decodableTypes` are the argument types (and a settable property's value type); `encodableType` is
-/// the single return type (or a property's value type on read), or `nil` when there's none.
-/// `callbackArgumentTypes` are the parameter types of closure arguments, which are encoded when native
-/// code calls the closure. Types known to conform are dropped from each; when nothing is left in any of
-/// them, returns `nil` so the caller emits no peer. `isStatic` mirrors a `static`/`class` member so the
-/// peer sits in the right metatype context.
-internal func directionalConformanceAssertion(
-  name: String,
-  decodableTypes: [String],
-  encodableType: String?,
-  callbackArgumentTypes: [String] = [],
-  isStatic: Bool
-) -> DeclSyntax? {
-  let decodables = distinctAssertableTypes(decodableTypes, constraint: javaScriptDecodableProtocolName)
-  let callbackArguments = distinctAssertableTypes(callbackArgumentTypes, constraint: javaScriptEncodableProtocolName)
-  let encodable = encodableType.flatMap { assertableBoundaryType($0, constraint: javaScriptEncodableProtocolName) }
-  guard !decodables.isEmpty || !callbackArguments.isEmpty || encodable != nil else {
+/// Returns `nil` when every type is known to conform, so the caller emits no peer. `isStatic` mirrors a
+/// `static`/`class` member so the peer sits in the right metatype context.
+internal func directionalConformanceAssertion(name: String, types: [AssertedType], isStatic: Bool) -> DeclSyntax? {
+  guard let assertion = memberConformanceAssertion(name: name, types: types) else {
     return nil
   }
-
-  // Arguments are constrained `JavaScriptDecodable`, and closure-argument parameters and the
-  // return/getter value `JavaScriptEncodable`. Every parameter suppresses `Copyable`, so a
-  // non-copyable boundary type such as `JavaScriptValue` can fill it.
-  let encodables = callbackArguments + [encodable].compactMap { $0 }
-  let decodableParameter = opaqueMetatypeParameter(constraint: "\(javaScriptDecodableProtocolName) & ~Copyable")
-  let encodableParameter = opaqueMetatypeParameter(constraint: "\(javaScriptEncodableProtocolName) & ~Copyable")
-  let parameters =
-    Array(repeating: decodableParameter, count: decodables.count)
-    + Array(repeating: encodableParameter, count: encodables.count)
-  let arguments = (decodables + encodables).map { "\($0).self" }
-
-  let helper = "func \(name)(\(parameters.joined(separator: ", "))) {}"
-  let call = "\(name)(\(arguments.joined(separator: ", ")))"
   let staticKeyword = isStatic ? "static " : ""
   let peerName = derivedIdentifier(from: name, prefix: "_assertTypesConformance_")
   return """
     private \(raw: staticKeyword)func \(raw: peerName)() {
-    \(raw: helper)
-    \(raw: call)
+    \(raw: assertion.helper)
+    \(raw: assertion.call)
     }
     """
 }
 
+/// The local helper of a member's conformance assertion and its call, or `nil` when every type is known
+/// to conform. The helper is named after the member and takes the labels of the types, so the
+/// diagnostic reads like the member's signature, such as `local function 'move(_:by:returning:)'
+/// requires that 'Point' conform to 'JavaScriptEncodable'`. A type that holds a tuple contributes the
+/// types in it (see `distinctAssertableTypes`), under its label. Every parameter suppresses `Copyable`,
+/// so a non-copyable boundary type such as `JavaScriptValue` can fill it.
+internal func memberConformanceAssertion(name: String, types: [AssertedType]) -> MemberConformanceAssertion? {
+  var seen: Set<String> = []
+  var parameters: [AssertedType] = []
+  for asserted in types {
+    for type in distinctAssertableTypes([asserted.type], constraint: asserted.constraint) {
+      let key = "\(asserted.label ?? "_") \(type) \(asserted.constraint)"
+      if seen.insert(key).inserted {
+        parameters.append(AssertedType(label: asserted.label, type: type, constraint: asserted.constraint))
+      }
+    }
+  }
+  guard !parameters.isEmpty else {
+    return nil
+  }
+  let declared = parameters.map { parameter in
+    let metatype = "(some \(parameter.constraint) & ~Copyable).Type"
+    return parameter.label.map { "\($0) _: \(metatype)" } ?? "_: \(metatype)"
+  }
+  let passed = parameters.map { parameter in
+    return parameter.label.map { "\($0): \(parameter.type).self" } ?? "\(parameter.type).self"
+  }
+  let labels = parameters.map { "\($0.label ?? "_"):" }.joined()
+  return MemberConformanceAssertion(
+    signature: "\(name)(\(labels))",
+    helper: "func \(name)(\(declared.joined(separator: ", "))) {}",
+    call: "\(name)(\(passed.joined(separator: ", ")))"
+  )
+}
+
 /// 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
@@ -182,11 +203,16 @@ internal func opaqueMetatypeParameter(constraint: String) -> String {
 }
 
 /// The distinct types to assert against `constraint` from a list, mapping each through
-/// `assertableBoundaryType` (which drops what needs no assertion) and deduping in first-seen order.
-private func distinctAssertableTypes(_ types: [String], constraint: String) -> [String] {
+/// `assertableBoundaryType` (which drops what needs no assertion) and deduping in first-seen order. A
+/// type that holds a tuple converts element by element (see `TupleConversion`), so the types in it that
+/// convert through their own `decode` / `encode` are asserted in its place.
+internal func distinctAssertableTypes(_ types: [String], constraint: String) -> [String] {
   var seen: Set<String> = []
   var distinct: [String] = []
-  let assertable = types.compactMap { assertableBoundaryType($0, constraint: constraint) }
+  let assertable = types.flatMap { type in
+    let elementTypes = tupleConversion(of: type)?.conformingTypes ?? [type]
+    return elementTypes.compactMap { assertableBoundaryType($0, constraint: constraint) }
+  }
   for type in assertable where seen.insert(type).inserted {
     distinct.append(type)
   }
@@ -207,3 +233,40 @@ private func unwrappedOptional(_ type: String) -> String {
   }
   return String(result)
 }
+
+/// The conformance assertion of one member: a local helper function named after the member, which takes
+/// the metatype of each asserted type, and its call.
+internal struct MemberConformanceAssertion {
+  /// The helper's full name with its argument labels, such as `load(_:)`.
+  let signature: String
+  /// The helper's declaration.
+  let helper: String
+  /// The call of the helper with each asserted type's metatype.
+  let call: String
+}
+
+/// One assertion member covering the `@JS` members of an `@ExpoModule` or `@SharedObject` class, which
+/// the class macro emits in place of the `@JS` peers: each member's helper and its call, in member order.
+/// The helpers are local functions, so two helpers with the same name and labels (members that differ
+/// only by argument types) would redeclare the same function: such a helper sits in its own `do` block.
+/// Returns `nil` when no member has a type to assert.
+internal func classConformanceAssertions(_ assertions: [MemberConformanceAssertion]) -> DeclSyntax? {
+  guard !assertions.isEmpty else {
+    return nil
+  }
+  var signatureCounts: [String: Int] = [:]
+  for assertion in assertions {
+    signatureCounts[assertion.signature, default: 0] += 1
+  }
+  let lines = assertions.flatMap { assertion in
+    guard signatureCounts[assertion.signature, default: 0] > 1 else {
+      return [assertion.helper, assertion.call]
+    }
+    return ["do {", "  \(assertion.helper)", "  \(assertion.call)", "}"]
+  }
+  return """
+    private func _assertTypesConformance() {
+    \(raw: lines.joined(separator: "\n"))
+    }
+    """
+}

package/build/index.d.ts

@@ -1,4 +1,4 @@
-import { ScanExportsResult, ScanModulesResult } from './types';
+import { ExpandResult, ScanExportsResult, ScanModulesResult } from './types';
 export * from './types';
 /** Options accepted by `scanModules`, mirroring the CLI's `scan-modules` flags. */
 export interface ScanModulesOptions {
@@ -19,6 +19,21 @@ export interface ScanExportsOptions {
     /** Milliseconds after which the scanner is killed and the scan fails. No limit by default. */
     timeout?: number;
 }
+/** Options accepted by `expandMacros`, mirroring the CLI's `expand` flags. */
+export interface ExpandMacrosOptions {
+    /**
+     * Limits the result to these symbols: a type (`'MyModule'`, `'MyModule.Options'`) or a member
+     * (`'MyModule.greet'`). A member expands its type with only the declarations of that name. Each
+     * symbol must be declared in one of the files, or the call fails with a `ScannerError`.
+     */
+    symbols?: string[];
+    /** Returns only the diagnostics, with no expansions. */
+    diagnosticsOnly?: boolean;
+    /** Overrides the scanner binary path. Defaults to the one shipped with this package. */
+    binaryPath?: string;
+    /** Milliseconds after which the scanner is killed and the call fails. No limit by default. */
+    timeout?: number;
+}
 /**
  * Thrown when the scanner exits non-zero. Exit code 2 is a usage error (bad subcommand or flags) and
  * 1 means the report couldn't be encoded; both put a message on stderr, carried here as `stderr`.
@@ -68,3 +83,18 @@ export declare function scanModules(paths: string[], options?: ScanModulesOption
  * what it guards is not reported.
  */
 export declare function scanExports(paths: string[], options?: ScanExportsOptions): Promise<ScanExportsResult>;
+/**
+ * Expands the Expo macros in process, without a build, and returns the generated
+ * code with the syntax errors and the macro diagnostics. The macros only read the syntax tree, so
+ * the code is what the compiler gets, except for the names that a macro makes unique. Errors that
+ * need type checking, for example a type that doesn't conform to a protocol, still need a build.
+ *
+ * Each path is a `.swift` file, which is always expanded and keeps its path in the result, or a
+ * directory. A directory is walked like the scans walk it, and only its files that use one of the
+ * macros are expanded, with their absolute paths.
+ *
+ * Error diagnostics don't make the call fail: check `severity` in `diagnostics`. Only an input that
+ * can't be expanded (a missing path, a file that isn't Swift, a symbol that no file declares) throws
+ * a `ScannerError`.
+ */
+export declare function expandMacros(paths: string[], options?: ExpandMacrosOptions): Promise<ExpandResult>;

package/build/index.js

@@ -21,6 +21,7 @@ exports.ScannerSchemaVersionError = exports.ScannerError = void 0;
 exports.getScannerBinaryPath = getScannerBinaryPath;
 exports.scanModules = scanModules;
 exports.scanExports = scanExports;
+exports.expandMacros = expandMacros;
 const node_child_process_1 = require("node:child_process");
 const node_path_1 = __importDefault(require("node:path"));
 const types_1 = require("./types");
@@ -210,3 +211,36 @@ async function scanExports(paths, options = {}) {
     }
     return result;
 }
+/**
+ * Expands the Expo macros in process, without a build, and returns the generated
+ * code with the syntax errors and the macro diagnostics. The macros only read the syntax tree, so
+ * the code is what the compiler gets, except for the names that a macro makes unique. Errors that
+ * need type checking, for example a type that doesn't conform to a protocol, still need a build.
+ *
+ * Each path is a `.swift` file, which is always expanded and keeps its path in the result, or a
+ * directory. A directory is walked like the scans walk it, and only its files that use one of the
+ * macros are expanded, with their absolute paths.
+ *
+ * Error diagnostics don't make the call fail: check `severity` in `diagnostics`. Only an input that
+ * can't be expanded (a missing path, a file that isn't Swift, a symbol that no file declares) throws
+ * a `ScannerError`.
+ */
+async function expandMacros(paths, options = {}) {
+    if (paths.length === 0) {
+        throw new TypeError('expandMacros requires at least one path');
+    }
+    assertRepresentablePaths('expandMacros', paths);
+    const args = ['expand', '--json'];
+    for (const symbol of options.symbols ?? []) {
+        args.push('--symbol', symbol);
+    }
+    if (options.diagnosticsOnly) {
+        args.push('--diagnostics-only');
+    }
+    args.push(...paths);
+    const result = await runScanner(options.binaryPath ?? getScannerBinaryPath(), args, options.timeout);
+    if (result.schemaVersion !== types_1.SUPPORTED_EXPAND_SCHEMA_VERSION) {
+        throw new ScannerSchemaVersionError('expand', result.schemaVersion, types_1.SUPPORTED_EXPAND_SCHEMA_VERSION);
+    }
+    return result;
+}