If you’ve heard about Monads but never had time learn them, here’s a simple explanation. Not a theoretical nonsense. It’s a simple, practical tutorial for JavaScript developers showing how some monads can be used. It’s for engineers, not scientists.

In theory there is no difference between theory and practice. In practice there is.

Yogu Berra

All examples are based on monet.jsa tool bag that assists Functional Programming by providing a rich set of Monads and other useful functions. I’ll use arrow functions introduced in ES6. They are much more readable than regular functions when used as single operation “callbacks”. Also in some examples TypeScript type definitions will be added to enhance overall readability.


Monad is a box containing some value. People say it has something to do with freaky category theory but we can ignore that fact. Our box is not just a wrapper. It has tools to bind computations to the value. It can serve multiple different purposes – asynchronicity, fail-fast, error accumulation, lazy evaluation, etc… but these will be covered in future articles.

Monads are defined by 3 axioms. One of the things that axioms tell us is that there have to be some function that binds calculations to the value contained in a monad box. It’s called bind (or flatMap) and has to meet 3 requirements:
bind takes one parameter – a function (let’s call it callback)
callback takes current value and returns monad containing result of calculation
bind returns a monad returned by callback

var monadWithValue = Monad( value );

function callback(value) {
    var newValue = calculate…new…value…from…value;
    return Monad( newValue );

var monadWithNewValue = monadWithValue.bind(callback);

And TypeScript definition:

declare class Monad {
    bind<T, V>((value: T) => Monad<V>): Monad<V>;

Let’s forget about theory now and jump into practical examples:


Axioms tell us that there should be some function that creates a monad. Consider we have Identity(value) function that does the job:

var monadWith3 = Identity(3); // number 3 wrapped in an Identity box

var monadWith5 = monadWith3.bind( value => Identity(value + 2) );
// => Identity(5)

But why should I ever complicate my life so much if all I want is to add two integers?

Right. Previous example is not a real life one at all. But we can try to .bind() several operations to some value. And we may use another common (in monad world) method – .map(). When mapping you don’t have to return a monad from callback – returned value is wrapped under the hood in a same monad:

var monadWith3 = Identity(3);
var monadWith5 = monadWith3.map( value => value + 2 ); 
// => Identity(5);

So let’s do some real computation:

function getPercentRatio(wrongCount, correctCount): string {
    return Identity(wrongCount)

        // we get total count here
        .map(wrongCount => wrongCount + correctCount)

        // ratio between 0 and 1
        .map(totalCount => correctCount / totalCount)

        // ratio between 0 and 100
        .map(ratio => Math.round(100 * ratio))

        // ratio as a string like '28%'
        .map(percentRatio => String(ratio) + '%')

        // get value from inside of the Identity

A .map() in Identity works exactly like in an Array:

function getPercentRatio(wrongCount, correctCount): string {
    return [wrongCount]

        // we get total count here
        .map(wrongCount => wrongCount + correctCount)

        // ratio between 0 and 1
        .map(totalCount => correctCount / totalCount)

        // ratio between 0 and 100
        .map(ratio => Math.round(100 * ratio))

        // ratio as a string like '28%'
        .map(percentRatio => String(ratio) + '%')

        // get value from inside of the Identity

For the purpose of this example, calculations above are rather simple but they show idea of how to compose operations in descriptive, readable way. Consider other possibilities:

function getPercentRatio(wrongCount, correctCount): string {
    return String(Math.round(correctCount / (wrongCount + correctCount)) * 100) + '%';

or in more functional style:

function getPercentRatio(wrongCount, correctCount): string {
    return toPercentString(Math.round(ratio2percent(ratio(correctCount)(wrongCount))));

And now think about real-life, complex compositions of calculations…

Promise A/A+

Common JavaScript Promises are quite similar to monads. They are boxes containing values (or rejections). Compare this portion of code with initial Identity example:

var promiseOf3 = Q.resolve(3); // a Promise with number 3 inside
var promiseOf5 = promiseOf3.then( value => Q.resolve(value + 2) );
// => a Promise with number 5 inside

It is a simple example. Actually Promise A/A+ is not as typesafe as Monads are. Method .then() is so elastic that it does a job of several different methods of a monad (bind/flatMap, map, orElse, cata and few more).

But for sure there exist monadic implementations of JavaScript Promise!


There are several monads in the wild. Probably the most common is Maybe (Option). It can be Some(value) or Nothing. Example that fits previous ones:

var optionOf3 = Some(3);
var optionOf5 = optionOf3.flatMap((value) => Some(value + 2));
// Name 'flatMap' is commonly used for 'bind' method.
// I'll stick to it the rest of this article.

It becomes useful when we have methods/functions returning some value or null/undefined. For example getCurrentUser():

function getCurrentUser(): User { /* some implementation */ };

It can return a User entity or… null. See this:

function getId() {
    // will throw error if user is null or undefined
    return getCurrentUser().id;

We can fix this with some if/else bloat:

function getId(): string {
    var user = getCurrentUser();
    if (user) {
        return user.id;
    return null;

…or we can pack our values in a Maybe box:

function getCurrentUser(): Maybe<User>; // another implementation

function getId(): Maybe<string> {
    return getCurrentUser().map(user => user.id);

We are safe. No Uncaught TypeError: Cannot read property 'id' of null exceptions. And we do not have to add the evil if/else complexity to the code.

Maybe has few base methods:
flatMap which is core of any monad
map lets us get Maybe from Maybe
filter lets us change Some into None if a condition is not met
orSome – get monad value or just another value
orElse – get monad (if is Some) or else new passed monad
cata – whooo lot of magic…

Let’s .filter() and .map() like an Array

If you treat a Maybe as a single element (Some) or empty (None) array – map and filter will work the same:

let maybeUser = [{id: "3asd4asd", name: "James"}];
maybeUser.map(user => user.id); // => ["3asd4asd"]
maybeUser.filter(user => user.name === "John"); // => []

let notUser = [];
notUser.map(user => user.id); // => []
notUser.filter(user => user.name === "John"); // => []

…and for Maybe:

let maybeUser = Some({id: "3asd4asd", name: "James"});
maybeUser.map(user => user.id); // => Some("3asd4asd")
maybeUser.filter(user => user.name === "John"); // => None

let notUser = None;
notUser.map(user => user.id); // => None
notUser.filter(user => user.name === "John"); // => None

Let’s create a new getter (similar to getId() few lines above):

function getName(): Maybe<string> {
    return getCurrentUser().map(user => user.name);

The difference from Array’s map is that monad mapping should fail if callback returns no value. So if user’s name is null or undefined above example will be broken. We can easily fix this with filtering:

function getName(): Maybe<string> {
    // if user.name is null or undefined map 'callback' will never be called
    return getCurrentUser()
        .filter(user => !!user.name)
        .map(user => user.name);

“But that becomes so complex…” you would say. And you are right. Basic monad method is flatMap (aka unit) and it can handle this situation.

So let’s .flatMap()

function getName(userOption: Maybe<User>): Maybe<string> {
    return userOption.flatMap(user => {
        if (user.name) {
            return Maybe.Some(user.name);
        return Maybe.None;

…but that is still a bit unattractive. And that’s why my favorite JavaScript implementation (monet.js) provides additional way to create a Maybe monad:

let name = 'James';
let otherName;

let maybeName = Maybe.fromNull(name); // this one is Some('James');

let maybeOtherName = Maybe.fromNull(otherName); // None

With this JavaScript oriented super power we can:

function getName(userOption: Maybe): Maybe {
    return userOption.flatMap(user => Maybe.fromNull(user.name));

We can easily imagine a situation in which empty user name could be filled with some default value, e.g. 'Guest'. We can use .orSome() for this.

Get value .orSome() other value

Let’s get user name with fallback to 'Guest':

// Some getters defined earlier:
function getCurrentUser(): Maybe<User>;
function getName(userOption: Maybe<User>): Maybe<string>;

// And the meat and potatoes:
let name = getName(getCurrentUser()).orSome('Guest');

This one in other implementations is called .getOrElse()get value or else another passed value.

Without monads this would look like:

function getCurrentUser(): User;
function getName(user: User): string;

let user = getCurrentUSer();
let name;

if (user) {
    name = getName(user);

if (!name) {
    name = 'Guest';

Ugly, isn’t it?

Now what is the difference between .orSome() and .orElse() ?

Maybe tea .orElse() maybe coffee…

We have considered a default value for optional name field. We may also want to fill it with optional value from any other field in our source value like nickname. Here’s what can we do with the filthy imperative tools:

function getName(user: User): string;
function getNick(user: User): string;

function getPrintableName(user: User) {
    let name;

    if (user) {
        name = getName(user);
        if (!name) {
            name = getNick(user);

    return name || 'Guest';

So returning to a safe ground:

function getName(userOption: Maybe<User>): Maybe<string>;
function getNick(userOption: Maybe<User>): Maybe<string>;

function getPrintableName(userOption: Maybe<User>): Maybe<string> {
    return getName(userOption).orElse(getNick(userOption)).orSome('Guest');

Simple, isn’t it?

Catastrophism vs. Catamorphism

In category theory, the concept of catamorphism (from Greek: κατά = downwards or according to; μορφή = form or shape) denotes the unique homomorphism from an initial algebra into some other algebra.

We can ignore that scientific bullshit I think. It’s easy to remember that the most complex part of monet.js‘s Maybe monad is .cata() just like catastrophism. It can lead to catastrophe or cataclysm if used carelessly or without type safety in mind. It is also the best tool (along with .orSome() and .orElse()) to link our brand new functional code with an old and nasty third-party libraries 😉

It is like hybrid of .orSome() and .map() with 2 callbacks:
– for case we have None – it takes none args and returns fallback value
– for case we have Some(value) – it takes one arg (a value) and returns new value

It returns output of the callback that was called. Its signature in context of Maybe looks like this:

Maybe<T> {
    cata<Z>(noneCallback: () => Z, someCallback: (val: T) => Z): Z;

Consider another case – we have a Maybe (option of user name) and need to get greeting – different for named user and different for anonymous Guest:

function getGreeting(nameOption: Maybe<string>): string {
    return nameOption.cata(() => 'Hi Guest!', name => 'Welcome back ' + name + '!');

Sophisticated scientific name for a simple operation.


This simple little monad can save you a lot of time and some code. Identity gives you ability to write complex computations as descriptive steps. Maybe brings protection from Cannot read property of null exceptions. And what is most important – it’s only first step to functional programing monadic world where you can find more similar tools like Either (fail-fast handling), Validation (error accumulation), Promise (async operations), immutable List, Lazy, Continuation, Free, Read, etc… And some of them will be covered here shortly!

Remember, a monad is really nothing more than a chainable computation. It is simply a functional way to sequence things. That’s it.

A Gentle Intro to Monads … Maybe? Sean Voisen

Further reading: