@expo/expo-modules-macros-plugin 0.6.1 → 0.7.0

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -2,7 +2,7 @@ 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, the enclosing
-/// macro synthesizes a decorator (`_decorateModule` / `_decorateSharedObject`) that binds each such
+/// macro synthesizes a decorator (`_decorateModule(object:)` / `_decorateSharedObject(prototype:)`) that binds each such
 /// function into the 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.
@@ -60,7 +60,7 @@ internal struct JSFunction {
     let maximum = parameters.count
     var lines: [String] = []
 
-    if let unwrap = receiver.unwrapStatement {
+    if let unwrap = receiver.unwrapStatement(isAsync: isAsync) {
       lines.append(unwrap)
     }
 
@@ -177,11 +177,26 @@ internal struct JSFunction {
   /// and throws instead of silently encoding an out-of-safe-range value as a lossy number — the
   /// catchable error is the right behavior, and matches how non-primitive integers already encode. A
   /// no-return function returns `.undefined` instead.
+  ///
+  /// For an `async` function the encode must run on the JS thread. An `async` body may suspend and
+  /// resume on an arbitrary cooperative-pool thread, and encoding a heap-allocated JS value (a string,
+  /// object, array, or typed array) off the JS thread races the engine's garbage collector and
+  /// corrupts the heap. `runtime.execute` hops the encode onto the JS thread, running inline when it is
+  /// already there (the common case, where the body never truly suspended), so synchronous functions —
+  /// which always run on the JS thread — keep encoding directly without the wrapper.
   private func encodeResultLines() -> [String] {
     guard let returnType else {
       return ["return .undefined"]
     }
-    return ["return try \(expressionType(returnType)).encode(result, in: runtime)"]
+    let encode = "try \(expressionType(returnType)).encode(result, in: runtime)"
+    if isAsync {
+      return [
+        "return try await runtime.execute {",
+        "  return \(encode)",
+        "}",
+      ]
+    }
+    return ["return \(encode)"]
   }
 
   /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode
@@ -194,7 +209,7 @@ internal struct JSFunction {
   /// 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. A shared object
   /// captures nothing of the instance: it recovers the typed receiver from the JS `this` per call.
-  func decorateStatements(receiver: Receiver) -> String {
+  func decorateStatements(object: String, receiver: Receiver) -> String {
     // Synchronous `@JS` bindings bind through the unowned-`this` `setProperty` overload, which hands
     // `this` in as a borrowed `JavaScriptUnownedValue` instead of allocating an owning
     // `JavaScriptValue` and forming its `weak`-runtime reference on every call. A module ignores
@@ -210,7 +225,6 @@ internal struct JSFunction {
       ? "this, arguments"
       : "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
 
-    let object = receiver.decoratedObject
     return """
         \(object).setProperty("\(jsName)") { \(captures)\(parameters) in
       \(bodyStatements(receiver: receiver, indent: "    "))
@@ -221,7 +235,7 @@ internal struct JSFunction {
 
 /// A `@JS var` collected for **direct JSI binding**. Instead of describing the property with a
 /// `Property(...)` DSL entry, the enclosing macro synthesizes a get/set accessor into the JS object
-/// inside its decorator (`_decorateModule` / `_decorateSharedObject`): it builds a descriptor object
+/// inside its decorator (`_decorateModule(object:)` / `_decorateSharedObject(prototype:)`): it builds a descriptor object
 /// (`enumerable` + `get`, and `set` when the property is settable) and installs it with
 /// `object.defineProperty(name, descriptor:)`, mirroring core's `PropertyDefinition.buildDescriptor`.
 /// The `get`/`set` host functions are installed the same way `@JS func`s are — the closure-taking
@@ -248,13 +262,13 @@ internal struct JSProperty {
   /// closure — and installs it with `object.defineProperty(name, descriptor:)`. Capture matches the
   /// function bindings: a module captures `self` strong, a shared object captures nothing of the
   /// instance. Getter and setter are gated independently.
-  func decorateStatements(receiver: Receiver) -> String {
+  func decorateStatements(object: String, receiver: Receiver) -> String {
     let descriptorName = "\(swiftName)Descriptor"
     let callee = receiver.callee
-    let object = receiver.decoratedObject
     // A shared object's accessors unwrap the JS `this` into `_self` before reading/writing; a module
-    // reads `self` directly. The unwrap leads each accessor body.
-    let unwrap = receiver.unwrapStatement.map { "\($0)\n" } ?? ""
+    // reads `self` directly. The unwrap leads each accessor body. Property accessors are synchronous, so
+    // they take the borrowed unowned `this`.
+    let unwrap = receiver.unwrapStatement(isAsync: false).map { "\($0)\n" } ?? ""
     var lines: [String] = []
 
     lines.append("let \(descriptorName) = runtime.createObject()")
@@ -318,24 +332,30 @@ internal struct JSProperty {
   }
 }
 
-/// The body shared by both decorators: every `@JS func` bound via an inlined `setProperty` closure
-/// and every `@JS var` via a `defineProperty` accessor, joined for the function body. The `receiver`
-/// selects how each binding reaches its Swift value (module `self` vs. shared-object `_self`).
-private func decorateBody(functions: [JSFunction], properties: [JSProperty], receiver: Receiver) -> String {
-  let functionBody = functions.map { $0.decorateStatements(receiver: receiver) }
-  let propertyBody = properties.map { $0.decorateStatements(receiver: receiver) }
+/// The body shared by every decorator phase: every `@JS func` bound via an inlined `setProperty`
+/// closure and every `@JS var` via a `defineProperty` accessor, joined for the function body. `object`
+/// is the local the bindings decorate (matching the entry point's argument label); `receiver` selects
+/// 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
+) -> String {
+  let functionBody = functions.map { $0.decorateStatements(object: object, receiver: receiver) }
+  let propertyBody = properties.map { $0.decorateStatements(object: object, receiver: receiver) }
   return (functionBody + propertyBody).joined(separator: "\n")
 }
 
-/// The single generated function that decorates the module's JS object. Core supplies the object;
-/// this binds every `@JS func` (via an inlined `setProperty` closure) and every `@JS var` (via a
-/// `defineProperty` accessor) into it. 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`). The bindings call into the module `self`.
+/// The module decorator: a `_decorateModule(object:)` that binds every `@JS func` (via an inlined
+/// `setProperty` closure) and every `@JS var` (via a `defineProperty` accessor) into the module's own
+/// JS object. Core supplies the object; the bindings call into the module `self`. It's an *instance*
+/// method (a module is a singleton, satisfying the `AnyModule` requirement of the same name), mirroring
+/// core's `ObjectDefinition.decorate(object:)` including the `borrowing` object parameter (it mutates
+/// through the reference without reassigning or taking ownership). Only emitted when there's at least
+/// one member to bind. Uses the shared body generation with the module `object:` phase and `self`
+/// receiver; the shared-object counterpart is `buildDecorateSharedObjectPhase`.
 internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties: [JSProperty]) -> DeclSyntax {
-  let body = decorateBody(functions: functions, properties: properties, receiver: .module)
+  let body = decorateBody(
+    functions: functions, properties: properties, object: Phase.object.rawValue, receiver: .module)
   return """
     @JavaScriptActor
     public func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime) throws {
@@ -344,22 +364,28 @@ internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties:
     """
 }
 
-/// The shared-object counterpart of `_decorateModule`. Core supplies the class `prototype`; this binds
-/// every `@JS func` and `@JS var` of the given shared-object type onto it. Because a shared object has a
-/// distinct native instance behind each JS object, the bindings recover the typed receiver from the JS
-/// `this` per call (`try SharedObject.native(from: this.asObject(in: runtime), as: <Type>.self)`)
-/// rather than capturing a singleton `self`. Overrides the base `SharedObject` class method so core can
-/// dispatch to it through the concrete type's metatype. The first parameter is `prototype` (not `object`
-/// as on `_decorateModule`) because it's the shared class prototype, not an instance. The constructor is
-/// bound separately (see `JSConstructor.buildConstructor`). Only emitted when the type has at least one
-/// `@JS func`/`var`.
-internal func buildDecorateSharedObject(
-  functions: [JSFunction], properties: [JSProperty], typeName: String
+/// A shared-object decorator phase, a label overload of `_decorateSharedObject` overriding the matching
+/// `open class func` on the `SharedObject` base so core can dispatch through the concrete type's
+/// metatype. The `prototype:` overload binds the type's instance `@JS func`/`var` members onto the class
+/// prototype (the original hook, unchanged); the `constructor:` overload binds the `static`/`class` ones
+/// onto the constructor function itself (a new, additive overload, so introducing it isn't a breaking
+/// core change). Both are *static* (a shared object has no singleton `self`). An instance binding
+/// recovers its typed receiver from the JS `this` per call (`SharedObject.native(from:as:)`); a static
+/// binding calls the Swift member on the type and ignores `this` (which, on the static side, is the
+/// constructor). The constructor *object* the static members decorate is distinct from the `@JS init`,
+/// 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
 ) -> DeclSyntax {
-  let body = decorateBody(functions: functions, properties: properties, receiver: .sharedObject(typeName: typeName))
+  let receiver: Receiver = phase == .constructor
+    ? .staticMember(typeName: typeName)
+    : .sharedObject(typeName: typeName)
+  let body = decorateBody(
+    functions: functions, properties: properties, object: phase.rawValue, receiver: receiver)
   return """
     @JavaScriptActor
-    public override class func _decorateSharedObject(prototype: borrowing JavaScriptObject, in runtime: JavaScriptRuntime) throws {
+    public override class func _decorateSharedObject(\(raw: phase.rawValue): borrowing JavaScriptObject, in runtime: JavaScriptRuntime) throws {
     \(raw: body)
     }
     """

package/apple/Sources/ExpoModulesMacros/JSMacro.swift

@@ -98,14 +98,6 @@ private func boundaryMember(of declaration: some DeclSyntaxProtocol) -> Boundary
   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 {

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -43,6 +43,15 @@ internal func isOptionalType(_ type: TypeSyntax) -> Bool {
   return false
 }
 
+/// True when the modifiers make the member type-level (`static` or `class`). A shared object routes
+/// such members to its constructor (JS-static) and instance members to its prototype; the `@JS`
+/// conformance assertion also uses this to emit its peer in the matching metatype context.
+internal func isTypeLevel(_ modifiers: DeclModifierListSyntax) -> Bool {
+  return modifiers.contains {
+    $0.name.tokenKind == .keyword(.static) || $0.name.tokenKind == .keyword(.class)
+  }
+}
+
 /// True if a trailing occurrence of this parameter may be omitted by the JS caller: it either has a
 /// default value (Swift applies it) or is an optional type (an absent slot becomes `nil`). The arity
 /// range and the per-arity call branches are derived from this.
@@ -145,14 +154,13 @@ internal func memberHasJSAttribute(_ decl: DeclSyntaxProtocol) -> Bool {
   return false
 }
 
-/**
- Decides whether the macro should stamp `@JavaScriptActor` on a `@JS`-marked member.
- The macro defers to the user when they've already chosen an isolation:
- - the `nonisolated` modifier is present on the member
- - any attribute whose name matches a known global actor (`@MainActor`, `@JavaScriptActor`)
-   or follows the `*Actor` naming convention is present on the member or its enclosing type
- Async members never get the stamp because `AsyncFunction` controls their dispatch separately.
- */
+/// Decides whether the macro should stamp `@JavaScriptActor` on a `@JS`-marked member.
+/// The macro defers to the user when they've already chosen an isolation:
+/// - the `nonisolated` modifier is present on the member
+/// - any attribute whose name matches a known global actor (`@MainActor`, `@JavaScriptActor`)
+///   or follows the `*Actor` naming convention is present on the member or its enclosing type
+/// `async` members are stamped too: an `async` function starts its execution on the JS thread and
+/// stays there until the first suspension point, where it may hop to another executor.
 internal func shouldStampJavaScriptActor(
   on member: DeclSyntaxProtocol,
   enclosedBy enclosing: some DeclGroupSyntax
@@ -162,11 +170,6 @@ internal func shouldStampJavaScriptActor(
     return false
   }
 
-  if let funcDecl = member.as(FunctionDeclSyntax.self),
-    funcDecl.signature.effectSpecifiers?.asyncSpecifier != nil {
-    return false
-  }
-
   let memberAttributes = memberAttributes(of: member)
   if memberAttributes.contains(where: hasGlobalActorShape) {
     return false

package/apple/Sources/ExpoModulesMacros/Receiver.swift

@@ -1,57 +1,80 @@
 import SwiftSyntax
 
-/// Where a directly-bound closure gets the Swift value it calls into. A module is a singleton, so its
-/// bindings call `self` and ignore the JS `this`; a shared object has a distinct native instance per JS
-/// object, so its bindings recover the typed receiver from `this`.
+/// Where a directly-bound closure gets the Swift value it calls into. This is one of the two
+/// orthogonal axes of a binding; the other is the `Phase` (which JS object the member is installed
+/// on). The two are independent: choosing the prototype phase does not by itself decide whether the
+/// receiver is `self`, `_self`, or the metatype.
+///
+/// - A module is a singleton, so its bindings call `self` and ignore the JS `this`.
+/// - A shared-object *instance* member has a distinct native instance per JS object, so it recovers
+///   the typed receiver from `this`.
+/// - A `static`/`class` member has no instance at all; it calls the Swift member on the metatype
+///   (`Cache.open(…)`) and ignores `this` (which, on the static side, is the constructor).
 internal enum Receiver {
   /// The module singleton; the closure captures `self` strong.
   case module
   /// A shared object of the given concrete type; the closure captures nothing and recovers the receiver
   /// from `this` per call.
   case sharedObject(typeName: String)
+  /// A `static`/`class` member of the given concrete type; the closure captures nothing and calls the
+  /// Swift member on the type itself, ignoring `this`.
+  case staticMember(typeName: String)
 
   /// The expression the body calls members on: `self` for a module, `_self` (bound by `unwrapStatement`)
-  /// for a shared object. The leading underscore avoids colliding with a user member like `var owner`.
+  /// for a shared-object instance, the type name for a static member. The leading underscore on `_self`
+  /// avoids colliding with a user member like `var owner`.
   var callee: String {
     switch self {
     case .module:
       return "self"
     case .sharedObject:
       return "_self"
+    case .staticMember(let typeName):
+      return typeName
     }
   }
 
-  /// The JS object the decorator binds members onto, matching its first parameter: `object` for a
-  /// module (its own JS object), `prototype` for a shared object (the shared class prototype).
-  var decoratedObject: String {
+  /// The leading body line binding the receiver, or `nil` when nothing needs to be unwrapped (a module
+  /// reads `self` directly; a static member calls the type directly). For a shared-object instance,
+  /// `native(from:as:)` recovers the typed instance from `this`, throwing on a foreign object or a type
+  /// mismatch.
+  ///
+  /// The `this` object comes from the borrowed `JavaScriptUnownedValue` in a sync binding (`asObject(in:)`)
+  /// and from the owning `JavaScriptValue` in an async one (`asObject()`). An async binding must take an
+  /// owning `this` because a borrowed unowned value can't survive the closure's suspension points.
+  func unwrapStatement(isAsync: Bool) -> String? {
     switch self {
-    case .module:
-      return "object"
-    case .sharedObject:
-      return "prototype"
-    }
-  }
-
-  /// The leading body line binding the receiver, or `nil` for a module (it reads `self` directly). For a
-  /// shared object, `native(from:as:)` recovers the typed instance from the borrowed `this`, throwing on
-  /// a foreign object or a type mismatch.
-  var unwrapStatement: String? {
-    switch self {
-    case .module:
+    case .module, .staticMember:
       return nil
     case .sharedObject(let typeName):
-      return "let _self = try SharedObject.native(from: this.asObject(in: runtime), as: \(typeName).self)"
+      let thisObject = isAsync ? "this.asObject()" : "this.asObject(in: runtime)"
+      return "let _self = try SharedObject.native(from: \(thisObject), as: \(typeName).self)"
     }
   }
 
   /// The capture-clause fragment (with a trailing space, or empty when nothing is captured). A module
-  /// captures `self` strong; a shared object captures nothing of the instance.
+  /// captures `self` strong; a shared-object instance and a static member capture nothing.
   var captureClause: String {
     switch self {
     case .module:
       return "[self] "
-    case .sharedObject:
+    case .sharedObject, .staticMember:
       return ""
     }
   }
 }
+
+/// Which JS object a set of bindings is installed on: the second orthogonal axis alongside `Receiver`.
+/// It selects the decorator entry point's argument label and the local name the body binds members onto,
+/// mirroring JS class semantics (a class has a constructor function whose `.prototype` carries instance
+/// members) and core's `ClassDefinition.decorate`.
+/// The raw value is the argument label of the decorator entry point, which is also the local name the
+/// body binds members onto.
+internal enum Phase: String {
+  /// A concrete JS object: a singleton's own object (the module). Instance method; receiver `self`.
+  case object
+  /// The class constructor's `prototype`, carrying per-instance members. Static; receiver `_self`.
+  case prototype
+  /// The class constructor function itself, carrying `static`/`class` members. Static; receiver the type.
+  case constructor
+}

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -42,13 +42,20 @@ public struct SharedObjectMacro: MemberMacro {
     let jsName = jsNameArgument(of: node) ?? typeName
 
     // `@JS func`s/`var`s and the `@JS init` are bound directly into the shared object's JS object by
-    // the synthesized `_decorateSharedObject` / `_constructSharedObject` rather than described with a
-    // `Function(...)` / `Property(...)` / `Constructor { … }` DSL entry, so they're collected here
-    // instead of appended to the `Class` block. The block keeps only non-`@JS` definitions (none are
-    // collected today), so it's empty when every member is `@JS`.
+    // the synthesized `_decorateSharedObject(prototype:)` / `_decorateSharedObject(constructor:)` / `_constructSharedObject`
+    // rather than described with a `Function(...)` / `Property(...)` / `Constructor { … }` DSL entry, so
+    // they're collected here instead of appended to the `Class` block. The block keeps only non-`@JS`
+    // definitions (none are collected today), so it's empty when every member is `@JS`.
+    //
+    // Members split by the `static`/`class` modifier onto two different JS objects: instance members
+    // decorate the prototype (receiver recovered from JS `this`), static members decorate the
+    // constructor (called on the metatype). A JS instance and static member may share a name without
+    // colliding: they live on different objects.
     let entries: [String] = []
-    var functions: [JSFunction] = []
-    var properties: [JSProperty] = []
+    var instanceFunctions: [JSFunction] = []
+    var instanceProperties: [JSProperty] = []
+    var staticFunctions: [JSFunction] = []
+    var staticProperties: [JSProperty] = []
     var constructor: JSConstructor?
 
     for member in classDecl.memberBlock.members {
@@ -66,13 +73,23 @@ public struct SharedObjectMacro: MemberMacro {
 
       if let funcDecl = decl.as(FunctionDeclSyntax.self),
         let attribute = funcDecl.attributes.firstAttribute(named: "JS") {
-        functions.append(JSFunction(funcDecl: funcDecl, attribute: attribute))
+        let function = JSFunction(funcDecl: funcDecl, attribute: attribute)
+        if isTypeLevel(funcDecl.modifiers) {
+          staticFunctions.append(function)
+        } else {
+          instanceFunctions.append(function)
+        }
         continue
       }
 
       if let varDecl = decl.as(VariableDeclSyntax.self),
         let attribute = varDecl.attributes.firstAttribute(named: "JS") {
-        properties.append(contentsOf: collectProperties(varDecl: varDecl, attribute: attribute))
+        let collected = collectProperties(varDecl: varDecl, attribute: attribute)
+        if isTypeLevel(varDecl.modifiers) {
+          staticProperties.append(contentsOf: collected)
+        } else {
+          instanceProperties.append(contentsOf: collected)
+        }
       }
     }
 
@@ -89,13 +106,22 @@ public struct SharedObjectMacro: MemberMacro {
       """
     ]
 
-    // Direct JSI binding: one `_decorateSharedObject` that binds each `@JS func`/`var` onto the JS
-    // object (unwrapping the per-call receiver from `this`), and a `_constructSharedObject` that
-    // builds an instance from the `@JS init` arguments. Each is emitted only when it has something
-    // to do.
-    if !functions.isEmpty || !properties.isEmpty {
+    // Direct JSI binding, split by which JS object each member decorates:
+    // `_decorateSharedObject(prototype:)` binds instance `@JS func`/`var`s (unwrapping the per-call receiver from
+    // `this`); `_decorateSharedObject(constructor:)` binds `static`/`class` ones (called on the metatype); and
+    // `_constructSharedObject` builds an instance from the `@JS init` arguments. Each is emitted only
+    // when it has something to bind.
+    if !instanceFunctions.isEmpty || !instanceProperties.isEmpty {
+      emitted.append(
+        buildDecorateSharedObjectPhase(
+          phase: .prototype, functions: instanceFunctions, properties: instanceProperties,
+          typeName: typeName))
+    }
+    if !staticFunctions.isEmpty || !staticProperties.isEmpty {
       emitted.append(
-        buildDecorateSharedObject(functions: functions, properties: properties, typeName: typeName))
+        buildDecorateSharedObjectPhase(
+          phase: .constructor, functions: staticFunctions, properties: staticProperties,
+          typeName: typeName))
     }
     if let constructor {
       emitted.append(constructor.buildConstructor(typeName: typeName))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/expo-modules-macros-plugin",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Swift macro plugin for Expo modules",
   "license": "MIT",
   "author": "650 Industries, Inc.",