0
# Type Conversion
1

2
Bidirectional conversion functions between Kotlin and JavaScript types for seamless data exchange between Kotlin/Wasm and JavaScript.
3

4
## Capabilities
5

6
### Boolean Conversion
7

8
Convert between Kotlin Boolean and JavaScript boolean types.
9

10
```kotlin { .api }
11
/**
12
 * Convert Kotlin Boolean to JsBoolean
13
 * @return JsBoolean JavaScript boolean representation
14
 */
15
fun Boolean.toJsBoolean(): JsBoolean
16

17
/**
18
 * Convert JsBoolean to Kotlin Boolean
19
 * @return Boolean Kotlin boolean representation
20
 */
21
fun JsBoolean.toBoolean(): Boolean
22
```
23

24
**Usage Example:**
25

26
```kotlin
27
val kotlinBool = true
28
val jsBool: JsBoolean = kotlinBool.toJsBoolean()
29
val backToKotlin: Boolean = jsBool.toBoolean()
30
```
31

32
### String Conversion
33

34
Convert Kotlin String to JavaScript string type.
35

36
```kotlin { .api }
37
/**
38
 * Convert Kotlin String to JsString
39
 * @return JsString JavaScript string representation
40
 */
41
fun String.toJsString(): JsString
42

43
/**
44
 * Convert JsString to Kotlin String
45
 * @return String Kotlin string representation
46
 */
47
fun JsString.toString(): String
48
```
49

50
**Usage Example:**
51

52
```kotlin
53
val kotlinString = "Hello, World!"
54
val jsString: JsString = kotlinString.toJsString()
55
val backToKotlin: String = jsString.toString()
56
```
57

58
### Number Conversion
59

60
Convert between Kotlin numeric types and JavaScript number.
61

62
```kotlin { .api }
63
/**
64
 * Convert Kotlin Double to JsNumber
65
 * @return JsNumber JavaScript number representation
66
 */
67
fun Double.toJsNumber(): JsNumber
68

69
/**
70
 * Convert Kotlin Int to JsNumber
71
 * @return JsNumber JavaScript number representation
72
 */
73
fun Int.toJsNumber(): JsNumber
74

75
/**
76
 * Convert JsNumber to Kotlin Double
77
 * @return Double Kotlin double representation
78
 */
79
fun JsNumber.toDouble(): Double
80

81
/**
82
 * Convert JsNumber to Kotlin Int
83
 * @return Int Kotlin int representation
84
 */
85
fun JsNumber.toInt(): Int
86
```
87

88
**Usage Examples:**
89

90
```kotlin
91
// Double conversion
92
val kotlinDouble = 3.14159
93
val jsNumber: JsNumber = kotlinDouble.toJsNumber()
94
val backToDouble: Double = jsNumber.toDouble()
95

96
// Int conversion
97
val kotlinInt = 42
98
val jsNumberFromInt: JsNumber = kotlinInt.toJsNumber()
99
val backToInt: Int = jsNumberFromInt.toInt()
100
```
101

102
### BigInt Conversion
103

104
Convert between Kotlin Long and JavaScript bigint.
105

106
```kotlin { .api }
107
/**
108
 * Convert Kotlin Long to JsBigInt
109
 * @return JsBigInt JavaScript bigint representation
110
 */
111
fun Long.toJsBigInt(): JsBigInt
112

113
/**
114
 * Convert JsBigInt to Kotlin Long
115
 * @return Long Kotlin long representation
116
 */
117
fun JsBigInt.toLong(): Long
118
```
119

120
**Usage Example:**
121

122
```kotlin
123
val kotlinLong = 9223372036854775807L // Long.MAX_VALUE
124
val jsBigInt: JsBigInt = kotlinLong.toJsBigInt()
125
val backToLong: Long = jsBigInt.toLong()
126
```
127

128
### Array Conversion
129

130
Convert between Kotlin collections and JavaScript arrays.
131

132
```kotlin { .api }
133
/**
134
 * Convert Kotlin Array to JsArray
135
 * @return JsArray<T> JavaScript array representation
136
 */
137
fun <T> Array<T>.toJsArray(): JsArray<T>
138

139
/**
140
 * Convert Kotlin List to JsArray
141
 * @return JsArray<T> JavaScript array representation
142
 */
143
fun <T> List<T>.toJsArray(): JsArray<T>
144

145
/**
146
 * Convert JsArray to Kotlin Array
147
 * @return Array<T> Kotlin array representation
148
 */
149
fun <T> JsArray<T>.toArray(): Array<T>
150

151
/**
152
 * Convert JsArray to Kotlin List
153
 * @return List<T> Kotlin list representation
154
 */
155
fun <T> JsArray<T>.toList(): List<T>
156
```
157

158
**Usage Examples:**
159

160
```kotlin
161
// Array conversion
162
val kotlinArray = arrayOf("apple", "banana", "cherry")
163
val jsArray: JsArray<String> = kotlinArray.toJsArray()
164
val backToArray: Array<String> = jsArray.toArray()
165

166
// List conversion
167
val kotlinList = listOf("red", "green", "blue")
168
val jsArrayFromList: JsArray<String> = kotlinList.toJsArray()
169
val backToList: List<String> = jsArrayFromList.toList()
170
```
171

172
### Reference Conversion
173

174
Convert Kotlin objects to JavaScript references for safe object passing.
175

176
```kotlin { .api }
177
/**
178
 * Convert any Kotlin object to JsReference
179
 * @return JsReference<T> JavaScript reference to the Kotlin object
180
 */
181
fun <T : Any> T.toJsReference(): JsReference<T>
182

183
/**
184
 * Retrieve original Kotlin value from JsReference
185
 * @return T The original Kotlin value
186
 */
187
fun <T> JsReference<T>.get(): T
188
```
189

190
**Usage Example:**
191

192
```kotlin
193
data class User(val name: String, val age: Int)
194

195
val user = User("Alice", 25)
196
val jsRef: JsReference<User> = user.toJsReference()
197

198
// Later, retrieve the original object
199
val retrievedUser: User = jsRef.get()
200
println("${retrievedUser.name}, ${retrievedUser.age}") // Alice, 25
201
```
202

203
### Exception Conversion
204

205
Convert JavaScript exceptions to Kotlin exceptions.
206

207
```kotlin { .api }
208
/**
209
 * For a JsAny value caught in JS, returns corresponding Throwable if thrown from Kotlin, null otherwise
210
 * @return Throwable? Corresponding Throwable or null
211
 */
212
fun JsAny.toThrowableOrNull(): Throwable?
213
```
214

215
**Usage Example:**
216

217
```kotlin
218
try {
219
    // Some operation that might throw JavaScript exception
220
    js("throw new Error('JavaScript error')")
221
} catch (jsError: JsAny) {
222
    val kotlinException = jsError.toThrowableOrNull()
223
    if (kotlinException != null) {
224
        println("Caught Kotlin exception: ${kotlinException.message}")
225
    } else {
226
        println("Caught JavaScript exception: $jsError")
227
    }
228
}
229
```
230

231
## Type Conversion Patterns
232

233
### Complex Data Structures
234

235
```kotlin
236
// Converting complex nested structures
237
data class ApiResponse(val data: List<String>, val success: Boolean)
238

239
val response = ApiResponse(listOf("item1", "item2"), true)
240

241
// Convert to JavaScript-friendly format
242
val jsData = response.data.map { it.toJsString() }.toJsArray()
243
val jsResponse = js("""({
244
    data: arguments[0],
245
    success: arguments[1]
246
})""") as JsAny
247

248
// Function parameters: jsData, response.success.toJsBoolean()
249
```
250

251
### Working with JavaScript APIs
252

253
```kotlin
254
// Prepare data for JavaScript API calls
255
val formData = mapOf(
256
    "username" to "alice",
257
    "email" to "alice@example.com",
258
    "age" to 25
259
)
260

261
// Convert for JavaScript consumption
262
val jsFormData = js("({})") as JsAny
263
formData.forEach { (key, value) ->
264
    when (value) {
265
        is String -> js("arguments[0][arguments[1]] = arguments[2]")(jsFormData, key, value.toJsString())
266
        is Int -> js("arguments[0][arguments[1]] = arguments[2]")(jsFormData, key, value.toJsNumber())
267
        is Boolean -> js("arguments[0][arguments[1]] = arguments[2]")(jsFormData, key, value.toJsBoolean())
268
    }
269
}
270
```