@expo/expo-modules-macros-plugin 0.4.0 → 0.5.0

package/apple/Sources/ExpoModulesMacros/DecorateModuleBuilder.swift

@@ -1,17 +1,15 @@
 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).
- */
+/// 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
+/// 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.
+///
+/// The receiver (see `Receiver`) is the module's `self` for a module binding, or the per-call `_self`
+/// unwrapped from the JS `this` for a shared-object binding. 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
@@ -50,19 +48,23 @@ internal struct JSFunction {
   }
 
   /// The decode-call-encode statements that form the host-function body, indented with the given
-  /// prefix. An arity guard (an exact check when every parameter is required, otherwise a range
-  /// check) throwing `Exceptions.ArgumentsRangeMismatch`; then the decode of the always-present
-  /// required prefix (primitives via a direct typed accessor like `asDouble()` on a zero-copy
-  /// `arguments.unownedValue(at:)`, others via `getDynamicType().cast(...)`); then the call and
-  /// result encode (primitives via `toJavaScriptValue(in:)`, others via `castToJS(...)`). When a
-  /// trailing run of parameters is omittable the call branches on `arguments.count`, decoding only
-  /// the slots that branch actually has — `arguments[i]` traps past `count`, so a slot the caller
-  /// didn't pass is never indexed.
-  private func bodyStatements(indent: String) -> String {
+  /// prefix. Receiver unwrap (shared objects only), then an arity guard (an exact check when every
+  /// parameter is required, otherwise a range check) throwing `Exceptions.ArgumentsRangeMismatch`;
+  /// then the decode of the always-present required prefix (primitives via a direct typed accessor
+  /// like `asDouble()` on a zero-copy `arguments.unownedValue(at:)`, others via
+  /// `getDynamicType().cast(...)`); then the call and result encode (primitives via
+  /// `toJavaScriptValue(in:)`, others via `castToJS(...)`). When a trailing run of parameters is
+  /// omittable the call branches on `arguments.count`, decoding only the slots that branch actually
+  /// has — `arguments[i]` traps past `count`, so a slot the caller didn't pass is never indexed.
+  private func bodyStatements(receiver: Receiver, indent: String) -> String {
     let required = requiredArgumentCount
     let maximum = parameters.count
     var lines: [String] = []
 
+    if let unwrap = receiver.unwrapStatement {
+      lines.append(unwrap)
+    }
+
     if required == maximum {
       lines.append(
         """
@@ -87,7 +89,7 @@ internal struct JSFunction {
 
     if required == maximum {
       // No omittable trailing run: a single flat call with every argument decoded.
-      lines.append(contentsOf: callAndEncodeLines(arity: maximum, decodingFrom: required))
+      lines.append(contentsOf: callAndEncodeLines(receiver: receiver, arity: maximum, decodingFrom: required))
     } else {
       // One call shape per accepted arity. Each branch decodes only the trailing slots it has and
       // fills the rest (defaulted params drop their label so Swift applies the default; optional
@@ -105,7 +107,7 @@ internal struct JSFunction {
         for index in required..<arity {
           lines.append("  " + decodeStatement(at: index))
         }
-        lines.append("  \(callExpression(arity: arity))")
+        lines.append("  \(callExpression(receiver: receiver, arity: arity))")
       }
       lines.append("}")
       lines.append(contentsOf: encodeResultLines())
@@ -127,13 +129,14 @@ internal struct JSFunction {
     if let accessor = fastDecodeAccessor(for: type) {
       return "let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()"
     }
-    return "let arg\(index) = try \(type).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(type)"
+    let exprType = expressionType(type)
+    return "let arg\(index) = try \(exprType).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(exprType)"
   }
 
-  /// The `self.<name>(...)` call for the given arity. Slots `0..<arity` are passed their decoded
+  /// The `<callee>.<name>(...)` 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(arity: Int) -> String {
+  private func callExpression(receiver: Receiver, arity: Int) -> String {
     var callArguments: [String] = []
     for (index, parameter) in parameters.enumerated() {
       let label = parameter.firstName.text
@@ -154,21 +157,22 @@ internal struct JSFunction {
     }
     let tryKeyword = (isThrowing || isAsync) ? "try " : ""
     let awaitKeyword = isAsync ? "await " : ""
-    return "\(tryKeyword)\(awaitKeyword)self.\(swiftName)(\(callArguments.joined(separator: ", ")))"
+    return "\(tryKeyword)\(awaitKeyword)\(receiver.callee).\(swiftName)(\(callArguments.joined(separator: ", ")))"
   }
 
   /// The flat (single-arity) call-and-encode lines used when no trailing parameter is omittable:
-  /// `let result = self.f(...)` then the return encode (or the no-return `self.f(...)` + `.undefined`).
-  private func callAndEncodeLines(arity: Int, decodingFrom: Int) -> [String] {
+  /// `let result = <callee>.f(...)` then the return encode (or the no-return `<callee>.f(...)` +
+  /// `.undefined`).
+  private func callAndEncodeLines(receiver: Receiver, arity: Int, decodingFrom: Int) -> [String] {
     var lines: [String] = []
     for index in decodingFrom..<arity {
       lines.append(decodeStatement(at: index))
     }
     if returnType != nil {
-      lines.append("let result = \(callExpression(arity: arity))")
+      lines.append("let result = \(callExpression(receiver: receiver, arity: arity))")
       lines.append(contentsOf: encodeResultLines())
     } else {
-      lines.append(callExpression(arity: arity))
+      lines.append(callExpression(receiver: receiver, arity: arity))
       lines.append("return .undefined")
     }
     return lines
@@ -184,7 +188,7 @@ internal struct JSFunction {
     if fastDecodeAccessor(for: returnType) != nil {
       return ["return result.toJavaScriptValue(in: runtime)"]
     }
-    return ["return try \(returnType).getDynamicType().castToJS(result, appContext: appContext, in: runtime)"]
+    return ["return try \(expressionType(returnType)).getDynamicType().castToJS(result, appContext: appContext, in: runtime)"]
   }
 
   /// The `setProperty` statement that installs this function on the JS object. The decode-call-encode
@@ -193,42 +197,44 @@ internal struct JSFunction {
   /// 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.
+  /// Capture mirrors core's `SyncFunctionDefinition.build`: a module captures its `self` **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. A shared object
+  /// captures nothing of the instance: it recovers the typed receiver from the JS `this` per call.
   /// `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 {
-    // Synchronous `@JS` functions never decode `this` (the receiver is the module's real `self`), so
-    // they 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. The first parameter is typed `borrowing
+  func decorateStatements(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
+    // `this`; a shared object unwraps it (still borrowed). The first parameter is typed `borrowing
     // JavaScriptUnownedValue` to select that (otherwise `@_disfavoredOverload`) overload — which
     // requires the *parenthesized, fully typed* parameter list, since Swift rejects a type annotation
     // on a shorthand `{ [capture] name, name in }` parameter. Async functions keep the untyped
     // shorthand and the owning-`this` overload: there is no unowned-`this` async variant and the buffer
     // escapes into the task anyway.
-    let captures = usesAppContext ? "[weak appContext, self]" : "[self]"
+    let captures = receiver.captureClause(usesAppContext: usesAppContext)
     let parameters =
       isAsync
       ? "this, arguments"
       : "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
 
+    let object = receiver.decoratedObject
     if usesAppContext {
       return """
-          object.setProperty("\(jsName)") { \(captures) \(parameters) in
+          \(object).setProperty("\(jsName)") { \(captures)\(parameters) in
             guard let appContext else {
               throw Exceptions.AppContextLost()
             }
-        \(bodyStatements(indent: "    "))
+        \(bodyStatements(receiver: receiver, indent: "    "))
           }
         """
     }
     return """
-        object.setProperty("\(jsName)") { \(captures) \(parameters) in
-      \(bodyStatements(indent: "    "))
+        \(object).setProperty("\(jsName)") { \(captures)\(parameters) in
+      \(bodyStatements(receiver: receiver, indent: "    "))
         }
       """
   }
@@ -248,17 +254,18 @@ internal struct JSFunction {
 }
 
 /// A `@JS var` collected for **direct JSI binding**. Instead of describing the property with a
-/// `Property(...)` DSL entry, `@ExpoModule` synthesizes a get/set accessor into the module's JS
-/// object inside `_decorateModule`: 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 `setProperty(_:)` overload, with the
-/// read/write body inlined into the closure.
+/// `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
+/// (`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
+/// `setProperty(_:)` overload, with the read/write body inlined into the closure.
 ///
-/// The receiver is the module's real `self`, so the getter reads `self.<name>` and the setter writes
-/// `self.<name> = …` directly, ignoring the JS `this`. Decode/encode of the value reuse the same
-/// static-type fast path as functions (primitives through a direct typed accessor / `toJavaScriptValue`,
-/// other types through the `getDynamicType()` converter).
+/// The receiver (see `Receiver`) is the module's `self` for a module binding, or the per-call `_self`
+/// unwrapped from the JS `this` for a shared object. The getter reads `<callee>.<name>` and the setter
+/// writes `<callee>.<name> = …`. Decode/encode of the value reuse the same static-type fast path as
+/// functions (primitives through a direct typed accessor / `toJavaScriptValue`, other types through
+/// the `getDynamicType()` converter).
 internal struct JSProperty {
   let swiftName: String
   let jsName: String
@@ -271,54 +278,66 @@ internal struct JSProperty {
   let isSettable: Bool
 
   /// The statements that install this property's accessor on the JS object, indented for the
-  /// `_decorateModule` body. Builds a descriptor object (`enumerable` + `get`, and `set` when
-  /// settable) via the closure-taking `setProperty(_:)` overload — with the read/write body inlined
-  /// into each closure — and installs it with `object.defineProperty(name, descriptor:)`. Capture
-  /// matches the function bindings: `self` strong, `appContext` weak + guarded — and, like functions,
-  /// the `appContext` capture + guard are omitted from an accessor whose body never references it (a
-  /// primitive value, decoded/encoded without the dynamic converter), to avoid the unused-capture
-  /// warning. Getter and setter are gated independently.
-  var decorateStatements: String {
+  /// decorator body. Builds a descriptor object (`enumerable` + `get`, and `set` when settable) via
+  /// the closure-taking `setProperty(_:)` overload — with the read/write body inlined into each
+  /// 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; `appContext` is weak + guarded — and, like functions, the `appContext` capture + guard
+  /// are omitted from an accessor whose body never references it (a primitive value, decoded/encoded
+  /// without the dynamic converter), to avoid the unused-capture warning. Getter and setter are gated
+  /// independently.
+  func decorateStatements(receiver: Receiver) -> String {
     let descriptorName = "\(swiftName)Descriptor"
+    let callee = receiver.callee
+    let object = receiver.decoratedObject
     // A primitive value type encodes/decodes without `getDynamicType()`, so its accessor body never
     // references `appContext`. `nil` (untyped) goes through the dynamic-less `toJavaScriptValue`
     // getter, which also doesn't use it.
     let usesAppContext = valueType.map { fastDecodeAccessor(for: $0) == nil } ?? false
+    // 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" } ?? ""
     var lines: [String] = []
 
     lines.append("let \(descriptorName) = runtime.createObject()")
     lines.append("\(descriptorName).setProperty(\"enumerable\", value: true)")
 
-    // Getter: read `self.<name>` and encode the result back to JS.
+    // Getter: read `<callee>.<name>` and encode the result back to JS.
     let getEncode: String
     if let valueType, fastDecodeAccessor(for: valueType) != nil {
-      getEncode = "return self.\(swiftName).toJavaScriptValue(in: runtime)"
+      getEncode = "return \(callee).\(swiftName).toJavaScriptValue(in: runtime)"
     } else if let valueType {
       getEncode =
-        "return try \(valueType).getDynamicType().castToJS(self.\(swiftName), appContext: appContext, in: runtime)"
+        "return try \(expressionType(valueType)).getDynamicType().castToJS(\(callee).\(swiftName), appContext: appContext, in: runtime)"
     } else {
-      // No known type: fall back to converting whatever `self.<name>` is. This only happens when the
-      // declaration has neither an annotation nor a literal default, which is rare for a stored var.
-      getEncode = "return self.\(swiftName).toJavaScriptValue(in: runtime)"
+      // No known type: fall back to converting whatever `<callee>.<name>` is. This only happens when
+      // the declaration has neither an annotation nor a literal default, which is rare for a stored
+      // var.
+      getEncode = "return \(callee).\(swiftName).toJavaScriptValue(in: runtime)"
     }
-    lines.append(accessorClosure(descriptorName, "get", usesAppContext: usesAppContext, body: getEncode))
+    lines.append(
+      accessorClosure(
+        descriptorName, "get", receiver: receiver, usesAppContext: usesAppContext, body: "\(unwrap)\(getEncode)"))
 
-    // Setter: decode argument 0 by the static type and write `self.<name>`. A typed setter needs a
-    // known value type; when the type couldn't be inferred the property is bound getter-only (a
+    // Setter: decode argument 0 by the static type and write `<callee>.<name>`. A typed setter needs
+    // a known value type; when the type couldn't be inferred the property is bound getter-only (a
     // settable var with neither an annotation nor a literal default is rare and can't be decoded).
     if isSettable, let valueType {
       let setDecode: String
       if let accessor = fastDecodeAccessor(for: valueType) {
-        setDecode = "self.\(swiftName) = try arguments.unownedValue(at: 0).\(accessor)()"
+        setDecode = "\(callee).\(swiftName) = try arguments.unownedValue(at: 0).\(accessor)()"
       } else {
+        let exprType = expressionType(valueType)
         setDecode =
-          "self.\(swiftName) = try \(valueType).getDynamicType().cast(jsValue: arguments[0], appContext: appContext) as! \(valueType)"
+          "\(callee).\(swiftName) = try \(exprType).getDynamicType().cast(jsValue: arguments[0], appContext: appContext) as! \(exprType)"
       }
       lines.append(
-        accessorClosure(descriptorName, "set", usesAppContext: usesAppContext, body: "\(setDecode)\nreturn .undefined"))
+        accessorClosure(
+          descriptorName, "set", receiver: receiver, usesAppContext: usesAppContext,
+          body: "\(unwrap)\(setDecode)\nreturn .undefined"))
     }
 
-    lines.append("object.defineProperty(\"\(jsName)\", descriptor: \(descriptorName))")
+    lines.append("\(object).defineProperty(\"\(jsName)\", descriptor: \(descriptorName))")
 
     return lines
       .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
@@ -326,26 +345,29 @@ internal struct JSProperty {
       .joined(separator: "\n")
   }
 
-  /// One `descriptor.setProperty("get"/"set") { … }` accessor entry. Captures `self` strong and, when
-  /// `usesAppContext`, `appContext` weak + guarded (matching the function bindings); otherwise the
-  /// capture and guard are omitted so a primitive accessor doesn't warn on an unused capture.
+  /// One `descriptor.setProperty("get"/"set") { … }` accessor entry. The capture list follows the
+  /// receiver (a module captures `self` strong; a shared object captures nothing of the instance) and,
+  /// when `usesAppContext`, adds `appContext` weak + guarded (matching the function bindings);
+  /// otherwise the guard is omitted so a primitive accessor doesn't warn on an unused capture.
   private func accessorClosure(
-    _ descriptorName: String, _ key: String, usesAppContext: Bool, body: String
+    _ descriptorName: String, _ key: String, receiver: Receiver, usesAppContext: Bool, body: String
   ) -> String {
+    let captures = receiver.captureClause(usesAppContext: usesAppContext)
     // Indent each line of a (possibly multi-line) body to sit one level inside the closure, aligned
     // with the `guard`; a bare `\(body)` interpolation would only indent the first line.
     let indentedBody = body
       .split(separator: "\n", omittingEmptySubsequences: false)
       .map { "  \($0)" }
       .joined(separator: "\n")
-    // Property `get`/`set` accessors are always synchronous and never decode `this`, so they bind
-    // through the unowned-`this` `setProperty` overload like sync functions. The parameter list is
-    // parenthesized and fully typed because Swift rejects a type annotation on a shorthand closure
-    // parameter; the explicit `borrowing JavaScriptUnownedValue` selects the unowned-`this` overload.
+    // Property `get`/`set` accessors are always synchronous, so they bind through the unowned-`this`
+    // `setProperty` overload like sync functions. The parameter list is parenthesized and fully typed
+    // because Swift rejects a type annotation on a shorthand closure parameter; the explicit
+    // `borrowing JavaScriptUnownedValue` selects the unowned-`this` overload. A module ignores `this`;
+    // a shared object unwraps it in the body.
     let parameters = "(this: borrowing JavaScriptUnownedValue, arguments: consuming JavaScriptValuesBuffer)"
     if usesAppContext {
       return """
-        \(descriptorName).setProperty("\(key)") { [weak appContext, self] \(parameters) in
+        \(descriptorName).setProperty("\(key)") { \(captures)\(parameters) in
           guard let appContext else {
             throw Exceptions.AppContextLost()
           }
@@ -354,24 +376,31 @@ internal struct JSProperty {
         """
     }
     return """
-      \(descriptorName).setProperty("\(key)") { [self] \(parameters) in
+      \(descriptorName).setProperty("\(key)") { \(captures)\(parameters) in
       \(indentedBody)
       }
       """
   }
 }
 
+/// 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) }
+  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`).
+/// shared object's counterpart is `_decorateSharedObject`). The bindings call into the module `self`.
 internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties: [JSProperty]) -> DeclSyntax {
-  let functionBody = functions.map { $0.decorateStatements }
-  let propertyBody = properties.map { $0.decorateStatements }
-  let body = (functionBody + propertyBody).joined(separator: "\n")
+  let body = decorateBody(functions: functions, properties: properties, receiver: .module)
   return """
     @JavaScriptActor
     public func _decorateModule(object: borrowing JavaScriptObject, in runtime: JavaScriptRuntime, appContext: AppContext) throws {
@@ -380,23 +409,24 @@ internal func buildDecorateJavaScriptObject(functions: [JSFunction], properties:
     """
 }
 
-/// 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
-  }
+/// 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 are **static** and 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`. 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
+) -> DeclSyntax {
+  let body = decorateBody(functions: functions, properties: properties, receiver: .sharedObject(typeName: typeName))
+  return """
+    @JavaScriptActor
+    public static func _decorateSharedObject(prototype: borrowing JavaScriptObject, in runtime: JavaScriptRuntime, appContext: AppContext) throws {
+    \(raw: body)
+    }
+    """
 }
 
 /// True when a return clause is absent or written as `Void` / `()` — i.e. the function returns

package/apple/Sources/ExpoModulesMacros/ExpoModuleMacro.swift

@@ -244,55 +244,3 @@ private func hasAppContextInitializer(_ classDecl: ClassDeclSyntax) -> Bool {
   }
   return false
 }
-
-// MARK: - Member builders
-
-private func collectProperties(
-  varDecl: VariableDeclSyntax,
-  attribute: AttributeSyntax
-) -> [JSProperty] {
-  let jsNameOverride = jsNameArgument(of: attribute)
-  // A `let` is never settable; only `var` bindings can carry a setter.
-  let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
-
-  return varDecl.bindings.compactMap { binding in
-    guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
-      return nil
-    }
-    let swiftName = ident.identifier.text
-    // Prefer the explicit annotation; recover the type from a literal default (`var x = false`)
-    // when there's none. `nil` falls back to inference at the use site.
-    let valueType = binding.typeAnnotation?.type.trimmedDescription
-      ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
-    return JSProperty(
-      swiftName: swiftName,
-      jsName: jsNameOverride ?? swiftName,
-      valueType: valueType,
-      isSettable: isVar && bindingIsSettable(binding)
-    )
-  }
-}
-
-/// Whether a `var` binding is settable from JS. A stored property (no accessor block) is settable;
-/// a computed property is settable only when it declares an explicit `set` accessor. A getter-only
-/// computed property (`{ get }` or a single getter body) stays read-only. `willSet`/`didSet`
-/// observers imply stored storage, which is also settable.
-private func bindingIsSettable(_ binding: PatternBindingSyntax) -> Bool {
-  guard let accessorBlock = binding.accessorBlock else {
-    return true
-  }
-  switch accessorBlock.accessors {
-  case .accessors(let accessors):
-    return accessors.contains { accessor in
-      switch accessor.accessorSpecifier.tokenKind {
-      case .keyword(.set), .keyword(.willSet), .keyword(.didSet):
-        return true
-      default:
-        return false
-      }
-    }
-  case .getter:
-    return false
-  }
-}
-

package/apple/Sources/ExpoModulesMacros/JSConstructor.swift

@@ -0,0 +1,60 @@
+import SwiftSyntax
+
+/// A `@JS init` collected for direct JSI binding. A shared-object type has at most one (JS classes
+/// have a single constructor). Instead of a `Constructor { … }` DSL entry, the macro synthesizes a
+/// static `_constructSharedObject(...)` that decodes the JS arguments and returns a fresh instance;
+/// unlike the method/property bindings it produces the native instance rather than recovering one.
+internal struct JSConstructor {
+  let parameters: [FunctionParameterSyntax]
+
+  init(initDecl: InitializerDeclSyntax) {
+    self.parameters = Array(initDecl.signature.parameterClause.parameters)
+  }
+
+  /// The body statements, indented with `indent`: arity guard, per-argument decode (primitives via a
+  /// typed accessor, others via the dynamic converter), then `return <Type>(label: arg0, …)`.
+  private func bodyStatements(typeName: String, indent: String) -> String {
+    var lines: [String] = []
+
+    lines.append(
+      """
+      guard arguments.count == \(parameters.count) else {
+        throw Exceptions.ArgumentsRangeMismatch((functionName: "\(typeName)", received: arguments.count, required: \(parameters.count), maximum: \(parameters.count)))
+      }
+      """)
+
+    var callArguments: [String] = []
+    for (index, parameter) in parameters.enumerated() {
+      let type = parameter.type.trimmedDescription
+
+      if let accessor = fastDecodeAccessor(for: type) {
+        lines.append("let arg\(index) = try arguments.unownedValue(at: \(index)).\(accessor)()")
+      } else {
+        let exprType = expressionType(type)
+        lines.append(
+          "let arg\(index) = try \(exprType).getDynamicType().cast(jsValue: arguments[\(index)], appContext: appContext) as! \(exprType)")
+      }
+
+      let label = parameter.firstName.text
+      callArguments.append(label == "_" ? "arg\(index)" : "\(label): arg\(index)")
+    }
+
+    lines.append("return \(typeName)(\(callArguments.joined(separator: ", ")))")
+
+    return lines
+      .flatMap { $0.split(separator: "\n", omittingEmptySubsequences: false) }
+      .map { indent + $0 }
+      .joined(separator: "\n")
+  }
+
+  /// The static `_constructSharedObject` entry point the runtime calls to build an instance from JS
+  /// arguments, returning the concrete type. `this`/`appContext` may go unreferenced, which is harmless.
+  func buildConstructor(typeName: String) -> DeclSyntax {
+    return """
+      @JavaScriptActor
+      public static func _constructSharedObject(this: JavaScriptValue, arguments: borrowing JavaScriptValuesBuffer, in runtime: JavaScriptRuntime, appContext: AppContext) throws -> \(raw: typeName) {
+      \(raw: bodyStatements(typeName: typeName, indent: "  "))
+      }
+      """
+  }
+}

package/apple/Sources/ExpoModulesMacros/MacroHelpers.swift

@@ -245,3 +245,87 @@ extension AttributeListSyntax {
     return nil
   }
 }
+
+/// A type spelled so it's valid in expression position (before `.getDynamicType()` or after `as!`).
+/// Implicitly-unwrapped optionals (`T!`) are only allowed in type-annotation position, so a trailing
+/// `!` is rewritten to `?` (`T!` and `T?` are both `Optional<T>`, which the dynamic-type / cast layer
+/// treats identically). Other type spellings pass through unchanged.
+internal func expressionType(_ type: String) -> String {
+  guard type.hasSuffix("!") else {
+    return type
+  }
+  return type.dropLast() + "?"
+}
+
+// MARK: - @JS property collection
+
+/// Collects the `@JS var` bindings of a declaration into `JSProperty` values for direct JSI binding.
+/// Shared between `@ExpoModule` and `@SharedObject` — the resulting properties are receiver-agnostic;
+/// the decorator that emits them picks the receiver (module `self` vs. shared-object `_self`).
+internal func collectProperties(
+  varDecl: VariableDeclSyntax,
+  attribute: AttributeSyntax
+) -> [JSProperty] {
+  let jsNameOverride = jsNameArgument(of: attribute)
+  // A `let` is never settable; only `var` bindings can carry a setter.
+  let isVar = varDecl.bindingSpecifier.tokenKind == .keyword(.var)
+
+  return varDecl.bindings.compactMap { binding in
+    guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
+      return nil
+    }
+    let swiftName = ident.identifier.text
+    // Prefer the explicit annotation; recover the type from a literal default (`var x = false`)
+    // when there's none. `nil` falls back to inference at the use site.
+    let valueType = binding.typeAnnotation?.type.trimmedDescription
+      ?? binding.initializer.flatMap { inferredLiteralType(of: $0.value) }
+    return JSProperty(
+      swiftName: swiftName,
+      jsName: jsNameOverride ?? swiftName,
+      valueType: valueType,
+      isSettable: isVar && bindingIsSettable(binding)
+    )
+  }
+}
+
+/// Whether a `var` binding is settable from JS. A stored property (no accessor block) is settable;
+/// a computed property is settable only when it declares an explicit `set` accessor. A getter-only
+/// computed property (`{ get }` or a single getter body) stays read-only. `willSet`/`didSet`
+/// observers imply stored storage, which is also settable.
+private func bindingIsSettable(_ binding: PatternBindingSyntax) -> Bool {
+  guard let accessorBlock = binding.accessorBlock else {
+    return true
+  }
+  switch accessorBlock.accessors {
+  case .accessors(let accessors):
+    return accessors.contains { accessor in
+      switch accessor.accessorSpecifier.tokenKind {
+      case .keyword(.set), .keyword(.willSet), .keyword(.didSet):
+        return true
+      default:
+        return false
+      }
+    }
+  case .getter:
+    return false
+  }
+}
+
+/// The throwing `JavaScriptUnownedValue` accessor that decodes the given primitive type directly
+/// (`asDouble()` for `Double`, etc.), bypassing the dynamic-type converter. Returns `nil` for types
+/// without a dedicated accessor (arrays, records, optionals, shared objects, other numeric widths),
+/// which decode through `getDynamicType().cast(...)`.
+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
+  }
+}

package/apple/Sources/ExpoModulesMacros/Receiver.swift

@@ -0,0 +1,58 @@
+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`.
+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)
+
+  /// 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`.
+  var callee: String {
+    switch self {
+    case .module:
+      return "self"
+    case .sharedObject:
+      return "_self"
+    }
+  }
+
+  /// 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 {
+    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:
+      return nil
+    case .sharedObject(let typeName):
+      return "let _self = try SharedObject.native(from: this.asObject(in: runtime), 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. `appContext`, when used,
+  /// is captured weak in both cases.
+  func captureClause(usesAppContext: Bool) -> String {
+    switch self {
+    case .module:
+      return usesAppContext ? "[weak appContext, self] " : "[self] "
+    case .sharedObject:
+      return usesAppContext ? "[weak appContext] " : ""
+    }
+  }
+}

package/apple/Sources/ExpoModulesMacros/RecordMacro.swift

@@ -316,7 +316,8 @@ private func jsObjectReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
   for property in properties {
     let valueVar = "\(property.name)JSValue"
-    let cast = "try \(property.type).getDynamicType().cast(jsValue: \(valueVar), appContext: appContext) as! \(property.type)"
+    let exprType = expressionType(property.type)
+    let cast = "try \(exprType).getDynamicType().cast(jsValue: \(valueVar), appContext: appContext) as! \(exprType)"
     lines.append("  let \(valueVar) = object.getProperty(\"\(property.name)\")")
     if property.isRequired {
       lines.append("  guard !\(valueVar).isUndefined() else {")
@@ -337,7 +338,8 @@ private func dictionaryReadLines(properties: [RecordProperty]) -> [String] {
   var lines: [String] = []
   for property in properties {
     let valueVar = "\(property.name)Value"
-    let cast = "try \(property.type).getDynamicType().cast(\(valueVar), appContext: appContext) as! \(property.type)"
+    let exprType = expressionType(property.type)
+    let cast = "try \(exprType).getDynamicType().cast(\(valueVar), appContext: appContext) as! \(exprType)"
     lines.append("  let \(valueVar) = dictionary[\"\(property.name)\"]")
     if property.isRequired {
       lines.append("  guard let \(valueVar) else {")
@@ -399,7 +401,7 @@ private func toObjectMethod(properties: [RecordProperty], inheritsRecord: Bool)
     lines.append("  let object = try appContext.runtime.createObject()")
   }
   for property in properties {
-    lines.append("  object.setProperty(\"\(property.name)\", value: try \(property.type).getDynamicType().convertToJS(self.\(property.name), appContext: appContext))")
+    lines.append("  object.setProperty(\"\(property.name)\", value: try \(expressionType(property.type)).getDynamicType().convertToJS(self.\(property.name), appContext: appContext))")
   }
   lines.append("  return object")
   let body = lines.joined(separator: "\n")

package/apple/Sources/ExpoModulesMacros/SharedObjectMacro.swift

@@ -41,35 +41,38 @@ public struct SharedObjectMacro: MemberMacro {
     let typeName = classDecl.name.text
     let jsName = jsNameArgument(of: node) ?? typeName
 
-    var entries: [String] = []
-    var sawConstructor = false
+    // `@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`.
+    let entries: [String] = []
+    var functions: [JSFunction] = []
+    var properties: [JSProperty] = []
+    var constructor: JSConstructor?
 
     for member in classDecl.memberBlock.members {
       let decl = member.decl
 
       if let initDecl = decl.as(InitializerDeclSyntax.self),
         initDecl.attributes.firstAttribute(named: "JS") != nil {
-        if sawConstructor {
+        if constructor != nil {
           throw MacroExpansionErrorMessage(
             "@SharedObject classes can have at most one @JS initializer; JavaScript classes have a single constructor.")
         }
-        sawConstructor = true
-        entries.append(buildConstructorEntry(initDecl: initDecl, typeName: typeName))
+        constructor = JSConstructor(initDecl: initDecl)
         continue
       }
 
       if let funcDecl = decl.as(FunctionDeclSyntax.self),
         let attribute = funcDecl.attributes.firstAttribute(named: "JS") {
-        entries.append(
-          buildClassFunctionEntry(funcDecl: funcDecl, attribute: attribute, typeName: typeName))
+        functions.append(JSFunction(funcDecl: funcDecl, attribute: attribute))
         continue
       }
 
       if let varDecl = decl.as(VariableDeclSyntax.self),
         let attribute = varDecl.attributes.firstAttribute(named: "JS") {
-        entries.append(
-          contentsOf: buildClassPropertyEntries(
-            varDecl: varDecl, attribute: attribute, typeName: typeName))
+        properties.append(contentsOf: collectProperties(varDecl: varDecl, attribute: attribute))
       }
     }
 
@@ -78,13 +81,27 @@ public struct SharedObjectMacro: MemberMacro {
       ? "  return Class(\"\(jsName)\", \(typeName).self) {\n  }"
       : "  return Class(\"\(jsName)\", \(typeName).self) {\n\(lines)\n  }"
 
-    let method: DeclSyntax = """
+    var emitted: [DeclSyntax] = [
+      """
       public static func _synthesizedClassDefinition() -> ClassDefinition {
       \(raw: body)
       }
       """
+    ]
+
+    // 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 {
+      emitted.append(
+        buildDecorateSharedObject(functions: functions, properties: properties, typeName: typeName))
+    }
+    if let constructor {
+      emitted.append(constructor.buildConstructor(typeName: typeName))
+    }
 
-    return [method]
+    return emitted
   }
 }
 
@@ -111,81 +128,3 @@ extension SharedObjectMacro: MemberAttributeMacro {
 private func inheritsFromSharedObject(_ classDecl: ClassDeclSyntax) -> Bool {
   return inheritsFromAny(classDecl, names: ["SharedObject"])
 }
-
-// MARK: - Class-scope entry builders
-
-private func buildClassFunctionEntry(
-  funcDecl: FunctionDeclSyntax,
-  attribute: AttributeSyntax,
-  typeName: String
-) -> String {
-  let swiftName = funcDecl.name.text
-  let jsName = jsNameArgument(of: attribute) ?? swiftName
-  let effects = funcDecl.signature.effectSpecifiers
-  let isAsync = effects?.asyncSpecifier != nil
-  let isThrowing = effects?.throwsClause?.throwsSpecifier != nil
-  let dslEntry = isAsync ? "AsyncFunction" : "Function"
-
-  let params = funcDecl.signature.parameterClause.parameters
-  let closureParamList: String
-  let callArgList: String
-  if params.isEmpty {
-    closureParamList = "(this: \(typeName))"
-    callArgList = ""
-  } else {
-    let typedParams = params.enumerated().map { index, param in
-      "_ arg\(index): \(param.type.trimmedDescription)"
-    }.joined(separator: ", ")
-    closureParamList = "(this: \(typeName), \(typedParams))"
-
-    callArgList = params.enumerated().map { index, param in
-      let label = param.firstName.text
-      return label == "_" ? "arg\(index)" : "\(label): arg\(index)"
-    }.joined(separator: ", ")
-  }
-
-  let awaitKeyword = isAsync ? "await " : ""
-  let tryKeyword = (isAsync || isThrowing) ? "try " : ""
-  let callExpr = "\(tryKeyword)\(awaitKeyword)this.\(swiftName)(\(callArgList))"
-
-  return "\(dslEntry)(\"\(jsName)\") { \(closureParamList) in \(callExpr) }"
-}
-
-private func buildClassPropertyEntries(
-  varDecl: VariableDeclSyntax,
-  attribute: AttributeSyntax,
-  typeName: String
-) -> [String] {
-  let jsNameOverride = jsNameArgument(of: attribute)
-
-  return varDecl.bindings.compactMap { binding in
-    guard let ident = binding.pattern.as(IdentifierPatternSyntax.self) else {
-      return nil
-    }
-    let swiftName = ident.identifier.text
-    let jsName = jsNameOverride ?? swiftName
-    return "Property(\"\(jsName)\") { (this: \(typeName)) in this.\(swiftName) }"
-  }
-}
-
-private func buildConstructorEntry(
-  initDecl: InitializerDeclSyntax,
-  typeName: String
-) -> String {
-  let params = initDecl.signature.parameterClause.parameters
-
-  if params.isEmpty {
-    return "Constructor { \(typeName)() }"
-  }
-
-  let argList = params.enumerated().map { index, param in
-    "_ arg\(index): \(param.type.trimmedDescription)"
-  }.joined(separator: ", ")
-
-  let callArgs = params.enumerated().map { index, param in
-    let label = param.firstName.text
-    return label == "_" ? "arg\(index)" : "\(label): arg\(index)"
-  }.joined(separator: ", ")
-
-  return "Constructor { (\(argList)) in \(typeName)(\(callArgs)) }"
-}

package/package.json

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