forked from swiftwasm/JavaScriptKit
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathMacros.swift
More file actions
258 lines (250 loc) · 9.79 KB
/
Copy pathMacros.swift
File metadata and controls
258 lines (250 loc) · 9.79 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
/// Controls how Swift enums annotated with `@JS` are emitted to TypeScript.
/// - `const`: Emit the current BridgeJS style: a `const` object with literal members plus a type alias.
/// - `tsEnum`: Emit a TypeScript `enum` declaration (only valid for simple enums and raw-value enums with String or numeric raw types).
public enum JSEnumStyle: String {
case const
case tsEnum
}
/// Controls where BridgeJS reads imported JS values from.
///
/// - `global`: Read from `globalThis`.
/// - `snippet`: Read from a JavaScript file shipped inside the Swift target.
/// - `module`: Read from an external ECMAScript module.
public enum JSImportFrom {
case global
/// Read from a JavaScript file that ships with the Swift target.
///
/// The path is rooted at the Swift target directory and must begin with `/`
/// and end in `.js` or `.mjs`, e.g. `.snippet("/Modules/utils.mjs")`. The
/// leading `/` denotes the target root, not the filesystem root, and the file
/// must exist inside that target. BridgeJS copies referenced files into the
/// generated package.
case snippet(String)
/// Read from an external ECMAScript module, resolved by the JavaScript host.
///
/// The value is passed to the module resolver verbatim, which covers Node
/// built-in modules and installed packages, e.g. `.module("node:path")`,
/// `.module("lodash/fp")`, or `.module("@scope/package")`. Nothing is copied
/// for these, and making them resolvable at load time is up to you.
///
/// To reference a file in your own target, use ``JSImportFrom/snippet(_:)``.
case module(String)
}
/// Names the JavaScript member that an imported declaration refers to.
///
/// A string literal is accepted directly, so `jsName: "basename"` means
/// ``JSName/name(_:)`` with that value.
public enum JSName: ExpressibleByStringLiteral {
/// A member looked up by name.
case name(String)
/// The default export of an ECMAScript module.
///
/// Only valid on a top-level `@JSFunction`, `@JSGetter`, or `@JSClass`
/// that also specifies `from: .module(...)` or `from: .snippet(...)`.
case `default`
public init(stringLiteral value: String) {
self = .name(value)
}
}
/// A macro that exposes Swift functions, classes, and methods to JavaScript.
///
/// Apply this macro to Swift declarations that you want to make callable from JavaScript:
///
/// ```swift
/// // Export a function to JavaScript
/// @JS public func greet(name: String) -> String {
/// return "Hello, \(name)!"
/// }
///
/// // Export a class and its members
/// @JS class Counter {
/// private var count = 0
///
/// @JS init() {}
///
/// @JS func increment() {
/// count += 1
/// }
///
/// @JS func getValue() -> Int {
/// return count
/// }
/// }
/// ```
///
/// If you prefer to access through namespace-based syntax, you can use `namespace` parameter
///
/// Example:
///
/// ```swift
/// // Export a function to JavaScript with a custom namespace
/// @JS(namespace: "__Swift.Foundation.UUID") public func create() -> String {
/// UUID().uuidString
/// }
///
/// // Export a class with a custom namespace (note that only top level macro needs to specify the namespace)
/// @JS(namespace: "Utils.Greeters") class Greeter {
/// var name: String
///
/// @JS init(name: String) {
/// self.name = name
/// }
///
/// @JS func greet() -> String {
/// return "Hello, " + self.name + "!"
/// }
///
/// @JS func changeName(name: String) {
/// self.name = name
/// }
/// }
/// ```
/// And the corresponding TypeScript declaration will be generated as:
/// ```javascript
/// declare global {
/// namespace Utils {
/// namespace Greeters {
/// class Greeter {
/// constructor(name: string);
/// greet(): string;
/// changeName(name: string): void;
/// }
/// }
/// }
/// namespace __Swift {
/// namespace Foundation {
/// namespace UUID {
/// function create(): string;
/// }
/// }
/// }
/// }
/// ```
/// The above Swift class will be accessible in JavaScript as:
/// ```javascript
/// const greeter = new globalThis.Utils.Greeters.Greeter("World");
/// console.log(greeter.greet()); // "Hello, World!"
/// greeter.changeName("JavaScript");
/// console.log(greeter.greet()); // "Hello, JavaScript!"
///
/// const uuid = new globalThis.__Swift.Foundation.UUID.create(); // "1A83F0E0-F7F2-4FD1-8873-01A68CF79AF4"
/// ```
///
/// When you build your project with the BridgeJS plugin, these declarations will be
/// accessible from JavaScript, and TypeScript declaration files (`.d.ts`) will be
/// automatically generated to provide type safety.
///
/// For detailed usage information, see the article <doc:Exporting-Swift-to-JavaScript>.
///
/// - Parameter name: A different name to use in the exported JavaScript.
/// - Parameter namespace: A dot-separated string that defines the namespace hierarchy in JavaScript.
/// Each segment becomes a nested object in the resulting JavaScript structure.
/// - Parameter enumStyle: Controls how enums are emitted to TypeScript for this declaration:
/// use `.const` (default) to emit a const object + type alias,
/// or `.tsEnum` to emit a TypeScript `enum`.
/// `.tsEnum` is supported for case enums and raw-value enums with String or numeric raw types.
/// Bool raw-value enums are not supported with `.tsEnum` and will produce an error.
///
/// - Important: This feature is still experimental. No API stability is guaranteed, and the API may change in future releases.
@attached(peer)
public macro JS(
_ name: String? = nil,
as aliasOf: Any.Type? = nil,
namespace: String? = nil,
enumStyle: JSEnumStyle = .const,
identityMode: Bool = false
) = Builtin.ExternalMacro
/// A macro that generates a Swift getter that reads a value from JavaScript.
///
/// This macro is used by BridgeJS-generated Swift declarations.
///
/// - Parameter jsName: An optional string that specifies the name of the JavaScript property to read from.
/// If not provided, the Swift property name is used.
///
/// Example:
///
/// ```swift
/// import JavaScriptKit
///
/// @JSGetter var count: Int
///
/// struct Greeter {
/// @JSGetter var name: String
/// }
/// ```
///
/// - Parameter from: Selects where the property is read from.
/// Use `.global` to read from `globalThis` (e.g. `console`, `document`).
/// Use `.snippet("/path/to/module.js")` to read a named export from a file rooted at the Swift target,
/// or `.module("node:os")` to read a named export from an external module.
/// Pass `jsName: .default` to read the module's default export.
@attached(accessor)
public macro JSGetter(jsName: JSName? = nil, from: JSImportFrom? = nil) =
#externalMacro(module: "BridgeJSMacros", type: "JSGetterMacro")
/// A macro that generates a Swift function body that writes a value to JavaScript.
///
/// This macro is used by BridgeJS-generated Swift declarations.
///
/// - Parameter jsName: An optional string that specifies the name of the JavaScript property to write to.
/// If not provided, automatically derived from the Swift property name. (e.g. "setName" -> "name")
///
/// Example:
///
/// ```swift
/// import JavaScriptKit
///
/// @JSSetter func setName(_ value: String) throws (JSException)
/// ```
@attached(body)
public macro JSSetter(jsName: JSName? = nil, from: JSImportFrom? = nil) =
#externalMacro(module: "BridgeJSMacros", type: "JSSetterMacro")
/// A macro that generates a Swift function body that calls a JavaScript function.
///
/// This macro is used by BridgeJS-generated Swift declarations.
///
/// Example:
///
/// ```swift
/// import JavaScriptKit
///
/// @JSFunction func greet() throws (JSException) -> String
/// @JSFunction init(_ name: String) throws (JSException)
/// ```
///
/// - Parameter jsName: An optional string that specifies the name of the JavaScript function or method to call.
/// If not provided, the Swift function name is used.
/// - Parameter from: Selects where the function is looked up from.
/// Use `.global` to call a function on `globalThis` (e.g. `setTimeout`).
/// Use `.snippet("/path/to/module.js")` to call a named export from a file rooted at the Swift target,
/// or `.module("node:path")` to call a named export from an external module.
/// Pass `jsName: .default` to call the module's default export.
@attached(body)
public macro JSFunction(jsName: JSName? = nil, from: JSImportFrom? = nil) =
#externalMacro(module: "BridgeJSMacros", type: "JSFunctionMacro")
/// A macro that adds bridging members for a Swift type that represents a JavaScript class.
///
/// This macro is used by BridgeJS-generated Swift declarations.
///
/// Example:
///
/// ```swift
/// import JavaScriptKit
///
/// @JSClass
/// struct JsGreeter {
/// @JSGetter var name: String
/// @JSSetter func setName(_ value: String) throws (JSException)
/// @JSFunction init(_ name: String) throws (JSException)
/// @JSFunction func greet() throws (JSException) -> String
/// }
/// ```
///
/// - Parameter from: Selects where the constructor is looked up from.
/// Use `.global` to construct globals like `WebSocket` via `globalThis`.
/// Use `.snippet("/path/to/module.js")` to construct a named class export from a file rooted at the Swift target,
/// or `.module("@scope/package")` to construct a named class export from an external module.
/// Pass `jsName: .default` to construct the module's default export.
@attached(member, names: named(jsObject), named(init(unsafelyWrapping:)))
@attached(extension, conformances: _JSBridgedClass)
public macro JSClass(jsName: JSName? = nil, from: JSImportFrom? = nil) =
#externalMacro(module: "BridgeJSMacros", type: "JSClassMacro")