You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Plugins/BridgeJS/README.md
+77-31Lines changed: 77 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
> This feature is still experimental, and the API may change frequently. Use at your own risk with `JAVASCRIPTKIT_EXPERIMENTAL_BRIDGEJS=1` environment variable.
5
5
6
6
> [!NOTE]
7
-
> This documentation is intended for JavaScriptKit developers, not JavaScriptKit users.
7
+
> This documentation is intended for JavaScriptKit developers, not JavaScriptKit users. For user documentation, see [Exporting Swift to JavaScript](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/exporting-swift-to-javascript) and [Importing TypeScript into Swift](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/importing-typescript-into-swift).
8
8
9
9
## Overview
10
10
@@ -14,6 +14,7 @@ BridgeJS provides easy interoperability between Swift and JavaScript/TypeScript.
14
14
2.**Exporting Swift APIs to JavaScript**: Make your Swift APIs available to JavaScript code
15
15
16
16
The workflow is:
17
+
17
18
1.`ts2swift` converts TypeScript definitions (`bridge-js.d.ts`) to macro-annotated Swift declarations (`BridgeJS.Macros.swift`)
18
19
2.`bridge-js generate` processes both Swift source files (for export) and macro-annotated Swift files (for import) to generate:
@@ -109,23 +136,37 @@ The ABI will not be stable, and not meant to be interposed by other tools.
109
136
110
137
### Parameter Passing
111
138
112
-
Parameter passing follows Wasm calling conventions, with custom handling for complex types like strings and objects.
139
+
Parameter passing follows Wasm calling conventions, with custom handling for complex types:
113
140
114
-
TBD
141
+
-**Primitives**: Passed directly as Wasm arguments (`i32`, `i64`, `f32`, `f64`)
142
+
-**Strings**: UTF-8 bytes stored in `swift.memory`, ID + length passed as Wasm arguments
143
+
-**Swift Classes**: Raw Swift heap pointer passed as `i32`
144
+
-**JSObjects**: Object stored in `swift.memory.heap`, object ID passed as `i32`
145
+
-**Structs/Arrays**: Fields/elements pushed to type-specific stacks, Swift pops in reverse order
146
+
-**Closures**: Boxed and retained in memory, handle passed as `i32`
115
147
116
148
### Return Values
117
149
118
-
TBD
150
+
Return values use direct Wasm returns for primitives, and imported intrinsic functions for complex types:
151
+
152
+
-**Primitives**: Returned directly via Wasm return value
153
+
-**Strings**: Swift writes UTF-8 bytes to shared memory, JS decodes
154
+
-**Swift Classes**: Pointer returned directly, JS wraps in `SwiftHeapObject` with `FinalizationRegistry`
155
+
-**Structs/Arrays**: Swift pushes fields/elements to type-specific stacks, JS reconstructs
156
+
157
+
### Memory Management
158
+
159
+
-**Swift Classes**: Live on Swift heap. JS holds pointer wrapped in `SwiftHeapObject`. `FinalizationRegistry` calls `deinit` on GC. Optional `release()` for deterministic cleanup.
160
+
-**JSObjects**: Live in `swift.memory.heap` (JS side). Swift holds ID wrapped in `JSObject`. Reference counted via `retain`/`release`.
161
+
-**Structs/Arrays/Enums**: Copy semantics - data serialized across boundary. No cleanup needed.
162
+
-**Closures**: Boxed on source side, released when GC'd on either side.
163
+
164
+
For detailed semantics, see the [How It Works sections](https://swiftpackageindex.com/swiftwasm/JavaScriptKit/documentation/javascriptkit/exporting-swift-class#How-It-Works) in the user documentation.
Copy file name to clipboardExpand all lines: Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Class.md
+11Lines changed: 11 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -76,6 +76,17 @@ export type Exports = {
76
76
}
77
77
```
78
78
79
+
## How It Works
80
+
81
+
Classes use **reference semantics** when crossing the Swift/JavaScript boundary:
82
+
83
+
1. **Object Creation**: When you create a class instance (via `new` in JS), the object lives on the Swift heap
84
+
2. **Reference Passing**: JavaScript receives a reference (handle) to the Swift object, not a copy
85
+
3. **Shared State**: Changes made through either Swift or JavaScript affect the same object
86
+
4. **Memory Management**: `FinalizationRegistry` automatically releases Swift objects when they're garbage collected in JavaScript. You can optionally call `release()` for deterministic cleanup.
87
+
88
+
This differs from structs, which use copy semantics and transfer data by value.
Copy file name to clipboardExpand all lines: Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Closure.md
+9-7Lines changed: 9 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,4 +1,4 @@
1
-
# Exporting Swift Closures
1
+
# Exporting Swift Closures to JS
2
2
3
3
Learn how to use closure/function types as parameters and return values in BridgeJS.
4
4
@@ -89,18 +89,20 @@ export type Exports = {
89
89
}
90
90
```
91
91
92
-
## Memory Management
92
+
## How It Works
93
93
94
-
When JavaScript passes a function to Swift, it's automatically stored in `swift.memory` with reference counting. When Swift's closure wrapper is deallocated by ARC, the JavaScript function is released.
94
+
Closures use **reference semantics** when crossing the Swift/JavaScript boundary:
95
95
96
-
When Swift returns a closure to JavaScript, the Swift closure is boxed and automatically released when the JavaScript function is garbage collected.
96
+
1. **JavaScript → Swift**: When JavaScript passes a function to Swift, it's stored in `swift.memory` with reference counting. When Swift's closure wrapper is deallocated by ARC, the JavaScript function is released.
97
+
2. **Swift → JavaScript**: When Swift returns a closure to JavaScript, the Swift closure is boxed and automatically released when the JavaScript function is garbage collected.
98
+
3. **Memory Management**: Both directions use automatic memory management via `FinalizationRegistry` - no manual cleanup required.
97
99
98
-
Both directions use automatic memory management - no manual cleanup required.
100
+
This differs from structs and arrays, which use copy semantics and transfer data by value.
Copy file name to clipboardExpand all lines: Sources/JavaScriptKit/Documentation.docc/Articles/BridgeJS/Exporting-Swift/Exporting-Swift-Default-Parameters.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -143,6 +143,7 @@ custom.release();
143
143
```
144
144
145
145
**Requirements:**
146
+
146
147
- Constructor/initializer arguments must be literal values (`"text"`, `42`, `true`, `false`, `nil`)
147
148
- Struct initializers must use labeled arguments (e.g., `Point(x: 1.0, y: 2.0)`)
148
149
- Complex expressions, computed properties, or method calls are not supported
0 commit comments