Monads explained in Kotlin
Monads, I don’t know if you heard about them, if not please keep reading, if yes, please don’t give up and keep reading as well.
The term ‘monad’ itself is weird but if you google it is even worse, you will be overflowed by a lot of cryptic blogs of
functional programming trying to explain them or just being arrogant to show how smartasses they are and how stupid you are.
Well, this is just another one, the difference, I am not a functional expert, just a simple engineer trying to make the
suffering less painful when it comes to monads.
Why I am doing this? During my career I’ve been always trying to keepup to date but also learn new things, and one of them
was functional programming, and trust me, when you try to learn it there is a point that you face this scary term, yes, monads.
First reaction? Cool a new thing with a cool name… (after some minutes) … mmmh, this is abstract … (after some hours) …
this is really hard … (after weeks) … I think I am getting it … (after months) … Ok, let’s start over.
I don’t know if you have had the same experience, but to me, it’s been challenging in two ways:
 Understand what a monad is
 Explain what a Monad is
TBH, I think I will never be successful in any of them, but I least I will try 🤘.
Having said that, are you interested?
You got my attention! I want to learn more!
Note: Maybe some the assumptions are not totally accurate from either mathematical or functional perspective, but, again,
I am just trying to explain this useful pattern for nonfunctionalexperts.
First things first: Some theory
Let’s refresh a couple of concepts, because it is always good to keep in mind and reinforce base concepts before go in
details with a more complex topic like Monads.
What is a function?
In mathematics a function is a relationship between two sets of data, where each element of one corresponds to one element of
the other. Based in that definition, in programming a function is a relationship between two types, since a data type is a set
of values.
What is FP?
Is a functional programming paradigm where programs are made composing functions.
Functional Programming is based on λcalculus (compose and transform)
instead of Imperative Programming, which is based in Von Neumann (mutate state).
Related concepts:
 Functions are first class citizens
 High Order Functions
 Pure functions and Referential Transparency
 Recursion
 Nonstrict Evaluation
 Algebraic Data Types
 Immutability
 Side effects
 Declarative Programming
 Currying and Partial Application
 Monads
FP adds a different way of thinking about problemsolving.
I had enough, please, explain the topic
One thing more before jump into monads: Let’s use a real and practical problem to guide us through.
The Bank Account
Let’s pick up a real and easy problem that will help us to explain the concept along the exercise in a practical way.
We are going to use the simplest bank account implementation that we can use for the sake of explaining the monads
(a real bank account would be far more complex)
data class Account(val balance: BigDecimal)
What is the challenge here?
Operations like create an account
, deposit
or withdraw
are susceptible to fail, let’s see how we can deal with
them with monads.
Why not just raise exceptions?
There is a lot of discussions and strong opinions around this topic over the net, to me is really easy, given an error:
 Is it a crash? Then let it crash, let the exception fly, they are exceptional cases. Errors that you don’t
create/control, that come from other libs, frameworks, external resources, deal with them outside your domain, at the
boundary of you program.  Is it an error that you control? Then use another error handling mechanism.
Why would be bad to use exceptions for my own errors?
 In almost all the languages exceptions hide nonhappy case flows, you can not type them in the function signatures,
therefore, from client perspective you can not even notice and deal properly with them.  Using exceptions you are not forced to face your own errors, you can easily let it crash, delegating the control of
the flow to someone else.  They can be expensive in terms of performance.
Yeah, sure, you will need to convince me
What is a monad?
A monad is a functional design pattern
Design pattern: Reusable solution to a commonly occurring problem within a given context in software design. In OOP
we have the famous GOF – Gang of Four patterns (Singleton, Adapter, Decorator, Strategy, Observer, Visitor…).
A monad is a functional design pattern that solves recurrent problems such as:
 Nullability – Maybe/Option monad
 Error Handling – Either monad
 DI (Dependency Injection) – Reader monad
 Logging – Writer monad
 Side Effects – IO monad
 State handling – State monad
 Iterable – List monad
 Many others …
Either Monad
For our exercise we are going to use one of the most useful ones, the Either
monad (can have different names, for
instance F# has Result
type, in Golang it’s a part of the syntax when function is obliged to return 2 results, etc.),
to handle our errors:

Either
type represents values with two possibilities, eitherLeft
orRight

Convention dictates that
Left
is used forfailure
andRight
is used forsuccess
. 
Mnemonic: “right” also means “success/correct/good”.
A monad is a type in a context
Monads work with a type in a context, where context is a generic container that holds a value:
 Is a type that wraps another type/s.
 Is parameterised
 The context matters, is semantic, gives some form of quality to the underlying type.
And here a very basic implementation:
sealed class Either<out A, out B> {
data class Left<A>(val value: A) : Either<A, Nothing>()
data class Right<B>(val value: B) : Either<Nothing, B>()
}
Bla bla bla, so boring, show me something real
Sure!
Let’s create an account
In order to create an account we need to provide a way, we could use the constructor, but it does not allow us to return
other types than the constructed one. Therefore, we can provide a factory method and make the constructor private, with
this we can enforce the invariants of our account.
data class Account private constructor(val balance: BigDecimal) {
companion object {
fun create(initialBalance: BigDecimal): Either<NegativeAmount, Account> =
if (initialBalance < 0) Either.Left(NegativeAmount)
else Either.Right(Account(initialBalance))
}
}
The code from consumer perspective looks like this:
Account.create(initialBalance: BigDecimal): Either<NegativeAmount, Account>
If we try to read it like a text, what is this signature telling us?
This creates an account with an initial balance, it can either fail because the amount was negative or success
Amazing 😍, isn’t it?
I still prefer my amazing code throwing exceptions
Are you sure? The same signature with exceptions:
Account.create(initialBalance: BigDecimal): Account
What can go wrong? Nothing, no signals of errors … a consumer can happily use it without knowing that it can actually
fail, this is a hidden flow.
I don’t buy it, I can always:
 Add an amazing documentation.
 Check the implementation.
 Come back to java where I can use checked exceptions.
Well:
 Documentation: not clean, code should be selfexplanatory, and also if you pass the function around as a lambda you
will lose it.  Check the implementation: Really? Not clean, a consumer should not know about the implementation details.
 Sure, come back to java where you can type it with
throws NegativeAmountException
, only one problem, since your
method is throwing checked exceptions you can not pass the function around, bye bye HighOrderFunctions. Maybe you
can find a workaround to pass it, yeah, just a workaround.
Ok, fine, you got me
A monad can be mapped over.
What??? Easy, easy, calm down mathematicians and functional programming experts!!
Sadly, we can not explain monads without explain another pattern, the Functor.
Basically, a functor is a container that holds a value and allows us to map over it with one function called fmap
or map
:
Functor? fmap? Do I have an arrogant haskeller face?
Ok, ok, maybe you are more familiar with this:
listOf(1, 2).map { it + 1 }
You already have used the pattern in many languages and multiple times, mainly in collections when you want to map over
all the elements and change them given a lambda.
Don’t think in abstractions, supertypes or interfaces … the implementation differs depending on the language, you can
understand a functor as:
 A parametric type
 Has a ~
map
function to change the inner value typeA
passing a lambda(A > B)
Possible simple implementation in kotlin using an interface:
interface Functor<out A> {
fun <B> map(fn: (A) > B) : Functor<B>
}
Interesting, I was using functors without knowing it … 🤦
But why this is related to monads?
A Monad is also a functor and from client perspective, a monad without a map function is not the most useful
construct.
Why I would need this with our Account?
Deposit money into the bank account
What if we want to deposit money to this account?
Easy! we just add a method on the account
data class Account private constructor(val balance: BigDecimal) {
companion object {
fun create(initialBalance: BigDecimal): Either<NegativeAmount, Account> =
if (initialBalance < 0) Either.Left(NegativeAmount)
else Either.Right(Account(initialBalance))
}
fun deposit(amount: BigDecimal): Account = this.copy(balance = this.balance + amount)
}
object NegativeAmount
Now let’s try to add money
val account = Account.create(100.toBigDecimal())
when (account) {
is Either.Right > account.value.deposit(100.toBigDecimal())
is Either.Left > TODO() // now what?
}
Come on, this is worse than my beautifulimperative code! What I have to do now? Throw an exception? And, what is all this boilerplate code?
Wait again, map
to the rescue!
sealed class Either<out A, out B> {
class Left<A>(val value: A) : Either<A, Nothing>()
class Right<B>(val value: B) : Either<Nothing, B>()
fun <C> map(fn: (B) > C): Either<A, C> = when (this) {
is Right > Right(fn(this.value))
is Left > this
}
}
And …
val account = Account.create(100.toBigDecimal())
.map { a > a.deposit(100.toBigDecimal()) }
Boom! Cool, right?
But then, what if
Account.create
returns an error?
Our map
is semantically attached to the type of the monad, in our case to the Either
monad, it will only apply
the fn
if we have a Right
, otherwise the function will be just ignored, our monad is right biased.
But, what if the amount is negative? What about errors?
Good! Kid, you are sharp, I’ll give you that. The next section is going to fix that.
A Monad is a couple of functions
**Disclaimer: This is the most important part, pay attention.**
I am there!
Monads define two functions:
 One to wrap a value in a monad (the container), called
return
orunit
:
 Another, known as
bind
orflatmap
, to apply a function to the contained value that outputs another monad:
What the f****? Please, why I would even need these functions? explain this before I leave!
Take it easy, I am going to do it
Deposit money into the bank account, second try
Remember our function to deposit money without errors:
data class Account private constructor(val balance: BigDecimal) {
// other stuff
fun deposit(amount: BigDecimal): Account = this.copy(balance = this.balance + amount)
}
Let’s add some errors here:
data class Account private constructor(val balance: BigDecimal) {
companion object {
fun create(initialBalance: BigDecimal): Either<NegativeAmount, Account> =
applyAmount(initialBalance) { Account(it) }
private fun applyAmount(amount: BigDecimal, fn: (BigDecimal) > Account) =
if (amount < ZERO) Either.Left(NegativeAmount)
else Either.Right(fn(amount))
}
fun deposit(amount: BigDecimal): Either<NegativeAmount, Account> =
applyAmount(amount) { this.copy(balance = this.balance + it) }
}
BTW, our Right
and Left
constructors could be considered as the unit
function, they put a value in the Either
context.
Now, it’s time to deposit money again:
val account = Account.create(100.toBigDecimal())
.map { a > a.deposit(100.toBigDecimal()) }
And the tricky question. Could you tell me the type inferred into the val account?
Mmmm, I guess is … Either<NegativeAmount, Account>?
Nope, the type is:
val account: Either<NegativeAmount, Either<NegativeAmount, Account>> = Account.create(100.toBigDecimal())
.map { a > a.deposit(100.toBigDecimal()) }
🤯, either inception!
Remember map
is a function that maps type A
to type B
, in our case, the function deposit(A):B
:
A
: BigDecimal typeB
: Either<NegativeAmount, Account>
Therefore, we are applying a fn that not just transform the value, it wraps into a context to an already wrapped context.
Guess what,flatmap
fixes this, because it expects a function that returns another contained value, fixing the mess for you:
sealed class Either<out A, out B> {
class Left<A>(val value: A) : Either<A, Nothing>()
class Right<B>(val value: B) : Either<Nothing, B>()
fun <C> map(fn: (B) > C): Either<A, C> = when (this) {
is Right > Right(fn(this.value))
is Left > this
}
fun <A, C> flatMap(fn: (B) > Either<A, C>): Either<A, C> = when (this) {
is Right > fn(this.value)
is Left > this as Either<A, C>
}
}
And finally:
val account: Either<NegativeAmount, Account> = Account.create(100.toBigDecimal())
.flatMap { a > a.deposit(100.toBigDecimal()) }
It is a simple thing, but it took me a while to get it, bind~flatmap
is the most important function to understand,
once you get it, you can use monads without struggling and guessing types.
Ok, any tip? suggestion?
Yes, think in types, never in what the monad is doing under the hood (implementation), then if you have any value
wrapped in a monad such as SomeMonad of A
, if you apply a fn:
 If fn goes from
A > B
applymap
 If fn goes from
A > SomeMonad of B
applyflatmap
Got it!
One more thing, remember that we said that all monads are functors? See this:
sealed class Either<out A, out B> {
class Left<A>(val value: A) : Either<A, Nothing>()
class Right<B>(val value: B) : Either<Nothing, B>()
fun <C> map(fn: (B) > C): Either<A, C> = flatMap { Right(fn(it)) }
fun <A, C> flatMap(fn: (B) > Either<A, C>): Either<A, C> = when (this) {
is Right > fn(this.value)
is Left > this as Either<A, C>
}
}
map
can be defined with unit
and flatmap
, that’s one of the reasons why a monad can be a functor.
A Monad is a Workflow/Pipeline builder
Monads allow you to compose small operations to create workflows and achieve bigger purposes.
This statement seems broad and ambiguous to me
Remember what we said about functional programming at the very beginning? FP is all about make programs by
composing functions.
So, this is what monads do, compose functions, chain functions, combine them to create workflows.
Show it to me
Compose deposit and withdraw
Let’s introduce a new operation in the account, withdraw money, with this operation we are also introducing a new error:
data class Account private constructor(val balance: BigDecimal) {
// Other methods
fun withdraw(amount: BigDecimal): Either<AccountError, Account> =
applyAmount(amount) { this.copy(balance = this.balance  it) }
.flatMap {
if ((balance  amount) < ZERO) Left(NotEnoughFunds) else Right(Account(balance  amount))
}
}
sealed class AccountError {
object NegativeAmount : AccountError()
object NotEnoughFunds : AccountError()
}
Scenario 1: Jane wants to open an account with 100, afterwards she will deposit 100 and finally withdraw 250, therefore
an error should popup, because Jane has not enough funds.
val account = Account.create(100.toBigDecimal())
.flatMap { it.deposit(100.toBigDecimal()) }
.flatMap { it.withdraw(250.toBigDecimal()) }
// account = Left(value=NotEnoughFunds)
Meh!, okayish … but could you show me how we can use it in my fancy real application?
Sure, let’s create some application Services/UseCases.
Scenario 2: We want to create a service to transfer money within two different accounts.
class TransferMoney {
operator fun invoke(debtor: Account, creditor: Account, amount: BigDecimal): Either<AccountError, Pair<Account, Account>> =
debtor
.withdraw(amount)
.flatMap { d > creditor.deposit(amount).map { Pair(d, it) } }
}
Scenario 3: We want to get an account from a repository, add some cash, and save it back with the new state.
interface AccountRepository {
fun findBy(userId: UUID): Either<AccountNotFound, Account>
fun save(account: Account)
}
sealed class AccountError {
object NegativeAmount : AccountError()
object NotEnoughFunds : AccountError()
object AccountNotFound : AccountError()
}
class DepositCash(private val repository: AccountRepository) {
operator fun invoke(userId: UUID, amount: BigDecimal): Either<AccountError, Unit> =
repository.findBy(userId)
.flatMap { it.deposit(amount) }
.map(repository::save)
}
Ok, finally you have my vote, at least I will consider it in my next project!
Summary and Conclusion
I hope this helped someone to understand monads or at least to awake some curiosity on the topic.
I have skipped on purpose several topics and important things regarding monads, such as applicatives (sequence, traverse),
monad laws, fold family, monad comprehensions and a lot more, but, as I said at the very beginning, this is just an
introduction, complex topics should be learnt step by step.
A recap, what is a Monad for an imperative mind?
 A monad is a functional design pattern, that serves for several purposes such as represent emptiness, error
handling, side effects …  A monad is a type in a context, it wraps a type meaningfully.
 “A monad can be mapped over”, implements in one way or another the
map
function  A Monad is a couple of functions,
unit
andflatmap
 A Monad is a Workflow/Computation builder, you can compose, chain and combine to create a business flow.