BridgeJS: Address @js(as:) review feedback

krodak · krodak · commit 76d11c0738f2 · 2026-06-24T14:09:45.000+02:00
Follow-up to the review on #750: - ImportTS: give the unreachable `.alias` cases in loweringParameterInfo / liftingReturnInfo a message stating the `.unaliased` invariant, so a future change that breaks it fails loudly instead of trapping silently. - JSGlueGen: in `optionalConvention` and `wasmParams`, delegate `.alias` to its underlying type rather than `preconditionFailure()`. These switch on `self` (not `.unaliased`), so this removes a latent crash for alias-wrapped values and matches how abiReturnType / mangleTypeName already handle `.alias`. - SwiftToSkeleton: diagnose `@JS(as:)` combined with `namespace:` instead of silently dropping the namespace; an alias adopts its representation's placement. Adds a diagnostics test. - BridgeJSSkeleton: note why alias mangling uses the (unique) swiftCallName only. - Docs: add an "Exporting a Type With a Custom JS Representation" article and link it from the exporting topics.
diff --git a/Plugins/BridgeJS/Sources/BridgeJSCore/ImportTS.swift b/Plugins/BridgeJS/Sources/BridgeJSCore/ImportTS.swift
@@ -958,7 +958,7 @@ extension BridgeType {
         case .array, .dictionary:
             return LoweringParameterInfo(loweredParameters: [])
         case .alias:
-            preconditionFailure()
+            preconditionFailure("`.alias` must be resolved by `.unaliased` before reaching loweringParameterInfo")
         }
     }
 
@@ -1032,7 +1032,7 @@ extension BridgeType {
         case .array, .dictionary:
             return LiftingReturnInfo(valueToLift: nil)
         case .alias:
-            preconditionFailure()
+            preconditionFailure("`.alias` must be resolved by `.unaliased` before reaching liftingReturnInfo")
         }
     }
 }
diff --git a/Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift b/Plugins/BridgeJS/Sources/BridgeJSCore/SwiftToSkeleton.swift
@@ -1635,7 +1635,7 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
         }
 
         if let aliasTarget = parent.extractAliasTarget(from: jsAttribute) {
-            recordAlias(node: node, aliasTarget: aliasTarget)
+            recordAlias(node: node, jsAttribute: jsAttribute, aliasTarget: aliasTarget)
             return .skipChildren
         }
 
@@ -1739,9 +1739,20 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
 
     private func recordAlias(
         node: some SyntaxProtocol & NamedDeclSyntax,
+        jsAttribute: AttributeSyntax,
         aliasTarget: TypeSyntax
     ) {
         let swiftCallName = SwiftToSkeleton.computeSwiftCallName(for: node, itemName: node.name.text)
+        if extractNamespace(from: jsAttribute) != nil {
+            errors.append(
+                DiagnosticError(
+                    node: node,
+                    message: "`namespace` is not supported on `@JS(as:)` types",
+                    hint: "Remove the `namespace:` argument; an alias adopts its target's representation"
+                )
+            )
+            return
+        }
         var lookupErrors: [DiagnosticError] = []
         guard
             let aliasBridgeType = parent.aliasType(
@@ -1774,7 +1785,7 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
         }
 
         if let aliasTarget = parent.extractAliasTarget(from: jsAttribute) {
-            recordAlias(node: node, aliasTarget: aliasTarget)
+            recordAlias(node: node, jsAttribute: jsAttribute, aliasTarget: aliasTarget)
             return .skipChildren
         }
 
@@ -1962,7 +1973,7 @@ private final class ExportSwiftAPICollector: SyntaxAnyVisitor {
         }
 
         if let aliasTarget = parent.extractAliasTarget(from: jsAttribute) {
-            recordAlias(node: node, aliasTarget: aliasTarget)
+            recordAlias(node: node, jsAttribute: jsAttribute, aliasTarget: aliasTarget)
             return .skipChildren
         }
 
diff --git a/Plugins/BridgeJS/Sources/BridgeJSLink/JSGlueGen.swift b/Plugins/BridgeJS/Sources/BridgeJSLink/JSGlueGen.swift
@@ -2685,8 +2685,8 @@ private extension BridgeType {
             return .stackABI
         case .nullable(let wrapped, _):
             return wrapped.optionalConvention
-        case .alias:
-            preconditionFailure()
+        case .alias(_, let underlying):
+            return underlying.optionalConvention
         }
     }
 
@@ -2783,8 +2783,8 @@ private extension BridgeType {
             return []
         case .nullable(let wrapped, _):
             return wrapped.wasmParams
-        case .alias:
-            preconditionFailure()
+        case .alias(_, let underlying):
+            return underlying.wasmParams
         }
     }
 
diff --git a/Plugins/BridgeJS/Sources/BridgeJSSkeleton/BridgeJSSkeleton.swift b/Plugins/BridgeJS/Sources/BridgeJSSkeleton/BridgeJSSkeleton.swift
@@ -1770,6 +1770,8 @@ extension BridgeType {
             // Dictionary mangling: "SD" prefix followed by value type (key is always String)
             return "SD\(valueType.mangleTypeName)"
         case .alias(let name, _):
+            // `name` is the namespace-qualified swiftCallName (unique), so the underlying
+            // representation isn't mangled in - aliases bridge via their JS type's ABI.
             return "Al\(name.count)\(name)"
         }
     }
diff --git a/Plugins/BridgeJS/Tests/BridgeJSToolTests/DiagnosticsTests.swift b/Plugins/BridgeJS/Tests/BridgeJSToolTests/DiagnosticsTests.swift
@@ -426,6 +426,27 @@ import Testing
         }
     }
 
+    @Test
+    func jsAsWithNamespaceDiagnostic() throws {
+        let source = """
+            @JS final class Box { @JS init() {} }
+            @JS(as: Box.self, namespace: "Foo") struct Wrapped {
+                consuming func bridgeToJS() -> Box { fatalError() }
+                static func bridgeFromJS(_ value: consuming Box) -> Wrapped { fatalError() }
+            }
+            """
+        let swiftAPI = SwiftToSkeleton(
+            progress: .silent,
+            moduleName: "TestModule",
+            exposeToGlobal: false,
+            externalModuleIndex: .empty
+        )
+        swiftAPI.addSourceFile(Parser.parse(source: source), inputFilePath: "test.swift")
+        #expect(throws: BridgeJSCoreDiagnosticError.self) {
+            _ = try swiftAPI.finalize()
+        }
+    }
+
     @Test
     func omitsNextLineWhenErrorIsOnLastLine() throws {
         let source = """
diff --git a/Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSCodegenTests/DocComments.json b/Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSCodegenTests/DocComments.json
@@ -1,5 +1,8 @@
 {
   "exported" : {
+    "aliases" : [
+
+    ],
     "classes" : [
       {
         "constructor" : {
diff --git a/Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSLinkTests/Alias.js b/Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSLinkTests/Alias.js
@@ -78,14 +78,14 @@ export async function createInstantiator(options, swift) {
             bjs["swift_js_init_memory"] = function(sourceId, bytesPtr) {
                 const source = swift.memory.getObject(sourceId);
                 swift.memory.release(sourceId);
-                const bytes = new Uint8Array(memory.buffer, bytesPtr);
+                const bytes = new Uint8Array(memory.buffer, bytesPtr >>> 0);
                 bytes.set(source);
             }
             bjs["swift_js_make_js_string"] = function(ptr, len) {
                 return swift.memory.retain(decodeString(ptr, len));
             }
             bjs["swift_js_init_memory_with_result"] = function(ptr, len) {
-                const target = new Uint8Array(memory.buffer, ptr, len);
+                const target = new Uint8Array(memory.buffer, ptr >>> 0, len >>> 0);
                 target.set(tmpRetBytes);
                 tmpRetBytes = undefined;
             }
@@ -345,6 +345,7 @@ export async function createInstantiator(options, swift) {
             /// Represents a Swift heap object like a class instance or an actor instance.
             class SwiftHeapObject {
                 static __wrap(pointer, deinit, prototype, identityCache) {
+                    pointer = pointer >>> 0;
                     const makeFresh = (identityMap) => {
                         const obj = Object.create(prototype);
                         const state = { pointer, deinit, hasReleased: false, identityMap };
diff --git a/Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSLinkTests/AliasInClosure.js b/Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSLinkTests/AliasInClosure.js
@@ -39,7 +39,7 @@ export async function createInstantiator(options, swift) {
         const state = { pointer, file, line, unregistered: false };
         const real = (...args) => {
             if (state.unregistered) {
-                const bytes = new Uint8Array(memory.buffer, state.file);
+                const bytes = new Uint8Array(memory.buffer, state.file >>> 0);
                 let length = 0;
                 while (bytes[length] !== 0) { length += 1; }
                 const fileID = decodeString(state.file, length);
@@ -70,14 +70,14 @@ export async function createInstantiator(options, swift) {
             bjs["swift_js_init_memory"] = function(sourceId, bytesPtr) {
                 const source = swift.memory.getObject(sourceId);
                 swift.memory.release(sourceId);
-                const bytes = new Uint8Array(memory.buffer, bytesPtr);
+                const bytes = new Uint8Array(memory.buffer, bytesPtr >>> 0);
                 bytes.set(source);
             }
             bjs["swift_js_make_js_string"] = function(ptr, len) {
                 return swift.memory.retain(decodeString(ptr, len));
             }
             bjs["swift_js_init_memory_with_result"] = function(ptr, len) {
-                const target = new Uint8Array(memory.buffer, ptr, len);
+                const target = new Uint8Array(memory.buffer, ptr >>> 0, len >>> 0);
                 target.set(tmpRetBytes);
                 tmpRetBytes = undefined;
             }
@@ -312,6 +312,7 @@ export async function createInstantiator(options, swift) {
             /// Represents a Swift heap object like a class instance or an actor instance.
             class SwiftHeapObject {
                 static __wrap(pointer, deinit, prototype, identityCache) {
+                    pointer = pointer >>> 0;
                     const makeFresh = (identityMap) => {
                         const obj = Object.create(prototype);
                         const state = { pointer, deinit, hasReleased: false, identityMap };
diff --git a/Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSLinkTests/EnumAlias.js b/Plugins/BridgeJS/Tests/BridgeJSToolTests/__Snapshots__/BridgeJSLinkTests/EnumAlias.js
@@ -45,14 +45,14 @@ export async function createInstantiator(options, swift) {
             bjs["swift_js_init_memory"] = function(sourceId, bytesPtr) {
                 const source = swift.memory.getObject(sourceId);
                 swift.memory.release(sourceId);
-                const bytes = new Uint8Array(memory.buffer, bytesPtr);
+                const bytes = new Uint8Array(memory.buffer, bytesPtr >>> 0);
                 bytes.set(source);
             }
             bjs["swift_js_make_js_string"] = function(ptr, len) {
                 return swift.memory.retain(decodeString(ptr, len));
             }
             bjs["swift_js_init_memory_with_result"] = function(ptr, len) {
-                const target = new Uint8Array(memory.buffer, ptr, len);
+                const target = new Uint8Array(memory.buffer, ptr >>> 0, len >>> 0);
                 target.set(tmpRetBytes);
                 tmpRetBytes = undefined;
             }
@@ -237,6 +237,7 @@ export async function createInstantiator(options, swift) {
             /// Represents a Swift heap object like a class instance or an actor instance.
             class SwiftHeapObject {
                 static __wrap(pointer, deinit, prototype, identityCache) {
+                    pointer = pointer >>> 0;
                     const makeFresh = (identityMap) => {
                         const obj = Object.create(prototype);
                         const state = { pointer, deinit, hasReleased: false, identityMap };
diff --git a/Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift-to-JavaScript.md b/Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift-to-JavaScript.md
@@ -22,6 +22,7 @@ Configure your package and build for JavaScript as described in <doc:Setting-up-
 - <doc:Exporting-Swift-Closure>
 - <doc:Exporting-Swift-Protocols>
 - <doc:Exporting-Swift-Optional>
+- <doc:Exporting-Swift-Custom-Representation>
 - <doc:Exporting-Swift-Default-Parameters>
 - <doc:Exporting-Swift-Static-Functions>
 - <doc:Exporting-Swift-Static-Properties>
diff --git a/Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Custom-Representation.md b/Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Custom-Representation.md
@@ -0,0 +1,114 @@
+# Exporting a Type With a Custom JS Representation
+
+Learn how to give a Swift type a different representation on the JavaScript side using `@JS(as:)`.
+
+## Overview
+
+> Tip: You can quickly preview what interfaces will be exposed on the Swift/JavaScript/TypeScript sides using the [BridgeJS Playground](https://swiftwasm.org/JavaScriptKit/PlayBridgeJS/).
+
+BridgeJS picks a sensible default representation for each exported type - structs cross by copy, classes by reference, and so on. Sometimes that default is a poor fit:
+
+- A struct copied at the boundary is expensive when it holds a large payload (for example a polygon with thousands of vertices).
+- A type uses a feature BridgeJS does not export directly (for example a dictionary with integer keys).
+
+`@JS(as:)` is the escape hatch. It lets a Swift type keep its idiomatic shape while being bridged to JavaScript through a different `@JS` type that you control, without duplicating the surrounding API.
+
+Mark the type with `@JS(as: OtherType.self)` and provide two conversions:
+
+```swift
+import JavaScriptKit
+
+@JS(as: JSPolygon.self) struct Polygon {
+    var vertices: [Point]
+
+    consuming func bridgeToJS() -> JSPolygon {
+        JSPolygon(underlying: self)
+    }
+
+    static func bridgeFromJS(_ value: consuming JSPolygon) -> Polygon {
+        value.underlying
+    }
+}
+
+@JS final class JSPolygon {
+    var underlying: Polygon
+
+    @JS init(underlying: Polygon) {
+        self.underlying = underlying
+    }
+
+    @JS var vertexCount: Int { underlying.vertices.count }
+}
+
+@JS func merge(_ a: Polygon, _ b: Polygon) -> Polygon
+```
+
+Existing Swift code keeps using the idiomatic `Polygon`. Anywhere `Polygon` crosses the boundary - parameters, return values, optionals, arrays - BridgeJS substitutes `JSPolygon`, so JavaScript sees the reference type and avoids copying.
+
+The generated TypeScript declarations refer to the representation type:
+
+```typescript
+export interface JSPolygon extends SwiftHeapObject {
+    readonly vertexCount: number;
+}
+
+export type Exports = {
+    JSPolygon: {
+        new(underlying: JSPolygon): JSPolygon;
+    }
+    merge(a: JSPolygon, b: JSPolygon): JSPolygon;
+}
+```
+
+## The Bridging Contract
+
+A type marked `@JS(as: R.self)` must provide both halves of the conversion to and from its representation `R`:
+
+```swift
+consuming func bridgeToJS() -> R
+static func bridgeFromJS(_ value: consuming R) -> Self
+```
+
+BridgeJS inserts a call to `bridgeToJS()` at the first opportunity when a value leaves Swift, and `bridgeFromJS(_:)` at the last opportunity when one enters. The rest of the generated glue just uses `R`'s ABI, so the conversions are the only code you write.
+
+## Wrapping a Primitive
+
+The representation does not have to be a class. A small wrapper over a primitive is a common case - for example exposing a strongly-typed identifier as a plain string:
+
+```swift
+@JS(as: String.self) struct UUID {
+    var rawValue: String
+
+    consuming func bridgeToJS() -> String { rawValue }
+    static func bridgeFromJS(_ value: consuming String) -> UUID { UUID(rawValue: value) }
+}
+
+@JS func currentUser() -> UUID
+```
+
+JavaScript sees a `string`, while Swift keeps the distinct `UUID` type.
+
+## Supported Representations
+
+The representation type (the `as:` target) must itself be a type BridgeJS can export by value or reference:
+
+| Representation | Status |
+|:---------------|:-------|
+| `@JS class` | ✅ |
+| `@JSClass` (imported) | ✅ |
+| `@JS struct` | ✅ |
+| Primitives (`Int`, `Double`, `Float`, `Bool`, `String`) | ✅ |
+| `JSValue` | ✅ |
+| Case enums and associated-value enums | ✅ |
+| Raw-value enums | ❌ |
+| `@JS protocol` | ❌ |
+| Another `@JS(as:)` type (chained aliases) | ❌ |
+| Closures, arrays, dictionaries, optionals as the direct target | ❌ |
+
+`@JS(as:)` cannot be combined with `namespace:` - an aliased type adopts its representation's placement.
+
+## See Also
+
+- <doc:Exporting-Swift-Struct>
+- <doc:Exporting-Swift-Class>
+- <doc:Supported-Types>

Original file line number	Diff line number	Diff line change
`@@ -958,7 +958,7 @@ extension BridgeType {`
`958`	`958`	`case .array, .dictionary:`
`959`	`959`	`return LoweringParameterInfo(loweredParameters: [])`
`960`	`960`	`case .alias:`
`961`		`- preconditionFailure()`
	`961`	+ preconditionFailure("`.alias` must be resolved by `.unaliased` before reaching loweringParameterInfo")
`962`	`962`	`}`
`963`	`963`	`}`
`964`	`964`
`@@ -1032,7 +1032,7 @@ extension BridgeType {`
`1032`	`1032`	`case .array, .dictionary:`
`1033`	`1033`	`return LiftingReturnInfo(valueToLift: nil)`
`1034`	`1034`	`case .alias:`
`1035`		`- preconditionFailure()`
	`1035`	+ preconditionFailure("`.alias` must be resolved by `.unaliased` before reaching liftingReturnInfo")
`1036`	`1036`	`}`
`1037`	`1037`	`}`
`1038`	`1038`	`}`
Original file line number	Diff line number	Diff line change
`@@ -2685,8 +2685,8 @@ private extension BridgeType {`
`2685`	`2685`	`return .stackABI`
`2686`	`2686`	`case .nullable(let wrapped, _):`
`2687`	`2687`	`return wrapped.optionalConvention`
`2688`		`- case .alias:`
`2689`		`- preconditionFailure()`
	`2688`	`+ case .alias(_, let underlying):`
	`2689`	`+ return underlying.optionalConvention`
`2690`	`2690`	`}`
`2691`	`2691`	`}`
`2692`	`2692`
`@@ -2783,8 +2783,8 @@ private extension BridgeType {`
`2783`	`2783`	`return []`
`2784`	`2784`	`case .nullable(let wrapped, _):`
`2785`	`2785`	`return wrapped.wasmParams`
`2786`		`- case .alias:`
`2787`		`- preconditionFailure()`
	`2786`	`+ case .alias(_, let underlying):`
	`2787`	`+ return underlying.wasmParams`
`2788`	`2788`	`}`
`2789`	`2789`	`}`
`2790`	`2790`
Original file line number	Diff line number	Diff line change
`@@ -1770,6 +1770,8 @@ extension BridgeType {`
`1770`	`1770`	`// Dictionary mangling: "SD" prefix followed by value type (key is always String)`
`1771`	`1771`	`return "SD\(valueType.mangleTypeName)"`
`1772`	`1772`	`case .alias(let name, _):`
	`1773`	+ // `name` is the namespace-qualified swiftCallName (unique), so the underlying
	`1774`	`+ // representation isn't mangled in - aliases bridge via their JS type's ABI.`
`1773`	`1775`	`return "Al\(name.count)\(name)"`
`1774`	`1776`	`}`
`1775`	`1777`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,8 @@`
`1`	`1`	`{`
`2`	`2`	`"exported" : {`
	`3`	`+ "aliases" : [`
	`4`	`+`
	`5`	`+ ],`
`3`	`6`	`"classes" : [`
`4`	`7`	`{`
`5`	`8`	`"constructor" : {`