typelevel/cats

Cats is a library which provides abstractions for functional programming in the Scala programming language.

Scala supports both object-oriented and functional programming, and this is reflected in the hybrid approach of the standard library. Cats strives to provide functional programming abstractions that are core, binary compatible, modular, approachable and efficient. A broader goal of Cats is to provide a foundation for an ecosystem of pure, typeful libraries to support functional programming in Scala applications.

For more detail about Cats' motivations, go here.

The name is a playful shortening of the word category, from "category theory".

Regardless, you do not need to know anything about category theory to use Cats.

This project exists thanks to all the people who contribute. We welcome contributions to Cats and would love for you to help build Cats. See our contributor guide for more information about how you can get involved as a developer. If you are looking for something to start with, here is a beginner friendly list.

Become a financial contributor and help us sustain our community. Donations directly support office hours for maintainers, better documentation and strategic initiatives.

Cats is available for Scala.js and Scala Native, as well as the standard JVM runtime.

Cats relies on improved type inference via the fix for SI-2712, which is not enabled by default. For Scala 2.12 you should add the following to your build.sbt:

scalacOptions += "-Ypartial-unification"

(Partial unification is on by default since Scala 2.13, the compiler no longer accepts -Ypartial-unification)

And then create the Cats dependency, by adding the following to your build.sbt:

libraryDependencies += "org.typelevel" %% "cats-core" % "2.9.0"

This will pull in the cats-core module. If you require some other functionality, you can pick-and-choose from amongst these modules (used in place of "cats-core"):

• cats-kernel: Small set of basic type classes (required).
• cats-core: Most core type classes and functionality (required).
• cats-laws: Laws for testing type class instances.
• cats-free: Free structures such as the free monad, and supporting type classes.
• cats-testkit: lib for writing tests for type class instances using laws.
• algebra: Type classes to represent algebraic structures.
• alleycats-core: Cats instances and classes which are not lawful.

There are several other Cats modules that are in separate repos so that they can maintain independent release cycles.

• cats-effect: standard IO type together with Sync, Async and Effect type classes
• cats-mtl: transformer typeclasses for Cats' Monads, Applicatives and Functors.
• mouse: a small companion to Cats that provides convenient syntax (aka extension methods)
• kittens: automatic type class instance derivation for Cats and generic utility functions
• cats-tagless: Utilities for tagless final encoded algebras
• cats-collections: Data structures which facilitate pure functional programming
• cats-testkit-scalatest: Cats testkit integration with Scalatest

Past release notes for Cats are available in CHANGES.md.

Links:

1. Website: typelevel.org/cats/
2. ScalaDoc: typelevel.org/cats/api/
3. Type classes: typelevel.org/cats/typeclasses.html
4. Data types: typelevel.org/cats/datatypes.html
5. Algebra overview: typelevel.org/cats/algebra.html
6. Glossary: typelevel.org/cats/nomenclature.html
7. Resources for Learners: typelevel.org/cats/resources_for_learners.html
8. FAQ: typelevel.org/cats/faq.html
9. The Typelevel Ecosystem: typelevel.org/cats/typelevelEcosystem.html

Discussion around Cats is currently happening on GitHub issues, PR pages, and Discord:

The Typelevel Discord has #cats and #cats-dev channels, as well as community channels such as #beginners. Please join us!

People are expected to follow the Scala Code of Conduct when discussing Cats on GitHub, Discord, or other venues.

We hope that our community will be respectful, helpful, and kind. If you find yourself embroiled in a situation that becomes heated, or that fails to live up to our expectations, you should disengage and contact one of the project maintainers in private. We hope to avoid letting minor aggressions and misunderstandings escalate into larger problems.

If you are being harassed, please contact one of us immediately so that we can support you.

After 1.0.0 release, we decided to use MAJOR.MINOR.PATCH Semantic Versioning 2.0.0 going forward, which is different from the EPOCH.MAJOR.MINOR scheme common among Java and Scala libraries (including the Scala lang).

Cats strives to provide a solid and stable foundation for an ecosystem of FP libraries. Thus, we treat backward binary compatibility maintenance with a high priority. In semantic versioning, backward breaking change is ONLY allowed between MAJOR versions. We will maintain backward binary compatibility between PATCH AND MINOR versions. For example, when we release Cats 1.1.0, it will be backward binary compatible with the previous 1.0.x versions. I.E. the new JAR will be a drop-in replacement for the old one. This is critical when your application has a diamond dependency on Cats - depending on two or more libraries that all depend on Cats. If one library upgrades to the new 1.1.0 Cats before the other one does, your application still runs thanks to this backward binary compatibility.

Also worth noting is that according to semantic versioning, MINOR version Y (x.Y.z | x > 0) MUST be incremented if new, backwards compatible functionality is introduced to the public API. It MUST be incremented if any public API functionality is marked as deprecated.

Any binary breaking changes will require a MAJOR version bump, which we will be very cautious about. We will also consider using organization and package name for major versioning in the future. But that decision is yet to be made.

A (non-exhaustive) list of companies that use Cats in production is featured in ADOPTERS.md. Don't see yours? You can add it in a PR! And if you can, consider supporting us.

The current maintainers (people who can merge pull requests) are:

• rossabaker Ross Baker
• armanbilge Arman Bilge
• johnynek P. Oscar Boykin
• adelbertc Adelbert Chang
• danicheg Daniel Esik
• LukaJCB Luka Jacobowitz
• peterneyens Peter Neyens
• tpolecat Rob Norris
• non Erik Osheim
• barambani Filippo Mariotti
• mpilquist Michael Pilquist
• milessabin Miles Sabin
• djspiewak Daniel Spiewak
• fthomas Frank Thomas
• satorg Sergey Torgashov
• julien-truffaut Julien Truffaut
• kailuowang Kailuo Wang

Retired committers include:

• ceedubs Cody Allen
• travisbrown Travis Brown

We are currently following a practice of requiring at least two sign-offs to merge code PRs (and for large or contentious issues we may wait for more). For typos, documentation improvements or minor build fix we relax this to a single sign-off. More detail in the process document.

All code is available to you under the MIT license, available at http://opensource.org/licenses/mit-license.php and also in the COPYING file. The design is informed by many other projects, in particular Scalaz.

Copyright the maintainers, 2015-2023.