https://github.com/ivanbakel/ytl
Yesod Transformer Library - MTL for site stacks
https://github.com/ivanbakel/ytl
mtl site-transformers yesod
Last synced: 8 months ago
JSON representation
Yesod Transformer Library - MTL for site stacks
- Host: GitHub
- URL: https://github.com/ivanbakel/ytl
- Owner: ivanbakel
- License: bsd-3-clause
- Created: 2020-12-24T22:49:08.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2020-12-29T12:59:00.000Z (over 5 years ago)
- Last Synced: 2025-10-21T13:50:05.384Z (8 months ago)
- Topics: mtl, site-transformers, yesod
- Language: Haskell
- Homepage:
- Size: 15.6 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ytl - Yesod Transformer Library
[Yesod](https://github.com/yesodweb/yesod) is a powerful, type-safe webserver library. At its core, Yesod lets you describe *foundation sites* which carry the configuration of your webserver, and *handlers* and *widgets* which use that foundation to handle requests, generate HTML and CSS, and even access a database.
Haskellers who are familiar with [mtl](https://github.com/haskell/mtl) are used to transforming monad stacks, adding or computing monadic features at whim, to introduce wide-ranging effects to a program with a few small, type-safe changes. Unfortunately, Yesod does not support monad transformers - its basic `HandlerFor` and `WidgetFor` monads are woven into the server code, and won't allow for other monads to stack on top.
However, a `mtl`-style approach can be done for Yesod - the secret is, rather than transforming Yesod's `HandlerFor` and `WidgetFor` monads, to *transform the foundation site itself*. The result is `ytl` - the Yesod transfomer library, which exports a similar API to `mtl`, but in terms of site transformers.
A site transformer wraps a Yesod foundation site in additional information. Yesod's code is fine with custom foundation types, so the wrapped site can be used in Yesod code as normal - giving additional effects to existing Yesod code for "free".
## An example
The `ReaderSite` transformer adds additional data to a site, similar to how `ReaderT` adds data to a monad stack. The data accessible by `ReaderSite` can be accessed through a `MonadReader`-style API in Yesod's `HandlerFor` and `WidgetFor` monads - like this:
```haskell
useValue
:: (SiteReader r site)
=> HandlerFor site a
-> (r -> m site b)
-> HandlerFor site (a, b)
useValue mArg f = do
a <- mArg
r <- ask
b <- f r
pure (a, b)
```
## Writing your own transformers
Writing your own `ytl` site transformers is relatively simple. Define your site wrapper, and some class for its API - in the above example, `ReaderSite` is the wrapper, and `SiteReader` is the API class.
Implement the class for the wrapper (duh!). Then, to interact nicely with the other transformers, you'll want to define a lifting instance, which lifts the API implementation through any transformer layers. For `ReaderSite`, this looks like
```haskell
instance {-# OVERLAPPABLE #-}
(SiteTrans t, SiteReader r site) => SiteReader r (t site) where
...
```
### Implement `RenderRoute`, and maybe `Yesod`
You'll also need to implement `RenderRoute` for your wrapped site type - make sure to make the route type coercible to the route type of the base site, because `ytl` relies on them being representation-identical (see `SiteCompatible`)! This is normally fine, because you don't want to modify the routes anyways.
If your site transformer changes some `Yesod` behaviour - like logging, middleware, etc. - you need to also implement `Yesod` for your wrapped site type. `ytl` comes with some Template Haskell helpers for writing `Yesod` implementations that pass through to the base site most of the time; so if you just want to override how logging works, you can ignore the other `Yesod` methods and they'll be implemented for you.
### Why isn't my translation of this mtl type working?
Remember that, in Yesod's handlers and widgets, the site is in *reader* position - it gets passed into Yesod functions. That means that the site type is basically contravariant (as evidenced by `withSiteT`) - so `HandlerFor` and `WidgetFor` are an awful lot like profunctors. That means that you can't translate `mtl`-style code directly - you have to consider the difference in data flow.
For example, `ReaderSite` is not an exact copy of `ReaderT`: `ReaderT` takes the read value as an argument:
```
data ReaderT m a = ReaderT (r -> m a)
```
But for Yesod, the site is already in reader position - taking `r` as an argument wouldn't have the right semantics. Instead, `ReaderSite` includes `r` *alongside* the site:
```
data ReaderSite r site = ReaderSite r site
```
That looks very different. However, they end up being very similar in use:
```haskell
runReaderT :: ReaderT r m a -> r -> m a
runReaderSite :: HandlerFor (ReaderSite r site) a -> r -> HandlerFor site a
```