Cats Effect
Cats Effect is a high-performance, asynchronous, composable framework for building real-world applications in a purely functional style within the Typelevel ecosystem. It provides a concrete tool, known as "the IO
monad", for capturing and controlling actions, often referred to as "effects", that your program wishes to perform within a resource-safe, typed context with seamless support for concurrency and coordination. These effects may be asynchronous (callback-driven) or synchronous (directly returning values); they may return within microseconds or run infinitely.
Even more importantly, Cats Effect defines a set of typeclasses which define what it means to be a purely functional runtime system. These abstractions power a thriving ecosystem consisting of streaming frameworks, JDBC database layers, HTTP servers and clients, asynchronous clients for systems like Redis and MongoDB, and so much more! Additionally, you can leverage these abstractions within your own application to unlock powerful capabilities with little-or-no code changes, for example solving problems such as dependency injection, multiple error channels, shared state across modules, tracing, and more.
Usage
Versions of Cats Effect:
- Stable:
2.2.0
See compatibility and versioning for more information on our compatibility and semantic versioning policies.
libraryDependencies += "org.typelevel" %% "cats-effect" % "2.2.0"
Cats Effect relies on improved type inference and needs partial unification enabled as described in the Cats Getting Started documentation.
If your project uses Scala.js, replace the double-%
with a triple. Note that cats-effect has an upstream dependency on cats-core version 2.x.
Cross-builds are available for Scala 2.12.x and 2.13.x, with Scala.js builds targeting 1.x (note that, prior to 2.2.0, Cats Effect was available for Scala.js 0.6).
The most current snapshot (or major release) can be found in the maven badge at the top of this readme. If you are a very brave sort, you are free to depend on snapshots; they are stable versions, as they are derived from the git hash rather than an unstable -SNAPSHOT
suffix, but they do not come with any particular confidence or compatibility guarantees.
Please see this document for information on how to cryptographically verify the integrity of cats-effect releases. You should absolutely be doing this! It takes five minutes and eliminates the need to trust a third-party with your classpath.
Laws
The cats-effect-laws artifact provides Discipline-style laws for the Sync
, Async
, Concurrent
, Effect
and ConcurrentEffect
typeclasses (LiftIO
is lawless, but highly parametric). It is relatively easy to use these laws to test your own implementations of these typeclasses. Take a look here for more.
libraryDependencies += "org.typelevel" %% "cats-effect-laws" % "2.2.0" % "test"
These laws are compatible with both Specs2 and ScalaTest.
Documentation
Links:
- Website: typelevel.org/cats-effect/
- ScalaDoc: typelevel.org/cats-effect/api/
Related Cats links (the core):
- Website: typelevel.org/cats/
- ScalaDoc: typelevel.org/cats/api/
Libraries
These are some well known libraries that depend on cats-effect
:
Project | Description |
---|---|
Ciris | Lightweight, extensible, and validated configuration loading in Scala |
Doobie | A principled JDBC layer for Scala |
Eff | Extensible Effects for Scala |
Fs2 | Functional Streams for Scala (Streaming I/O library) |
Finch | Scala combinator API for building Finagle HTTP services |
Http4s | Typeful, functional, streaming HTTP for Scala |
Monix / Monix BIO | Asynchronous, Reactive Programming for Scala and Scala.js |
Pure Config | A boilerplate-free library for loading configuration files |
Scala Cache | A facade for the most popular cache implementations for Scala |
Sttp | The Scala HTTP client you always wanted |
Related Projects
These are some of the projects that provide high-level functions on top of cats-effect
:
Project | Description |
---|---|
Cats Retry | A library for retrying actions that can fail |
Console4cats | Console I/O for Cats Effect |
Fuuid | Functional UUID's |
Linebacker | Thread Pool Management for Scala: Enabling functional blocking where needed |
Log4cats | Functional Logging |
Cats STM | Software Transactional Memory for Cats Effect |
Mau | A tiny library for an auto polling Ref |
Odin | Fast & Functional logger with own logging backend |
cats-effect-testing | Experimental integration between cats-effect and testing frameworks |
graphite4s | lightweight graphite client |
Development
We use the standard pull request driven github workflow. Pull requests are always welcome, even if it's for something as minor as a whitespace tweak! If you're a maintainer, you are expected to do your work in pull requests, rather than pushing directly to the main branch. Ideally, someone other than yourself will merge your PR. However, if you've received at least one explicit 👍 from another maintainer (or significant volume of 👍 from the general Cats community), you may merge your own PR in the interest of moving forward with important efforts. Please don't abuse this policy.
Do not rebase commits that have been PR'd! That history doesn't belong to you anymore, and it is not yours to rewrite. This goes for maintainers and contributors alike. Rebasing locally is completely fine (and encouraged), since linear history is pretty and checkpoint commits are not. Just don't rebase something that's already out there unless you've explicitly marked it as a work in progress (e.g. [WIP]
) in some clear and unambiguous way.
cats-effect is a Typelevel project. This means we embrace pure, typeful, functional programming, and provide a safe and friendly environment for teaching, learning, and contributing as described in the Code of Conduct.
Contributing documentation
The sources for the cats-effect microsite can be found in site/src/main/mdoc
.
The menu structure is in site/src/main/resources/microsite/data/menu.yml
.
You can build the microsite with sbt microsite/makeMicrosite
.
To preview your changes you need to have
jekyll installed. This depends on your
platform, but assuming you have ruby installed it could be as simple as gem install jekyll jekyll-relative-links sass
. Alternatively, you can use the provided
Gemfile under site
to install jekyll
and the required plugins.
Start a local server by navigating to site/target/site
, then run jekyll serve -b /cats-effect
. Finally point your browser at
http://localhost:4000/cats-effect/. Any
changes should be picked up immediately when you re-run sbt microsite/makeMicrosite
.
Tool Sponsorship
Development of Cats Effect is generously supported in part by YourKit through the use of their excellent Java profiler.
License
Copyright (c) 2017-2019 The Typelevel Cats-effect Project Developers
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.