BridgeJS: Optimize numeric array bridging with bulk TypedArray transfer

Use bulk TypedArray memory copy instead of element-by-element stack
serialization for numeric arrays ([Int], [UInt8], [Float], [Double],
etc.). TypeScript types remain number[]/bigint[] — no API change.

Swift->JS: withUnsafeBufferPointer passes (ptr, count, kind) to
swift_js_push_typed_array which copies bytes into a JS TypedArray,
then Array.from() converts to number[] for the caller.

JS->Swift: retains the array as a TypedArray in the JS heap, passes
(id, count) as WASM params, Swift allocates via
Array(unsafeUninitializedCapacity:) and calls back to JS to bulk copy.

Non-numeric arrays (String, structs, classes, enums) are unaffected
and continue using the existing element-by-element stack protocol.

Author: krodak

Benchmarks/Sources/Generated/BridgeJS.swift

@@ -1829,9 +1829,9 @@ public func _bjs_ArrayRoundtrip_init() -> UnsafeMutableRawPointer {
 
 @_expose(wasm, "bjs_ArrayRoundtrip_takeIntArray")
 @_cdecl("bjs_ArrayRoundtrip_takeIntArray")
-public func _bjs_ArrayRoundtrip_takeIntArray(_ _self: UnsafeMutableRawPointer) -> Void {
+public func _bjs_ArrayRoundtrip_takeIntArray(_ _self: UnsafeMutableRawPointer, _ valuesSourceId: Int32, _ valuesCount: Int32) -> Void {
     #if arch(wasm32)
-    ArrayRoundtrip.bridgeJSLiftParameter(_self).takeIntArray(_: [Int].bridgeJSStackPop())
+    ArrayRoundtrip.bridgeJSLiftParameter(_self).takeIntArray(_: _bridgeJS_typedArrayLiftParameter(valuesSourceId, valuesCount) as [Int])
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -1842,18 +1842,18 @@ public func _bjs_ArrayRoundtrip_takeIntArray(_ _self: UnsafeMutableRawPointer) -
 public func _bjs_ArrayRoundtrip_makeIntArray(_ _self: UnsafeMutableRawPointer) -> Void {
     #if arch(wasm32)
     let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).makeIntArray()
-    ret.bridgeJSStackPush()
+    _bridgeJS_typedArrayPush(ret)
     #else
     fatalError("Only available on WebAssembly")
     #endif
 }
 
 @_expose(wasm, "bjs_ArrayRoundtrip_roundtripIntArray")
 @_cdecl("bjs_ArrayRoundtrip_roundtripIntArray")
-public func _bjs_ArrayRoundtrip_roundtripIntArray(_ _self: UnsafeMutableRawPointer) -> Void {
+public func _bjs_ArrayRoundtrip_roundtripIntArray(_ _self: UnsafeMutableRawPointer, _ valuesSourceId: Int32, _ valuesCount: Int32) -> Void {
     #if arch(wasm32)
-    let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).roundtripIntArray(_: [Int].bridgeJSStackPop())
-    ret.bridgeJSStackPush()
+    let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).roundtripIntArray(_: _bridgeJS_typedArrayLiftParameter(valuesSourceId, valuesCount) as [Int])
+    _bridgeJS_typedArrayPush(ret)
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -1864,17 +1864,17 @@ public func _bjs_ArrayRoundtrip_roundtripIntArray(_ _self: UnsafeMutableRawPoint
 public func _bjs_ArrayRoundtrip_makeIntArrayLarge(_ _self: UnsafeMutableRawPointer) -> Void {
     #if arch(wasm32)
     let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).makeIntArrayLarge()
-    ret.bridgeJSStackPush()
+    _bridgeJS_typedArrayPush(ret)
     #else
     fatalError("Only available on WebAssembly")
     #endif
 }
 
 @_expose(wasm, "bjs_ArrayRoundtrip_takeDoubleArray")
 @_cdecl("bjs_ArrayRoundtrip_takeDoubleArray")
-public func _bjs_ArrayRoundtrip_takeDoubleArray(_ _self: UnsafeMutableRawPointer) -> Void {
+public func _bjs_ArrayRoundtrip_takeDoubleArray(_ _self: UnsafeMutableRawPointer, _ valuesSourceId: Int32, _ valuesCount: Int32) -> Void {
     #if arch(wasm32)
-    ArrayRoundtrip.bridgeJSLiftParameter(_self).takeDoubleArray(_: [Double].bridgeJSStackPop())
+    ArrayRoundtrip.bridgeJSLiftParameter(_self).takeDoubleArray(_: _bridgeJS_typedArrayLiftParameter(valuesSourceId, valuesCount) as [Double])
     #else
     fatalError("Only available on WebAssembly")
     #endif
@@ -1885,18 +1885,18 @@ public func _bjs_ArrayRoundtrip_takeDoubleArray(_ _self: UnsafeMutableRawPointer
 public func _bjs_ArrayRoundtrip_makeDoubleArray(_ _self: UnsafeMutableRawPointer) -> Void {
     #if arch(wasm32)
     let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).makeDoubleArray()
-    ret.bridgeJSStackPush()
+    _bridgeJS_typedArrayPush(ret)
     #else
     fatalError("Only available on WebAssembly")
     #endif
 }
 
 @_expose(wasm, "bjs_ArrayRoundtrip_roundtripDoubleArray")
 @_cdecl("bjs_ArrayRoundtrip_roundtripDoubleArray")
-public func _bjs_ArrayRoundtrip_roundtripDoubleArray(_ _self: UnsafeMutableRawPointer) -> Void {
+public func _bjs_ArrayRoundtrip_roundtripDoubleArray(_ _self: UnsafeMutableRawPointer, _ valuesSourceId: Int32, _ valuesCount: Int32) -> Void {
     #if arch(wasm32)
-    let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).roundtripDoubleArray(_: [Double].bridgeJSStackPop())
-    ret.bridgeJSStackPush()
+    let ret = ArrayRoundtrip.bridgeJSLiftParameter(_self).roundtripDoubleArray(_: _bridgeJS_typedArrayLiftParameter(valuesSourceId, valuesCount) as [Double])
+    _bridgeJS_typedArrayPush(ret)
     #else
     fatalError("Only available on WebAssembly")
     #endif

Plugins/BridgeJS/Sources/BridgeJSCore/ClosureCodegen.swift

@@ -132,6 +132,19 @@ public struct ClosureCodegen {
 
         for (index, paramType) in signature.parameters.enumerated() {
             let paramName = "param\(index)"
+
+            // Numeric arrays use bulk TypedArray transfer with (sourceId, count) WASM params
+            if case .array(let elementType) = paramType, elementType.isNumericScalar {
+                let sourceIdName = "\(paramName)SourceId"
+                let countName = "\(paramName)Count"
+                abiParams.append((sourceIdName, .i32))
+                abiParams.append((countName, .i32))
+                liftedParams.append(
+                    "_bridgeJS_typedArrayLiftParameter(\(sourceIdName), \(countName)) as [\(elementType.swiftType)]"
+                )
+                continue
+            }
+
             let liftInfo = try paramType.liftParameterInfo()
 
             for (argName, wasmType) in liftInfo.parameters {

Plugins/BridgeJS/Sources/BridgeJSCore/ExportSwift.swift

@@ -137,6 +137,18 @@ public class ExportSwift {
             case .swiftStruct(let structName):
                 typeNameForIntrinsic = structName
                 liftingExpr = ExprSyntax("\(raw: structName).bridgeJSLiftParameter()")
+            case .array(let elementType) where elementType.isNumericScalar:
+                // Numeric arrays use bulk TypedArray transfer with (sourceId, count) WASM params
+                let elementSwiftType = elementType.swiftType
+                typeNameForIntrinsic = param.type.swiftType
+                liftingExpr = ExprSyntax(
+                    "_bridgeJS_typedArrayLiftParameter(\(raw: param.name)SourceId, \(raw: param.name)Count) as [\(raw: elementSwiftType)]"
+                )
+                // Override the ABI signatures: two i32 params instead of stack-based
+                liftedParameterExprs.append(liftingExpr)
+                abiParameterSignatures.append(("\(param.name)SourceId", .i32))
+                abiParameterSignatures.append(("\(param.name)Count", .i32))
+                return
             case .array:
                 typeNameForIntrinsic = param.type.swiftType
                 liftingExpr = StackCodegen().liftExpression(for: param.type)
@@ -301,6 +313,8 @@ public class ExportSwift {
             switch returnType {
             case .closure(_, useJSTypedClosure: false):
                 append("return JSTypedClosure(ret).bridgeJSLowerReturn()")
+            case .array(let elementType) where elementType.isNumericScalar:
+                append("_bridgeJS_typedArrayPush(ret)")
             case .array, .nullable(.array, _):
                 let stackCodegen = StackCodegen()
                 for stmt in stackCodegen.lowerStatements(for: returnType, accessor: "ret", varPrefix: "ret") {

Plugins/BridgeJS/Sources/BridgeJSCore/ImportTS.swift

@@ -152,6 +152,10 @@ public struct ImportTS {
                 // The just created JSObject is not owned by the caller unlike those passed in parameters,
                 // so we need to extend its lifetime during the call to ensure the JSObject.id is valid.
                 valuesToExtendLifetimeDuringCall.append(param.name)
+            case .array(let elementType) where elementType.isNumericScalar:
+                // Numeric arrays use bulk TypedArray transfer instead of element-by-element
+                stackLoweringStmts.insert("_bridgeJS_typedArrayPush(\(param.name))", at: 0)
+                return
             default:
                 break
             }
@@ -302,6 +306,12 @@ public struct ImportTS {
                 switch returnType {
                 case .closure(let signature, _):
                     liftExpr = "_BJS_Closure_\(signature.mangleName).bridgeJSLift(ret)"
+                case .array(let elementType) where elementType.isNumericScalar:
+                    // Numeric arrays: JS pushed (sourceId, count) onto i32 stack
+                    let swiftElementType = elementType.swiftType
+                    body.write("let _count = _swift_js_pop_i32()")
+                    body.write("let _sourceId = _swift_js_pop_i32()")
+                    liftExpr = "_bridgeJS_typedArrayLiftParameter(_sourceId, _count) as [\(swiftElementType)]"
                 default:
                     if liftingInfo.valueToLift != nil {
                         liftExpr = "\(returnType.swiftType).bridgeJSLiftReturn(ret)"

Plugins/BridgeJS/Sources/BridgeJSLink/BridgeJSLink.swift

@@ -345,6 +345,8 @@ public struct BridgeJSLink {
             "let \(JSGlueVariableScope.reservedF32Stack) = [];",
             "let \(JSGlueVariableScope.reservedF64Stack) = [];",
             "let \(JSGlueVariableScope.reservedPointerStack) = [];",
+            "let \(JSGlueVariableScope.reservedTaStack) = [];",
+            "const \(JSGlueVariableScope.reservedTypedArrayConstructors) = [Int8Array, Uint8Array, Int16Array, Uint16Array, Int32Array, Uint32Array, BigInt64Array, BigUint64Array, Float32Array, Float64Array];",
             "const \(JSGlueVariableScope.reservedEnumHelpers) = {};",
             "const \(JSGlueVariableScope.reservedStructHelpers) = {};",
             "",
@@ -487,6 +489,66 @@ public struct BridgeJSLink {
                     printer.write("return \(JSGlueVariableScope.reservedI64Stack).pop();")
                 }
                 printer.write("}")
+                printer.write("bjs[\"swift_js_push_typed_array\"] = function(ptr, count, kind) {")
+                printer.indent {
+                    printer.write(
+                        "const Constructor = \(JSGlueVariableScope.reservedTypedArrayConstructors)[kind];"
+                    )
+                    printer.write(
+                        "const elemSize = Constructor.BYTES_PER_ELEMENT;"
+                    )
+                    printer.write(
+                        "const totalBytes = count * elemSize;"
+                    )
+                    printer.write(
+                        "const copy = new Uint8Array(totalBytes);"
+                    )
+                    printer.write(
+                        "copy.set(new Uint8Array(\(JSGlueVariableScope.reservedMemory).buffer, ptr, totalBytes));"
+                    )
+                    printer.write(
+                        "\(JSGlueVariableScope.reservedTaStack).push(new Constructor(copy.buffer));"
+                    )
+                }
+                printer.write("}")
+                printer.write("bjs[\"swift_js_init_typed_array_memory\"] = function(sourceId, destPtr, count, kind) {")
+                printer.indent {
+                    printer.write(
+                        "const source = \(JSGlueVariableScope.reservedSwift).\(JSGlueVariableScope.reservedMemory).getObject(sourceId);"
+                    )
+                    printer.write(
+                        "\(JSGlueVariableScope.reservedSwift).\(JSGlueVariableScope.reservedMemory).release(sourceId);"
+                    )
+                    printer.write(
+                        "const Constructor = \(JSGlueVariableScope.reservedTypedArrayConstructors)[kind];"
+                    )
+                    printer.write(
+                        "const elemSize = Constructor.BYTES_PER_ELEMENT;"
+                    )
+                    printer.write(
+                        "if (destPtr % elemSize === 0) {"
+                    )
+                    printer.indent {
+                        printer.write(
+                            "const dest = new Constructor(\(JSGlueVariableScope.reservedMemory).buffer, destPtr, count);"
+                        )
+                        printer.write("dest.set(source);")
+                    }
+                    printer.write(
+                        "} else {"
+                    )
+                    printer.indent {
+                        printer.write(
+                            "const dest = new Uint8Array(\(JSGlueVariableScope.reservedMemory).buffer, destPtr, count * elemSize);"
+                        )
+                        printer.write(
+                            "const srcBytes = new Uint8Array(source.buffer, source.byteOffset, source.byteLength);"
+                        )
+                        printer.write("dest.set(srcBytes);")
+                    }
+                    printer.write("}")
+                }
+                printer.write("}")
                 if !allStructs.isEmpty {
                     for structDef in allStructs {
                         printer.write("bjs[\"swift_js_struct_lower_\(structDef.abiName)\"] = function(objectId) {")

Plugins/BridgeJS/Sources/BridgeJSLink/JSGlueGen.swift

@@ -34,6 +34,8 @@ final class JSGlueVariableScope {
     static let reservedStructHelpers = "structHelpers"
     static let reservedSwiftClosureRegistry = "swiftClosureRegistry"
     static let reservedMakeSwiftClosure = "makeClosure"
+    static let reservedTaStack = "taStack"
+    static let reservedTypedArrayConstructors = "typedArrayConstructors"
 
     private let intrinsicRegistry: JSIntrinsicRegistry
 
@@ -63,6 +65,8 @@ final class JSGlueVariableScope {
         reservedStructHelpers,
         reservedSwiftClosureRegistry,
         reservedMakeSwiftClosure,
+        reservedTaStack,
+        reservedTypedArrayConstructors,
     ]
 
     init(intrinsicRegistry: JSIntrinsicRegistry) {
@@ -1317,6 +1321,8 @@ struct IntrinsicJSFragment: Sendable {
             )
         case .namespaceEnum(let string):
             throw BridgeJSLinkError(message: "Namespace enums are not supported to be passed as parameters: \(string)")
+        case .array(let elementType) where elementType.isNumericScalar:
+            return numericArrayLower(elementType: elementType)
         case .array(let elementType):
             return try arrayLower(elementType: elementType)
         case .dictionary(let valueType):
@@ -1374,6 +1380,8 @@ struct IntrinsicJSFragment: Sendable {
             throw BridgeJSLinkError(
                 message: "Namespace enums are not supported to be returned from functions: \(string)"
             )
+        case .array(let elementType) where elementType.isNumericScalar:
+            return numericArrayLift(elementType: elementType)
         case .array(let elementType):
             return try arrayLift(elementType: elementType)
         case .dictionary(let valueType):
@@ -1472,6 +1480,8 @@ struct IntrinsicJSFragment: Sendable {
                 message:
                     "Namespace enums are not supported to be passed as parameters to imported JS functions: \(string)"
             )
+        case .array(let elementType) where elementType.isNumericScalar:
+            return numericArrayLift(elementType: elementType)
         case .array(let elementType):
             return try arrayLift(elementType: elementType)
         case .dictionary(let valueType):
@@ -1534,6 +1544,8 @@ struct IntrinsicJSFragment: Sendable {
             throw BridgeJSLinkError(
                 message: "Namespace enums are not supported to be returned from imported JS functions: \(string)"
             )
+        case .array(let elementType) where elementType.isNumericScalar:
+            return numericArrayLowerReturn(elementType: elementType)
         case .array(let elementType):
             return try arrayLower(elementType: elementType)
         case .dictionary(let valueType):
@@ -1828,6 +1840,66 @@ struct IntrinsicJSFragment: Sendable {
 
     // MARK: - Array Helpers
 
+    /// Lowers a numeric array from JS to Swift via bulk TypedArray transfer.
+    /// Converts the JS Array to a TypedArray, retains it, and passes (sourceId, count) as WASM params.
+    static func numericArrayLower(elementType: BridgeType) -> IntrinsicJSFragment {
+        let kind = elementType.typedArrayKind!
+        return IntrinsicJSFragment(
+            parameters: ["arr"],
+            printCode: { arguments, context in
+                let (scope, printer) = (context.scope, context.printer)
+                let arr = arguments[0]
+                let typedArrVar = scope.variable("typedArr")
+                let idVar = scope.variable("typedArrId")
+                printer.write(
+                    "const \(typedArrVar) = new \(JSGlueVariableScope.reservedTypedArrayConstructors)[\(kind)](\(arr));"
+                )
+                printer.write(
+                    "const \(idVar) = \(JSGlueVariableScope.reservedSwift).memory.retain(\(typedArrVar));"
+                )
+                return [idVar, "\(typedArrVar).length"]
+            }
+        )
+    }
+
+    /// Lowers a numeric array from JS to Swift for return values (stack-based).
+    /// Pushes (sourceId, count) onto the i32 stack.
+    static func numericArrayLowerReturn(elementType: BridgeType) -> IntrinsicJSFragment {
+        let kind = elementType.typedArrayKind!
+        return IntrinsicJSFragment(
+            parameters: ["arr"],
+            printCode: { arguments, context in
+                let (scope, printer) = (context.scope, context.printer)
+                let arr = arguments[0]
+                let typedArrVar = scope.variable("typedArr")
+                let idVar = scope.variable("typedArrId")
+                printer.write(
+                    "const \(typedArrVar) = new \(JSGlueVariableScope.reservedTypedArrayConstructors)[\(kind)](\(arr));"
+                )
+                printer.write(
+                    "const \(idVar) = \(JSGlueVariableScope.reservedSwift).memory.retain(\(typedArrVar));"
+                )
+                scope.emitPushI32Parameter(idVar, printer: printer)
+                scope.emitPushI32Parameter("\(typedArrVar).length", printer: printer)
+                return []
+            }
+        )
+    }
+
+    /// Lifts a numeric array from Swift to JS via bulk TypedArray transfer.
+    /// Swift side pushed the typed array view onto taStack; JS pops and converts to plain Array.
+    static func numericArrayLift(elementType: BridgeType) -> IntrinsicJSFragment {
+        return IntrinsicJSFragment(
+            parameters: [],
+            printCode: { arguments, context in
+                let (scope, printer) = (context.scope, context.printer)
+                let resultVar = scope.variable("arrayResult")
+                printer.write("const \(resultVar) = Array.from(\(JSGlueVariableScope.reservedTaStack).pop());")
+                return [resultVar]
+            }
+        )
+    }
+
     /// Lowers an array from JS to Swift by iterating elements and pushing to stacks
     static func arrayLower(elementType: BridgeType) throws -> IntrinsicJSFragment {
         return IntrinsicJSFragment(

Plugins/BridgeJS/Sources/BridgeJSSkeleton/BridgeJSSkeleton.swift

@@ -275,6 +275,42 @@ public enum BridgeType: Codable, Equatable, Hashable, Sendable {
     indirect case closure(ClosureSignature, useJSTypedClosure: Bool)
 }
 
+extension BridgeType {
+    /// Returns true if this type is a numeric scalar eligible for bulk TypedArray transfer.
+    /// Used by codegen to route `[NumericType]` through the optimized typed-array path
+    /// instead of element-by-element stack operations.
+    public var isNumericScalar: Bool {
+        switch self {
+        case .integer, .float, .double: return true
+        default: return false
+        }
+    }
+
+    /// Returns the JavaScript TypedArray constructor kind index for numeric scalars.
+    /// The index matches the `typedArrayConstructors` table in JS glue code.
+    /// Returns nil for non-numeric types.
+    public var typedArrayKind: Int? {
+        switch self {
+        case .integer(let t):
+            switch (t.width, t.isSigned) {
+            case (.w8, true): return 0  // Int8Array
+            case (.w8, false): return 1  // Uint8Array
+            case (.w16, true): return 2  // Int16Array
+            case (.w16, false): return 3  // Uint16Array
+            case (.w32, true): return 4  // Int32Array
+            case (.w32, false): return 5  // Uint32Array
+            case (.w64, true): return 6  // BigInt64Array
+            case (.w64, false): return 7  // BigUint64Array
+            case (.word, true): return 4  // Int (i32 on wasm32) → Int32Array
+            case (.word, false): return 5  // UInt (u32 on wasm32) → Uint32Array
+            }
+        case .float: return 8  // Float32Array
+        case .double: return 9  // Float64Array
+        default: return nil
+        }
+    }
+}
+
 public enum WasmCoreType: String, Codable, Sendable {
     case i32, i64, f32, f64, pointer
 }