expo-modules-macros 0.21.0 → 0.22.0

package/.github/workflows/swift-format.yml

@@ -0,0 +1,76 @@
+name: Swift Format
+
+# Checks that the Swift sources are formatted with the pinned swift-format version.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch: {}
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  # Keep in sync with the version in the Development section of README.md.
+  SWIFT_FORMAT_VERSION: '604.0.0'
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-24.04
+    # The same image as the Linux workflow. swift-format links the Swift runtime from it.
+    container: swift:6.4.0-rhel-ubi9@sha256:802a003f1eacbca9c20664a8ba79621d13f4538c3d329e745b7f8d53c70604a3
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5
+
+      - name: Setup Node
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+        with:
+          node-version: 24
+
+      - name: Restore swift-format
+        id: swift-format-cache
+        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.local/bin/swift-format
+          # The binary links the Swift runtime of the container image, so the key changes with this
+          # file, which sets the image.
+          key: swift-format-${{ runner.os }}-${{ env.SWIFT_FORMAT_VERSION }}-${{ hashFiles('.github/workflows/swift-format.yml') }}
+
+      - name: Build swift-format
+        if: steps.swift-format-cache.outputs.cache-hit != 'true'
+        run: |
+          set -euo pipefail
+          src="$(mktemp -d)"
+          git clone --depth 1 --branch "$SWIFT_FORMAT_VERSION" https://github.com/swiftlang/swift-format.git "$src"
+          cd "$src"
+          swift build -c release --product swift-format
+          mkdir -p ~/.local/bin
+          cp "$(swift build -c release --show-bin-path)/swift-format" ~/.local/bin/swift-format
+
+      - name: Save swift-format
+        # Saves the binary before the lint, so that a run with findings doesn't build it again.
+        if: steps.swift-format-cache.outputs.cache-hit != 'true'
+        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: ~/.local/bin/swift-format
+          key: ${{ steps.swift-format-cache.outputs.cache-primary-key }}
+
+      - name: Add swift-format to PATH
+        run: echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+
+      - name: Lint
+        run: |
+          # The script lists the files with `git ls-files`. The checkout belongs to another user than
+          # the container's root user, so Git needs it marked as safe.
+          git config --global --add safe.directory "$GITHUB_WORKSPACE"
+          npm run swift:lint

package/AGENTS.md

@@ -13,6 +13,7 @@
 - `apple/PodTests`: a stub test so that `expo/expo` native tests can install this package as a pod. Do not add real tests here.
 - `src/`: the TypeScript wrapper around the scanner CLI. `types.ts` mirrors the Swift `Codable` output types by hand.
 - `scripts/build.js` (`npm run build`): builds the release binaries: the universal macOS `apple/ExpoModulesMacros` (committed and published), and on Windows and Linux `platforms/win32-<arch>/ExpoModulesMacros.exe` or `platforms/linux-<arch>/ExpoModulesMacros` for the host architecture (not committed; published in that package).
+- `scripts/swift-format.js` (`npm run swift:format`, `npm run swift:lint`): runs swift-format on the `.swift` files that Git tracks or doesn't ignore, with the configuration in `.swift-format`.
 
 ## Commands
 
@@ -23,9 +24,11 @@ cd apple && swift build      # debug build
 cd apple && swift test       # all Swift tests
 npm run typecheck            # TypeScript wrapper
 npm run build                # release binary (slow; on macOS uses Rosetta for x86_64)
+npm run swift:format         # format the Swift sources in place
+npm run swift:lint           # check the formatting, as CI does
 ```
 
-CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.github/workflows/windows.yml`), and on Linux x64 and arm64 (`.github/workflows/linux.yml`). On macOS it runs the release build, checks both binary slices, then runs `swift test` and `npm run typecheck`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper with `scripts/check-scan.js`, which must find the executable there. On Linux it does the same in the `swift:6.4.0-rhel-ubi9` image, and also checks that no Swift library is linked dynamically, the newest glibc symbol version that the binary needs, and that the package keeps the executable bit. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
+CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.github/workflows/windows.yml`), and on Linux x64 and arm64 (`.github/workflows/linux.yml`). On macOS it runs the release build, checks both binary slices, then runs `swift test` and `npm run typecheck`. On Windows it builds and tests the package, builds the release binary, checks that it starts without the Swift runtime, packs it into its `platforms/` package (checking the files and the `os`/`cpu` fields), installs that package, and scans through the TypeScript wrapper with `scripts/check-scan.js`, which must find the executable there. On Linux it does the same in the `swift:6.4.0-rhel-ubi9` image, and also checks that no Swift library is linked dynamically, the newest glibc symbol version that the binary needs, and that the package keeps the executable bit. The Swift Format workflow (`.github/workflows/swift-format.yml`) builds the pinned swift-format version and runs `npm run swift:lint`. Code in `Sources` and `Tests` must not assume Apple platforms or POSIX paths.
 
 ## Windows
 
@@ -39,9 +42,11 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 
 ## Conventions
 
-- Swift uses 2-space indentation. Write new doc comments as `///` line comments, not `/** */` blocks.
+- swift-format formats the Swift sources. After you change Swift code, run `npm run swift:format` and then `npm run swift:lint`, which also reports the rules that the formatter doesn't fix. `.swift-format` is a copy of the configuration in `expo/expo`, so keep the two the same. Each repository pins its own swift-format version.
+- The scripts run the swift-format on `PATH`, or on macOS the one in Xcode when there is none. CI builds the version in `SWIFT_FORMAT_VERSION` (`.github/workflows/swift-format.yml`, also named in the README), which can format differently from the one in Xcode. When CI reports a finding that the local lint doesn't, fix it as CI reports it.
+- Write new doc comments as `///` line comments, not `/** */` blocks.
 - Tests use Swift Testing (`import Testing`, `@Test`) with backtick-quoted descriptive names, for example ``func `Prunes .build, Pods, .git, and node_modules directories`()``.
-- Macro tests compare full expansions with `assertMacroExpansion` from `SwiftSyntaxMacrosGenericTestSupport`, using `indentationWidth: .spaces(2)`. Each test file wraps it in a local `assertExpansion` helper.
+- Macro tests compare full expansions with `assertMacroExpansion` from `SwiftSyntaxMacrosGenericTestSupport`, using `indentationWidth: .spaces(2)`. Each test file wraps it in a local `assertExpansion` helper that passes `recordIssue` (`IssueRecording.swift`) as the failure handler.
 - Scanner tests reach internal API with `@testable import ExpoModulesScanner`. Do not make scanner types `public` only for tests.
 - `@JS` applies to functions, properties and initializers. Do not write code or comments that assume it marks only functions.
 - Code comments describe the code as it is. Do not refer to open PRs, branches or planned work.
@@ -49,7 +54,7 @@ CI runs on macOS (`.github/workflows/swift.yml`), on Windows x64 and arm64 (`.gi
 ## Changing macros
 
 - The scanner re-implements the macros' naming and member rules on the syntax tree; it does not call the macro code. When a macro changes which members it binds or how it names them (the `@JS` name override, the `on` prefix `@Event` strips, which properties `@Record` treats as fields), change `scan-exports` to match, or generated TypeScript types drift from the runtime.
-- The scanner only parses files that match the pre-filter built by `macroAttributeRegex` in `Core/SourceScan.swift`. A new attribute or conformance the scanner must detect has to be added there, or files that use it are skipped without an error.
+- The scanner only parses files that pass the pre-filter, `MacroPrefilter` in `Core/SourceScan.swift`. Each command builds it from the `macros` and `conformances` arguments of its `scanFiles` call. A new attribute or conformance the scanner must detect has to be added to those arguments (an attribute also needs a `DetectedMacro` case), or files that use it are skipped without an error.
 - A new macro needs: the implementation in `apple/Sources/ExpoModulesMacros`, an entry in `providingMacros` in `Plugin.swift`, an expansion test file, the `#externalMacro` declaration in `expo-modules-core`, and an entry in the macro list in `README.md`.
 
 ## Contracts with other packages

package/README.md

@@ -25,10 +25,10 @@ This package lists them as optional dependencies, and their `os`, `cpu` and (on
 # Macros
 
 - **`@ExpoModule(_ name: String? = nil, classes: [Any.Type] = [])`** on a class. Turns the class into a module: binds its `@JS` members into the module's JavaScript object and resolves the module name from the argument, falling back to the class name. It also synthesizes everything inheriting from `Module` used to provide, so a module class can carry any superclass, or none.
-- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
+- **`@JS(_ jsName: String? = nil, _ options: JSOptions...)`** on a member of a module or shared object. Marks a function, property or initializer for export. `@ExpoModule` and `@SharedObject` bind each marked member straight into the JavaScript object, with the argument decoding, the call and the result encoding inlined, so there is no dynamic per-call path. The JS name defaults to the Swift name; pass a string to override it. Two `@JS` members with the same JS name on one JavaScript object are a compile-time error, since JavaScript could reach only one of them. A shared object's static and instance members bind onto different objects, so they can share a name. The macro also checks that every type crossing the boundary is convertible in the direction it travels, so a bad type is reported on the author's own declaration rather than on the enclosing type. The `.concurrent` option moves an `async` body off the JavaScript thread while still decoding and encoding on it. The `.withAsync("name")` option binds a synchronous function a second time under that name, as a function that returns a promise and runs the body on the concurrent thread pool. That function isn't isolated to the JavaScript thread, so its body must be safe to run on any thread. The macro reports a function isolated to a global actor through its own attribute or its type's. When the isolation comes from elsewhere, such as a protocol or the module's default isolation, the error points into the generated code, so mark the function `nonisolated`. A function or initializer can take a closure argument, such as `(Point) throws -> Size` or `(String) async throws -> Data`. JavaScript passes a function for it, and native code can store the closure and call it from any thread. A closure that throws or returns a value blocks the caller until JavaScript returns, and an `async` closure suspends instead and awaits a promise that the function returns. A closure that returns a value must be `throws`, so that an error from JavaScript can reach the caller. A non-throwing `Void` closure returns before JavaScript reads its arguments, so don't change a class instance after passing it to one.
 - **`@Event(_ name: String? = nil, sync: Bool = false)`** on a function-typed `var`. Expands the property into a closure that emits the event, so calling the property sends it to JavaScript with the closure's parameter as the payload. The JS name defaults to the property name with a leading `on` stripped. `sync: true` dispatches inline instead of asynchronously.
 - **`@SharedObject(_ name: String? = nil)`** on a `SharedObject` subclass. Collects the class's `@JS` members into a class definition that a module exposes through `@ExpoModule(classes:)`.
-- **`@Record()`** on a record type. Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.
+- **`@Record()`** on a struct, or on a final class with no inheritance clause (declare a class's protocol conformances in an extension). Treats every non-static, non-private, non-computed stored property as a field, with no per-field wrapper, and synthesizes the memberwise initializer, the conversions in both directions, and the `Record` conformance. Requiredness is inferred: a default value makes a field optional, an optional type makes it nullable and optional.
 - **`@Union()`** on an enum whose cases each carry one associated value. Models a TypeScript union. Synthesizes the conversions in both directions, a typed accessor per payload type, and the `JavaScriptDecodable` and `JavaScriptEncodable` conformances. Decoding is ordered: the first case whose payload decodes wins, so the more specific case goes first.
 
 How that looks in a module:
@@ -116,6 +116,19 @@ swift build
 swift test
 ```
 
+The Swift sources are formatted with [swift-format](https://github.com/swiftlang/swift-format), using the same configuration (`.swift-format`) as the `expo/expo` repository. `npm run swift:format` formats the `.swift` files that Git tracks or doesn't ignore in place, and `npm run swift:lint` checks them without changes, as CI does.
+
+The scripts run the `swift-format` on `PATH`, or on macOS the one in the selected Xcode when there is none on `PATH`. CI uses swift-format `604.0.0`, which can format differently from the one in Xcode. To get the version that CI uses, build it from source:
+
+```sh
+git clone --depth 1 --branch 604.0.0 https://github.com/swiftlang/swift-format.git /tmp/swift-format
+(cd /tmp/swift-format && swift build -c release --product swift-format)
+mkdir -p ~/.local/bin
+cp "$(cd /tmp/swift-format && swift build -c release --show-bin-path)/swift-format" ~/.local/bin/
+```
+
+Then add `~/.local/bin` to `PATH`.
+
 `npm run build` runs `scripts/build.js`, which builds the release binary with SwiftPM's native build system (Swift Build, the default since Swift 6.4, doesn't build a macro tool that no target in the package uses).
 
 - On macOS, it builds for arm64 and x86_64, merges the slices into `apple/ExpoModulesMacros` with `lipo`, strips it, and verifies both slices are present. SwiftPM only builds macro tools for the host architecture, so the x86_64 slice is produced by running the toolchain under Rosetta; the script installs Rosetta if it is missing.

package/apple/Package.resolved

@@ -1,13 +1,13 @@
 {
-  "originHash" : "f142f4d4b3ea8f139f9a2f206e382cf98031da4c8ea8691ddec05cb0c9d2285f",
+  "originHash" : "a90a0c6d6b4023098b6a673ded4f314ec06c219ded1559e5d5595f23c7dc323b",
   "pins" : [
     {
       "identity" : "swift-syntax",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/swiftlang/swift-syntax.git",
       "state" : {
-        "revision" : "79e4b74a295b6eb74a8b585e3a39d29e70c1dbd1",
-        "version" : "603.0.2"
+        "revision" : "050f1a346fbbac0ca2cfb15a95274f7bd1cf0ccf",
+        "version" : "604.0.0"
       }
     }
   ],

package/apple/Package.swift

@@ -9,7 +9,7 @@ let package = Package(
   name: "ExpoModulesMacros",
   platforms: [.macOS(.v13)],
   dependencies: [
-    .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "603.0.0-latest")
+    .package(url: "https://github.com/swiftlang/swift-syntax.git", from: "604.0.0-latest")
   ],
   targets: [
     // The plugin executable doubles as the scanner CLI: the compiler launches it without arguments
@@ -44,7 +44,6 @@ if FileManager.default.fileExists(atPath: Context.packageDirectory + "/Tests") {
       name: "ExpoModulesMacrosTests",
       dependencies: [
         "ExpoModulesMacros",
-        .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),
         .product(name: "SwiftSyntaxMacrosGenericTestSupport", package: "swift-syntax"),
       ]
     )

package/apple/Sources/ExpoModulesMacros/ClosureArguments.swift

@@ -189,7 +189,9 @@ internal func diagnoseClosureTypes(
           message: ClosureDiagnosticMessage(
             "A @JS function can't return a closure: a native closure can't be encoded to a JavaScript function.",
             id: "js-closure-return"
-          )))
+          )
+        )
+      )
     }
     return
   }
@@ -199,14 +201,17 @@ internal func diagnoseClosureTypes(
   }
   if let varDecl = declaration.as(VariableDeclSyntax.self),
     let type = varDecl.bindings.first?.typeAnnotation?.type,
-    let nested = firstFunctionType(in: type) {
+    let nested = firstFunctionType(in: type)
+  {
     context.diagnose(
       Diagnostic(
         node: nested,
         message: ClosureDiagnosticMessage(
           "A @JS property can't have a closure type: a native closure can't be encoded to a JavaScript function.",
           id: "js-closure-property"
-        )))
+        )
+      )
+    )
   }
 }
 
@@ -223,7 +228,9 @@ private func diagnoseClosureParameters(
             message: ClosureDiagnosticMessage(
               "A closure in a @JS argument must be the argument's own type, optionally wrapped in an optional. Closures inside other types, such as arrays or dictionaries, aren't supported.",
               id: "js-closure-nested-in-type"
-            )))
+            )
+          )
+        )
       }
       continue
     }
@@ -245,7 +252,9 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
         message: ClosureDiagnosticMessage(
           "'@\(name)' isn't supported on a @JS closure argument. The closure calls JavaScript through its own thread hop, so only '@escaping' and '@Sendable' are allowed.",
           id: "js-closure-attribute"
-        )))
+        )
+      )
+    )
   }
 
   if let throwsClause = functionType.effectSpecifiers?.throwsClause, throwsClause.type != nil {
@@ -255,7 +264,9 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
         message: ClosureDiagnosticMessage(
           "A @JS closure argument can't use typed throws: the error from JavaScript can be any error. Write 'throws' without a type.",
           id: "js-closure-typed-throws"
-        )))
+        )
+      )
+    )
   }
 
   for parameter in closure.parameters {
@@ -266,7 +277,9 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
           message: ClosureDiagnosticMessage(
             "A @JS closure argument can't take an '\(specifier)' parameter: its value is encoded and sent to JavaScript, which can't write it back or share its isolation.",
             id: "js-closure-parameter-specifier"
-          )))
+          )
+        )
+      )
     }
     if parameter.isVariadic {
       context.diagnose(
@@ -275,7 +288,9 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
           message: ClosureDiagnosticMessage(
             "A @JS closure argument can't take a variadic parameter. Use an array instead.",
             id: "js-closure-variadic-parameter"
-          )))
+          )
+        )
+      )
     }
   }
 
@@ -290,7 +305,9 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
           message: ClosureDiagnosticMessage(
             "A @JS closure argument can't take or return another closure.",
             id: "js-closure-nested"
-          )))
+          )
+        )
+      )
     } else if mentionsFreeFormAny(type) {
       context.diagnose(
         Diagnostic(
@@ -298,7 +315,9 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
           message: ClosureDiagnosticMessage(
             "A @JS closure argument can't use the free-form '\(type.trimmedDescription)'. Use a concrete type, or 'JavaScriptValue' to pass a JS value through unchanged.",
             id: "js-closure-free-form"
-          )))
+          )
+        )
+      )
     }
   }
 
@@ -310,7 +329,9 @@ private func diagnoseClosure(_ closure: JSClosureType, in context: some MacroExp
           "A @JS closure argument that returns a value must be 'throws': when the JavaScript function throws, the closure has no value to return.",
           id: "js-closure-requires-throws"
         ),
-        fixIts: [insertThrowsFixIt(for: functionType)]))
+        fixIts: [insertThrowsFixIt(for: functionType)]
+      )
+    )
   }
 }
 
@@ -321,13 +342,16 @@ private func insertThrowsFixIt(for functionType: FunctionTypeSyntax) -> FixIt {
   var newType = functionType
   if var effectSpecifiers = functionType.effectSpecifiers, let asyncSpecifier = effectSpecifiers.asyncSpecifier {
     effectSpecifiers.throwsClause = ThrowsClauseSyntax(
-      throwsSpecifier: .keyword(.throws, trailingTrivia: asyncSpecifier.trailingTrivia))
+      throwsSpecifier: .keyword(.throws, trailingTrivia: asyncSpecifier.trailingTrivia)
+    )
     effectSpecifiers.asyncSpecifier = asyncSpecifier.with(\.trailingTrivia, .space)
     newType.effectSpecifiers = effectSpecifiers
   } else {
     newType.effectSpecifiers = TypeEffectSpecifiersSyntax(
       throwsClause: ThrowsClauseSyntax(
-        throwsSpecifier: .keyword(.throws, trailingTrivia: functionType.rightParen.trailingTrivia)))
+        throwsSpecifier: .keyword(.throws, trailingTrivia: functionType.rightParen.trailingTrivia)
+      )
+    )
     newType.rightParen = functionType.rightParen.with(\.trailingTrivia, .space)
   }
   return FixIt(
@@ -360,7 +384,8 @@ internal func firstFunctionType(in type: some SyntaxProtocol) -> FunctionTypeSyn
 /// same type as `(Int) -> Void`.
 private func unparenthesized(_ type: TypeSyntax) -> TypeSyntax {
   if let tuple = type.as(TupleTypeSyntax.self), tuple.elements.count == 1,
-    let element = tuple.elements.first, element.firstName == nil {
+    let element = tuple.elements.first, element.firstName == nil
+  {
     return unparenthesized(element.type)
   }
   return type

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -13,18 +13,27 @@ import SwiftSyntax
 /// unwrap, arity guard, argument decode, all while `this` and the arguments are still valid)
 /// and returns the async body (call and result encode), so nothing JSI-owned crosses the asynchronous
 /// boundary and JS gets a promise.
+///
+/// A synchronous function marked `@JS(.withAsync("name"))` also binds a promise-returning variant
+/// under that name (see `asyncVariant`). It decodes and encodes like an `async` function, and calls
+/// the function on the concurrent pool.
 internal struct JSFunction {
   let swiftName: String
-  let jsName: String
+  private(set) var jsName: String
   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
+  private(set) var isAsync: Bool
   /// The function's name in the source, where a JavaScript name collision is reported.
-  let nameToken: TokenSyntax
+  private(set) var nameToken: TokenSyntax
+  /// The name from `.withAsync("name")` and its token, or `nil` when the attribute doesn't list it.
+  private var asyncVariantName: (name: String, token: TokenSyntax)?
+  /// True for the binding `asyncVariant` returns: it calls the synchronous function on the concurrent
+  /// pool instead of on the JavaScript thread.
+  private(set) var isAsyncVariant = false
 
   init(funcDecl: FunctionDeclSyntax, attribute: AttributeSyntax) {
     self.swiftName = funcDecl.name.text
@@ -39,6 +48,23 @@ internal struct JSFunction {
     let effectSpecifiers = funcDecl.signature.effectSpecifiers
     self.isThrowing = effectSpecifiers?.throwsClause?.throwsSpecifier != nil
     self.isAsync = effectSpecifiers?.asyncSpecifier != nil
+    self.asyncVariantName = asyncVariantOption(of: attribute).flatMap(asyncVariantName(of:))
+  }
+
+  /// The promise-returning binding that `.withAsync("name")` adds next to a synchronous function, or
+  /// `nil` when the attribute doesn't list it. An `async` function gets none: `@JS` reports the option
+  /// there.
+  var asyncVariant: JSFunction? {
+    guard let asyncVariantName, !isAsync else {
+      return nil
+    }
+    var variant = self
+    variant.jsName = asyncVariantName.name
+    variant.nameToken = asyncVariantName.token
+    variant.isAsync = true
+    variant.isAsyncVariant = true
+    variant.asyncVariantName = nil
+    return variant
   }
 
   /// The number of leading parameters that must always be supplied: the total minus the maximal
@@ -79,14 +105,16 @@ internal struct JSFunction {
         guard arguments.count == \(maximum) else {
           throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
         }
-        """)
+        """
+      )
     } else {
       lines.append(
         """
         guard arguments.count >= \(required) && arguments.count <= \(maximum) else {
           throw Exceptions.ArgumentsRangeMismatch((functionName: "\(jsName)", received: arguments.count, required: \(required), maximum: \(maximum)))
         }
-        """)
+        """
+      )
     }
 
     // Decode the required prefix once — these slots are present in every accepted arity, so the
@@ -142,7 +170,8 @@ internal struct JSFunction {
       lines.append(contentsOf: encodeResultLines())
     }
 
-    return lines
+    return
+      lines
       .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
       .map { indent + $0 }
       .joined(separator: "\n")
@@ -152,14 +181,22 @@ internal struct JSFunction {
   /// the function's async body (`AsyncFunctionBody`), awaiting the call and encoding the result. It
   /// captures only what the call needs — the decoded `arg<i>` locals, the receiver, and `runtime`
   /// for the encode — never `this` or the arguments buffer, which are only valid for the duration
-  /// of the host call.
+  /// of the host call. The `asyncVariant` binding awaits its call on the concurrent pool instead.
   private func asyncBodyLines(receiver: Receiver, arity: Int) -> [String] {
     var lines: [String] = ["return {"]
+    let call =
+      isAsyncVariant
+      ? concurrentCallExpression(receiver: receiver, arity: arity)
+      : callExpression(receiver: receiver, arity: arity)
+    // The concurrent call spans several lines, so each of its lines is indented into the body.
+    let indented = { (statement: String) in
+      statement.split(separator: "\n", omittingEmptySubsequences: false).map { "  " + $0 }
+    }
     if returnType != nil {
-      lines.append("  let result = \(callExpression(receiver: receiver, arity: arity))")
+      lines.append(contentsOf: indented("let result = \(call)"))
       lines.append(contentsOf: encodeResultLines().map { "  " + $0 })
     } else {
-      lines.append("  \(callExpression(receiver: receiver, arity: arity))")
+      lines.append(contentsOf: indented(call))
       lines.append("  return .undefined()")
     }
     lines.append("}")
@@ -179,10 +216,36 @@ internal struct JSFunction {
     )
   }
 
-  /// The `<callee>.<name>(...)` call for the given arity. Slots `0..<arity` are passed their decoded
+  /// The `<callee>.<name>(...)` call for the given arity, with the arguments from `callArguments`.
+  private func callExpression(receiver: Receiver, arity: Int) -> String {
+    // `try` only for a throwing function. An `async` call that doesn't throw must not get one, or the
+    // expansion warns that no throwing call occurs within the `try` expression.
+    let tryKeyword = isThrowing ? "try " : ""
+    let awaitKeyword = isAsync ? "await " : ""
+    return "\(tryKeyword)\(awaitKeyword)\(receiver.callee).\(swiftName)(\(callArguments(arity: arity)))"
+  }
+
+  /// The call of the `asyncVariant` binding for the given arity: the synchronous function runs in a
+  /// `@concurrent` closure, so it leaves the JavaScript thread, and the body continues once it returns.
+  private func concurrentCallExpression(receiver: Receiver, arity: Int) -> String {
+    // The closure captures the receiver and the decoded arguments, so Swift 6 requires them to be
+    // `Sendable`, as it does for the receiver and arguments of a `.concurrent` call. The signature is
+    // spelled out because `@concurrent` needs an `async` closure, and a body without `await` would
+    // infer a synchronous one.
+    let tryKeyword = isThrowing ? "try " : ""
+    let effects = isThrowing ? "async throws" : "async"
+    let returnClause = returnType.map { " -> \(expressionType($0))" } ?? ""
+    return """
+      \(tryKeyword)await { @concurrent () \(effects)\(returnClause) in
+        \(tryKeyword)\(receiver.callee).\(swiftName)(\(callArguments(arity: arity)))
+      }()
+      """
+  }
+
+  /// The argument list of a call for the given arity. Slots `0..<arity` are passed their decoded
   /// `arg<i>`; a trailing optional-without-default slot that this arity omits is passed `nil`; a
   /// trailing defaulted slot that this arity omits is dropped entirely so Swift applies its default.
-  private func callExpression(receiver: Receiver, arity: Int) -> String {
+  private func callArguments(arity: Int) -> String {
     var callArguments: [String] = []
     for (index, parameter) in parameters.enumerated() {
       let label = parameter.firstName.text
@@ -201,11 +264,7 @@ internal struct JSFunction {
       }
       callArguments.append(label == "_" ? value : "\(label): \(value)")
     }
-    // `try` only for a throwing function. An `async` call that doesn't throw must not get one, or the
-    // expansion warns that no throwing call occurs within the `try` expression.
-    let tryKeyword = isThrowing ? "try " : ""
-    let awaitKeyword = isAsync ? "await " : ""
-    return "\(tryKeyword)\(awaitKeyword)\(receiver.callee).\(swiftName)(\(callArguments.joined(separator: ", ")))"
+    return callArguments.joined(separator: ", ")
   }
 
   /// The flat (single-arity) call-and-encode lines used when no trailing parameter is omittable:
@@ -347,7 +406,8 @@ internal struct JSProperty {
       getEncode = "return \(callee).\(swiftName).toJavaScriptValue(in: runtime)"
     }
     lines.append(
-      accessorClosure(descriptorName, "get", receiver: receiver, body: "\(unwrap)\(getEncode)"))
+      accessorClosure(descriptorName, "get", receiver: receiver, body: "\(unwrap)\(getEncode)")
+    )
 
     // Setter: decode argument 0 by the static type through `decode` and write `<callee>.<name>`. A
     // typed setter needs a known value type; when the type couldn't be inferred the property is bound
@@ -358,12 +418,19 @@ internal struct JSProperty {
       let setDecode = "\(callee).\(swiftName) = try \(decode)"
       lines.append(
         accessorClosure(
-          descriptorName, "set", receiver: receiver, returnsVoid: true, body: "\(unwrap)\(setDecode)"))
+          descriptorName,
+          "set",
+          receiver: receiver,
+          returnsVoid: true,
+          body: "\(unwrap)\(setDecode)"
+        )
+      )
     }
 
     lines.append("\(object).defineProperty(\"\(jsName)\", descriptor: \(descriptorName))")
 
-    return lines
+    return
+      lines
       .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
       .map { "  " + $0 }
       .joined(separator: "\n")
@@ -374,12 +441,17 @@ internal struct JSProperty {
   /// A setter passes `returnsVoid`, so its closure declares `-> Void` and binds through the `Void`
   /// overload, like a function that returns nothing.
   private func accessorClosure(
-    _ descriptorName: String, _ key: String, receiver: Receiver, returnsVoid: Bool = false, body: String
+    _ descriptorName: String,
+    _ key: String,
+    receiver: Receiver,
+    returnsVoid: Bool = false,
+    body: String
   ) -> String {
     let captures = receiver.captureClause
     // Indent each line of a (possibly multi-line) body to sit one level inside the closure; a bare
     // `\(body)` interpolation would only indent the first line.
-    let indentedBody = body
+    let indentedBody =
+      body
       .split(separator: "\n", omittingEmptySubsequences: false)
       .map { "  \($0)" }
       .joined(separator: "\n")
@@ -404,7 +476,10 @@ internal struct JSProperty {
 /// how each binding reaches its Swift value (module `self`, shared-object instance `_self`, or the
 /// metatype for a static member).
 private func decorateBody(
-  functions: [JSFunction], properties: [JSProperty], object: String, receiver: Receiver
+  functions: [JSFunction],
+  properties: [JSProperty],
+  object: String,
+  receiver: Receiver
 ) -> String {
   let functionBody = functions.map { $0.decorateStatements(object: object, receiver: receiver) }
   let propertyBody = properties.map { $0.decorateStatements(object: object, receiver: receiver) }
@@ -421,7 +496,11 @@ private func decorateBody(
 /// receiver; the shared-object counterpart is `buildDecorateSharedObjectPhase`.
 internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties: [JSProperty]) -> DeclSyntax {
   let body = decorateBody(
-    functions: functions, properties: properties, object: Phase.object.rawValue, receiver: .module)
+    functions: functions,
+    properties: properties,
+    object: Phase.object.rawValue,
+    receiver: .module
+  )
   return """
     @JavaScriptActor
     public func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime) throws {
@@ -442,13 +521,21 @@ internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties:
 /// which builds an instance and is emitted separately (see `JSConstructor.buildConstructor`). Each phase
 /// is emitted only when the type has a member for it.
 internal func buildDecorateSharedObjectPhase(
-  phase: Phase, functions: [JSFunction], properties: [JSProperty], typeName: String
+  phase: Phase,
+  functions: [JSFunction],
+  properties: [JSProperty],
+  typeName: String
 ) -> DeclSyntax {
-  let receiver: Receiver = phase == .constructor
+  let receiver: Receiver =
+    phase == .constructor
     ? .staticMember(typeName: typeName)
     : .sharedObject(typeName: typeName)
   let body = decorateBody(
-    functions: functions, properties: properties, object: phase.rawValue, receiver: receiver)
+    functions: functions,
+    properties: properties,
+    object: phase.rawValue,
+    receiver: receiver
+  )
   return """
     @JavaScriptActor
     public override class func _decorateSharedObject(\(raw: phase.rawValue): borrowing JavaScriptObject, in runtime: JavaScriptRuntime) throws {