Cats MTL Typed Errors (Scala)

Quick start

• Define a domain error type; it may or may not extend Throwable depending on context.
• Use Cats MTL Raise[F, E] in functions that can raise errors.
• Use Handle.allow/rescue (Scala 3) or Handle.allowF (Scala 2) to introduce a scoped error capability and handle it like try/catch.
• Prefer Cats MTL over IO[Either[E, A]] and avoid EitherT[IO, E, A]; pure functions returning Either[E, A] are fine at API boundaries.
• F[_] is optional: you can write IO-specific code or keep F[_] for polymorphism, depending on the project.

Workflow

1. Model domain errors as sealed ADTs (Scala 2) or enums (Scala 3)
2. For effectful code that can raise errors, require Raise[F, E] (and Monad[F] or Applicative[F]).
3. Raise errors with .raise and return successful values with pure.
4. At a boundary, use Handle.allow (Scala 3) or Handle.allowF (Scala 2) to create a scope where raises are valid.
5. Close the scope with .rescue to handle each error case explicitly.
6. Keep Cats Effect resource and concurrency semantics intact by staying in the monofunctor error channel.

Patterns to apply

• Typed errors in signatures: treat the error type parameter E as the checked-exception channel in the function signature.