0
# JavaScript Annotations
1

2
Annotations for controlling JavaScript exports, imports, and naming to enable seamless JavaScript integration with Kotlin/Wasm.
3

4
## Capabilities
5

6
### JsExport Annotation
7

8
Exports top-level declarations to JavaScript platform. For Kotlin/Wasm, only functions can be exported.
9

10
```kotlin { .api }
11
/**
12
 * Exports top-level declaration on JS platform (functions only for K/Wasm)
13
 */
14
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.CONSTRUCTOR, AnnotationTarget.FUNCTION)
15
@ExperimentalJsExport
16
annotation class JsExport
17

18
/**
19
 * Nested annotation to ignore declarations from export
20
 */
21
@Target(AnnotationTarget.FUNCTION)
22
@ExperimentalJsExport
23
annotation class JsExport.Ignore
24
```
25

26
**Usage Examples:**
27

28
```kotlin
29
@JsExport
30
fun calculateSum(a: Int, b: Int): Int {
31
    return a + b
32
}
33

34
@JsExport
35
fun processData(data: String): String {
36
    return data.uppercase()
37
}
38

39
// This function won't be exported
40
@JsExport.Ignore
41
fun internalHelper(): String {
42
    return "internal"
43
}
44
```
45

46
### JsName Annotation
47

48
Specifies JavaScript name for external and imported declarations, allowing custom naming in JavaScript.
49

50
```kotlin { .api }
51
/**
52
 * Specifies JavaScript name for external and imported declarations
53
 * @param name The JavaScript name to use
54
 */
55
@Target(
56
    AnnotationTarget.CLASS,
57
    AnnotationTarget.FUNCTION,
58
    AnnotationTarget.PROPERTY,
59
    AnnotationTarget.CONSTRUCTOR,
60
    AnnotationTarget.PROPERTY_GETTER,
61
    AnnotationTarget.PROPERTY_SETTER
62
)
63
annotation class JsName(val name: String)
64
```
65

66
**Usage Examples:**
67

68
```kotlin
69
// External JavaScript function with custom name
70
@JsName("getElementById")
71
external fun getElementByIdJs(id: String): JsAny?
72

73
// External JavaScript class with custom name
74
@JsName("XMLHttpRequest")
75
external class XmlHttpRequest {
76
    fun open(method: String, url: String)
77
    fun send(data: String?)
78
}
79

80
// Exported function with custom JavaScript name
81
@JsExport
82
@JsName("addNumbers")
83
fun kotlinAdd(x: Int, y: Int): Int = x + y
84
```
85

86
### JsModule Annotation
87

88
Denotes external declaration that must be imported from a JavaScript module.
89

90
```kotlin { .api }
91
/**
92
 * Denotes external declaration that must be imported from JavaScript module
93
 * @param import The module import path
94
 */
95
@Target(
96
    AnnotationTarget.CLASS,
97
    AnnotationTarget.PROPERTY,
98
    AnnotationTarget.FUNCTION,
99
    AnnotationTarget.FILE
100
)
101
annotation class JsModule(val import: String)
102
```
103

104
**Usage Examples:**
105

106
```kotlin
107
// Import from npm package
108
@JsModule("lodash")
109
@JsName("_")
110
external object Lodash {
111
    fun map(collection: JsArray<JsAny>, iteratee: (JsAny) -> JsAny): JsArray<JsAny>
112
    fun filter(collection: JsArray<JsAny>, predicate: (JsAny) -> Boolean): JsArray<JsAny>
113
}
114

115
// Import specific function from module
116
@JsModule("axios")
117
@JsName("default")
118
external fun axios(config: JsAny): Promise<JsAny>
119

120
// File-level module import
121
@file:JsModule("my-utils")
122

123
@JsName("formatDate")
124
external fun formatDate(date: JsAny): JsString
125
```
126

127
### JsQualifier Annotation
128

129
Adds prefix to external declarations in a source file.
130

131
```kotlin { .api }
132
/**
133
 * Adds prefix to external declarations in a source file
134
 * @param value The qualifier prefix
135
 */
136
@Target(AnnotationTarget.FILE)
137
annotation class JsQualifier(val value: String)
138
```
139

140
**Usage Example:**
141

142
```kotlin
143
@file:JsQualifier("window.myLibrary")
144

145
// This will be accessed as window.myLibrary.helper
146
external fun helper(): JsString
147

148
// This will be accessed as window.myLibrary.Config
149
external class Config {
150
    val version: JsString
151
    fun init(): Unit
152
}
153
```
154

155
### JsFun Annotation
156

157
Implements annotated function in JavaScript and automatically imports it to WebAssembly.
158

159
```kotlin { .api }
160
/**
161
 * Implements annotated function in JavaScript and automatically imports to Wasm
162
 * @param code The JavaScript code implementation
163
 */
164
@Target(
165
    AnnotationTarget.FUNCTION,
166
    AnnotationTarget.PROPERTY_GETTER,
167
    AnnotationTarget.PROPERTY_SETTER
168
)
169
annotation class JsFun(val code: String)
170
```
171

172
**Usage Examples:**
173

174
```kotlin
175
// Simple JavaScript function implementation
176
@JsFun("() => Date.now()")
177
external fun getCurrentTimestamp(): Double
178

179
// Function with parameters
180
@JsFun("(x, y) => x + y")
181
external fun addInJs(x: Double, y: Double): Double
182

183
// Property getter implemented in JavaScript
184
@get:JsFun("() => window.location.href")
185
external val currentUrl: String
186

187
// Property setter implemented in JavaScript
188
@set:JsFun("(value) => document.title = value")
189
external var documentTitle: String
190

191
// More complex JavaScript implementation
192
@JsFun("""
193
(element, eventType, callback) => {
194
    element.addEventListener(eventType, callback);
195
    return () => element.removeEventListener(eventType, callback);
196
}
197
""")
198
external fun addEventListener(
199
    element: JsAny,
200
    eventType: String,
201
    callback: (JsAny) -> Unit
202
): () -> Unit
203
```
204

205
## Annotation Patterns
206

207
### Module Integration
208

209
```kotlin
210
// Complete integration with external JavaScript library
211
@file:JsModule("chart.js")
212

213
@JsName("Chart")
214
external class Chart(canvas: JsAny, config: ChartConfig) {
215
    fun update(): Unit
216
    fun destroy(): Unit
217
}
218

219
external interface ChartConfig {
220
    val type: String
221
    val data: ChartData
222
    val options: JsAny?
223
}
224

225
external interface ChartData {
226
    val labels: JsArray<String>
227
    val datasets: JsArray<Dataset>
228
}
229

230
external interface Dataset {
231
    val label: String
232
    val data: JsArray<Double>
233
    val backgroundColor: String?
234
}
235
```
236

237
### Custom JavaScript Integration
238

239
```kotlin
240
// Combining multiple annotation types for complex integration
241
@JsExport
242
@JsName("KotlinDataProcessor")
243
class DataProcessor {
244
    @JsExport
245
    @JsName("processJson")
246
    fun processJsonData(jsonString: String): String {
247
        return processData(jsonString)
248
    }
249
    
250
    @JsFun("(data) => JSON.parse(data)")
251
    private external fun parseJson(data: String): JsAny
252
    
253
    @JsFun("(obj) => JSON.stringify(obj)")
254
    private external fun stringifyJson(obj: JsAny): String
255
    
256
    private fun processData(json: String): String {
257
        val parsed = parseJson(json)
258
        // Process the data...
259
        return stringifyJson(parsed)
260
    }
261
}
262
```
263

264
### Browser API Integration
265

266
```kotlin
267
@file:JsQualifier("window")
268

269
@JsName("console")
270
external object Console {
271
    fun log(message: JsAny)
272
    fun error(message: JsAny)
273
    fun warn(message: JsAny)
274
}
275

276
@JsName("document")
277
external object Document {
278
    fun getElementById(id: String): JsAny?
279
    fun createElement(tagName: String): JsAny
280
}
281

282
@JsName("fetch")
283
external fun fetch(url: String, options: JsAny?): Promise<JsAny>
284
```