0
# Cats Core
1

2
Cats Core is a comprehensive functional programming library for Scala providing lightweight, modular, and extensible abstractions. It offers fundamental type classes like Functor, Applicative, and Monad, along with powerful data structures and syntax extensions that form the foundation of functional programming in Scala.
3

4
## Package Information
5

6
- **Package Name**: cats-core
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.typelevel" %% "cats-core" % "1.6.1"`
10

11
## Core Imports
12

13
```scala
14
import cats._
15
import cats.implicits._
16
```
17

18
For selective imports:
19

20
```scala
21
import cats.syntax.functor._     // Just Functor syntax
22
import cats.syntax.applicative._ // Just Applicative syntax
23
import cats.instances.list._     // Just List instances
24
```
25

26
## Basic Usage
27

28
```scala
29
import cats._
30
import cats.implicits._
31

32
// Using type class syntax
33
val list = List(1, 2, 3)
34
val doubled = list.map(_ * 2)         // Functor
35
val nested = List(List(1, 2), List(3, 4))
36
val flattened = nested.flatten        // Monad
37

38
// Working with Option
39
val opt1 = Some(42)
40
val opt2 = Some(10) 
41
val result = (opt1, opt2).mapN(_ + _) // Applicative
42

43
// Error handling with Either
44
val either1: Either[String, Int] = Right(5)
45
val either2: Either[String, Int] = Right(10)
46
val combined = (either1, either2).mapN(_ * _)
47

48
// Validation with error accumulation
49
import cats.data.Validated
50
import cats.data.ValidatedNel
51

52
val valid1: ValidatedNel[String, Int] = Validated.valid(42)
53
val valid2: ValidatedNel[String, Int] = Validated.valid(10)
54
val validResult = (valid1, valid2).mapN(_ + _)
55
```
56

57
## Architecture
58

59
Cats Core is built around several key components:
60

61
- **Type Classes**: Abstract interfaces defining functional capabilities (Functor, Monad, Applicative, etc.)
62
- **Data Types**: Functional data structures and monad transformers (NonEmptyList, Validated, EitherT, etc.)
63
- **Syntax Extensions**: Implicit methods that provide ergonomic APIs for type classes
64
- **Type Class Instances**: Implementations of type classes for standard Scala types
65
- **Arrow Types**: Category theory abstractions for composable computations
66

67
The library follows the principle of providing core, binary-compatible abstractions that can be composed and extended while maintaining performance through zero-overhead patterns.
68

69
## Capabilities
70

71
### Type Classes
72

73
Fundamental functional programming abstractions including the core type class hierarchy from Functor through Monad, error handling classes, and specialized variants with mathematical laws and stack-safe implementations.
74

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

80
trait Applicative[F[_]] extends Functor[F] {
81
  def pure[A](a: A): F[A]
82
  def ap[A, B](ff: F[A => B])(fa: F[A]): F[B]  
83
}
84

85
trait Monad[F[_]] extends Applicative[F] {
86
  def flatMap[A, B](fa: F[A])(f: A => F[B]): F[B]
87
  def tailRecM[A, B](a: A)(f: A => F[Either[A, B]]): F[B]
88
}
89
```
90

91
[Type Classes](./type-classes.md)
92

93
### Data Types
94

95
Functional data structures and monad transformers including non-empty collections, validation types, and composable transformers for building complex functional programs.
96

97
```scala { .api }
98
// Non-empty collections
99
final case class NonEmptyList[+A](head: A, tail: List[A])
100
final case class NonEmptyVector[+A](toVector: Vector[A])
101

102
// Validation with error accumulation  
103
sealed abstract class Validated[+E, +A]
104
final case class Valid[+A](a: A) extends Validated[Nothing, A]
105
final case class Invalid[+E](e: E) extends Validated[E, Nothing]
106

107
// Monad transformers
108
final case class OptionT[F[_], A](value: F[Option[A]])
109
final case class EitherT[F[_], A, B](value: F[Either[A, B]])
110
```
111

112
[Data Types](./data-types.md)
113

114
### Syntax Extensions
115

116
Implicit syntax methods that provide ergonomic APIs for all type classes, enabling natural method-chaining and operator-style programming with functional abstractions.
117

118
```scala { .api }
119
// Example syntax extensions (provided via implicits)
120
implicit class FunctorOps[F[_], A](fa: F[A])(implicit F: Functor[F]) {
121
  def map[B](f: A => B): F[B] = F.map(fa)(f)
122
  def void: F[Unit] = F.void(fa)
123
  def fproduct[B](f: A => B): F[(A, B)] = F.fproduct(fa)(f)
124
}
125
```
126

127
[Syntax Extensions](./syntax.md)
128

129
### Error Handling
130

131
Comprehensive error handling abstractions including MonadError and ApplicativeError for recoverable errors, plus data types like Validated and Ior for error accumulation patterns.
132

133
```scala { .api }
134
trait ApplicativeError[F[_], E] extends Applicative[F] {
135
  def raiseError[A](e: E): F[A]
136
  def handleErrorWith[A](fa: F[A])(f: E => F[A]): F[A]
137
  def attempt[A](fa: F[A]): F[Either[E, A]]
138
}
139

140
trait MonadError[F[_], E] extends ApplicativeError[F, E] with Monad[F] {
141
  def recover[A](fa: F[A])(pf: PartialFunction[E, A]): F[A]
142
}
143
```
144

145
[Error Handling](./error-handling.md)
146

147
### Arrow Types
148

149
Category theory abstractions for composable computations including natural transformations, categories, arrows, and profunctors that enable advanced functional programming patterns.
150

151
```scala { .api }
152
// Natural transformation between functors
153
trait FunctionK[F[_], G[_]] {
154
  def apply[A](fa: F[A]): G[A]
155
}
156

157
// Category abstraction
158
trait Category[F[_, _]] {
159
  def id[A]: F[A, A]
160
  def compose[A, B, C](f: F[B, C], g: F[A, B]): F[A, C]
161
}
162
```
163

164
[Arrow Types](./arrows.md)
165

166
### Type Class Instances
167

168
Implementations of type classes for standard Scala types including collections, Option, Either, Future, and numeric types, providing immediate access to functional abstractions.
169

170
```scala { .api }
171
// Available instances (provided automatically via cats.implicits._)
172
// List[A]: Monad[List], Traverse[List], MonoidK[List], Alternative[List]
173
// Option[A]: Monad[Option], Traverse[Option], Alternative[Option]  
174
// Either[E, A]: Monad[Either[E, ?]], Bifunctor[Either]
175
// Function1[A, B]: Monad[Function1[A, ?]], Category[Function1]
176
```
177

178
[Type Class Instances](./instances.md)