0
# Arrow Core
1
2
Arrow Core is a comprehensive functional programming library for Kotlin that provides a lingua franca of interfaces and abstractions across Kotlin libraries. It serves as the foundation for typed functional programming in Kotlin, offering high-level abstractions for error handling, data transformation, and computation composition that seamlessly integrate across different Kotlin platforms including JVM, Android, JavaScript, and Native targets.
3
4
## Package Information
5
6
- **Package Name**: arrow-core
7
- **Package Type**: maven
8
- **Language**: Kotlin (Multiplatform)
9
- **Installation**: `implementation("io.arrow-kt:arrow-core:1.2.4")`
10
11
## Core Imports
12
13
```kotlin
14
import arrow.core.*
15
import arrow.core.raise.*
16
```
17
18
For specific types:
19
20
```kotlin
21
import arrow.core.Either
22
import arrow.core.Option
23
import arrow.core.NonEmptyList
24
import arrow.core.raise.either
25
import arrow.core.raise.option
26
```
27
28
## Basic Usage
29
30
```kotlin
31
import arrow.core.*
32
import arrow.core.raise.*
33
34
// Type-safe error handling with Either
35
val result: Either<String, Int> = either {
36
val x = parseNumber("42").bind() // Extract success or raise error
37
val y = parseNumber("24").bind()
38
x + y
39
}
40
41
// Optional values with Option
42
val user: Option<User> = findUser(id).map { it.copy(active = true) }
43
44
// Non-empty collections
45
val items = nonEmptyListOf("first", "second", "third")
46
val processed = items.map { it.uppercase() }
47
48
fun parseNumber(s: String): Either<String, Int> =
49
Either.catch { s.toInt() }.mapLeft { "Invalid number: $s" }
50
```
51
52
## Architecture
53
54
Arrow Core is built around several key design principles:
55
56
- **Type Safety**: Replace runtime errors (null pointer, exceptions) with compile-time checked types
57
- **Functional Composition**: All types support map, flatMap, and functional composition patterns
58
- **Raise DSL**: Modern error handling system using coroutine-style builders instead of exceptions
59
- **Multiplatform**: Full Kotlin Multiplatform support across JVM, Android, JS, and Native
60
- **Interoperability**: Seamless integration with Kotlin's standard library and nullable types
61
- **Zero-Cost Abstractions**: Optimized implementations that don't sacrifice performance
62
63
## Capabilities
64
65
### Error Handling with Either
66
67
Type-safe error handling that makes failure cases explicit and composable. Either is right-biased, treating success (Right) as the default path and providing extensive combinators for error handling.
68
69
```kotlin { .api }
70
sealed class Either<out A, out B> {
71
data class Left<out A>(val value: A) : Either<A, Nothing>()
72
data class Right<out B>(val value: B) : Either<Nothing, B>()
73
74
companion object {
75
fun <A, B> Right(value: B): Either<A, B>
76
fun <A, B> Left(value: A): Either<A, B>
77
fun <R> catch(f: () -> R): Either<Throwable, R>
78
fun <reified T : Throwable, R> catchOrThrow(f: () -> R): Either<T, R>
79
80
// zipOrAccumulate methods for error accumulation
81
fun <E, A, B, Z> zipOrAccumulate(
82
combine: (E, E) -> E,
83
a: Either<E, A>,
84
b: Either<E, B>,
85
transform: (A, B) -> Z
86
): Either<E, Z>
87
88
fun <E, A, B, Z> zipOrAccumulate(
89
a: Either<E, A>,
90
b: Either<E, B>,
91
transform: (A, B) -> Z
92
): Either<NonEmptyList<E>, Z>
93
94
// Additional overloads for 3-10 parameters available
95
}
96
}
97
```
98
99
[Error Handling](./error-handling.md)
100
101
### Optional Values with Option
102
103
Safe handling of optional values without null pointer exceptions. Option provides a type-safe alternative to nullable types with comprehensive functional operations.
104
105
```kotlin { .api }
106
sealed class Option<out A> {
107
object None : Option<Nothing>()
108
data class Some<out A>(val value: A) : Option<A>()
109
110
companion object {
111
fun <A> fromNullable(value: A?): Option<A>
112
}
113
}
114
```
115
116
[Optional Values](./optional-values.md)
117
118
### Raise DSL for Typed Error Handling
119
120
Modern DSL for typed error handling using structured concurrency patterns. Raise provides ergonomic builders that eliminate boilerplate while maintaining type safety.
121
122
```kotlin { .api }
123
interface Raise<in Error> {
124
@RaiseDSL
125
fun raise(r: Error): Nothing
126
127
@RaiseDSL
128
fun ensure(condition: Boolean, raise: () -> Error)
129
}
130
131
fun <Error, A> either(block: Raise<Error>.() -> A): Either<Error, A>
132
fun <A> option(block: OptionRaise.() -> A): Option<A>
133
```
134
135
[Raise DSL](./raise-dsl.md)
136
137
### Collections and Data Structures
138
139
Type-safe collections that provide compile-time guarantees about their contents. Includes non-empty collections, validated containers, and functional collection operations.
140
141
```kotlin { .api }
142
data class NonEmptyList<out A>(val head: A, val tail: List<A>)
143
data class NonEmptySet<out A>(val head: A, val tail: Set<A>)
144
145
fun <A> nonEmptyListOf(head: A, vararg tail: A): NonEmptyList<A>
146
fun <A> nonEmptySetOf(head: A, vararg tail: A): NonEmptySet<A>
147
```
148
149
[Collections](./collections.md)
150
151
### Inclusive OR with Ior
152
153
Represents values that can be either one type, another type, or both simultaneously. Useful for computations that can produce partial results alongside errors or warnings.
154
155
```kotlin { .api }
156
sealed interface Ior<out A, out B> {
157
data class Left<out A>(val value: A) : Ior<A, Nothing>
158
data class Right<out B>(val value: B) : Ior<Nothing, B>
159
data class Both<out A, out B>(val left: A, val right: B) : Ior<A, B>
160
}
161
```
162
163
[Inclusive OR](./inclusive-or.md)
164
165
### Functional Utilities
166
167
Comprehensive utilities for function composition, currying, memoization, and other functional programming patterns. Provides building blocks for higher-order functional programming.
168
169
```kotlin { .api }
170
fun <A> identity(a: A): A
171
fun <A, B, C> ((B) -> C).compose(f: (A) -> B): (A) -> C
172
fun <A, B> ((A) -> B).memoize(): (A) -> B
173
```
174
175
[Functional Utilities](./functional-utilities.md)
176
177
## Types
178
179
### Core Type Aliases
180
181
```kotlin { .api }
182
typealias Nel<A> = NonEmptyList<A>
183
typealias EitherNel<E, A> = Either<NonEmptyList<E>, A>
184
typealias IorNel<E, A> = Ior<NonEmptyList<E>, A>
185
```
186
187
### Tuple Types
188
189
```kotlin { .api }
190
data class Tuple4<out A, out B, out C, out D>(
191
val first: A,
192
val second: B,
193
val third: C,
194
val fourth: D
195
)
196
197
// Similar definitions for Tuple5 through Tuple22
198
```
199
200
### Evaluation Types
201
202
```kotlin { .api }
203
sealed class Eval<out A> {
204
abstract fun value(): A
205
206
companion object {
207
fun <A> now(value: A): Eval<A>
208
fun <A> later(f: () -> A): Eval<A>
209
fun <A> always(f: () -> A): Eval<A>
210
}
211
}
212
```