0
# Kotlin Standard Library for WebAssembly JavaScript
1

2
The Kotlin Standard Library for WebAssembly JavaScript (kotlin-stdlib-wasm-js) provides comprehensive JavaScript interoperability for Kotlin applications targeting WebAssembly in JavaScript environments. It enables seamless integration between Kotlin/Wasm and JavaScript code, including DOM manipulation, browser APIs, and JavaScript type system mapping.
3

4
## Package Information
5

6
- **Package Name**: kotlin-stdlib-wasm-js
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Installation**: `implementation("org.jetbrains.kotlin:kotlin-stdlib-wasm-js:2.2.0")`
10

11
## Core Imports
12

13
```kotlin
14
import kotlin.js.*
15
import kotlin.wasm.js.*
16
```
17

18
## Basic Usage
19

20
```kotlin
21
import kotlin.js.*
22

23
// Convert between Kotlin and JavaScript types
24
val kotlinString = "Hello, World!"
25
val jsString: JsString = kotlinString.toJsString()
26
val backToKotlin: String = jsString.toString()
27

28
// Work with JavaScript arrays
29
val kotlinList = listOf("apple", "banana", "cherry")
30
val jsArray: JsArray<JsString> = kotlinList.map { it.toJsString() }.toJsArray()
31

32
// Handle JavaScript promises
33
val promise: Promise<JsString> = Promise { resolve, reject ->
34
    resolve("Success!".toJsString())
35
}
36

37
// Execute JavaScript code directly
38
js("console.log('Hello from Kotlin/Wasm!')")
39
```
40

41
## Architecture
42

43
The library is built around several key components:
44

45
- **JavaScript Type System**: Native JavaScript types (`JsAny`, `JsString`, `JsNumber`, etc.) with Kotlin interoperability
46
- **Type Conversion**: Bidirectional conversion functions between Kotlin and JavaScript types
47
- **Promise Support**: Full JavaScript Promise integration with async/await patterns
48
- **Reference System**: `JsReference` for wrapping Kotlin objects for JavaScript consumption
49
- **Annotation System**: Export and import annotations for JavaScript interoperability
50
- **Platform Integration**: I/O, time, random, UUID, and reflection support optimized for WebAssembly
51

52
## Capabilities
53

54
### JavaScript Type System
55

56
Core JavaScript interoperability types and their Kotlin representations for seamless type system integration.
57

58
```kotlin { .api }
59
external interface JsAny
60
external interface JsReference<out T : Any> : JsAny
61
external class JsString : JsAny
62
external class JsNumber : JsAny
63
external class JsBoolean : JsAny
64
external class JsBigInt : JsAny
65
external class JsArray<T : JsAny?> : JsAny
66
external class Promise<out T : JsAny?> : JsAny
67
```
68

69
[JavaScript Types](./js-types.md)
70

71
### Type Conversion
72

73
Bidirectional conversion functions between Kotlin and JavaScript types, enabling seamless data exchange.
74

75
```kotlin { .api }
76
fun String.toJsString(): JsString
77
fun Boolean.toJsBoolean(): JsBoolean
78
fun Double.toJsNumber(): JsNumber
79
fun Int.toJsNumber(): JsNumber
80
fun Long.toJsBigInt(): JsBigInt
81
fun <T> List<T>.toJsArray(): JsArray<T>
82
fun <T> Array<T>.toJsArray(): JsArray<T>
83
fun <T : Any> T.toJsReference(): JsReference<T>
84
```
85

86
[Type Conversion](./type-conversion.md)
87

88
### JavaScript Interoperability Annotations
89

90
Annotations for controlling JavaScript exports, imports, and naming for seamless JavaScript integration.
91

92
```kotlin { .api }
93
@Target(AnnotationTarget.FUNCTION)
94
annotation class JsExport
95

96
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY)
97
annotation class JsName(val name: String)
98

99
@Target(AnnotationTarget.CLASS, AnnotationTarget.PROPERTY, AnnotationTarget.FUNCTION, AnnotationTarget.FILE)
100
annotation class JsModule(val import: String)
101

102
@Target(AnnotationTarget.FUNCTION, AnnotationTarget.PROPERTY_GETTER, AnnotationTarget.PROPERTY_SETTER)
103
annotation class JsFun(val code: String)
104
```
105

106
[JavaScript Annotations](./js-annotations.md)
107

108
### Promise and Async Support
109

110
JavaScript Promise integration with full async/await support and error handling.
111

112
```kotlin { .api }
113
external class Promise<out T : JsAny?>(
114
    executor: (resolve: (T) -> Unit, reject: (JsAny) -> Unit) -> Unit
115
) : JsAny {
116
    fun <S : JsAny?> then(onFulfilled: ((T) -> S)?): Promise<S>
117
    fun <S : JsAny?> catch(onRejected: (JsAny) -> S): Promise<S>
118
    fun finally(onFinally: () -> Unit): Promise<T>
119
    
120
    companion object {
121
        fun <S : JsAny?> all(promise: JsArray<out Promise<S>>): Promise<JsArray<out S>>
122
        fun <S : JsAny?> race(promise: JsArray<out Promise<S>>): Promise<S>
123
        fun reject(e: JsAny): Promise<Nothing>
124
        fun <S : JsAny?> resolve(e: S): Promise<S>
125
    }
126
}
127
```
128

129
[Promise Support](./promises.md)
130

131
### Platform Services
132

133
I/O operations, time management, random number generation, UUID support, and reflection services optimized for WebAssembly.
134

135
```kotlin { .api }
136
// I/O Operations
137
fun println()
138
fun println(message: Any?)
139
fun print(message: Any?)
140

141
// Time Support
142
object MonotonicTimeSource : TimeSource.WithComparableMarks
143
fun systemClockNow(): Instant
144

145
// Random & UUID
146
fun defaultPlatformRandom(): Random
147
fun secureRandomUuid(): Uuid
148
```
149

150
[Platform Services](./platform-services.md)
151

152
## Types
153

154
```kotlin { .api }
155
// Exception handling for JavaScript errors
156
class JsException internal constructor(val thrownValue: JsAny?) : Throwable {
157
    override val message: String
158
}
159

160
// External class reflection support  
161
internal class KExternalClassImpl<T : Any> : KClass<T> {
162
    val simpleName: String?
163
    val qualifiedName: String?
164
    fun isInstance(value: Any?): Boolean
165
}
166
```