Yep. You got it. Monads are compared with value equality, not reference equality below. The flatMap behavior has to obey some laws:
The Associative Law states that flatMapping two functions in sequential order is the same as flatMapping over a composition of those two functions:
Monad(fa).flatMap(f).flatMap(g) valueEquals Monad(fa).flatMap(g(f))
It also has a method called return/point/pure that comes from the inherited Applicative interface:
interface Applicative> {
pure: (arg: A): F
}
That return/pure/point followed by flatMap has to obey the Left Identity law in a monad for it to be a valid monad:
Monad(fa).pure(x).flatMap(f) valueEquals f(x)
The Right Identity law states that if we have a Monadic value and flatMap over the point/pure/return method we get a new monad that has value equal to the original monad:
m = Monad(fa)
Monad(fa).flatMap( (v) => Monad(fa).pure(v)) valueEquals m
Those are your unit tests that you have to perform on your monad instances. If they pass, your implementation is correct, and you can rely upon it.
These laws are so that the monad interface can be composed/extended correctly with other referentially transparent interfaces, like
Functor -provides map, the map must be associative, like flatMap);
Apply extends Functor - provides ap, or applyParallel that allows parallel mapping over collections that can be safely parallelized. ap has to be consistent with flatMap when an implementation has a monad instance -- that is if you map over a list in parallel, the list you get out should be the same as if you flatMapped over that same list using the same function, but wrapping List() around the result, which is sequential;
Applicative extends Apply - provides pure/point/return, which just constructs instances that are Applicatives from a given value;
Semigroup - provides combine/concat/++, allowing two items of the same type to be combined into a new value of that type; There may be many instances for a type of semigroup (Boolean has && and || for example);
Monoid extends Semigroup - provides empty, which is a value for a type when combined with another value for that type results in the other value (0 in integer addition, for example, an empty list in list concatenation, for another);
traverse - provides sequence, which flips the types of wrapped values (Maybe> becomes List> when sequence is called), traverse,F, A, B>(ga: G)(f: A => F): F> -- used to define sequence, foldRight, foldMap, foldLeft, etc;
And ApplicativeError - provides raiseError, A,ERRORTYPE>(t: ERRORTYPE): F and handleError, A>(fa: F)(f: ERRORTYPE => A) and catchNonFatal, ERRORTYPE, A>(f: () => A):F -- obviously these only work if your type has two members, one for success, and one for failure.