Documentation refresh for monad transformers by reardonj · Pull Request #4724 · typelevel/cats

reardonj · 2025-03-04T02:22:08Z

This PR came out of a discussion in the Typelevel discord with @djspiewak and @armanbilge regarding unexpected interactions with monad transformers and Cats Effect.

This PR moves around monad transformer documentation to better reflect that it is a more advanced topic:

updates the monad transformer documentation
- to move the overview to a separate section instead of the jump start guide
- change uses of Future to Try to avoid suggesting developers use the deprecated Future instances
- add a Pitfalls section to warn users about unfortunate interactions with CE and direct users to Cats MTL as an alternative.
moves the Monad Transformer documentation pages out of Data Types to their own section.

I also made a few related changes for consistency:

remove the pointless Datatypes index pages that just listed all the datatype page links
move the Typeclass page to and Overview page under the Typeclasses section.
fix a broken link in guidelines.md

valencik

NICE!!! 🎉
Thanks so much for putting in this effort, I'm really excited about it.

I think this is a good organizational change, I like the reduced Future usage, and less transformers in the return types.
I think we can go a little bit further calling out the pitfalls. Namely, let's repeat them on their respective transformer pages.
And let's call out the return types advice more prominently.

valencik · 2025-03-04T12:37:36Z


 `Either` can be used for error handling in most situations. However, when
-`Either` is placed into effectful types such as `Option` or`Future`, a large
+`Either` is placed into effectful types such as `Option`, a large


There's still an example using Future below this, but I think if we change that it should happen in another PR.

Ya. Examples are awkward since one of the big motivations is IO, but we can't depend on CE here.

valencik · 2025-03-04T12:50:46Z

+The above `map` will return a value of type `OptionT[Try, String]`.
+
+To get the underlying `Try[Option[String]]` value, simply call `.value` on the `OptionT` instance.
+In practice, you should not include monad transformers in function signatures, and only use them as locally-scoped utilities to reduce boilerplate so that calling code is not required to care about the composition.


This sentence is kind of buried here, but I think it was a key point of the recent discussion about transformers.
Can we perhaps highlight this in a section of its own?

valencik · 2025-03-04T12:55:14Z

+class Account { /* ... */ }
+class Money { /* ... */ }
+
+def findUserById(userId: Long): Try[Option[User]] = { /* ... */ ??? }


Just want to note that these have changed from
OptionT[Future, User] to Try[Option[User]]

I think this is a good improvement if we're trying to recommend that folks don't use transformers in return types.

valencik · 2025-03-04T13:13:32Z

+While powerful, this can lead to unwieldy type signatures and poor type inference. 
+The [Cats MTL](https://typelevel.org/cats-mtl/) project provides a capability based approach to extend effect types without requiring as much boilerplate.
+
+Some monad transformers can also interact poorly with more powerful effect types that provide concurrent computation, such as Cats Effect's `IO` or fs2's `Stream`. You should avoid `StateT` and `WriterT` and use the concurrent data types provided by those libraries instead. Because `IO` already provides its own error channel, `EitherT[IO, Throwable]` can also lead to confusing behavior; prefer `IO`'s own error channel instead.


I think this warning should definitely be repeated on the EitherT, StateT, and WriterT, pages.

Thanks for the screenshots.
I think these are good.
The warning on EitherT is a little too up top front and center, but I don't think that's a blocker.

I couldn't identify a nice place to put that one, EitherT doesn't have a convenient intro like the other ones.

- add warnings to specific transformer pages - call out recommended usage more specifically - add CE link

valencik · 2025-03-08T22:48:05Z

To minimize these pitfalls, monad transformers should only be used as locally-scoped utilities to reduce boilerplate.
Do not include monad transformers in public method signatures.
Calling code can always use monad transformers themselves.

@typelevel/cats Anyone strongly disagree with this advice?

This PR has a somewhat large diff, but the focus of it is calling out this often repeated advice (and less examples with Future, and calling out more gotchas).

valencik · 2025-03-08T22:49:44Z

I should perhaps note, "strongly disagree" isn't the only option 😆
Adding more nuance is totally good too!

lenguyenthanh

some nit about using * import instead of _ import

reardonj · 2026-07-21T00:11:13Z

@valencik , I completely forgot this PR existed. Any chance we can get it merged?

reardonj · 2026-07-29T15:16:25Z

Any @typelevel/cats maintainers able to review this? The subject came up again in ⁠Discord yesterday and it would be really nice to have documentation to point at.

djspiewak

I'm on the fence because this is definitely an improvement over what's there, but it stops short of a more full rewrite (understandably!) and so the effect is kind of mixed. We still have holdover phrases like "in production, you'll often use such and such" when in reality people shouldn't be using this stuff in production 99% of the time.

reardonj · 2026-07-29T15:45:52Z

We still have holdover phrases like "in production, you'll often use such and such" when in reality people shouldn't be using this stuff in production 99% of the time.

…ya, I didn't want to get into the argument of whether people should even use this stuff. But just taking it out of the getting started guide will hopefully help there.

valencik reviewed Mar 4, 2025

View reviewed changes

johnynek mentioned this pull request Mar 4, 2025

Monad Transformer typeclass #4727

Open

reardonj added 2 commits March 4, 2025 21:38

extract monad transformers to their own section

c298cea

Clean up index headers

9264f63

reardonj force-pushed the documentation-refresh-monad-transformers branch from 518bcd6 to 9264f63 Compare March 5, 2025 03:10

Address review comments

b8a8984

- add warnings to specific transformer pages - call out recommended usage more specifically - add CE link

lenguyenthanh suggested changes Mar 9, 2025

View reviewed changes

Comment thread docs/imports.md

djspiewak approved these changes Jul 29, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

reardonj commented Mar 4, 2025

Uh oh!

valencik left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

valencik commented Mar 8, 2025

Uh oh!

valencik commented Mar 8, 2025

Uh oh!

lenguyenthanh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

reardonj commented Jul 21, 2026

Uh oh!

reardonj commented Jul 29, 2026

Uh oh!

djspiewak left a comment

Choose a reason for hiding this comment

Uh oh!

reardonj commented Jul 29, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants