0
# Scala 3 Library for Scala.js
1

2
The Scala 3 library compiled for JavaScript environments via Scala.js, providing the complete Scala 3 standard library API with JavaScript-specific runtime support and cross-platform compatibility. This library enables Scala 3 applications to run efficiently in web browsers and Node.js environments while maintaining type safety and performance.
3

4
## Package Information
5

6
- **Package Name**: org.scala-lang:scala3-library_sjs1_3
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Version**: 3.7.0
10
- **Platform**: Scala.js 1.x
11
- **Installation**: Add to your `build.sbt`:
12

13
```scala
14
libraryDependencies += "org.scala-lang" %%% "scala3-library" % "3.7.0"
15
```
16

17
## Core Imports
18

19
Standard Scala imports work seamlessly:
20

21
```scala
22
import scala.*
23
import scala.util.*
24
import scala.compiletime.*
25
import scala.quoted.*
26
import scala.deriving.*
27
```
28

29
Package-specific imports:
30

31
```scala
32
import scala.scalajs.js.internal.UnitOps.given
33
import scala.caps.{Capability, cap}
34
import scala.util.boundary.{boundary, break}
35
```
36

37
## Basic Usage
38

39
```scala
40
import scala.*
41
import scala.util.boundary
42

43
// Use Scala 3 tuples and named tuples
44
val coordinates: (Double, Double) = (1.5, 2.7)
45
val person = (name = "Alice", age = 30, city = "San Francisco")
46

47
// Immutable arrays with full API
48
val numbers = IArray(1, 2, 3, 4, 5)
49
val doubled = numbers.map(_ * 2)
50

51
// Union and intersection types  
52
def process[T](value: String | Int): T | Unit = value match
53
  case s: String => println(s"String: $s")
54
  case i: Int => println(s"Number: $i")
55

56
// Boundary-based control flow
57
boundary:
58
  for i <- 1 to 100 do
59
    if i > 50 then break(i)
60
```
61

62
## Architecture
63

64
The Scala 3 library for Scala.js is organized around several key architectural components:
65

66
- **Type System**: Union types (`|`), intersection types (`&`), and enhanced tuple system
67
- **Metaprogramming**: Compile-time operations, quoted expressions, and derivation system
68
- **Capability System**: Experimental capture checking and capability-safe programming
69
- **Runtime Support**: JavaScript-specific runtime adaptations and standard library patches
70
- **Collection APIs**: Immutable arrays (`IArray`) and enhanced tuple operations
71
- **Control Flow**: Boundary/break pattern for structured control flow
72

73
## Capabilities
74

75
### Core Type System
76

77
Foundation types including union types, intersection types, tuples, named tuples, equality system, and structural types. Essential for all Scala 3 programming with advanced type features.
78

79
```scala { .api }
80
type |[A, B] = A | B  // Union types
81
type &[A, B] = A & B  // Intersection types
82

83
sealed trait Tuple extends Product
84
case object EmptyTuple extends Tuple
85
sealed abstract class *:[+H, +T <: Tuple] extends NonEmptyTuple
86

87
trait CanEqual[-L, -R]
88
trait Matchable
89
```
90

91
[Core Types](./core-types.md)
92

93
### Immutable Collections
94

95
High-performance immutable arrays with covariant types and comprehensive collection operations. Provides JavaScript-optimized implementations of standard collection patterns.
96

97
```scala { .api }
98
opaque type IArray[+T] = Array[? <: T]
99

100
object IArray:
101
  def empty[T]: IArray[T]
102
  def apply[T](elems: T*): IArray[T]
103
  def fill[T](n: Int)(elem: => T): IArray[T]
104
  def tabulate[T](n: Int)(f: Int => T): IArray[T]
105
```
106

107
[Collections](./collections.md)
108

109
### Metaprogramming
110

111
Compile-time operations, quoted expressions, and macro support. Enables powerful metaprogramming with type-safe code generation and compile-time computation.
112

113
```scala { .api }
114
// Compile-time operations
115
inline def constValue[T]: T
116
inline def summonInline[T]: T
117
inline def error(msg: String): Nothing
118

119
// Quoted expressions  
120
abstract class Expr[+T]
121
trait Quotes
122

123
// Type-level operations
124
type ToString[X] <: String
125
type +[X <: Int, Y <: Int] <: Int
126
```
127

128
[Metaprogramming](./metaprogramming.md)
129

130
### Derivation System
131

132
Mirror-based generic programming for automatic derivation of type class instances. Supports both sum types (enums) and product types (case classes).
133

134
```scala { .api }
135
sealed trait Mirror:
136
  type MirroredMonoType
137
  type MirroredLabel <: String
138
  type MirroredElemLabels <: Tuple
139

140
trait Mirror.Sum extends Mirror:
141
  def ordinal(x: MirroredMonoType): Int
142

143
trait Mirror.Product extends Mirror:
144
  def fromProduct(p: scala.Product): MirroredMonoType
145
```
146

147
[Derivation](./derivation.md)
148

149
### Capability System
150

151
Experimental capture checking system for capability-safe programming. Provides fine-grained control over side effects and resource access.
152

153
```scala { .api }
154
trait Capability extends Any
155

156
object cap extends Capability
157

158
erased class CanThrow[-E <: Exception] extends Capability
159

160
sealed trait Contains[+C, R]
161
```
162

163
[Capabilities](./capabilities.md)
164

165
### Control Flow and Utilities
166

167
Boundary-based control flow, utility types, and helper functions. Includes structured exception-like control flow and advanced utility classes.
168

169
```scala { .api }
170
// Boundary control flow
171
object boundary:
172
  def apply[T](body: Label[T] ?=> T): T
173
  def break[T](value: T)(using Label[T]): Nothing
174

175
// Utility types
176
final class NotGiven[+T]
177
sealed trait TupledFunction[F, G]
178
```
179

180
[Utilities](./utilities.md)
181

182
### Annotations
183

184
Comprehensive annotation system including experimental features, macro annotations, and compiler hints. Supports both behavioral annotations and metaprogramming constructs.
185

186
```scala { .api }
187
class experimental extends StaticAnnotation
188
class targetName(name: String) extends StaticAnnotation
189
trait MacroAnnotation extends StaticAnnotation:
190
  def transform(definition: Any, companion: Option[Any]): List[Any]
191
```
192

193
[Annotations](./annotations.md)
194

195
### Runtime and JavaScript Interop
196

197
JavaScript-specific runtime support and Scala.js interoperability. Provides the bridge between Scala 3 language features and JavaScript runtime environment.
198

199
```scala { .api }
200
// Scala.js specific operations
201
object UnitOps:
202
  given unitOrOps[A](x: A | Unit): js.UndefOrOps[A]
203

204
// Runtime support
205
object Scala3RunTime
206
sealed abstract class AnonFunctionXXL extends scala.runtime.FunctionXXL
207
```
208

209
[Runtime](./runtime.md)
210

211
## Types
212

213
Core types used throughout the API:
214

215
```scala { .api }
216
// Foundation types
217
abstract class AnyKind
218
trait Matchable
219

220
// Tuple types
221
sealed trait Tuple extends Product
222
case object EmptyTuple extends Tuple
223
sealed trait NonEmptyTuple extends Tuple
224
sealed abstract class *:[+H, +T <: Tuple] extends NonEmptyTuple
225

226
// Opaque types
227
opaque type IArray[+T] = Array[? <: T]
228
opaque type NamedTuple[N <: Tuple, +V <: Tuple] = V
229

230
// Function types
231
trait PolyFunction
232
abstract class Conversion[-T, +U] extends Function1[T, U]
233

234
// Meta types
235
abstract class Expr[+T]
236
trait Type[T]
237
```