0
# ZIO
1

2
ZIO is a zero-dependency Scala library for asynchronous and concurrent programming, powered by highly-scalable, non-blocking fibers. It provides a comprehensive effect system with the core `ZIO[R, E, A]` type representing async workflows that require an environment `R` and can fail with `E` or succeed with `A`. ZIO features high-performance concurrent operations, type-safe error handling, resource management that prevents leaks, comprehensive testing capabilities, and functional programming primitives.
3

4
## Package Information
5

6
- **Package Name**: dev.zio:zio_2.12
7
- **Package Type**: Maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "dev.zio" %% "zio" % "2.1.19"`
10

11
## Core Imports
12

13
```scala
14
import zio._
15
import zio.ZIO._
16
```
17

18
For specific components:
19

20
```scala
21
import zio.{ZIO, ZLayer, Runtime, Fiber, Ref, Queue, Schedule, Cause, Chunk}
22
import zio.stm.{ZSTM, TRef, TMap, TQueue}
23
import zio.stream.{ZStream, ZSink, ZPipeline}
24
import zio.test.{Spec, ZIOSpecDefault, Assertion, Gen, TestAspect}
25
import zio.metrics.{Metric, MetricClient, MetricLabel}
26
```
27

28
## Basic Usage
29

30
```scala
31
import zio._
32

33
// Simple effect that always succeeds
34
val greeting: UIO[String] = ZIO.succeed("Hello, ZIO!")
35

36
// Effect that might fail
37
val mayFail: IO[String, Int] = ZIO.attempt {
38
  "123".toInt  // Could throw NumberFormatException
39
}.refineOrDie {
40
  case _: NumberFormatException => "Invalid number"
41
}
42

43
// Combining effects
44
val program: ZIO[Any, String, Unit] = for {
45
  message <- greeting
46
  number  <- mayFail
47
  _       <- Console.printLine(s"$message Number: $number")
48
} yield ()
49

50
// Running the program
51
object MyApp extends ZIOAppDefault {
52
  def run = program
53
}
54
```
55

56
## Architecture
57

58
ZIO is built around several key architectural components:
59

60
- **Effect System**: Core `ZIO[R, E, A]` type representing typed effects with environment, error, and success types
61
- **Runtime System**: Execution environment with fiber-based concurrency, scheduling, and resource management  
62
- **Layer System**: Dependency injection via `ZLayer` for composable service provisioning
63
- **STM**: Software Transactional Memory for lock-free concurrent programming
64
- **Type Safety**: Comprehensive type system preventing common concurrency and resource management errors
65
- **Zero Dependencies**: Pure Scala implementation with no external runtime dependencies
66

67
## Type System
68

69
ZIO provides a rich type alias system for common effect patterns:
70

71
```scala { .api }
72
// Core effect types
73
type IO[+E, +A]   = ZIO[Any, E, A]         // No requirements
74
type Task[+A]     = ZIO[Any, Throwable, A] // May fail with Throwable
75
type RIO[-R, +A]  = ZIO[R, Throwable, A]   // Requires R, may fail
76
type UIO[+A]      = ZIO[Any, Nothing, A]   // Cannot fail
77
type URIO[-R, +A] = ZIO[R, Nothing, A]     // Requires R, cannot fail
78

79
// Layer type aliases  
80
type RLayer[-RIn, +ROut]  = ZLayer[RIn, Throwable, ROut]
81
type URLayer[-RIn, +ROut] = ZLayer[RIn, Nothing, ROut] 
82
type Layer[+E, +ROut]     = ZLayer[Any, E, ROut]
83
type ULayer[+ROut]        = ZLayer[Any, Nothing, ROut]
84
type TaskLayer[+ROut]     = ZLayer[Any, Throwable, ROut]
85
```
86

87
## Capabilities
88

89
### Core Effect System
90

91
The foundational ZIO effect type and operations for building functional, concurrent applications with comprehensive error handling and resource safety.
92

93
```scala { .api }
94
sealed trait ZIO[-R, +E, +A] {
95
  // Core transformations
96
  def map[B](f: A => B): ZIO[R, E, B]
97
  def flatMap[R1 <: R, E1 >: E, B](k: A => ZIO[R1, E1, B]): ZIO[R1, E1, B]
98
  def mapError[E2](f: E => E2): ZIO[R, E2, A]
99
  
100
  // Error handling
101
  def catchAll[R1 <: R, E2, A1 >: A](h: E => ZIO[R1, E2, A1]): ZIO[R1, E2, A1]
102
  def orElse[R1 <: R, E2, A1 >: A](that: => ZIO[R1, E2, A1]): ZIO[R1, E2, A1]
103
  def retry[R1 <: R, S](policy: => Schedule[R1, E, S]): ZIO[R1, E, A]
104
  
105
  // Concurrency
106
  def fork: URIO[R, Fiber.Runtime[E, A]]
107
  def race[R1 <: R, E1 >: E, A1 >: A](that: => ZIO[R1, E1, A1]): ZIO[R1, E1, A1]
108
  def timeout(d: => Duration): ZIO[R, E, Option[A]]
109
}
110

111
// Factory methods
112
object ZIO {
113
  def succeed[A](a: => A): UIO[A]
114
  def fail[E](error: => E): IO[E, Nothing]  
115
  def attempt[A](code: => A): Task[A]
116
  def async[R, E, A](register: (ZIO[R, E, A] => Unit) => Any): ZIO[R, E, A]
117
}
118
```
119

120
[Core Effects](./core-effects.md)
121

122
### Dependency Injection
123

124
ZLayer system for building and composing services with compile-time dependency resolution and automatic resource management.
125

126
```scala { .api }
127
sealed abstract class ZLayer[-RIn, +E, +ROut] {
128
  // Composition operators
129
  def ++[E1 >: E, RIn2, ROut2](that: => ZLayer[RIn2, E1, ROut2]): ZLayer[RIn with RIn2, E1, ROut with ROut2]
130
  def >>>[E1 >: E, ROut2](that: => ZLayer[ROut, E1, ROut2]): ZLayer[RIn, E1, ROut2]
131
  def >+>[E1 >: E, ROut2](that: => ZLayer[ROut, E1, ROut2]): ZLayer[RIn, E1, ROut with ROut2]
132
  
133
  // Lifecycle
134
  def build: ZIO[RIn with Scope, E, ZEnvironment[ROut]]
135
  def launch: ZIO[RIn, E, Nothing]
136
}
137

138
object ZLayer {
139
  def succeed[A: Tag](a: => A): ULayer[A]
140
  def fromZIO[R, E, A: Tag](zio: => ZIO[R, E, A]): ZLayer[R, E, A]
141
  def scoped[R]: ScopedPartiallyApplied[R]
142
}
143
```
144

145
[Dependency Injection](./dependency-injection.md)
146

147
### Concurrency Primitives
148

149
Fiber-based lightweight concurrency with atomic data structures for building high-performance concurrent applications.
150

151
```scala { .api }
152
// Fiber - lightweight threads
153
sealed abstract class Fiber[+E, +A] {
154
  def await: UIO[Exit[E, A]]
155
  def join: IO[E, A]
156
  def interrupt: UIO[Exit[E, A]]
157
  def zip[E1 >: E, B](that: => Fiber[E1, B]): Fiber.Synthetic[E1, (A, B)]
158
}
159

160
// Ref - atomic reference
161
sealed abstract class Ref[A] {
162
  def get: UIO[A]
163
  def set(a: A): UIO[Unit]
164
  def modify[B](f: A => (B, A)): UIO[B]
165
  def update(f: A => A): UIO[Unit]
166
}
167

168
// Queue - concurrent queue
169
sealed abstract class Queue[A] {
170
  def offer(a: A): UIO[Boolean]
171
  def take: UIO[A]
172
  def size: UIO[Int]
173
}
174
```
175

176
[Concurrency](./concurrency.md)
177

178
### Error Handling and Scheduling
179

180
Comprehensive error model with rich failure causes and composable retry/repeat scheduling for resilient applications.
181

182
```scala { .api }
183
// Rich error representation
184
sealed abstract class Cause[+E] {
185
  def failures: List[E]
186
  def defects: List[Throwable]
187
  def &&[E1 >: E](that: Cause[E1]): Cause[E1]  // parallel composition
188
  def ++[E1 >: E](that: Cause[E1]): Cause[E1]  // sequential composition
189
}
190

191
// Retry/repeat scheduling
192
trait Schedule[-Env, -In, +Out] {
193
  def &&[Env1 <: Env, In1 <: In, Out2](that: Schedule[Env1, In1, Out2]): Schedule[...]
194
  def ||[Env1 <: Env, In1 <: In, Out2](that: Schedule[Env1, In1, Out2]): Schedule[...]
195
  def jittered: Schedule[Env, In, Out]
196
}
197

198
object Schedule {
199
  val forever: Schedule[Any, Any, Long]
200
  def exponential(base: Duration): Schedule[Any, Any, Duration]
201
  def spaced(duration: Duration): Schedule[Any, Any, Long]
202
}
203
```
204

205
[Error Handling](./error-handling.md)
206

207
### Resource Management
208

209
Scope-based resource lifecycle management with automatic cleanup and finalizer execution for leak-free applications.
210

211
```scala { .api }
212
sealed trait Scope {
213
  def addFinalizer(finalizer: => UIO[Any]): UIO[Unit]
214
  def addFinalizerExit(finalizer: Exit[Any, Any] => UIO[Any]): UIO[Unit]
215
  def fork: UIO[Scope.Closeable]
216
}
217

218
// Resource-safe operations
219
def acquireRelease[R, E, A, B](
220
  acquire: => ZIO[R, E, A]
221
)(release: A => URIO[R, Any]): ZIO[R with Scope, E, A]
222

223
def ensuring[R1 <: R](finalizer: => URIO[R1, Any]): ZIO[R1, E, A]
224
```
225

226
[Resource Management](./resource-management.md)
227

228
### Software Transactional Memory
229

230
Lock-free concurrent programming with composable transactional operations and automatic retry mechanisms.
231

232
```scala { .api }
233
// Transactional effects
234
sealed trait ZSTM[-R, +E, +A] {
235
  def commit: ZIO[R, E, A]
236
  def map[B](f: A => B): ZSTM[R, E, B]
237
  def flatMap[R1 <: R, E1 >: E, B](f: A => ZSTM[R1, E1, B]): ZSTM[R1, E1, B]
238
  def retry: USTM[Nothing]
239
}
240

241
// Transactional reference
242
sealed abstract class TRef[A] {
243
  def get: USTM[A]
244
  def set(a: A): USTM[Unit]
245
  def modify[B](f: A => (B, A)): USTM[B]
246
}
247

248
object ZSTM {
249
  def atomically[R, E, A](stm: ZSTM[R, E, A]): ZIO[R, E, A]
250
}
251
```
252

253
[Software Transactional Memory](./stm.md)
254

255
### Built-in Services
256

257
Standard services for common application needs including console I/O, time operations, randomness, and system access.
258

259
```scala { .api }
260
// Console operations
261
def printLine(line: => Any): IO[IOException, Unit]
262
def readLine: IO[IOException, String]
263

264
// Time operations  
265
def currentTime(unit: => TimeUnit): UIO[Long]
266
def sleep(duration: => Duration): UIO[Unit]
267
def nanoTime: UIO[Long]
268

269
// Random generation
270
def nextInt: UIO[Int]
271
def nextUUID: UIO[UUID]
272
def nextBytes(length: => Int): UIO[Chunk[Byte]]
273

274
// System access
275
def env(variable: => String): IO[SecurityException, Option[String]]
276
def property(prop: => String): Task[Option[String]]
277
```
278

279
[Built-in Services](./services.md)
280

281
### Application Framework
282

283
Complete application framework with dependency injection, configuration, and lifecycle management for building production applications.
284

285
```scala { .api }
286
trait ZIOApp {
287
  type Environment
288
  def bootstrap: ZLayer[ZIOAppArgs, Any, Environment]
289
  def run: ZIO[Environment with ZIOAppArgs with Scope, Any, Any]
290
}
291

292
// Default application base
293
abstract class ZIOAppDefault extends ZIOApp {
294
  type Environment = Any
295
  final def bootstrap: ZLayer[ZIOAppArgs, Any, Any] = ZLayer.empty
296
}
297

298
// Application helpers
299
def getArgs: ZIO[ZIOAppArgs, Nothing, Chunk[String]]
300
def exit(code: ExitCode): UIO[Unit]
301
```
302

303
[Application Framework](./application.md)
304

305
### ZIO Streams
306

307
Composable, resource-safe streaming data processing with comprehensive backpressure handling and error recovery for building data pipelines and reactive applications.
308

309
```scala { .api }
310
// Core streaming types
311
sealed trait ZStream[-R, +E, +A]
312
sealed trait ZSink[-R, +E, -In, +L, +Z]  
313
sealed trait ZPipeline[-R, +E, -In, +Out]
314

315
// Type aliases
316
type Stream[+E, +A] = ZStream[Any, E, A]
317
type UStream[+A] = ZStream[Any, Nothing, A]
318

319
// Stream construction
320
def fromIterable[A](as: => Iterable[A]): UStream[A]
321
def fromZIO[R, E, A](zio: => ZIO[R, E, A]): ZStream[R, E, A]
322
def repeat[A](a: => A): UStream[A]
323
```
324

325
[ZIO Streams](./streams.md)
326

327
### Testing Framework
328

329
Comprehensive testing framework with property-based testing, test services, and seamless integration with ZIO effects for testing concurrent and async code.
330

331
```scala { .api }
332
// Test specifications
333
sealed trait Spec[-R, +E]
334
abstract class ZIOSpec[R] extends ZIOApp
335
abstract class ZIOSpecDefault extends ZIOSpec[Any]
336

337
// Assertions and property testing
338
sealed trait Assertion[-A]
339
sealed trait Gen[+R, +A]
340
def assertTrue(condition: => Boolean): TestResult
341
def check[R, A](gen: Gen[R, A])(test: A => TestResult): ZIO[R, Nothing, TestResult]
342

343
// Test services
344
trait TestClock extends Clock
345
trait TestConsole extends Console
346
trait TestRandom extends Random
347
```
348

349
[Testing Framework](./testing.md)
350

351
### Metrics and Observability
352

353
Comprehensive metrics and observability capabilities for monitoring application performance, collecting telemetry data, and gaining insights into system behavior.
354

355
```scala { .api }
356
// Metric system
357
sealed trait Metric[In, Out]
358
trait MetricClient
359
case class MetricLabel(key: String, value: String)
360

361
// Metric types
362
def counter(name: String): Metric[Double, MetricState.Counter]
363
def gauge(name: String): Metric[Double, MetricState.Gauge]  
364
def histogram(name: String, boundaries: Boundaries): Metric[Double, MetricState.Histogram]
365

366
// Built-in metrics
367
val jvmMemoryUsed: Metric[Any, MetricState.Gauge]
368
val fiberCount: Metric[Any, MetricState.Gauge]
369
```
370

371
[Metrics and Observability](./metrics.md)