Merge pull request #469 from PassiveLogic/feat/configurable-global-namespace

BridgeJS: exposeToGlobal configuration option to control declare global declaration

Author: krodak

Benchmarks/Sources/Generated/JavaScript/BridgeJS.ExportSwift.json

@@ -502,7 +502,8 @@
       "staticProperties" : [
 
       ],
-      "swiftCallName" : "APIResult"
+      "swiftCallName" : "APIResult",
+      "tsFullPath" : "APIResult"
     },
     {
       "cases" : [
@@ -698,9 +699,11 @@
       "staticProperties" : [
 
       ],
-      "swiftCallName" : "ComplexResult"
+      "swiftCallName" : "ComplexResult",
+      "tsFullPath" : "ComplexResult"
     }
   ],
+  "exposeToGlobal" : false,
   "functions" : [
     {
       "abiName" : "bjs_run",

Examples/PlayBridgeJS/Sources/PlayBridgeJS/Generated/JavaScript/BridgeJS.ExportSwift.json

@@ -135,6 +135,7 @@
   "enums" : [
 
   ],
+  "exposeToGlobal" : false,
   "functions" : [
 
   ],

Examples/PlayBridgeJS/Sources/PlayBridgeJS/main.swift

@@ -17,7 +17,7 @@ import class Foundation.JSONDecoder
     }
 
     func _update(swiftSource: String, dtsSource: String) throws -> PlayBridgeJSOutput {
-        let exportSwift = ExportSwift(progress: .silent, moduleName: "Playground")
+        let exportSwift = ExportSwift(progress: .silent, moduleName: "Playground", exposeToGlobal: false)
         let sourceFile = Parser.parse(source: swiftSource)
         try exportSwift.addSourceFile(sourceFile, "Playground.swift")
         let exportResult = try exportSwift.finalize()

Package.swift

@@ -180,5 +180,18 @@ let package = Package(
             ],
             linkerSettings: testingLinkerFlags
         ),
+        .testTarget(
+            name: "BridgeJSGlobalTests",
+            dependencies: ["JavaScriptKit", "JavaScriptEventLoop"],
+            exclude: [
+                "bridge-js.config.json",
+                "bridge-js.d.ts",
+                "Generated/JavaScript",
+            ],
+            swiftSettings: [
+                .enableExperimentalFeature("Extern")
+            ],
+            linkerSettings: testingLinkerFlags
+        ),
     ]
 )

Plugins/BridgeJS/Sources/BridgeJSBuildPlugin/BridgeJSBuildPlugin.swift

@@ -44,6 +44,8 @@ struct BridgeJSBuildPlugin: BuildToolPlugin {
                 "export",
                 "--module-name",
                 target.name,
+                "--target-dir",
+                target.directoryURL.path,
                 "--output-skeleton",
                 outputSkeletonPath.path,
                 "--output-swift",

Plugins/BridgeJS/Sources/BridgeJSCommandPlugin/BridgeJSCommandPlugin.swift

@@ -107,6 +107,8 @@ extension BridgeJSCommandPlugin.Context {
                 "export",
                 "--module-name",
                 target.name,
+                "--target-dir",
+                target.directoryURL.path,
                 "--output-skeleton",
                 generatedJavaScriptDirectory.appending(path: "BridgeJS.ExportSwift.json").path,
                 "--output-swift",

Plugins/BridgeJS/Sources/BridgeJSCore/BridgeJSConfig.swift

@@ -10,6 +10,31 @@ public struct BridgeJSConfig: Codable {
     /// If not present, the tool will be searched for in the system PATH.
     public var tools: [String: String]?
 
+    /// Whether to expose exported Swift APIs to the global namespace.
+    ///
+    /// When `true`, exported functions, classes, and namespaces are available
+    /// via `globalThis` in JavaScript. When `false`, they are only available
+    /// through the exports object returned by `createExports()`.
+    ///
+    /// Default: `false`
+    public var exposeToGlobal: Bool
+
+    public init(tools: [String: String]? = nil, exposeToGlobal: Bool = false) {
+        self.tools = tools
+        self.exposeToGlobal = exposeToGlobal
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case tools
+        case exposeToGlobal
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        tools = try container.decodeIfPresent([String: String].self, forKey: .tools)
+        exposeToGlobal = try container.decodeIfPresent(Bool.self, forKey: .exposeToGlobal) ?? false
+    }
+
     /// Load the configuration file from the SwiftPM package target directory.
     ///
     /// Files are loaded **in this order** and merged (later files override earlier ones):
@@ -49,7 +74,8 @@ public struct BridgeJSConfig: Codable {
     /// Merge the current configuration with the overrides.
     func merging(overrides: BridgeJSConfig) -> BridgeJSConfig {
         return BridgeJSConfig(
-            tools: (tools ?? [:]).merging(overrides.tools ?? [:], uniquingKeysWith: { $1 })
+            tools: (tools ?? [:]).merging(overrides.tools ?? [:], uniquingKeysWith: { $1 }),
+            exposeToGlobal: overrides.exposeToGlobal
         )
     }
 }

Plugins/BridgeJS/Sources/BridgeJSCore/ExportSwift.swift

@@ -20,7 +20,7 @@ import BridgeJSUtilities
 public class ExportSwift {
     let progress: ProgressReporting
     let moduleName: String
-
+    private let exposeToGlobal: Bool
     private var exportedFunctions: [ExportedFunction] = []
     private var exportedClasses: [ExportedClass] = []
     private var exportedEnums: [ExportedEnum] = []
@@ -30,9 +30,10 @@ public class ExportSwift {
     private let enumCodegen: EnumCodegen = EnumCodegen()
     private let closureCodegen = ClosureCodegen()
 
-    public init(progress: ProgressReporting, moduleName: String) {
+    public init(progress: ProgressReporting, moduleName: String, exposeToGlobal: Bool) {
         self.progress = progress
         self.moduleName = moduleName
+        self.exposeToGlobal = exposeToGlobal
     }
 
     /// Processes a Swift source file to find declarations marked with @JS
@@ -55,6 +56,8 @@ public class ExportSwift {
 
     /// Finalizes the export process and generates the bridge code
     ///
+    /// - Parameters:
+    ///   - exposeToGlobal: Whether to expose exported APIs to the global namespace (default: false)
     /// - Returns: A tuple containing the generated Swift code and a skeleton
     /// describing the exported APIs
     public func finalize() throws -> (outputSwift: String, outputSkeleton: ExportedSkeleton)? {
@@ -68,7 +71,8 @@ public class ExportSwift {
                 functions: exportedFunctions,
                 classes: exportedClasses,
                 enums: exportedEnums,
-                protocols: exportedProtocols
+                protocols: exportedProtocols,
+                exposeToGlobal: exposeToGlobal
             )
         )
     }
@@ -882,10 +886,18 @@ public class ExportSwift {
                 message: "Enum visibility must be at least internal"
             )
 
+            let tsFullPath: String
+            if let namespace = namespaceResult.namespace, !namespace.isEmpty {
+                tsFullPath = namespace.joined(separator: ".") + "." + name
+            } else {
+                tsFullPath = name
+            }
+
             // Create enum directly in dictionary
             let exportedEnum = ExportedEnum(
                 name: name,
                 swiftCallName: swiftCallName,
+                tsFullPath: tsFullPath,
                 explicitAccessControl: explicitAccessControl,
                 cases: [],  // Will be populated in visit(EnumCaseDeclSyntax)
                 rawType: SwiftEnumRawType(rawType),