Monet is a library designed to bring great power to your JavaScript programming. It is a tool bag that assists Functional Programming by providing a rich set of Monads and other useful functions.

This library is inspired by those that have come before, especially the FunctionalJava and Scalaz projects.

While functional programming may be alien to you, this library is a simple way to introduce monads and pure functional programming into your daily practises.

The source is available at: https://github.com/cwmyers/monet.js.

Simply download and add to your html pages or we also support bower. You can also include `monet-pimp.js`

which contains extra functions on the `Object.prototype`

for creating monads.

```
<script type="text/javascript" src="monet.js"></script>
<!-- Optionally -->
<script type="text/javascript" src="monet-pimp.js"></script>
```

Using bower:

`bower install monet`

or to install a specific version

`bower install monet#0.8.1`

As you know JavaScript isn’t a strongly typed language. This kinda sucks. Types are a great help when it comes to functional programming as it makes the code more comprehensible and prevents a range of errors from being introduced.

Knowing the types of your functions and data is also important when writing documentation (such as this one), so we will invent some type annotations to make things more clear. We will only do this in the function definition and *not* in the **concrete examples**.

JavaScript doesn’t have generic types but it’s useful to know about them when dealing with Monads. For instance the `List`

monad is a type that requires another type, such as a string or integer or some other type before it can be constructed. So you would have a List of Strings or a List of Integers or generically a List of `A`

s where `A`

is a type you will supply. Now of course this is JavaScript and you can do as you please even though it doesn’t make sense. But to make things clearer (hopefully) we will attempt to do show generics or *type parameters* thusly:

`List[A]`

Which means a `List`

of `A`

s. Though of course you will have to keep track of the types yourself.

`function x(a: A, b: B): C`

And functions on a Monadic type that has been constructed with `A`

`Maybe[A].fromNull(a: A): Maybe[A]`

For functions that take other functions as parameters (which are called *Higher order functions*) we will use an abbreviated way to represent that function using a pseudo type lambda:

`A -> B `

So,

`function x(a: A -> B, c: B -> C): C`

means that function `x`

takes two parameters that are both functions themselves. `a`

is a function that takes a type `A`

and returns a type `B`

and `c`

is a function that takes a type `B`

and returns a type `C`

. The function `x`

will return a type `C`

.

Some functions (or lambdas) do not take a parameter, and some do not return anything. Will express this as:

`() -> A`

or

`A -> ()`

Everything that is a monad in will implement the following functions. The specific monads will be discussed in detail below.

`Monad[A].bind(f: A -> Monad[B]): Monad[B]`

Performs a monadic bind.

`Monad[A].map(f: A -> B): Monad[B]`

`Monad.unit(A): Monad[A]`

`Monad[A].ap(m: Monad[A -> B]): Monad[B]`

`Monad[Monad[A]].join(): Monad[A]`

The inner and outer monads are the same type.

`Monad[A].takeLeft(m: Monad[B]): Monad[A]`

Performs a combination of both monads and takes the left one.

For example:

```
Some(1).takeLeft(Some(2))
// result: Some(1)
Some(1).takeLeft(None())
// result: None
None().takeLeft(Some(3))
// result: None
```

`Monad[A].takeRight(m: Monad[B]): Monad[B]`

Performs a combination of both monads and takes the right one.

For example:

```
Some(1).takeRight(Some(2))
// result: Some(2)
Some(1).takeRight(None())
// result: None
None().takeRight(Some(2))
//result: None
```

The `Maybe`

type is the most common way of representing *nothingness* (or the `null`

type) with making the possibilities of `NullPointer`

issues disappear.

`Maybe`

is effectively abstract and has two concrete subtypes: `Some`

(also `Just`

) and `None`

(also `Nothing`

).

```
var maybe = Maybe.Some(val);
var maybe = Maybe.None();
var maybe = Maybe.fromNull(val); // none if val is null, some otherwise
```

or more simply with the pimped method on Object.

```
var maybe = "hello world".some()
var maybe = val.some()
```

`Maybe[A].map(fn: A -> B) : Maybe[B]`

`map`

takes a function (A -> B) and applies that function to the value inside the `Maybe`

and returns another `Maybe`

.

For example:

```
Maybe.Some(123).map(function(val) {
return val+1
})
=> 124
```

`Maybe[A].bind(fn: A -> Maybe[B]): Maybe[B]`

`bind`

takes a function that takes a value and returns an `Maybe`

. The value to the function will be supplied from the `Maybe`

you are binding on.

For example:

```
maybe.bind(function(val) {
if (val == "hi") {
return Maybe.Some("world")
} else {
return Maybe.None()
}
})
```

`Maybe[A].isSome(): Boolean`

`isSome`

on a `Some`

value will return `true`

and will return `false`

on a `None`

.

For example:

```
Maybe.some("hi").isSome()
//result: true
```

`Maybe[A].isNone(): Boolean`

`isNone`

on a `None`

value will return `true`

and will return `false`

on a `Some`

.

For example:

```
Maybe.none().isNone()
//result: true
```

`Maybe[A].some(): A`

`some`

will ‘reduce’ the `Maybe`

to its value. But warning! It will throw an error if you attempt to do this on a none. Use `orSome`

instead.

For example:

```
Maybe.some("hi").some()
//result: "hi"
```

`Maybe[A].orSome(a:A) : A`

Will return the containing value inside the `Maybe`

or return the supplied value.

```
maybe.some("hi").orSome("bye")
=> "hi"
Maybe.none().orSome("bye")
=> "bye"
```

`Maybe[A].orElse(Maybe[A]): Maybe[A]`

Returns the Maybe if it is a Some otherwise returns the supplied Maybe.

`Maybe[A].ap(Maybe[A->B]): Maybe[B]`

The `ap`

function implements the Applicative Functor pattern. It takes as a parameter another `Maybe`

type which contains a function, and then applies that function to the value contained in the calling `Maybe`

.

It may seem odd to want to apply a function to a monad that exists inside another monad, but this is particular useful for when you have a curried function being applied across many monads.

Here is an example for creating a string out of the result of a couple of `Maybe`

s. We use `curry()`

which is a pimped method on Function so we can partially apply.

```
var person = function (forename, surname, address) {
return forename + " " + surname + " lives in " + address
}.curry()
var maybeAddress = Maybe.just('Dulwich, London')
var maybeSurname = Maybe.just('Baker')
var maybeForename = Maybe.just('Tom')
var personString = maybeAddress
.ap(maybeSurname
.ap(maybeForename.map(person))).just()
// result: "Tom Baker lives in Dulwich, London"
```

For further reading see this excellent article.

`Maybe[A].toEither(fail: E): Either[E,A]`

Converts a Maybe to an Either

`Maybe[A].toValidation(fail: E): Validation[E,A]`

Converts a Maybe to a Validation.

`Maybe[A].toList: List[A]`

Converts to a list, returns an Empty list on None.

Either (or the disjunct union) is a type that can either hold a value of type `A`

or a value of type `B`

but never at the same time. Typically it is used to represent computations that can fail with an error. Think of it as a better way to handle exceptions. We think of an `Either`

as having two sides, the success is held on the right and the failure on the left. This is a right biased either which means that `map`

and `flatMap`

(`bind`

) will operate on the right side of the either.

```
var success = Either.Right(val);
var failure = Either.Left(val);
```

or with the pimped methods on object:

```
var success = val.right()
var failure = "some error".left()
```

`Either[E,A].map(fn: A -> B): Either[E,B]`

This will apply the supplied function over the right side of the either, if one exists, otherwise it returns the `Either`

untouched.

For example:

```
Right(123).map(function (e) {return e+1})
// result: Right(124)
Left("grr").map(function (e) {return e+1})
// result: Left("grr")
```

`Either[E,A].flatMap(fn: A -> Either[E,B]): Either[E,B]`

This will perform a monadic bind over the right side of the either, otherwise it will do nothing.

`Either[E,A].ap(v: Either[E, A -> B]): Either[E,B]`

This takes an either that has a function on the right side of the either and then applies it to the right side of itself. This implements the applicative functor pattern.

`Either[E,A].cata(leftFn: E -> X, rightFn: A ->X): X`

The catamorphism for either. If the either is `right`

the right function will be executed with the right value and the value of the function returned. Otherwise the `left`

function will be called with the left value.

```
For example:
var result = either.cata(function(failure) {
return "oh dear it failed because " + failure
}, function(success) {
return "yay! " + success
})
```

`Either[A,B].bimap(leftFn: A->C, rightFn: B->D): Either[C,D]`

`Either[E,A].isRight(): Boolean`

Returns true if this Either is right, false otherwise.

`Either[E,A].isLeft(): Boolean`

Returns true if this Either is left, false otherwise.

`Either[E,A].right(): A`

Returns the value in the right side, otherwise throws an exception.

`Either[E,A].left(): E`

Returns the value in the left side, otherwise throws an exception.

`Either[E,A].toValidation(): Validation[E,A]`

Converts the `Either`

to a `Validation`

.

`Either[E,A].toMaybe(): Maybe[A]`

Converts to a `Maybe`

dropping the left side.

Validation is not quite a monad as it doesn’t quite follow the monad rules, even though it has the monad methods. It that can hold either a success value or a failure value (i.e. an error message or some other failure object) and has methods for accumulating errors. We will represent a Validation like this: `Validation[E,A]`

where `E`

represents the error type and `A`

represents the success type.

```
var success = Validation.success(val);
var failure = Validation.fail("some error");
```

or with pimped methods on an object

```
var success = val.success();
var failure = "some error".fail();
```

`Validation[E,A].map(fn:A -> B): Validation[E,A]`

`map`

takes a function (A -> B) and applies that function to the value inside the `success`

side of the `Validation`

and returns another `Validation`

.

For example:

```
Validation.success(123).map(function(val) { return val + 1})
//result: Success(124)
```

`Validation[E,A].bind(fn:A -> Validation[E,B]) : Validation[E,B]`

`bind`

takes a function that takes a value and returns an `Validation`

. The value to the function will be supplied from the `Validation`

you are binding on.

For example:

```
validation.bind(function(val) {
if (val == "hi") {
return Validation.success("world")
} else {
return Validation.fail("wow, you really failed.")
}
})
```

`Validation[E,A].isSuccess() : Boolean`

Will return `true`

if this is a successful validation, `false`

otherwise.

`Validation[E,A].isFail() : Boolean`

Will return `false`

if this is a failed validation, `true`

otherwise.

`Validation[E,A].success() : A`

Will return the successful value.

`Validation[E,A].fail() : E`

Will return the failed value, usually an error message.

`Validation[E,A].ap(v: Validation[E, A->B]) : Validation[E,B]`

Implements the applicative functor pattern. `ap`

will apply a function over the validation from within the supplied validation. If any of the validations are `fail`

s then the function will collect the errors.

```
var person = function (forename, surname, address) {
return forename + " " + surname + " lives at " + address
}.curry();
var validateAddress = Validation.success('Dulwich, London')
var validateSurname = Validation.success('Baker')
var validateForename = Validation.success('Tom')
var personString = validateAddress.ap(validateSurname
.ap(validateForename.map(person))).success()
// result: "Tom Baker lives at Dulwich, London"
var result = Validation.fail(["no address"])
.ap(Validation.fail(["no surname"])
.ap(validateForename.map(person)))
// result: Validation(["no address", "no surname"])
```

`Validation[E,A].cata(failureFn: E->X, successFn: A->X): X`

The catamorphism for validation. If the validation is `success`

the success function will be executed with the success value and the value of the function returned. Otherwise the `failure`

function will be called with the failure value.

For example:

```
var result = v.cata(function(failure) {
return "oh dear it failed because " + failure
}, function(success) {
return "yay! " + success
})
```

`Validation[E,A].toEither(): Either[E,A]`

Converts an `Either`

to a `Validation`

`Validation[E,A].toMaybe(): Maybe[A]`

Converts to a `Maybe`

dropping the failure side.

An immutable list is a list that has a head element and a tail. A tail is another list. The empty list is represented by the `Nil`

constructor. An immutable list is also known as a “cons” list. Whenever an element is added to the list a new list is created which is essentially a new head with a pointer to the existing list.

The easiest way to create a list is with the pimped method on Array, available in monet-pimp.js.

`var myList = [1,2,3].list()`

which is equivalent to:

`var myList = List(1, List(2, List(3, Nil)))`

As you can see from the second example each List object contains a head element and the tail is just another list element.

`List[A].cons(a: A) : List[A]`

`cons`

will prepend the element to the front of the list and return a new list. The existing list remains unchanged.

For example:

```
var newList = myList.cons(4)
// newList.toArray() == [4,1,2,3]
// myList.toArray() == [1,2,3]
```

`cons`

is also available as a pimped method on `Object.prototype`

:

```
var myList = ["a","b","c"].list()
var newList = "z".cons(myList)
newList.toArray() == ["z","a","b","c"]
```

`List[A].map(fn: A->B): List[B]`

Maps the supplied function over the list.

```
var list = [1,2,3].list().map(function(a) {
return a+1
})
// list == [2,3,4]
```

`List[A].flatMap(fn: A -> List[B]): List[B]`

Maps the supplied function over the list and then flattens the returned list. The supplied function must return a new list.

`List[A].head(): A`

Returns the head of the list.

For example:

```
[1,2,3].list().head()
//result: 1
```

`List[A].headMaybe(): Maybe[A]`

Returns the optional head of the list.

For example:

```
[1,2,3,4].list().headMaybe()
// result: Some(1)
Nil.headMaybe()
// result: None()
```

`List[A].foldLeft(initialValue: B)(fn: (acc:B, element:A) -> B): B`

`foldLeft`

takes an initial value and a function and will ‘reduce’ the list to a single value. The supplied function takes an accumulator as its first value and the current element in the list as its second argument. The returned value from the function will be pass into the accumulator on the subsequent pass.

For example, say you wanted to add up a list of integers, your initial value would be `0`

and your function would return the sum of the accumulator and the passed in element.

```
var myList = [1,2,3,4].list()
var sum = myList.foldLeft(0)(function(acc, e) {
return e+acc
})
// sum == 10
```

`List[A].foldRight(initialValue: B)(fn: (element: A, acc: B) -> B): B`

Performs a fold right across the list. Similar to `foldLeft`

except the supplied function is first applied to the right most side of the list.

`List[A].append(list: List[A]) : List[A]`

Will append the second list to the current list. Both list must be of the same type.

For example:

```
var list1 = [1,2,3].list()
var list2 = [4,5,6].list()
var list3 = list1.append(list2)
// list3.toArray() == [1,2,3,4,5,6]
```

`List[Monad[A].sequence(Monad): Monad[List[A]]`

Will `sequence`

a list of monads. The signature above is slightly hard to represent, but this function will sequence a list of any type of monad, but you will need to supply the name of the monad you are sequencing.

**Note: This version of sequence will only work with Monads that can cope with eager evaluations. For lazy monads such as IO and Reader please use lazySequence or the explicit versions, such as sequenceIO.**

For example:

```
[1.right(), 2.left()].list().sequence(Either) // For Eithers
[1.some(), 2.none()].list().sequence(Maybe)
```

Or you can use the convenience methods like `sequenceMaybe`

or `sequenceEither`

below. Note that since Validation is not a true monad it will not work as expected for this method; use `sequenceValidation`

instead.

`List[Monad[A].lazySequence(Monad): Monad[List[A]]`

This is the same as `sequence`

except it caters for Monads that require laziness, such as `IO`

and `Reader`

.

`List[Maybe[A]].sequenceMaybe(): Maybe[List[A]]`

Takes a list of `Maybe`

s and turns it into a `Maybe`

`List`

. If the list contains at least one `None`

value then a `None`

will be returned, otherwise a `Some`

will be returned with a list of all the values.

For example:

```
var sequenced = [Some(1), Some(2), Some(3)].list().sequenceMaybe()
// sequenced == Some([1,2,3]) <- That's an immutable list not an array
var sequenced = [Some(1), Some(2), None, Some(3), None].list().sequenceMaybe()
// sequenced == None
```

This is the same as calling:

`[Some(1), Some(2)].sequence(Maybe)`

`List[Either[E,A]].sequenceEither(): Either[E, List[A]]`

This will sequence a `List`

of `Either`

s stopping on the first `Left`

that it finds. It will return either a `List`

of the `Right`

values or the first `Left`

value it encounters.

For example:

```
[1.right(), 2.right(), 3.right()].list().sequenceEither() == Right(List(1,2,3))
[1.right(), 2.left(), 3.left()].list() == Left(2)
```

Note: Unlike `sequenceValidation`

it does not accumulate the `Left`

(or “failing”) values, but rather stops execution and returns the first `Left`

.

`List[Validation[E,A]].sequenceValidation(): Validation[List[E], List[A]]`

Takes a list of `Validation`

s and turns it into a `Validation`

`List`

. It will collect all the `success`

values into a list on the `Success`

side of the validation or it accumulates the errors on the `Failure`

side, if there are **any** failures.

```
var sequenced = ["a".success(), "b".success(), "c".success()]
.list().sequenceValidation()
// sequenced == Success(["a", "b", "c"])
var sequenced = ["a".success(),
"b".success(),
"c".fail(),
"d".fail(),
"e".success()]
.list().sequenceValidation()
// sequenced == Fail(["c","d"])
```

`List[IO[A]].sequenceIO(): IO[List[A]]`

Will sequence a list of `IO`

actions.

`List[Reader[A]].sequenceReader(): Reader[List[A]]`

Will sequence a list of `Reader`

s.

`List[A].reverse(): List[A]`

Returns a new list reversed.

```
var list = [1,2,3].list().reverse()
// list.toArray() == [3,2,1]
```

Much like the immutable list, a Non Empty List can never be empty. It implements the `comonad`

pattern. It has a guaranteed head (total) and a guaranteed (total) tail.

```
var nonEmptyList = NonEmptyList(1, [2,3,4].list())
// alias
var nonEmptyList = NEL(1, [2,3,4].list())
// or
var nonEmptyList = NonEmptyList(1, Nil)
// or fromList which returns a Maybe[NonEmptyList].
var maybeNonEmptyList = NonEmptyList.fromList([1,2,3,4].list())
```

Trying to create an empty `NonEmptyList`

will throw an exception.

`NEL[A].map(fn: A -> B): NEL[B]`

Maps a function over a NonEmptyList.

`NEL[A].bind(fn: A -> NEL[B]): NEL[B]`

Performs a monadic bind over the NonEmptyList.

`NEL[A].head(): A`

Returns the head of the NonEmptyList. Also known as `copure`

or `extract`

this is part of the comonad pattern.

`NEL[A].tail(): List[A]`

Returns the tail of the `NonEmptyList`

.

`NEL[A].tails(): NEL[NEL[A]]`

Returns all the tails of the `NonEmptyList`

. Also known as `cojoin`

this is part of the comonad pattern. A list is considered a tail of itself.

For example:

```
NEL(1, [2,3,4].list()).tails()
//result: [
// [ 1, 2, 3, 4 ],
// [ 2, 3, 4 ],
// [ 3, 4 ],
// [ 4 ]
// ]
```

`NEL[A].mapTails(fn: NEL[A] -> B): NEL[B]`

Maps a function over the tails of the `NonEmptyList`

. Also known as `cobind`

this is part of the comonad pattern.

For example:

```
nonEmptyList.cobind(function (nel) {
return nel.foldLeft(0)(function(a,b){
return a+b
})
}
//result: [10,9,7,4]
```

`NEL[A].append(n: NEL[A]): NEL[A]`

Appends two NonEmptyLists together.

`NEL[A].reverse(): NEL[A]`

Reverses the `NonEmptyList`

.

`NEL.fromList(List[A]): Maybe[NEL[A]]`

Returns an optional `NonEmptyList`

. If the supplied `List`

is empty the result will be a `None`

, otherwise a `NonEmptyList`

wrapped in a `Some`

(or `Just`

).

The `IO`

monad is for isolating effects to maintain referential transparency in your software. Essentially you create a description of your effects of which is performed as the last action in your programme. The IO is lazy and will not be evaluated until the `perform`

(*alias* `run`

) method is called.

`var ioAction = IO(function () { return $("#id").val() })`

`IO[A](fn: () -> A): IO[A]`

The constructor for the `IO`

monad. It is a purely functional wrapper around the supplied effect and enables referential transparency in your software.

`IO[A](fn: A -> IO[B]): IO[B]`

Perform a monadic bind (flatMap) over the effect. It takes a function that returns an `IO`

. This will happen lazily and will not evaluate the effect.

Examples: see below

`IO[A](fn: A -> B): IO[B]`

Performs a map over the result of the effect. This will happen lazily and will not evaluate the effect.

Evaluates the effect inside the `IO`

monad. This can only be run once in your programme and at the very end.

Wraps a supplied function in an `IO`

. Assumes no arguments will be supplied to the function.

`function() { return $("#id") }.io()`

Returns a function that will return an `IO`

when one parameter is supplied.

`function(id) { return $(id) }.io1()`

or more simply

`$.io1()`

Say we have a function to read from the DOM and a function to write to the DOM. *This example uses jQuery.*

```
var read = function(id) {
return $(id).text()
}
var write = function(id, value) {
$(id).text(value)
}
```

On their own both functions would have a side effect because they violate referential transparency. The `read`

function is dependent on an ever changing DOM and thus subsequent calls to it would not produce the same result. The `write`

function obviously mutates the DOM and so it too is not referentially transparent, as each time it is called, an effect occurs.

We can modify this functions so that instead of performing these side-effects they will just return an `IO`

with the yet-to-be-executed function inside it.

```
var read = IO(function (id) { return $(id).text() })
var write = function(id) {
return IO(function(value) {
$(id).text(value)
})
}
```

You can call `write(id)`

until you are blue in the face but all it will do is return an `IO`

with a function inside.

We can now call `map`

and `flatMap`

to chain this two effects together. Say we wanted to read from a `div`

covert all the text to uppercase and then write back to that `div`

.

```
var toUpper = function (text) { return text.toUpperCase() }
var changeToUpperIO = read("#myId").map(toUpper).flatMap(write("#myId"))
```

So what is the type of `changeToUpperIO`

? Well it is the `IO`

type. And that means at this stage, **nothing has been executed yet**. The DOM has not been read from, the text has not been mapped and the DOM has not been updated. What we have is a **referentially transparent description** of our programme.

In other pure functional languages such as Haskell we would simply return this type back to the runtime, but in JavaScript we have to manage this ourselves. So now let’s run our effect.

`changeToUpperIO.run()`

Now our DOM should be updated with the text converted to upper case.

It becomes much clearer which functions deal with IO and which functions simply deal with data. `read`

and `write`

return an `IO`

effect but `toUpper`

simply converts a supplied string to upper case. This pattern is what you will often find in your software, having an effect when you start (i.e. reading from a data source, network etc), performing transformations on the results of that effect and finally having an effect at the end (such as writing result to a database, disk, or DOM).

The `Reader`

monad is a wonderful solution to inject dependencies into your functions. There are plenty of great resources to get your teeth into the `Reader`

monad such as these great talks.

The `Reader`

monad provides a way to “weave” your configuration throughout your programme.

Say you had this function which requires configuration:

```
function createPrettyName(name, printer) {
return printer.write("hello " + name)
}
```

Calling this function from other functions that don’t need the dependency `printer`

is kind of awkward.

```
function render(printer) {
return createPrettyName("Tom", printer)
}
```

One quick win would be to `curry`

the `createPrettyName`

function, and make `render`

partially apply the function and let the caller of `render`

supply the printer.

```
function createPrettyName(name, printer) {
return printer.write("hello " + name)
}.curry()
function render() {
return createPrettyName("Tom")
}
```

This is better, but what if `render`

wants to perform some sort of operation on the result of `createPrettyName`

? It would have to apply the final parameter (i.e. the `printer`

) before `createPrettyName`

would execute.

This where the `Reader`

monad comes in. We could rewrite `createPrettyName`

thusly:

```
function createPrettyName(name) {
return Reader(function(printer) {
return printer.write("hello " + name)
})
}
```

To sweeten up the syntax a little we can also write:

```
function createPrettyName(name, printer) {
return printer.write("hello " + name)
}.reader()
```

So now, when a name is supplied to `createPrettyName`

the `Reader`

monad is returned and being a monad it supports all the monadic goodness.

We can now get access to the result of `createPrettyName`

through a `map`

.

```
function reader() {
return createPrettyName("Tom").map(function (s) { return "---"+s+"---"})
}
```

The top level of our programme would co-ordinate the injecting of the dependency by calling `run`

on the resulting `Reader.`

`reader().run(new BoldPrinter())`

`Reader[A].map(f: A -> B): Reader[B]`

Maps the supplied function over the `Reader`

.

`Reader[A].bind(f: A -> Reader[B]): Reader[B]`

Performs a monadic bind over the `Reader`

.

`Reader[A].ap(a: Reader[A->B]): Reader[B]`

Applies the function inside the supplied `Reader`

to the value `A`

in the outer `Reader`

. Applicative Functor pattern.

`Reader[A].run(config)`

Executes the function wrapped in the `Reader`

with the supplied `config`

.

The `Free`

monad is a monad that is able to separate instructions from their interpreter. There are many applications for this monad, and one of them is for implementing Trampolines, (which is a way to make recursion constant stack for languages that don’t support tail call elimination, like JavaScript!).

Please see Ken Scambler’s excellent talk and example project to get an in-depth understanding of this very useful monad.

The `Free`

monad has two constructors, `Suspend`

and `Return`

, which represents the continuation of a calculation and the completion of one, respectively.

```
Return(a: A): Free[F[_], A]
Suspend(f: F[Free[F,A]]): Free[F[_], A]
var a = Return(1)
var sum = Suspend(Identity(Return(1))
// or
var sum = Free.liftF(Identity(1))
```

As you may see, `Return`

wraps a value A, where as `Suspend`

, wraps a `Functor`

containing another `Free`

.

`Free[F[_], A].map(f: A -> B): Free[F[_],B]`

Performs a map across the value inside the functor.

`Free[F[_],A].bind(f: A -> Free[F[_], B]): Free[F[_],B]`

Performs a monadic bind over the `Free`

.

`Free.liftF(F[A]): Free[F,A]`

Lifts a Funtor `F`

into a `Free`

.

`Free[F[_],A].resume(): Either[F[Free[F,A]] , A]`

Evalutates a single layer in the computation, returning either a suspension or a result.

`Free[F[_],A].go(f: F[Free[F, A]] -> Free[F, A]) : A`

Runs the computation to the end, returning the final result, using the supplied functor `f`

to extract the next `Free`

from the suspension.

`Free[Function, A].run(): A`

This function only makes sense for Tampolined computations where the supplied functor is a Function. This will run the computation to the end returning the result `A`

.

Function composition. `f.compose(g)`

is equivalent to:

```
function compose(x) {
return f(g(x))
}
```

Function composition flipped. `f.andThen(g)`

is equivalent to:

```
function compose(x) {
return g(f(x))
}
```

This method on function will curry that function so that it can be partially applied. This implementation is quite flexible and allows a method to be applied in the following ways:

```
var sum = function(a,b,c) {
return a+b+c
}.curry()
sum(1) // will return a function that takes b and c
sum(1,2)
//or
sum(1)(2) // will return a function that takes c
sum(1,2,3)
//or
sum(1)(2)(3)
//or
sum(1,2)(3)
//or
sum(1)(2,3)
// or nearly any other combination...
// will return 6
```

Written and maintained by Chris Myers @cwmyers. Follow Monet.js at @monetjs.