0
# Kotlin Standard Library for WebAssembly WASI
1

2
## Overview
3

4
The Kotlin Standard Library for WebAssembly WASI (`kotlin-stdlib-wasm-wasi`) provides platform-specific implementations of the Kotlin standard library for the WebAssembly System Interface (WASI) specification. This library enables Kotlin applications to run in WASI-compliant WebAssembly runtimes, providing essential functionality for I/O operations, time handling, random number generation, UUID creation, and reflection capabilities tailored specifically for the WASI environment.
5

6
As part of the Kotlin Multiplatform ecosystem, this library serves as the bridge between Kotlin's high-level programming model and low-level WebAssembly system interfaces, enabling developers to write Kotlin applications for server-side WASI environments, edge computing platforms, and other systems supporting the WASI specification.
7

8
## Package Information
9

10
- **Package Name:** `org.jetbrains.kotlin:kotlin-stdlib-wasm-wasi`
11
- **Package Type:** Library (Kotlin Standard Library)
12
- **Language:** Kotlin
13
- **Platform:** WebAssembly WASI
14
- **Version:** 2.2.0
15
- **License:** Apache-2.0
16

17
## Installation
18

19
This library is automatically included when targeting Kotlin/WASM with WASI in a Kotlin Multiplatform project. Add the WASI target to your Kotlin Multiplatform configuration:
20

21
```kotlin
22
kotlin {
23
    wasm {
24
        wasi {
25
            nodejs()
26
        }
27
    }
28
}
29
```
30

31
## Core Imports
32

33
The APIs in this library are accessed through standard Kotlin imports. Most functionality is available through the common Kotlin standard library packages:
34

35
```kotlin
36
// I/O operations
37
import kotlin.io.*
38

39
// Random number generation  
40
import kotlin.random.*
41

42
// Time and duration handling
43
import kotlin.time.*
44

45
// UUID generation (experimental)
46
import kotlin.uuid.*
47
import kotlin.uuid.ExperimentalUuidApi
48

49
// Reflection capabilities
50
import kotlin.reflect.*
51
```
52

53
## Basic Usage
54

55
```kotlin
56
@OptIn(ExperimentalUuidApi::class)
57
fun main() {
58
    // Console output
59
    println("Hello WASI World!")
60
    print("Output without newline")
61

62
    // Random number generation
63
    val randomInt = Random.nextInt(1, 100)
64
    val secureRandom = Random.nextBytes(16)
65

66
    // UUID generation (experimental API)
67
    val uuid = Uuid.random()
68

69
    // Time operations
70
    val now = Clock.System.now()
71
    val duration = measureTime {
72
        // Some operation
73
    }
74

75
    // Type reflection
76
    val type = typeOf<String>()
77
}
78
```
79

80
## Architecture
81

82
The kotlin-stdlib-wasm-wasi package is built on several key architectural components:
83

84
### WASI System Call Integration
85
The library integrates directly with WASI system calls through WebAssembly imports:
86
- `clock_time_get` - For time and duration operations
87
- `random_get` - For cryptographically secure random data generation
88
- `fd_write` - For console output operations
89

90
### Platform-Specific Implementations
91
All APIs are `actual` implementations of `expect` declarations from the common Kotlin standard library, providing WASI-specific behavior while maintaining cross-platform compatibility.
92

93
### Memory Safety
94
The library uses scoped memory allocators to ensure safe memory handling when interacting with WASI system calls, preventing memory leaks and buffer overflows.
95

96
## Capabilities
97

98
### Console I/O Operations
99
Basic console output functionality for WASI applications.
100

101
```kotlin { .api }
102
fun print(message: Any?)
103
fun println()
104
fun println(message: Any?)
105
```
106

107
[Console I/O Documentation](./console-io.md)
108

109
### Random Number Generation
110
Cryptographically secure random number generation using WASI's random_get system call.
111

112
```kotlin { .api }
113
object Random {
114
    fun nextInt(): Int
115
    fun nextInt(until: Int): Int
116
    fun nextInt(from: Int, until: Int): Int
117
    fun nextBytes(size: Int): ByteArray
118
    // ... other random functions
119
}
120
```
121

122
[Random Number Generation Documentation](./random.md)
123

124
### Time and Duration Handling
125
Time source implementations and duration operations for WASI environments.
126

127
```kotlin { .api }
128
object TimeSource.Monotonic : TimeSource
129
object Clock.System : Clock
130
```
131

132
[Time and Duration Documentation](./time.md)
133

134
### UUID Generation
135
Platform-specific UUID generation using WASI secure random number generation.
136

137
```kotlin { .api }
138
@ExperimentalUuidApi
139
object Uuid.Companion {
140
    @ExperimentalUuidApi
141
    fun random(): Uuid
142
}
143
```
144

145
[UUID Generation Documentation](./uuid.md)
146

147
### Reflection Capabilities
148
Type reflection support for WASI applications.
149

150
```kotlin { .api }
151
inline fun <reified T> typeOf(): KType
152
inline fun <reified T> typeOfLazyInit(): KType
153
```
154

155
[Reflection Documentation](./reflection.md)
156

157
### Exception Handling
158
WASI-specific exception handling and error management.
159

160
```kotlin { .api }
161
class Throwable(
162
    message: String? = null,
163
    cause: Throwable? = null
164
)
165
```
166

167
[Exception Handling Documentation](./exceptions.md)
168

169
## Platform Limitations
170

171
### Not Implemented Features
172
- **Console Input**: `readln()` and `readlnOrNull()` functions are not implemented in WASI and will throw `TODO` exceptions
173
- **File System Operations**: Only console I/O is supported; general file system operations are not available
174
- **Network Operations**: Network-related APIs are not supported in the current WASI implementation
175

176
### WASI Specification Dependency
177
This library depends on WASI preview1 specification. Future WASI versions may require library updates for compatibility.
178

179
## Error Handling
180

181
The library includes comprehensive error handling for WASI-specific scenarios:
182

183
- **WASI Error Codes**: All 82 WASI error codes from the preview1 specification are mapped to appropriate Kotlin exceptions
184
- **System Call Failures**: WASI system call failures are properly translated to Kotlin exceptions
185
- **Memory Management Errors**: Safe memory handling prevents common WebAssembly memory issues
186

187
## Performance Considerations
188

189
- **System Call Overhead**: Direct WASI system call integration minimizes overhead compared to higher-level abstractions
190
- **Memory Efficiency**: Scoped memory allocation prevents memory leaks in long-running applications
191
- **Cryptographic Security**: Random number generation uses hardware-backed entropy when available through WASI