Permalink
Find file Copy path
05e3cf4 Jun 18, 2018
4 contributors

Users who have contributed to this file

@ulfryk @tomecko @desfero @DanielFGray
408 lines (331 sloc) 9.26 KB

MonetJS documentation

A note on types

Well it's JavaScript - there ain't any

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.

Generic Types

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 As 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 As. Though of course you will have to keep track of the types yourself.

Functions

(a: A, b: B) => C

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

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

Anonymous functions

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,

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.

The Unit type

Some functions (or lambdas) do not take a parameter, and some do not return anything. This will be expressed as:

() => A

or

A => ()

All monads

Everything that is a monad in Monet will implement the following functions. The specific monads will be discussed in detail int their own sections.

bind

Aliases: flatMap, chain

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

Performs a monadic bind.

map

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

unit

Aliases: pure, of

Monad.unit(A): Monad[A]

ap

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

join

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

The inner and outer monads are the same type.

takeLeft

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))
// => Some(1)

Some(1).takeLeft(None())
// => None

None().takeLeft(Some(3))
// => None

takeRight

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))
// => Some(2)

Some(1).takeRight(None())
// => None

None().takeRight(Some(2))
// => None

static isInstance

MonadStatic.isInstance(m: Any): Boolean;

Checks if passed object is an instance of concrete Monet type.

static isOfType

MonadStatic.isInstance(m: Any): Boolean;

Checks if passed object is an instance of some similar type. This check is based on @@type property attached to constructor and/or every instance of every type holding a string of shape Monet/${name}. Its purpose is to enable checks with other JS libraries that also use same approach (e.g. https://github.com/ramda/ramda-fantasy, https://github.com/char0n/ramda-adjunct). This method is internally used in all types that extend Setoid in equals method.

Maybe

Either

Validation

List

Non Empty List

IO

Reader

Free

Other useful functions (monet-pimp)

Function

Object

  • cons
  • some
  • success
  • fail
  • right
  • left

Array

  • list