richard-gibson/cats

Cats

Overview

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

The name is a playful shortening of the word category.

Why?

Scala supports both object-oriented and functional programming, and this is reflected in the hybrid approach of the standard library. Cats augments the standard library with tools that further enable functional programming such as Validated, Monad, and Traverse. A broader goal of Cats is to provide a foundation for an ecosystem of pure, typeful libraries.

Getting Started

Cats is currently available for Scala 2.10, 2.11 and 2.12, and Scala.js.

To get started with SBT, simply add the following to your build.sbt file:

libraryDependencies += "org.typelevel" %% "cats-core" % "1.0.0-MF"

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-macros: Macros used by Cats syntax (required).
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.

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.
alleycats: cats instances and classes which are not lawful.
mouse: a small companion to cats that provides convenient syntax (aka extension methods)

Release notes for Cats are available in CHANGES.md.

Cats is still under active development. While we don't anticipate any major redesigns, changes that are neither source nor binary compatible are to be expected in upcoming cats releases. We will update the minor version of cats accordingly for such changes. Once cats 1.0 is released (ETA: Q4 2017), there will be an increased focus on making changes in compatible ways.

Enhancing type inference

To use cats you'll need sometimes support for improved type inference. To enable it for any supported Scalac version, use this sbt plugin.

Documentation

Cats information and documentation is available on the website.

We also have a Scaladoc index.

Finally, we have a list of frequently-asked questions.

Our goal is to have clear and comprehensive documentation. If you notice problems, omissions, or errors, please let us know.

The cats ecosystem

Many projects integrate with cats. By sharing the same set of type classes, instances and data types, projects can speak the same "cats language", and integrate with each other with ease.

General purpose libraries to support pure functional programming

Dogs: pure functional collections and data structures.
Kittens: automatic type class derivation for Cats and generic utility functions
eff: functional effects and effect handlers (alternative to monad transformers).
Freestyle: pure functional framework for Free and Tagless Final apps & libs.
mainecoon: Transform and compose tagless final encoded algebras
iota: Fast [co]product types with a clean syntax
origami: monadic folds
newts: Defines newtypes compatible with cats type classes.

Libraries with more specific uses

Circe: pure functional JSON library.
Fetch: efficient data access to heterogeneous data sources.
Frameless: Expressive types for Spark.
FS2: compositional, streaming I/O library
doobie: a pure functional JDBC layer for Scala
Monix: high-performance library for composing asynchronous and event-based programs.
http4s: A minimal, idiomatic Scala interface for HTTP
hammock: Purely functional HTTP client
atto: friendly little text parsers
decline: A composable command-line parser
seals: tools for schema evolution and language-integrated schemata
grafter: dependency-injection library using the Reader pattern
finch: Scala combinator library for building Finagle HTTP services
pureconfig: A boilerplate-free library for loading configuration files

Feel free to submit a PR if you want a project you maintain to be added to this list.

How can I contribute to Cats?

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.

Community

Discussion around Cats is currently happening on Github issue and PR pages as well as in two Gitter channels:

Gitter channel cats is for general user questions and discussions, and

Gitter channel cats-dev is dedicated for cats development related discussions. For people who wants to follow closely and/or to participate in the decisions in cats development, this is the room to join.

You can get an overview of who is working on what via Waffle.io.

People are expected to follow the Typelevel Code of Conduct when discussing Cats on the Github page, Gitter channel, 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.

Binary compatibility and versioning

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 maintainence 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.

Maintainers

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

ceedubs Cody Allen
rossabaker Ross Baker
johnynek P. Oscar Boykin
travisbrown Travis Brown
adelbertc Adelbert Chang
peterneyens Peter Neyens
edmundnoble Edmund Noble
tpolecat Rob Norris
stew Mike O'Connor
non Erik Osheim
mpilquist Michael Pilquist
milessabin Miles Sabin
djspiewak Daniel Spiewak
fthomas Frank Thomas
julien-truffaut Julien Truffaut
kailuowang Kailuo Wang

We are currently following a practice of requiring at least two sign-offs to merge PRs (and for large or contentious issues we may wait for more). For typos or other small fixes to documentation we relax this to a single sign-off.

Copyright and License

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.

richard-gibson / cats