cats-mtl Design

Overall, cats-mtl has similar design to cats: instances package, syntax package, implicits package.

There's also a hierarchy package, because cats-mtl uses a different typeclass encoding than cats to avoid implicit ambiguity.

The problem looks like this:

import cats._

type Err
type Log

def f[F[_]: MonadError[?, Err]: MonadWriter[?, Log]]: Unit = {
      // implicitly[Monad[F]] // ambiguity between derived monads from MonadError and MonadWriter
      // 1.pure[F].flatMap(_ => 1.raise) // same ambiguity affects MonadSyntax
      ()
}

The cause is that the implicit conversions MonadError[F, Err] => Monad[F] and MonadWriter[F, Log] => Monad[F] are the same priority. If those conversions were different priorities, the issue would be fixed, and that's exactly what cats-mtl's encoding does.

Similarly to the Scato project, instead of inheritance the transformer classes in cats-mtl use aggregation. Mtl classes thus contain instances of their superclasses.

Motivation

The motivation for cats-mtl's existence can be summed up in a few points:

• using subtyping to express typeclass subclassing results in implicit ambiguities, and doing it another way would result in a massive inconsistency inside cats if only done for MTL classes. for a detailed explanation, see Adelbert Chang's article here.
• most MTL classes do not actually require Monad as a constraint for their laws. cats-mtl weakens this constraint to Functor or Applicative whenever possible, with the result that there's now a notion of a Functor transformer stack and Applicative transformer stack in addition to that of a Monad transformer stack.
• the most used operations on MonadWriter and MonadReader are tell and ask, and the other operations severely restrict the space of implementations despite being used much less. To fix this Listen and Local are subclasses of Tell and Ask, which have only the essentials.

The first point there means that it's impossible for cats-mtl type classes to expose their base class instances implicitly; for example F[_]: Stateful[?[_], S] isn't enough for a Monad[F] to be visible in implicit scope, despite Stateful containing a Monad instance as a member. The root cause here is that prioritizing implicit conversions with subtyping explicitly can't work with cats and cats-mtl separate, as the Monad[F] instance for the type from cats will always conflict with a derived instance.

Thus F[_]: Stateful[?[_], S], translated, becomes F[_]: Monad: Stateful[?[_], S].

For some historical info on the origins of cats-mtl, see:

https://github.com/typelevel/cats/issues/1210

https://github.com/typelevel/cats/pull/1379

https://github.com/typelevel/cats/pull/1751

Laws

Type class laws come in a few varieties in cats-mtl: internal, external, and free.

Internal laws dictate how multiple operations inter-relate. One side of the equation can always be reduced to a single function application of an operation. These express "default" implementations that should be indistinguishable in result from the actual implementation.

External laws are laws that still need to be tested but don't fall into the internal laws.

Free laws are (in theory) unnecessary to test, because they are implied by other laws and the types of the operations in question. There will usually be rudimentary proofs or some justification attached to make sure these aren't just made up.