0
# Cats Core
1

2
Cats-core provides essential functional programming abstractions for Scala, serving as the foundation of the Cats ecosystem. It offers a comprehensive collection of type classes, data types, syntax extensions, and instances that enable developers to write pure, composable, and type-safe functional code.
3

4
## Package Information
5

6
- **Package Name**: cats-core_sjs0.6_2.11
7
- **Package Type**: maven
8
- **Organization**: org.typelevel
9
- **Language**: Scala 2.11 (Scala.js 0.6 build)
10
- **Installation**: `libraryDependencies += "org.typelevel" %%% "cats-core" % "2.0.0"`
11

12
## Core Imports
13

14
The most common import brings all syntax and instances into scope:
15

16
```scala
17
import cats._
18
import cats.implicits._
19
```
20

21
Selective imports for specific functionality:
22

23
```scala
24
import cats.{Functor, Applicative, Monad}
25
import cats.data.{Validated, NonEmptyList, Chain}
26
import cats.syntax.functor._
27
import cats.syntax.applicative._
28
```
29

30
## Basic Usage
31

32
```scala
33
import cats._
34
import cats.implicits._
35
import cats.data._
36

37
// Using type classes with syntax
38
val numbers = List(1, 2, 3)
39
val doubled = numbers.map(_ * 2)  // Using Functor syntax
40

41
// Working with validated data
42
val valid1: Validated[String, Int] = Validated.valid(42)
43
val valid2: Validated[String, Int] = Validated.valid(10)
44
val combined = (valid1, valid2).mapN(_ + _)  // Using Applicative syntax
45

46
// Non-empty collections
47
val nel = NonEmptyList.of(1, 2, 3, 4)
48
val sum = nel.reduce  // Safe reduction without empty case
49

50
// Monad transformers for composing effects
51
val result: OptionT[List, Int] = for {
52
  x <- OptionT.liftF(List(1, 2, 3))
53
  y <- OptionT.pure[List](10)
54
} yield x + y
55
```
56

57
## Architecture
58

59
Cats-core is built around several key architectural concepts:
60

61
- **Type Class Hierarchy**: A carefully designed hierarchy of abstract type classes (Functor, Applicative, Monad, etc.) that provide increasing levels of power
62
- **Data Types**: Concrete implementations of common functional programming patterns (Validated, Chain, NonEmptyList, etc.)
63
- **Syntax Extensions**: Implicit conversions that add methods to existing types for enhanced ergonomics
64
- **Instances**: Type class implementations for standard library types and cats data types
65
- **Composability**: All abstractions are designed to compose naturally with each other
66

67
## Capabilities
68

69
### Type Class Abstractions
70

71
Core abstractions that form the foundation of functional programming patterns.
72

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

79
// Applicative - pure and apply operations  
80
trait Applicative[F[_]] extends Functor[F] {
81
  def pure[A](x: A): F[A]
82
  def ap[A, B](ff: F[A => B])(fa: F[A]): F[B]
83
}
84

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

92
[Type Class Abstractions](./type-classes.md)
93

94
### Data Types and Structures
95

96
Functional data types that provide safety guarantees and composable operations.
97

98
```scala { .api }
99
// Validated - accumulating validation  
100
sealed abstract class Validated[+E, +A]
101
case class Valid[A](a: A) extends Validated[Nothing, A]
102
case class Invalid[E](e: E) extends Validated[E, Nothing]
103

104
// NonEmptyList - guaranteed non-empty list
105
final case class NonEmptyList[+A](head: A, tail: List[A])
106

107
// Chain - efficient sequence with O(1) append
108
sealed abstract class Chain[+A]
109
```
110

111
[Data Types and Structures](./data-types.md)
112

113
### Monad Transformers
114

115
Composable monadic effects that allow stacking of different effect types.
116

117
```scala { .api }
118
// EitherT - Either over any monad
119
final case class EitherT[F[_], A, B](value: F[Either[A, B]])
120

121
// OptionT - Option over any monad  
122
final case class OptionT[F[_], A](value: F[Option[A]])
123

124
// Kleisli - function composition in monadic context
125
final case class Kleisli[F[_], A, B](run: A => F[B])
126
```
127

128
[Monad Transformers](./monad-transformers.md)
129

130
### Syntax Extensions
131

132
Implicit syntax that enhances existing types with functional programming operations.
133

134
```scala { .api }
135
// Enhanced operations available through implicits
136
implicit class FunctorOps[F[_], A](fa: F[A])(implicit F: Functor[F]) {
137
  def map[B](f: A => B): F[B] = F.map(fa)(f)
138
  def void: F[Unit] = F.void(fa)
139
  def as[B](b: B): F[B] = F.as(fa, b)
140
}
141

142
implicit class ApplicativeOps[A](a: A) {
143
  def pure[F[_]](implicit F: Applicative[F]): F[A] = F.pure(a)
144
}
145
```
146

147
[Syntax Extensions](./syntax.md)
148

149
### Type Class Instances
150

151
Pre-defined implementations of type classes for standard library types.
152

153
```scala { .api }
154
// Available instances (imported via cats.implicits._)
155
implicit val optionMonad: Monad[Option]
156
implicit val listMonad: Monad[List]  
157
implicit val eitherMonad[E]: Monad[Either[E, *]]
158
implicit val function1Monad[A]: Monad[Function1[A, *]]
159
```
160

161
[Type Class Instances](./instances.md)
162

163
## Package Exports
164

165
Core type aliases and re-exports available from the cats package:
166

167
```scala { .api }
168
// Identity and function types
169
type Id[A] = A
170
type Endo[A] = A => A
171
type ~>[F[_], G[_]] = arrow.FunctionK[F, G]
172

173
// Kernel re-exports
174
type Eq[A] = cats.kernel.Eq[A]
175
type Order[A] = cats.kernel.Order[A]  
176
type Semigroup[A] = cats.kernel.Semigroup[A]
177
type Monoid[A] = cats.kernel.Monoid[A]
178
```