0
# Scala.js Standard Library (scalajs-scalalib)
1

2
The Scala.js Standard Library provides the core Scala standard library implementation specifically adapted for JavaScript compilation targets. It maintains full API compatibility with the JVM Scala standard library while providing optimized implementations for the JavaScript runtime environment, enabling seamless use of familiar Scala APIs in browser and Node.js environments.
3

4
## Package Information
5

6
- **Package Name**: scalajs-scalalib_2.13
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Build Tool**: sbt
10
- **Installation**: `libraryDependencies += "org.scala-js" %%% "scalalib" % "1.20.1"`
11

12
## Core Imports
13

14
The scalalib is automatically available when using Scala.js compilation. Standard Scala imports work as expected:
15

16
```scala
17
import scala.App
18
import scala.Array
19
import scala.Console
20
import scala.concurrent.ExecutionContext
21
import scala.util.DynamicVariable
22
import scala.collection._
23
```
24

25
## Basic Usage
26

27
```scala
28
// Using App trait for main program
29
object Main extends App {
30
  Console.println("Hello World: " + (args mkString ", "))
31
}
32

33
// Array operations
34
val numbers = Array(1, 2, 3, 4, 5)
35
val doubled = numbers.map(_ * 2)
36
val filtered = Array.range(1, 10).filter(_ % 2 == 0)
37

38
// Concurrent operations  
39
import scala.concurrent.ExecutionContext.Implicits.global
40
import scala.concurrent.Future
41

42
val future = Future {
43
  "Hello from JavaScript!"
44
}
45
```
46

47
## Architecture
48

49
The Scala.js Standard Library is organized around JavaScript-specific adaptations:
50

51
- **Override System**: Selective replacement of JVM standard library components with JavaScript-optimized implementations
52
- **Version Compatibility**: Separate implementations for Scala 2.12 and 2.13 compiler versions  
53
- **Single-threaded Model**: Adapted for JavaScript's single-threaded execution environment
54
- **Type Preservation**: Maintains Scala's type system while optimizing for JavaScript performance
55
- **API Compatibility**: Ensures existing Scala code compiles and runs correctly on JavaScript
56

57
## Capabilities
58

59
### Core Language Features
60

61
Essential Scala language constructs and basic functionality adapted for JavaScript execution.
62

63
```scala { .api }
64
trait App extends DelayedInit {
65
  val args: Array[String]
66
  val executionStart: Long
67
}
68

69
object Array {
70
  def apply[T](xs: T*): Array[T]
71
  def ofDim[T: ClassTag](n1: Int): Array[T]
72
  def empty[T: ClassTag]: Array[T]
73
  def fill[T: ClassTag](n: Int)(elem: => T): Array[T]
74
  def tabulate[T: ClassTag](n: Int)(f: Int => T): Array[T]
75
  def range(start: Int, end: Int): Array[Int]
76
  def concat[T: ClassTag](xss: Array[T]*): Array[T]
77
}
78

79
object Console {
80
  def print(obj: Any): Unit
81
  def println(obj: Any): Unit
82
  def println(): Unit
83
  def printf(text: String, args: Any*): Unit
84
  def readLine(): String
85
  def readLine(text: String): String
86
}
87
```
88

89
[Core Language Features](./core-features.md)
90

91
### Concurrent Programming
92

93
Asynchronous programming utilities adapted for JavaScript's event loop and single-threaded execution model.
94

95
```scala { .api }
96
trait ExecutionContext {
97
  def execute(runnable: Runnable): Unit
98
  def reportFailure(cause: Throwable): Unit
99
}
100

101
object ExecutionContext {
102
  def global: ExecutionContext
103
  def fromExecutor(executor: Executor): ExecutionContext
104
}
105
```
106

107
[Concurrent Programming](./concurrent.md)
108

109
### Collections Framework
110

111
Scala's collections library adapted for JavaScript with optimized implementations and JavaScript-specific performance characteristics.
112

113
```scala { .api }
114
// Collection operations and utilities
115
// (Detailed APIs available in collections sub-doc)
116
```
117

118
[Collections Framework](./collections.md)
119

120
### Utility Classes
121

122
General-purpose utility classes for common programming tasks, adapted for JavaScript environment constraints.
123

124
```scala { .api }
125
class DynamicVariable[T](init: T) {
126
  def value: T
127
  def value_=(newval: T): Unit
128
  def withValue[S](newval: T)(thunk: => S): S
129
}
130

131
class Enumeration {
132
  protected final def Value: Value
133
  protected final def Value(i: Int): Value  
134
  protected final def Value(name: String): Value
135
  protected final def Value(i: Int, name: String): Value
136
}
137

138
case class Symbol private (name: String) {
139
  override def toString: String = "'" + name
140
}
141
```
142

143
[Utility Classes](./utilities.md)
144

145
### Math Operations
146

147
Mathematical functions and numeric utilities optimized for JavaScript's number system and Math object.
148

149
```scala { .api }
150
// Math utility functions and constants
151
// (Detailed APIs available in math sub-doc)
152
```
153

154
[Math Operations](./math.md)
155

156
### Runtime Support
157

158
Low-level runtime support classes and utilities that provide the foundation for Scala.js execution.
159

160
```scala { .api }
161
// Runtime support APIs
162
// (Detailed APIs available in runtime sub-doc)  
163
```
164

165
[Runtime Support](./runtime.md)
166

167
## JavaScript-Specific Adaptations
168

169
The scalalib implementations are specifically optimized for JavaScript execution:
170

171
- **Single-threaded Execution**: All concurrent operations adapted for JavaScript's event loop
172
- **JavaScript Data Structures**: Optimized array and collection implementations using JavaScript arrays and objects
173
- **Performance Optimization**: Implementations tuned for JavaScript engine characteristics
174
- **Memory Management**: Adapted for JavaScript's garbage collection patterns
175
- **Type System Integration**: Maintains Scala's type safety while integrating with JavaScript's dynamic typing
176

177
## Version Compatibility
178

179
The library provides three levels of compatibility:
180

181
1. **General Overrides** (`overrides/scala/`) - Core APIs compatible with all Scala versions
182
2. **Scala 2.12 Specific** (`overrides-2.12/scala/`) - Scala 2.12 version-specific implementations  
183
3. **Scala 2.13 Specific** (`overrides-2.13/scala/`) - Scala 2.13 version-specific implementations
184

185
## Error Handling
186

187
Standard Scala exception handling works as expected. Common JavaScript-specific considerations:
188

189
- **TypeError**: May occur when interfacing with JavaScript code
190
- **RangeError**: Possible with large numeric operations
191
- **Memory Limits**: JavaScript heap size limitations may affect large data structures