0
# Scalaz-Core
1

2
Scalaz-core is the foundational module of the Scalaz library, providing essential functional programming abstractions for Scala. It implements a comprehensive collection of type classes including Functor, Applicative, Monad, Foldable, Traversable, and many others that form the mathematical foundations of functional programming. The library offers data structures like Free monads, State transformers, Reader/Writer monads, and validation types that enable composable and pure functional programming patterns.
3

4
## Package Information
5

6
- **Package Name**: scalaz-core_sjs1_2.13
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.scalaz" %%% "scalaz-core" % "7.3.8"`
10

11
## Core Imports
12

13
```scala
14
import scalaz._
15
import Scalaz._  // Imports all instances and syntax
16
```
17

18
For selective imports:
19

20
```scala
21
import scalaz.{Functor, Applicative, Monad, \/}
22
import scalaz.std.option._    // Option instances
23
import scalaz.std.list._      // List instances
24
import scalaz.syntax.monad._  // Monad syntax
25
```
26

27
## Basic Usage
28

29
```scala
30
import scalaz._
31
import Scalaz._
32

33
// Using type class instances
34
val doubled = List(1, 2, 3).map(_ * 2)  // Uses Functor[List]
35

36
// Validation for error accumulation
37
val result = (
38
  "John".successNel[String] |@|
39
  25.successNel[String] |@|
40
  "john@example.com".successNel[String]
41
) { (name, age, email) => User(name, age, email) }
42

43
// Disjunction (Either-like) with right bias
44
val computation: String \/ Int = \/-(42)
45
val mapped = computation.map(_ * 2)  // Results in \/-(84)
46

47
// State monad for stateful computations
48
val statefulComp = for {
49
  current <- State.get[Int]
50
  _       <- State.put(current + 1)
51
  final   <- State.get[Int]
52
} yield final
53

54
val (finalState, result) = statefulComp.run(10)  // (11, 11)
55
```
56

57
## Architecture
58

59
Scalaz-core follows the mathematical structure of category theory and abstract algebra:
60

61
- **Type Classes**: Abstract interfaces defining operations (Functor, Monad, etc.)
62
- **Instances**: Concrete implementations for specific types (List, Option, etc.)
63
- **Syntax**: Extension methods providing convenient operators and DSL
64
- **Data Types**: Functional data structures designed for immutability and composition
65
- **Transformers**: Monad transformers for composing effectful computations
66

67
The library provides three main packages:
68
- **scalaz**: Core type classes and data structures
69
- **scalaz.std**: Type class instances for standard library types
70
- **scalaz.syntax**: Implicit conversions and operator syntax
71

72
## Capabilities
73

74
### Core Type Classes
75

76
Essential type classes forming the mathematical foundations of functional programming, including functors, applicatives, monads, and their relationships.
77

78
```scala { .api }
79
trait Functor[F[_]] {
80
  def map[A, B](fa: F[A])(f: A => B): F[B]
81
}
82

83
trait Apply[F[_]] extends Functor[F] {
84
  def ap[A, B](fa: => F[A])(f: => F[A => B]): F[B]
85
}
86

87
trait Applicative[F[_]] extends Apply[F] {
88
  def point[A](a: => A): F[A]
89
}
90

91
trait Bind[F[_]] extends Apply[F] {
92
  def bind[A, B](fa: F[A])(f: A => F[B]): F[B]
93
}
94

95
trait Monad[F[_]] extends Applicative[F] with Bind[F]
96

97
trait Foldable[F[_]] {
98
  def foldMap[A, B](fa: F[A])(f: A => B)(implicit F: Monoid[B]): B
99
  def foldRight[A, B](fa: F[A], z: => B)(f: (A, => B) => B): B
100
}
101

102
trait Traverse[F[_]] extends Functor[F] with Foldable[F] {
103
  def traverseImpl[G[_], A, B](fa: F[A])(f: A => G[B])(implicit G: Applicative[G]): G[F[B]]
104
}
105
```
106

107
[Core Type Classes](./type-classes.md)
108

109
### Data Structures  
110

111
Immutable functional data structures designed for composition, including collections, trees, validation types, and specialized containers.
112

113
```scala { .api }
114
sealed abstract class NonEmptyList[+A] {
115
  def head: A
116
  def tail: List[A]
117
  def map[B](f: A => B): NonEmptyList[B]
118
  def flatMap[B](f: A => NonEmptyList[B]): NonEmptyList[B]
119
}
120

121
sealed abstract class Tree[A] {
122
  def rootLabel: A
123
  def subForest: Stream[Tree[A]]
124
  def map[B](f: A => B): Tree[B]
125
}
126

127
sealed abstract class \/[+A, +B] {
128
  def map[C](f: B => C): A \/ C
129
  def flatMap[C](f: B => A \/ C): A \/ C
130
  def isLeft: Boolean
131
  def isRight: Boolean
132
}
133

134
sealed abstract class Validation[+E, +A] {
135
  def map[B](f: A => B): Validation[E, B]
136
  def ap[EE >: E, B](f: => Validation[EE, A => B]): Validation[EE, B]
137
}
138
```
139

140
[Data Structures](./data-structures.md)
141

142
### Monad Transformers
143

144
Composable monad transformers for combining effects, including State, Reader, Writer, and their combinations.
145

146
```scala { .api }
147
case class StateT[S, F[_], A](run: S => F[(S, A)]) {
148
  def map[B](f: A => B)(implicit F: Functor[F]): StateT[S, F, B]
149
  def flatMap[B](f: A => StateT[S, F, B])(implicit F: Monad[F]): StateT[S, F, B]
150
}
151

152
type State[S, A] = StateT[S, Id, A]
153

154
case class ReaderT[E, F[_], A](run: E => F[A]) {
155
  def map[B](f: A => B)(implicit F: Functor[F]): ReaderT[E, F, B]
156
  def flatMap[B](f: A => ReaderT[E, F, B])(implicit F: Monad[F]): ReaderT[E, F, B]
157
}
158

159
case class WriterT[W, F[_], A](underlying: F[(W, A)]) {
160
  def map[B](f: A => B)(implicit F: Functor[F]): WriterT[W, F, B]
161
  def flatMap[B](f: A => WriterT[W, F, B])(implicit F: Monad[F], W: Semigroup[W]): WriterT[W, F, B]
162
}
163
```
164

165
[Monad Transformers](./transformers.md)
166

167
### Standard Library Integration
168

169
Type class instances for Scala and Java standard library types, enabling functional programming patterns with familiar types.
170

171
```scala { .api }
172
// Available instances (imported via scalaz.std.* or Scalaz._)
173
implicit val listMonad: Monad[List]
174
implicit val optionMonad: Monad[Option]  
175
implicit val vectorMonad: Monad[Vector]
176
implicit val setMonoid: Monoid[Set[A]]
177
implicit val stringMonoid: Monoid[String]
178
implicit val intOrder: Order[Int]
179
implicit val booleanEqual: Equal[Boolean]
180
```
181

182
[Standard Library Integration](./std-instances.md)
183

184
### Syntax Extensions
185

186
Implicit conversions and operators providing a convenient DSL for functional programming operations.
187

188
```scala { .api }
189
// Extension methods available via scalaz.syntax.* imports
190
implicit class FunctorOps[F[_], A](fa: F[A])(implicit F: Functor[F]) {
191
  def map[B](f: A => B): F[B] = F.map(fa)(f)
192
  def void: F[Unit] = F.void(fa)
193
  def fproduct[B](f: A => B): F[(A, B)] = F.fproduct(fa)(f)
194
}
195

196
implicit class ApplicativeOps[F[_], A](fa: F[A])(implicit F: Applicative[F]) {
197
  def |@|[B](fb: F[B]): ApplicativeBuilder[F, A, B]
198
}
199

200
implicit class MonadOps[F[_], A](fa: F[A])(implicit F: Monad[F]) {
201
  def flatMap[B](f: A => F[B]): F[B] = F.bind(fa)(f)
202
  def >>[B](fb: => F[B]): F[B] = F.bind(fa)(_ => fb)
203
}
204
```
205

206
[Syntax Extensions](./syntax.md)
207

208
### Free Structures
209

210
Free monads and cofree comonads for building composable, purely functional DSLs and interpreters.
211

212
```scala { .api }
213
sealed abstract class Free[S[_], A] {
214
  def map[B](f: A => B): Free[S, B]
215
  def flatMap[B](f: A => Free[S, B]): Free[S, B]
216
  def foldMap[M[_]](f: S ~> M)(implicit M: Monad[M]): M[A]
217
}
218

219
object Free {
220
  def liftF[S[_], A](sa: S[A]): Free[S, A]
221
  def pure[S[_], A](a: A): Free[S, A]
222
}
223

224
sealed abstract class Cofree[S[_], A] {
225
  def head: A
226
  def tail: S[Cofree[S, A]]
227
  def map[B](f: A => B): Cofree[S, B]
228
}
229
```
230

231
[Free Structures](./free-structures.md)