0
# Arrow Core
1

2
Arrow Core is the foundational module of the Arrow Kotlin library that provides essential data types and functional programming abstractions for Kotlin Multiplatform development. It offers type-safe alternatives to null values, railway-oriented programming for error handling, non-empty collections, and a powerful Raise DSL for typed error management.
3

4
## Package Information
5

6
- **Package Name**: io.arrow-kt:arrow-core
7
- **Package Type**: maven
8
- **Language**: Kotlin
9
- **Platform**: Kotlin Multiplatform (iosArm64, jvm, js, native targets)
10
- **Installation**: `implementation("io.arrow-kt:arrow-core:2.1.2")`
11

12
## Core Imports
13

14
```kotlin
15
import arrow.core.*
16
import arrow.core.raise.*
17
```
18

19
For specific imports:
20

21
```kotlin
22
import arrow.core.Either
23
import arrow.core.Option
24
import arrow.core.NonEmptyList
25
import arrow.core.raise.either
26
import arrow.core.raise.effect
27
```
28

29
## Basic Usage
30

31
```kotlin
32
import arrow.core.*
33
import arrow.core.raise.either
34

35
// Working with Optional values
36
val maybeUser: Option<String> = Some("Alice")
37
val greeting = maybeUser.map { "Hello, $it!" }.getOrElse { "Hello, Guest!" }
38

39
// Error handling with Either
40
val result: Either<String, Int> = either {
41
    val input = "42"
42
    input.toIntOrNull() ?: raise("Invalid number")
43
}
44

45
// Non-empty collections
46
val numbers = nonEmptyListOf(1, 2, 3, 4, 5)
47
val doubled = numbers.map { it * 2 }
48

49
// Using the Raise DSL for error accumulation
50
val validation = either {
51
    val name = validateName("") // raises error if empty
52
    val age = validateAge(-1)   // raises error if negative
53
    User(name, age)
54
}
55
```
56

57
## Architecture
58

59
Arrow Core is built around several key components:
60

61
- **Type-Safe Null Handling**: `Option<A>` provides a safe alternative to nullable types
62
- **Railway-Oriented Programming**: `Either<A, B>` enables clean error handling without exceptions
63
- **Error Accumulation**: `Ior<A, B>` allows collecting multiple errors while preserving successful computations
64
- **Guaranteed Non-Empty Collections**: `NonEmptyList` and `NonEmptySet` prevent empty collection errors at compile time
65
- **Raise DSL**: A composable system for typed error handling with short-circuiting and accumulation
66
- **Effect System**: Suspended computations with error handling capabilities
67
- **Functional Extensions**: Rich collection operations following functional programming principles
68

69
## Capabilities
70

71
### Core Data Types
72

73
Essential functional data types providing type-safe alternatives to nullable values, error handling, and guaranteed non-empty collections.
74

75
```kotlin { .api }
76
sealed class Either<out A, out B>
77
sealed class Option<out A>
78
sealed class Ior<out A, out B>
79
interface NonEmptyCollection<out E>: Collection<E>
80
data class NonEmptyList<out A>: NonEmptyCollection<A>
81
data class NonEmptySet<out A>: NonEmptyCollection<A>
82
```
83

84
[Core Data Types](./core-data-types.md)
85

86
### Raise DSL
87

88
Composable typed error handling system with short-circuiting and error accumulation capabilities. Includes the Effect system for asynchronous computations and RaiseAccumulate for error collection. The foundation for all error handling in Arrow.
89

90
```kotlin { .api }
91
@RaiseDSL
92
interface Raise<in Error> {
93
    fun raise(error: Error): Nothing
94
    fun <A> Either<Error, A>.bind(): A
95
    fun <A> Option<A>.bind(): A
96
}
97

98
class SingletonRaise<in Error>: Raise<Error>
99
class IorRaise<Error>: Raise<Error>
100
class RaiseAccumulate<Error>: Raise<NonEmptyList<Error>>
101

102
// Effect System types
103
typealias Effect<Error, A> = suspend Raise<Error>.() -> A
104
typealias EagerEffect<Error, A> = Raise<Error>.() -> A
105

106
suspend fun <Error, A> effect(block: suspend Raise<Error>.() -> A): Either<Error, A>
107
fun <Error, A> eagerEffect(block: Raise<Error>.() -> A): Either<Error, A>
108
```
109

110
[Raise DSL](./raise-dsl.md)
111

112
### Collection Extensions
113

114
Functional programming extensions for Kotlin collections including multi-parameter zip operations, alignment operations, error accumulation, and safety utilities.
115

116
```kotlin { .api }
117
fun <A, B, C, R> Iterable<A>.zip(other1: Iterable<B>, other2: Iterable<C>, transform: (A, B, C) -> R): List<R>
118
fun <Error, A, B> RaiseAccumulate<Error>.Iterable<A>.mapOrAccumulate(transform: Raise<Error>.(A) -> B): List<B>
119
fun <A, B> Iterable<A>.align(other: Iterable<B>): List<Ior<A, B>>
120
fun <A> Iterable<A>.firstOrNone(): Option<A>
121
```
122

123
[Collection Extensions](./collection-extensions.md)
124

125
### Tuple Types
126

127
Immutable tuple data types for grouping 4-9 related values with type safety and destructuring support.
128

129
```kotlin { .api }
130
data class Tuple4<out A, out B, out C, out D>(val first: A, val second: B, val third: C, val fourth: D)
131
data class Tuple5<out A, out B, out C, out D, out E>(val first: A, val second: B, val third: C, val fourth: D, val fifth: E)
132
// ... through Tuple9
133
data class TupleN<out A>(val values: List<A>)
134
```
135

136
[Tuple Types](./tuple-types.md)