0
# JavaScript Types
1

2
Core JavaScript interoperability types providing native JavaScript type representations with Kotlin integration.
3

4
## Capabilities
5

6
### JsAny Interface
7

8
Base interface representing any JavaScript value except null or undefined.
9

10
```kotlin { .api }
11
/**
12
 * Represents any JavaScript value except null or undefined
13
 */
14
external interface JsAny
15

16
/**
17
 * Cast JsAny to other JS type without runtime check
18
 * @return T The target JavaScript type
19
 */
20
fun <T : JsAny> JsAny.unsafeCast(): T
21
```
22

23
### JsReference Interface
24

25
JavaScript value that serves as a reference for any Kotlin value, behaving like an immutable empty object with null prototype in JavaScript.
26

27
```kotlin { .api }
28
/**
29
 * JavaScript value that serves as a reference for any Kotlin value
30
 */
31
sealed external interface JsReference<out T : Any> : JsAny
32

33
/**
34
 * Convert any Kotlin object to JsReference
35
 * @return JsReference<T> JavaScript reference to the Kotlin object
36
 */
37
fun <T : Any> T.toJsReference(): JsReference<T>
38

39
/**
40
 * Retrieve original Kotlin value from JsReference (internal use only)
41
 * @return T The original Kotlin value
42
 */
43
internal fun <T> JsReference<T>.get(): T
44
```
45

46
### JsString Class
47

48
JavaScript primitive string type.
49

50
```kotlin { .api }
51
/**
52
 * JavaScript primitive string
53
 */
54
@JsPrimitive("string")
55
external class JsString internal constructor() : JsAny {
56
    /**
57
     * Convert JsString to Kotlin String
58
     * @return String Kotlin string representation
59
     */
60
    override fun toString(): String
61
}
62
```
63

64
### JsNumber Class
65

66
JavaScript primitive number type.
67

68
```kotlin { .api }
69
/**
70
 * JavaScript primitive number
71
 */
72
@JsPrimitive("number")
73
external class JsNumber internal constructor() : JsAny
74
```
75

76
### JsBoolean Class
77

78
JavaScript primitive boolean type.
79

80
```kotlin { .api }
81
/**
82
 * JavaScript primitive boolean
83
 */
84
@JsPrimitive("boolean")
85
external class JsBoolean internal constructor() : JsAny
86
```
87

88
### JsBigInt Class
89

90
JavaScript primitive bigint type.
91

92
```kotlin { .api }
93
/**
94
 * JavaScript primitive bigint
95
 */
96
@JsPrimitive("bigint")
97
external class JsBigInt internal constructor() : JsAny
98
```
99

100
### JsArray Class
101

102
JavaScript Array with generic type support.
103

104
```kotlin { .api }
105
/**
106
 * JavaScript Array
107
 * @param T Type of array elements (must extend JsAny?)
108
 */
109
@JsName("Array")
110
external class JsArray<T : JsAny?> : JsAny {
111
    /** Array length */
112
    val length: Int
113
    
114
    /** Array element access */
115
    operator fun get(index: Int): T?
116
    
117
    /** Array element assignment */
118
    operator fun set(index: Int, value: T)
119
}
120
```
121

122
### JsException Class
123

124
Wrapper for exceptions thrown by JavaScript code.
125

126
```kotlin { .api }
127
/**
128
 * Wrapper for exceptions thrown by JavaScript code
129
 * @param thrownValue Value thrown by JavaScript code
130
 */
131
class JsException internal constructor(val thrownValue: JsAny?) : Throwable {
132
    /** Value thrown by JavaScript code */
133
    val thrownValue: JsAny?
134
    
135
    /** Exception message (overridden from Throwable) */
136
    override val message: String
137
}
138

139
/**
140
 * Constant that can be used to initialize external declarations without explicit initializer
141
 */
142
val definedExternally: Nothing
143

144
/**
145
 * Dynamic type for JavaScript interoperability (deprecated, use JsAny instead)
146
 * @deprecated Use JsAny and specific JavaScript types instead
147
 */
148
@Deprecated("Use JsAny and specific JavaScript types instead")
149
external interface dynamic : JsAny
150

151
**Usage Examples:**
152

153
```kotlin
154
import kotlin.js.*
155

156
// Working with JsAny
157
val jsValue: JsAny = "hello".toJsString()
158
val jsString: JsString = jsValue.unsafeCast<JsString>()
159

160
// Working with JsReference
161
data class User(val name: String, val age: Int)
162
val user = User("Alice", 25)
163
val jsRef: JsReference<User> = user.toJsReference()
164
val retrievedUser: User = jsRef.get()
165

166
// Working with JsArray
167
val jsArray = JsArray<JsString>()
168
jsArray[0] = "first".toJsString()
169
jsArray[1] = "second".toJsString()
170
println(jsArray.length) // 2
171

172
// Exception handling
173
try {
174
    js("throw new Error('Something went wrong')")
175
} catch (e: JsException) {
176
    println("JavaScript error: ${e.message}")
177
    println("Original JS value: ${e.thrownValue}")
178
}
179
```