JavaScript Types

/**
 * Represents any JavaScript value except null or undefined
 */
external interface JsAny

/**
 * Cast JsAny to other JS type without runtime check
 * @return T The target JavaScript type
 */
fun <T : JsAny> JsAny.unsafeCast(): T

/**
 * JavaScript value that serves as a reference for any Kotlin value
 */
sealed external interface JsReference<out T : Any> : JsAny

/**
 * Convert any Kotlin object to JsReference
 * @return JsReference<T> JavaScript reference to the Kotlin object
 */
fun <T : Any> T.toJsReference(): JsReference<T>

/**
 * Retrieve original Kotlin value from JsReference (internal use only)
 * @return T The original Kotlin value
 */
internal fun <T> JsReference<T>.get(): T

/**
 * JavaScript primitive string
 */
@JsPrimitive("string")
external class JsString internal constructor() : JsAny {
    /**
     * Convert JsString to Kotlin String
     * @return String Kotlin string representation
     */
    override fun toString(): String
}

/**
 * JavaScript primitive number
 */
@JsPrimitive("number")
external class JsNumber internal constructor() : JsAny

/**
 * JavaScript primitive boolean
 */
@JsPrimitive("boolean")
external class JsBoolean internal constructor() : JsAny

/**
 * JavaScript primitive bigint
 */
@JsPrimitive("bigint")
external class JsBigInt internal constructor() : JsAny

/**
 * JavaScript Array
 * @param T Type of array elements (must extend JsAny?)
 */
@JsName("Array")
external class JsArray<T : JsAny?> : JsAny {
    /** Array length */
    val length: Int
    
    /** Array element access */
    operator fun get(index: Int): T?
    
    /** Array element assignment */
    operator fun set(index: Int, value: T)
}

/**
 * Wrapper for exceptions thrown by JavaScript code
 * @param thrownValue Value thrown by JavaScript code
 */
class JsException internal constructor(val thrownValue: JsAny?) : Throwable {
    /** Value thrown by JavaScript code */
    val thrownValue: JsAny?
    
    /** Exception message (overridden from Throwable) */
    override val message: String
}

/**
 * Constant that can be used to initialize external declarations without explicit initializer
 */
val definedExternally: Nothing

/**
 * Dynamic type for JavaScript interoperability (deprecated, use JsAny instead)
 * @deprecated Use JsAny and specific JavaScript types instead
 */
@Deprecated("Use JsAny and specific JavaScript types instead")
external interface dynamic : JsAny

**Usage Examples:**

```kotlin
import kotlin.js.*

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

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

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

// Exception handling
try {
    js("throw new Error('Something went wrong')")
} catch (e: JsException) {
    println("JavaScript error: ${e.message}")
    println("Original JS value: ${e.thrownValue}")
}