@expo/expo-modules-macros-plugin 0.1.0 → 0.2.1

package/.github/workflows/publish.yml

@@ -97,7 +97,9 @@ jobs:
         run: |
           version="${{ steps.bump.outputs.version }}"
           git commit -am "Release $version"
-          git tag "$version"
+          # Use an annotated tag so `git push --follow-tags` actually pushes it
+          # (--follow-tags ignores lightweight tags).
+          git tag -a "$version" -m "Release $version"
           git push --follow-tags origin HEAD
 
       - name: Create GitHub release

package/apple/Sources/ExpoModulesMacros/DecorateFunctionBuilder.swift

@@ -0,0 +1,196 @@
+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. 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
+  }
+}
+
+/**
+ 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 == "()"
+}

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -42,6 +42,12 @@ 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.
+    var functions: [JSFunction] = []
+
     for typeName in classListArgument(of: node, label: "classes") {
       entries.append("\(typeName)._synthesizedClassDefinition()")
     }
@@ -51,7 +57,7 @@ public struct ExpoModuleMacro: MemberMacro {
 
       if let funcDecl = decl.as(FunctionDeclSyntax.self),
         let attribute = funcDecl.attributes.firstAttribute(named: "JS") {
-        entries.append(buildFunctionEntry(funcDecl: funcDecl, attribute: attribute))
+        functions.append(JSFunction(funcDecl: funcDecl, attribute: attribute))
         continue
       }
 
@@ -94,6 +100,13 @@ 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))
+    }
+
     return emitted
   }
 }
@@ -215,17 +228,6 @@ private func hasAppContextInitializer(_ classDecl: ClassDeclSyntax) -> Bool {
 
 // MARK: - Member builders
 
-private func buildFunctionEntry(
-  funcDecl: FunctionDeclSyntax,
-  attribute: AttributeSyntax
-) -> String {
-  let swiftName = funcDecl.name.text
-  let jsName = jsNameArgument(of: attribute) ?? swiftName
-  let isAsync = funcDecl.signature.effectSpecifiers?.asyncSpecifier != nil
-  let dslEntry = isAsync ? "AsyncFunction" : "Function"
-  return "\(dslEntry)(\"\(jsName)\", \(swiftName))"
-}
-
 private func buildPropertyEntries(
   varDecl: VariableDeclSyntax,
   attribute: AttributeSyntax

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/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)

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.1.0",
+  "version": "0.2.1",
   "description": "Swift macro plugin for Expo modules",
   "license": "MIT",
   "author": "650 Industries, Inc.",