In this article we’ll focus on building our own monad transformers.
We’ll start out with an example code and improve it by building a simple
wrapper over `IO (Maybe a)`

.

The following example is really simple, but I’m sure you can imagine
doing something similar in your own application. The `findById`

method
is there just to simulate a database query that might not find a result.

```
data User = User deriving Show
findById :: Int -> IO (Maybe User)
findById 1 = return $ Just User
findById _ = return Nothing
findUsers :: Int -> Int -> IO (Maybe (User, User))
findUsers x y = do
muser1 <- findById x
case muser1 of
Nothing -> return Nothing
Just user1 -> do
muser2 <- findById y
case muser2 of
Nothing -> return Nothing
Just user2 -> do
return $ Just (user1, user2)
```

While there’s nothing bad about `case`

statements with pattern matching
I’m sure we can all agree that this approach can easily blow out of
proportions.

One solution that won’t work all the time might be to fetch both of the users
at the same time, which would allow us to make use of the `Maybe`

monad. If our
`findById`

function didn’t do any side effects, we could’ve written this.

```
findById :: Int -> Maybe User
findById 1 = Just User
findById _ = Nothing
loadUsers :: Maybe (User, User)
loadUsers = do
user1 <- findById 1
user2 <- findById 2
return (user1, user2)
```

Because `Maybe`

is implemented in a way that it stops evaluating when it hits
on `Nothing`

we get the behavior we intended without pattern matching. If one of
our `findById`

fails to return a user, the whole function will return a
`Nothing`

.

Unfortunately the act of finding a user needs to reach out to the real world,
which forces the `IO`

monad upon us, making this approach impossible. We
somehow need to be able to teach `IO`

the notion of failure.

## Wrapping `IO`

in `MaybeIO`

Let’s introduce a new monad which will simply wrap our `IO`

computations into a
`Maybe`

.

```
data MaybeIO a = MaybeIO { runMaybeIO :: IO (Maybe a) }
```

The next step is to make `MaybeIO`

into a `Monad`

, which will allow us to use
it inside a `do`

block, but first things first. The next version of GHC (7.10)
will require every `Monad`

to also be an `Applicative`

, which also means that
every `Monad`

must be a `Functor`

. We’ll follow this an start out with a
`Functor`

instance.

```
instance Functor MaybeIO where
fmap f m = undefined
```

We’ll use type holes to hint us in while implementing these instances. First
let’s recap the type of `fmap`

, which is `(a -> b) -> f a -> f b`

, which means
we have a function `f :: a -> b`

and a functor value `m :: f a`

, or
specifically `m :: MaybeIO a`

.

Before we can do anything to the `m`

we need to unwrap `MaybeIO`

to get to the
insides. We’ll use pattern matching to do that since it’s more concise
than using `runMaybeIO`

.

```
instance Functor MaybeIO where
fmap f (MaybeIO m) = undefined
```

We only have two things available to us, the function `f :: a -> b`

which only works on the type `a`

, and the fact that both `Maybe`

and
`IO`

are also `Functor`

instances, which means we can use `fmap`

to
reach deep into the `Maybe (IO a)`

to apply our function `f`

to get the
result.

Here comes a little trick, since `fmap`

can also be thought of as `(a -> b) -> (f a -> f b)`

. If we compose `fmap`

with `fmap`

, it gives us exactly what we
need, a way to reach two functors deep to apply a function.

```
λ> :t fmap.fmap
:: (Functor f, Functor g) => (a -> b) -> f (g a) -> f (g b)
```

Substituting our types we get the following.

```
fmap.fmap :: (a -> b) -> (IO (Maybe a) -> IO (Maybe b))
```

We are not there quite yet, let’s see what happens if we use this
approach to implement the `Functor`

instance.

```
instance Functor MaybeIO where
fmap f (MaybeIO m) = (fmap.fmap) f m
-- Couldn't match type ‘Maybe’ with ‘MaybeIO’
```

We’re returning the wrong type! The original value passed in was `MaybeIO a`

and we’re returning `IO (Maybe b)`

instead of `MaybeIO b`

. Let’s add a type
hole to make this crystal clear.

```
instance Functor MaybeIO where
fmap f (MaybeIO m) = _ $ (fmap.fmap) f m
-- Found hole ‘_’ with type: Maybe (IO b) -> MaybeIO b
```

Now remember how in the beginning we said we’ll be wrapping the `IO (Maybe a)`

into a `MaybeIO`

? We can do that using the constructor of `MaybeIO`

!

```
instance Functor MaybeIO where
fmap f (MaybeIO m) = MaybeIO $ (fmap.fmap) f m
```

There you go, a `Functor`

instance for `MaybeIO`

.

`Applicative`

instance for `MaybeIO`

The next step is to implement an `Applicative`

instance for our `MaybeIO`

wrapper. Here’s how the `Applicative`

class looks in case you forgot.

```
class Applicative m where
pure :: a -> m a
(<*>) :: m (a -> b) -> m a -> m b
```

In terms of our `MaybeIO`

the types would look as following.

```
pure :: a -> MaybeIO a
(<*>) :: MaybeIO (a -> b) -> MaybeIO a -> MaybeIO b
```

Implementing `pure`

is simple, we just need to wrap a given value into a
minimal context. Since both `Maybe`

and `IO`

are an instance of `Applicative`

,
we can use their `pure`

much as we used `fmap`

when implementing the `Functor instance`

(don’t forget to import `Control.Applicative`

.)

```
instance Applicative MaybeIO where
pure = MaybeIO . pure . pure
```

We could’ve also written this more explicitly using `Just`

instead of `pure`

for wrapping the value in a `Maybe`

.

```
instance Applicative MaybeIO where
pure = MaybeIO . pure . Just
```

But moving on, now comes the hard part, implementing `<*>`

. This is probably
the hardest part of the whole article, so don’t worry if it seems a bit
complicated. First we need to pattern match to get rid of the `MaybeIO`

wrapper, and then we also need to wrap the value on the right hand side in the
last step.

```
instance Applicative MaybeIO where
pure = MaybeIO . pure . Just
MaybeIO f <*> MaybeIO m = MaybeIO $ _
-- Found hole ‘_’ with type: IO (Maybe b)
```

The type hole tells us that we need to somehow get to a `IO (Maybe b)`

with the
given `IO (Maybe (a -> b))`

and `IO (Maybe a)`

. This seems like a typical
*reach into a box/context and apply a function* kind of problem, and it is, but
we do need to do something which isn’t so apparent at first.

Both `Maybe`

and `IO`

are an instance of `Applicative`

, which means we need to
somehow use `<*>`

to apply the boxed function to the boxed value (pardon me for
saying boxed here, but it just seems like the right analogy here.)

The problem is that we can only use `<*>`

to apply a function nested one level
deep, since the type is `m (a -> b) -> m a -> m b`

. Knowing that `<*>`

is a two
argument function, meaning we can’t use simple `.`

, we need to look into the
documentation for `Applicative`

and find the function `liftA2`

, works just like
`fmap`

on functors, but for two argument functions.

```
λ> :t liftA2
:: Applicative f => (a -> b -> c) -> f a -> f b -> f c
```

If we combine these two together we do get exactly what we need, a function which takes two arguments, where first one is a function nested in two applicatives, and a value, and applies the function to that value.

```
λ> :t liftA2 (<*>)
:: (Applicative f, Applicative g) =>
f (g (a -> b)) -> f (g a) -> f (g b)
```

Let’s substitute our types once again to see how this exactly matches to what we need.

```
liftA2 (<*>)
:: IO (Maybe (a -> b)) -> IO (Maybe a) -> IO (Maybe b)
```

We already have both of the arguments of the correct types, which means we can just apply the function to them and get our instance.

```
instance Applicative MaybeIO where
pure = MaybeIO . pure . Just
MaybeIO f <*> MaybeIO m = MaybeIO $ liftA2 (<*>) f m
```

In the next step we’ll move onto implementing the `Monad`

instance. Make sure
you understand what we’ve done so far.

`Monad`

instance for `MaybeIO`

Now comes the final step that we’ve been waiting for, implementing a `Monad`

instance for our `MaybeIO`

wrapper. As we did before, here’s how the `Monad`

class looks.

```
class Monad m where
return :: a -> m a
(>>=) :: m a -> (a -> m b) -> m b
```

We can already see that `return`

will be exactly the same as `pure`

for our
`Applicative`

, so let’s do that first.

```
instance Monad MaybeIO where
return = pure
```

Next comes the implementation of `>>=`

or *bind*. First the initial structure

```
instance Monad MaybeIO where
return = pure
MaybeIO m >>= f = MaybeIO $ _
```

We have a value of type `m :: IO (Maybe a)`

and a function that we need to
apply to the inner `a`

which has a type `f :: a -> MaybeIO b`

. We can use `>>=`

to get to the value inside the `IO`

monad.

```
instance Monad MaybeIO where
return = pure
MaybeIO m >>= f = MaybeIO $ m >>= \x -> _
```

This leaves us with `x :: Maybe a`

, which is just one pattern match away from
the final solution.

```
instance Monad MaybeIO where
return = pure
MaybeIO m >>= f = MaybeIO $ m >>= \x -> case x of
Nothing -> return $ Nothing
Just val -> runMaybeIO $ f val
```

A very important thing to note here is that in the case of `Just val`

we
need to unwrap the `MaybeIO`

using `runMaybeIO`

. One might think that we
could instead write it like this.

```
instance Monad MaybeIO where
return = pure
MaybeIO m >>= f = m >>= \x -> case x of
Nothing -> MaybeIO $ return $ Nothing
Just val -> f val
-- Couldn't match type ‘IO’ with ‘MaybeIO’
```

The problem here is that `m >>= \x -> ...`

must have a return value of
`IO`

, but we’re trying to return `MaybeIO`

. This is why we need to
unwrap the result of `f val`

and then wrap it again after doing `>>=`

,
as we did in the previous example.

## Using `MaybeIO`

to cleanup our initial example

We manage to build ourselves a monad which combines the effects of `IO`

and
`Maybe`

together, which means we can use it to represent `IO`

computations
which can fail. This is perfect for our initial example which uses `findById :: Int -> IO (Maybe User)`

.

Since the type of our computation is `MaybeIO`

we need to wrap the `findById`

function to make use of the monad instance for `MaybeIO`

.

```
smartFindUsers :: Int -> Int -> MaybeIO (User, User)
smartFindUsers x y = do
user1 <- MaybeIO $ findById x
user2 <- MaybeIO $ findById y
return (user1, user2)
```

We can even go one step further and keep the original return value of
`findUsers`

`IO (Maybe (User, User))`

by unwrapping the `MaybeIO`

.

```
smartFindUsers :: Int -> Int -> IO (Maybe (User, User))
smartFindUsers x y = runMaybeIO $ do
user1 <- MaybeIO $ findById x
user2 <- MaybeIO $ findById y
return (user1, user2)
```

Now let’s go ahead and test this in GHCi to make sure we didn’t break anything.

```
λ> smartFindUsers 1 1
Just (User,User)
```

Our new version works exactly the same as the old one, but without the necessary error handling boilerplate. Much like monads allow you to capture control flow patterns, you can use monad transformers to add additional control flow to your existing monads without sacrificing readability of your code.

The next step is to make our `MaybeIO`

into an actual transformer by swapping
`IO`

for any `Monad`

.

## Generalizing `MaybeIO`

to `MaybeT`

The real monad transformers you’ll encounter in the world of Haskell are a bit
more generic than the one we just implemented. Instead of hard-coding the `IO`

monad we’ll pass it in as a type parameter, resulting in the following
definition of `MaybeT`

.

```
newtype MaybeT m a = MaybeT { runMaybeT :: m (Maybe a) }
```

There aren’t any significant changes, we just introduced a new type parameter
which will be the monad we’re wrapping. Since everything else remains almost
exactly the same, I’ll just show the `Monad`

implementation here.

```
newtype MaybeT m a = MaybeT { runMaybeT :: m (Maybe a) }
instance Monad m => Monad (MaybeT m) where
return = MaybeT . return . Just
MaybeT m >>= f = MaybeT $ do value <- m
case value of
Nothing -> return Nothing
Just x -> runMaybeT $ f x
```

The only notable thing here is that our type parameter `m`

is restricted to be
a `Monad`

as well, since we’re only going to be wrapping monads.

Our `findUsers`

function will be exactly the same, we’ll just need to swap
`runMaybeIO`

for `runMaybeT`

.

```
transformerFindUsers :: Int -> Int -> IO (Maybe (User, User))
transformerFindUsers x y = runMaybeT $ do
user1 <- MaybeT $ findById x
user2 <- MaybeT $ findById y
return (user1, user2)
```

Just to make it crystal clear what’s going on here, the function without using
`runMaybeT`

would look as follows.

```
wrappedFindUsers :: Int -> Int -> MaybeT IO (User, User)
wrappedFindUsers x y = do
user1 <- MaybeT $ findById x
user2 <- MaybeT $ findById y
return $ Just (user1, user2)
```

We can even introduce a type alias to have something called `MaybeIO`

using the
`MaybeT`

transformer.

```
type MaybeIO a = MaybeT IO a
```

This is actually how the well known monads such as `Reader`

, `Writer`

and
`State`

are defined. They’re just type synonyms for the respective transformers
using the `Identity`

monad.

```
type Reader r = ReaderT r Identity
type Writer w = WriterT w Identity
type State s = StateT s Identity
```

If you’re interested in learning more about the `Identity`

monad and how it can
be used in some more advanced settings, take a look at my Introduction to
Lenses article
where it’s explained step by step in great detail.

This concludes the first article in the series on Monad Transformers. Next time
we’ll take a look at how we can stack one transformer onto another and
introduce the `MonadTrans`

and `MonadIO`

type classes.

Haskell