0
# Runtime and JavaScript Interop
1

2
JavaScript-specific runtime support and Scala.js interoperability, providing the bridge between Scala 3 language features and JavaScript runtime environment.
3

4
## Capabilities
5

6
### Scala.js Internal Operations
7

8
Internal operations for Unit type handling and JavaScript interoperability.
9

10
```scala { .api }
11
/**
12
 * Internal operations for Unit type under Scala.js compilation
13
 * Provides implicit conversions for Unit | T unions to UndefOr operations
14
 */
15
object UnitOps:
16
  /**
17
   * Convert Unit | A unions to UndefOr operations for JavaScript compatibility
18
   * Enables natural handling of undefined values in JavaScript contexts
19
   */
20
  given unitOrOps[A](x: A | Unit): js.UndefOrOps[A]
21
```
22

23
**Usage Examples:**
24

25
```scala
26
import scala.scalajs.js
27
import scala.scalajs.js.internal.UnitOps.given
28

29
// Union types with Unit automatically get UndefOr operations
30
val value: String | Unit = if (condition) "hello" else ()
31

32
// Can use UndefOr operations due to implicit conversion
33
val orElse = value.getOrElse("default")  // Works due to UnitOps conversion
34
val mapped = value.map(_.toUpperCase)    // Maps only if not Unit
35

36
// Function returning optional values
37
def maybeString(condition: Boolean): String | Unit = 
38
  if condition then "result" else ()
39

40
val result = maybeString(true)
41
// result can use UndefOr operations thanks to UnitOps
42
```
43

44
### Scala.js Function Compatibility
45

46
Support for large-arity functions in Scala.js environments.
47

48
```scala { .api }
49
/**
50
 * Large arity anonymous function support for Scala.js compatibility
51
 * Deprecated since Scala.js 1.19 - replaced by NewLambda compilation
52
 * Maintained for compatibility with libraries compiled before 1.19
53
 */
54
@deprecated("used by the codegen before Scala.js 1.19", since = "3.7.0")
55
sealed abstract class AnonFunctionXXL extends scala.runtime.FunctionXXL
56
```
57

58
**Usage Examples:**
59

60
```scala
61
// This class is primarily used by the compiler, not directly by users
62
// Historical context: before Scala.js 1.19, functions with many parameters
63
// were compiled to AnonFunctionXXL instances
64

65
// Modern Scala.js (1.19+) uses NewLambda compilation instead
66
// Old compiled code referencing AnonFunctionXXL is automatically patched
67

68
// Function with many parameters (would historically use AnonFunctionXXL)
69
val manyParamFunction = (a: Int, b: Int, c: Int, d: Int, e: Int, 
70
                        f: Int, g: Int, h: Int, i: Int, j: Int) => 
71
  a + b + c + d + e + f + g + h + i + j
72

73
// In modern Scala.js, this compiles to efficient NewLambda representation
74
// Legacy AnonFunctionXXL references are handled transparently
75
```
76

77
### Runtime Support Classes
78

79
Core runtime support for Scala 3 language features.
80

81
```scala { .api }
82
/**
83
 * Core runtime support for Scala 3 operations
84
 * Provides runtime utilities for language features
85
 */
86
object Scala3RunTime:
87
  /** Runtime support for pattern matching */
88
  def isInstanceOf[T](x: Any, clazz: Class[?]): Boolean
89
  /** Runtime type checking with proper variance */
90
  def checkCast[T](x: Any): T
91
  /** Dynamic method selection support */
92
  def selectDynamic(receiver: Any, name: String): Any
93

94
/**
95
 * Array utility operations
96
 */
97
object Arrays:
98
  /** Copy array with proper type handling */
99
  def copyArray[T](src: Array[T], dst: Array[T], length: Int): Unit
100
  /** Create array of specific type */
101
  def newArray[T](componentType: Class[T], length: Int): Array[T]
102

103
/**
104
 * Enum value support for runtime operations
105
 */
106
trait EnumValue:
107
  /** Get enum ordinal */
108
  def ordinal: Int
109
  /** Get enum name */  
110
  def productPrefix: String
111

112
/**
113
 * Lazy value implementation support
114
 */
115
object LazyVals:
116
  /** Initialize lazy value with synchronization */
117
  def initialize[T](target: Any, offset: Long, value: T): T
118
  /** Get lazy value state */
119
  def getState(target: Any, offset: Long): Long
120

121
/**
122
 * Pattern matching case support
123
 */
124
class MatchCase[T](selector: T):
125
  /** Test if case matches */
126
  def isDefinedAt(x: Any): Boolean = ???
127
  /** Apply case logic */  
128
  def apply(x: Any): T = ???
129

130
/**
131
 * Type boxing utilities for generic operations
132
 */
133
object TypeBox:
134
  /** Box primitive values for generic context */
135
  def box[T](value: T): AnyRef
136
  /** Unbox values from generic context */
137
  def unbox[T](value: AnyRef): T
138
```
139

140
**Usage Examples:**
141

142
```scala
143
// Runtime type checking (typically used by compiler-generated code)
144
val obj: Any = "hello"
145
val isString = Scala3RunTime.isInstanceOf[String](obj, classOf[String])  // true
146
val asString = Scala3RunTime.checkCast[String](obj)  // "hello"
147

148
// Dynamic method selection for structural types
149
type HasName = { def name: String }
150
def getName(obj: HasName): String = 
151
  Scala3RunTime.selectDynamic(obj, "name").asInstanceOf[String]
152

153
// Array operations
154
val source = Array(1, 2, 3, 4, 5)
155
val dest = new Array[Int](5)
156
Arrays.copyArray(source, dest, 5)
157

158
// Enum operations (used internally)
159
enum Color extends EnumValue:
160
  case Red, Green, Blue
161

162
val red = Color.Red
163
println(red.ordinal)       // 0 (provided by EnumValue)
164
println(red.productPrefix) // "Red"
165

166
// Lazy values (compiler-generated usage)
167
lazy val expensiveComputation = {
168
  println("Computing...")
169
  42
170
}
171
// LazyVals.initialize is used internally to ensure thread-safe initialization
172

173
// Type boxing for generic operations
174
val boxed = TypeBox.box(42)           // java.lang.Integer
175
val unboxed = TypeBox.unbox[Int](boxed) // 42
176
```
177

178
### Tuple Runtime Support
179

180
Runtime support for tuple operations and large-arity tuples.
181

182
```scala { .api }
183
/**
184
 * Support for tuples with arity > 22
185
 */
186
class TupleXXL(private val elems: Array[Object]) extends Product:
187
  /** Get element at index */
188
  def productElement(n: Int): Any = elems(n)
189
  /** Get tuple arity */
190
  def productArity: Int = elems.length
191
  /** Check equality */
192
  override def equals(that: Any): Boolean = ???
193
  /** Hash code */  
194
  override def hashCode(): Int = ???
195

196
/**
197
 * Mirror support for tuple reflection
198
 */
199
object TupleMirror:
200
  /** Get mirror for tuple type */
201
  def apply[T <: Tuple]: Mirror.ProductOf[T] = ???
202

203
/**
204
 * Tuple utility operations
205
 */
206
object Tuples:
207
  /** Convert product to tuple */
208
  def fromProduct(p: Product): Tuple = ???
209
  /** Convert array to tuple */
210
  def fromArray(arr: Array[Object]): Tuple = ???
211
  /** Convert tuple to array */
212
  def toArray(t: Tuple): Array[Object] = ???
213

214
/**
215
 * Support for tupled function operations  
216
 */
217
object TupledFunctions:
218
  /** Convert function to tupled form */
219
  def tupled[F, G](f: F): G = ???
220
  /** Convert tupled function to regular form */
221
  def untupled[F, G](g: G): F = ???
222
```
223

224
**Usage Examples:**
225

226
```scala
227
// Large tuples (arity > 22) use TupleXXL internally
228
val largeTuple = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 
229
                 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
230
                 21, 22, 23, 24, 25)
231
// Internally represented as TupleXXL
232

233
println(largeTuple.productArity)    // 25
234
println(largeTuple.productElement(0)) // 1
235

236
// Tuple utilities
237
val product = ("Alice", 30, true)
238
val array = Tuples.toArray(product)          // Array("Alice", 30, true)
239
val backToTuple = Tuples.fromArray(array)    // ("Alice", 30, true)
240

241
// Function tupling
242
val add3 = (x: Int, y: Int, z: Int) => x + y + z
243
val tupledAdd3 = TupledFunctions.tupled(add3)
244
val result = tupledAdd3((1, 2, 3))  // 6
245
```
246

247
### Function Runtime Support
248

249
Support for large-arity functions and function operations.
250

251
```scala { .api }
252
/**
253
 * Support for functions with arity > 22
254
 */
255
abstract class FunctionXXL:
256
  /** Apply function with arguments array */
257
  def apply(args: Array[Object]): Object
258
  /** Get function arity */
259
  def arity: Int
260

261
/**
262
 * Exception throwing support for runtime
263
 */
264
object $throws:
265
  /** Mark method as potentially throwing */
266
  def apply[T <: Exception]: Any = ???
267
```
268

269
**Usage Examples:**
270

271
```scala
272
// Large-arity functions use FunctionXXL internally
273
val manyArgFunction = (a1: Int, a2: Int, a3: Int, a4: Int, a5: Int,
274
                      a6: Int, a7: Int, a8: Int, a9: Int, a10: Int,
275
                      a11: Int, a12: Int, a13: Int, a14: Int, a15: Int,
276
                      a16: Int, a17: Int, a18: Int, a19: Int, a20: Int,
277
                      a21: Int, a22: Int, a23: Int) => 
278
  a1 + a2 + a3 + a4 + a5 + a6 + a7 + a8 + a9 + a10 +
279
  a11 + a12 + a13 + a14 + a15 + a16 + a17 + a18 + a19 + a20 +
280
  a21 + a22 + a23
281

282
// Internally extends FunctionXXL
283
val args = Array.tabulate(23)(_.asInstanceOf[Object])
284
// Function can be called via apply(args) method
285
```
286

287
### Standard Library Patches
288

289
Compatibility patches for standard library components.
290

291
```scala { .api }
292
/**
293
 * Patched Predef object for Scala 3 compatibility
294
 */
295
object Predef:
296
  /** Standard assertion */
297
  def assert(assertion: Boolean): Unit = ???
298
  def assert(assertion: Boolean, message: => Any): Unit = ???
299
  
300
  /** Require preconditions */
301
  def require(requirement: Boolean): Unit = ???
302
  def require(requirement: Boolean, message: => Any): Unit = ???
303
  
304
  /** Standard print operations */
305
  def print(x: Any): Unit = ???
306
  def println(x: Any): Unit = ???
307
  def println(): Unit = ???
308

309
/**
310
 * Language feature imports
311
 */
312
object language:
313
  /** Language features that can be imported */
314
  object experimental:
315
    /** Capture checking feature */
316
    given captureChecking: languageFeature = ???
317
    /** Named tuples support */
318
    given namedTuples: languageFeature = ???
319
  
320
  /** Implicit conversions */  
321
  given implicitConversions: languageFeature = ???
322
  /** Postfix operators */
323
  given postfixOps: languageFeature = ???
324

325
type languageFeature = Unit
326
```
327

328
**Usage Examples:**
329

330
```scala
331
// Standard operations work as expected
332
Predef.assert(1 + 1 == 2)
333
Predef.require(args.nonEmpty, "Arguments required")
334
Predef.println("Hello, Scala 3!")
335

336
// Language feature imports
337
import scala.language.experimental.captureChecking
338
import scala.language.implicitConversions
339
import scala.language.postfixOps
340

341
// Enable experimental features
342
import scala.language.experimental.namedTuples
343
val person = (name = "Alice", age = 30)  // Named tuples enabled
344
```
345

346
### Coverage Support
347

348
Support for code coverage instrumentation.
349

350
```scala { .api }
351
/**
352
 * Code coverage instrumentation support
353
 */
354
object Invoker:
355
  /** Record coverage hit for instrumentation */
356
  def invoked(id: Int, count: Int): Unit = ???
357
  /** Initialize coverage tracking */
358
  def initializeInvoker(): Unit = ???
359
```
360

361
**Usage Examples:**
362

363
```scala
364
// Coverage instrumentation (typically compiler-generated)
365
def instrumentedMethod(): String = {
366
  Invoker.invoked(1, 1)  // Coverage tracking call (compiler-generated)
367
  "result"
368
}
369

370
// Coverage initialization (build tool integration)
371
// Invoker.initializeInvoker() called by coverage tools
372
```
373

374
## Types
375

376
```scala { .api }
377
// Scala.js interop types
378
object UnitOps:
379
  given unitOrOps[A](x: A | Unit): js.UndefOrOps[A]
380

381
sealed abstract class AnonFunctionXXL extends scala.runtime.FunctionXXL
382

383
// Runtime support types
384
object Scala3RunTime
385
object Arrays
386
trait EnumValue
387
object LazyVals
388
class MatchCase[T]
389
object TypeBox
390

391
// Tuple support types
392
class TupleXXL extends Product
393
object TupleMirror
394
object Tuples
395
object TupledFunctions
396

397
// Function support types
398
abstract class FunctionXXL:
399
  def apply(args: Array[Object]): Object
400
  def arity: Int
401

402
// Standard library patches
403
object Predef
404
object language
405
type languageFeature = Unit
406

407
// Coverage support
408
object Invoker
409
```