0
# Reflection
1

2
Runtime reflection capabilities with JavaScript class interoperability for dynamic type inspection and instance creation. This module provides type information and reflection operations adapted for JavaScript environments.
3

4
## Capabilities
5

6
### Core Reflection Interfaces
7

8
Runtime type information and class reflection.
9

10
```kotlin { .api }
11
/**
12
 * Represents a class and provides introspection capabilities
13
 */
14
actual interface KClass<T : Any> {
15
    val simpleName: String?
16
    val qualifiedName: String?
17
    val members: Collection<KCallable<*>>
18
    val constructors: Collection<KFunction<T>>
19
    val nestedClasses: Collection<KClass<*>>
20
    val objectInstance: T?
21
    val typeParameters: List<KTypeParameter>
22
    val supertypes: List<KType>
23
    val sealedSubclasses: List<KClass<out T>>
24
    val visibility: KVisibility?
25
    val isFinal: Boolean
26
    val isOpen: Boolean
27
    val isAbstract: Boolean
28
    val isSealed: Boolean
29
    val isData: Boolean
30
    val isInner: Boolean
31
    val isCompanion: Boolean
32
    val isFun: Boolean
33
    val isValue: Boolean
34
    
35
    fun isInstance(value: Any?): Boolean
36
}
37

38
/**
39
 * Represents a function and provides introspection capabilities
40
 */
41
actual interface KFunction<out R> : KCallable<R>, Function<R> {
42
    val isInline: Boolean
43
    val isExternal: Boolean
44
    val isOperator: Boolean
45
    val isInfix: Boolean
46
    val isSuspend: Boolean
47
}
48

49
/**
50
 * Represents a property and provides introspection capabilities
51
 */
52
actual interface KProperty<out V> : KCallable<V> {
53
    val isLateinit: Boolean
54
    val isConst: Boolean
55
    val getter: KProperty.Getter<V>
56
    
57
    interface Getter<out V> : KFunction<V>
58
}
59

60
/**
61
 * Base interface for callable entities (functions and properties)
62
 */
63
actual interface KCallable<out R> {
64
    val name: String
65
    val parameters: List<KParameter>
66
    val returnType: KType
67
    val typeParameters: List<KTypeParameter>
68
    val visibility: KVisibility?
69
    val isFinal: Boolean
70
    val isOpen: Boolean
71
    val isAbstract: Boolean
72
    val isSuspend: Boolean
73
    
74
    fun call(vararg args: Any?): R
75
    fun callBy(args: Map<KParameter, Any?>): R
76
}
77

78
/**
79
 * Represents type information
80
 */
81
actual interface KType {
82
    val classifier: KClassifier?
83
    val arguments: List<KTypeProjection>
84
    val isMarkedNullable: Boolean
85
}
86
```
87

88
### JavaScript Class Integration
89

90
Seamless interoperability between Kotlin and JavaScript classes.
91

92
```kotlin { .api }
93
/**
94
 * JavaScript class wrapper interface
95
 */
96
external interface JsClass<T : Any> {
97
    val name: String
98
    val length: Int
99
}
100

101
/**
102
 * Get JavaScript class from Kotlin class
103
 */
104
val <T : Any> KClass<T>.js: JsClass<T>
105

106
/**
107
 * Get Kotlin class from JavaScript class
108
 */
109
val <T : Any> JsClass<T>.kotlin: KClass<T>
110

111
/**
112
 * Create instance of a class using default constructor
113
 */
114
fun <T : Any> KClass<T>.createInstance(): T
115

116
/**
117
 * Get KClass for an object instance
118
 */
119
val <T : Any> T.kotlin: KClass<T>
120
```
121

122
**Usage Examples:**
123

124
```kotlin
125
import kotlin.reflect.*
126

127
class Person(val name: String, val age: Int)
128

129
// Get class reference
130
val personClass = Person::class
131

132
// Access JavaScript class
133
val jsClass = personClass.js
134
console.log("JS class name: ${jsClass.name}") // "Person"
135

136
// Create instance
137
val person = personClass.createInstance() // Uses default constructor
138
// Note: This would fail if no default constructor exists
139

140
// Get class from instance
141
val instance = Person("John", 30)
142
val klass = instance::class
143
console.log("Class name: ${klass.simpleName}") // "Person"
144

145
// Check instance type
146
val isPersonInstance = personClass.isInstance(instance) // true
147
```
148

149
### Function and Property Reflection
150

151
Reflection capabilities for functions and properties.
152

153
```kotlin { .api }
154
/**
155
 * Get KFunction reference for a function
156
 */
157
fun <T> T.javaClass: KClass<out T> // Extension for compatibility
158

159
/**
160
 * Function reference operators
161
 */
162
operator fun <T> KFunction<T>.invoke(vararg args: Any?): T
163
```
164

165
**Usage Examples:**
166

167
```kotlin
168
import kotlin.reflect.*
169

170
class Calculator {
171
    fun add(a: Int, b: Int): Int = a + b
172
    val pi: Double = 3.14159
173
}
174

175
val calc = Calculator()
176

177
// Function reflection
178
val addFunction = Calculator::add
179
console.log("Function name: ${addFunction.name}") // "add"
180
console.log("Parameter count: ${addFunction.parameters.size}") // 3 (including receiver)
181

182
// Property reflection  
183
val piProperty = Calculator::pi
184
console.log("Property name: ${piProperty.name}") // "pi"
185
console.log("Return type: ${piProperty.returnType}") // Double type info
186

187
// Call function reflectively
188
val result = addFunction.call(calc, 5, 3) // 8
189

190
// Access property reflectively
191
val value = piProperty.call(calc) // 3.14159
192
```
193

194
### Type Parameter and Generic Information
195

196
Runtime generic type information (limited in JavaScript).
197

198
```kotlin { .api }
199
/**
200
 * Represents a type parameter of a generic class or function
201
 */
202
actual interface KTypeParameter : KClassifier {
203
    val name: String
204
    val upperBounds: List<KType>
205
    val variance: KVariance
206
    val isReified: Boolean
207
}
208

209
/**
210
 * Represents a type projection in generic type arguments
211
 */
212
actual class KTypeProjection {
213
    val variance: KVariance?
214
    val type: KType?
215
    
216
    companion object {
217
        val STAR: KTypeProjection
218
        fun invariant(type: KType): KTypeProjection
219
        fun contravariant(type: KType): KTypeProjection
220
        fun covariant(type: KType): KTypeProjection
221
    }
222
}
223

224
/**
225
 * Base interface for type classifiers
226
 */
227
actual interface KClassifier
228

229
/**
230
 * Variance annotation for type parameters
231
 */
232
actual enum class KVariance {
233
    INVARIANT, IN, OUT
234
}
235
```
236

237
### Associated Objects (Experimental)
238

239
Experimental feature for associating metadata objects with classes.
240

241
```kotlin { .api }
242
/**
243
 * Experimental annotation for associated objects feature
244
 */
245
@RequiresOptIn("Associated objects API is experimental")
246
annotation class ExperimentalAssociatedObjects
247

248
/**
249
 * Find associated object of given type
250
 */
251
@ExperimentalAssociatedObjects
252
inline fun <reified T : Any> KClass<*>.findAssociatedObject(): T?
253

254
/**
255
 * Find associated object by class
256
 */
257
@ExperimentalAssociatedObjects  
258
fun <T : Any> KClass<*>.findAssociatedObject(klass: KClass<T>): T?
259
```
260

261
**Usage Examples:**
262

263
```kotlin
264
@file:OptIn(ExperimentalAssociatedObjects::class)
265

266
import kotlin.reflect.*
267

268
// Define metadata class
269
class SchemaInfo(val version: Int, val table: String)
270

271
// Use with associated objects (experimental)
272
@AssociatedObjectKey(SchemaInfo::class)
273
class User(val id: Int, val name: String)
274

275
// Find associated object
276
val userClass = User::class
277
val schema = userClass.findAssociatedObject<SchemaInfo>()
278
schema?.let {
279
    console.log("Table: ${it.table}, Version: ${it.version}")
280
}
281
```
282

283
## Types
284

285
```kotlin { .api }
286
// Core reflection interfaces
287
actual interface KClass<T : Any> : KClassifier
288
actual interface KFunction<out R> : KCallable<R>, Function<R>
289
actual interface KProperty<out V> : KCallable<V>
290
actual interface KCallable<out R>
291
actual interface KType
292
actual interface KTypeParameter : KClassifier
293
actual interface KClassifier
294

295
// JavaScript integration
296
external interface JsClass<T : Any>
297

298
// Type system
299
actual class KTypeProjection
300
actual enum class KVariance { INVARIANT, IN, OUT }
301

302
// Parameter and visibility
303
actual interface KParameter
304
actual enum class KVisibility { PUBLIC, PROTECTED, INTERNAL, PRIVATE }
305

306
// Property accessors
307
interface KProperty.Getter<out V> : KFunction<V>
308
interface KMutableProperty.Setter<in V> : KFunction<Unit>
309

310
// Mutable property
311
actual interface KMutableProperty<V> : KProperty<V> {
312
    val setter: Setter<V>
313
    interface Setter<in V> : KFunction<Unit>
314
}
315

316
// Annotations (experimental)
317
@RequiresOptIn("Associated objects API is experimental")
318
annotation class ExperimentalAssociatedObjects
319

320
@Target(AnnotationTarget.CLASS)
321
annotation class AssociatedObjectKey(val kclass: KClass<*>)
322
```