Adding Monad#join, alias of flatMap(id())

Author: jnape

CHANGELOG.md

@@ -14,6 +14,7 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/).
 - `SortWith` for sorting an `Iterable` given a `Comparator` over its elements
 - `IO#externallyManaged`, for supplying an `IO` with externally-managed futures
 - test jar is now published
+- `Monad#join` static alias for `flatMap(id())`
 
 ### Fixed
 - issue where certain ways to compose `Effect`s unintentionally nullified the effect 

src/main/java/com/jnape/palatable/lambda/monad/Monad.java

@@ -1,9 +1,12 @@
 package com.jnape.palatable.lambda.monad;
 
+import com.jnape.palatable.lambda.functions.builtin.fn1.Id;
 import com.jnape.palatable.lambda.functor.Applicative;
 
 import java.util.function.Function;
 
+import static com.jnape.palatable.lambda.functions.builtin.fn1.Id.id;
+
 /**
  * Monads are {@link Applicative} functors that support a flattening operation to unwrap <code>M&lt;M&lt;A&gt;&gt;
  * -&gt; M&lt;A&gt;</code>. This flattening operation, coupled with {@link Applicative#zip(Applicative)}, gives rise to
@@ -53,7 +56,7 @@ default <B> Monad<B, M> fmap(Function<? super A, ? extends B> fn) {
      */
     @Override
     default <B> Monad<B, M> zip(Applicative<Function<? super A, ? extends B>, M> appFn) {
-        return appFn.<Monad<Function<? super A, ? extends B>, M>>coerce().flatMap(ab -> fmap(ab::apply));
+        return appFn.<Monad<Function<? super A, ? extends B>, M>>coerce().flatMap(this::fmap);
     }
 
     /**
@@ -71,4 +74,17 @@ default <B> Monad<B, M> discardL(Applicative<B, M> appB) {
     default <B> Monad<A, M> discardR(Applicative<B, M> appB) {
         return Applicative.super.discardR(appB).coerce();
     }
+
+    /**
+     * Convenience static method equivalent to {@link Monad#flatMap(Function) flatMap}{@link Id#id() (id())};
+     *
+     * @param mma  the outer monad
+     * @param <M>  the monad type
+     * @param <A>  the nested type parameter
+     * @param <MA> the nested monad
+     * @return the nested monad
+     */
+    static <M extends Monad, A, MA extends Monad<A, M>> MA join(Monad<? extends MA, M> mma) {
+        return mma.flatMap(id()).coerce();
+    }
 }

src/test/java/testsupport/traits/MonadLaws.java

@@ -12,6 +12,8 @@
 import static com.jnape.palatable.lambda.adt.Maybe.nothing;
 import static com.jnape.palatable.lambda.functions.builtin.fn1.Constantly.constantly;
 import static com.jnape.palatable.lambda.functions.builtin.fn1.Id.id;
+import static com.jnape.palatable.lambda.functions.builtin.fn1.Upcast.upcast;
+import static com.jnape.palatable.lambda.monad.Monad.join;
 import static java.util.Arrays.asList;
 
 public class MonadLaws<M extends Monad> implements Trait<Monad<?, M>> {
@@ -22,7 +24,8 @@ public void test(Monad<?, M> m) {
                 .<Function<Monad<?, M>, Maybe<String>>>foldMap(f -> f.apply(m), asList(
                         this::testLeftIdentity,
                         this::testRightIdentity,
-                        this::testAssociativity))
+                        this::testAssociativity,
+                        this::testJoin))
                 .peek(s -> {
                     throw new AssertionError("The following Monad laws did not hold for instance of " + m.getClass() + ": \n\t - " + s);
                 });
@@ -32,21 +35,29 @@ private Maybe<String> testLeftIdentity(Monad<?, M> m) {
         Object a = new Object();
         Fn1<Object, Monad<Object, M>> fn = id().andThen(m::pure);
         return m.pure(a).flatMap(fn).equals(fn.apply(a))
-                ? nothing()
-                : just("left identity (m.pure(a).flatMap(fn).equals(fn.apply(a)))");
+               ? nothing()
+               : just("left identity (m.pure(a).flatMap(fn).equals(fn.apply(a)))");
     }
 
     private Maybe<String> testRightIdentity(Monad<?, M> m) {
         return m.flatMap(m::pure).equals(m)
-                ? nothing()
-                : just("right identity: (m.flatMap(m::pure).equals(m))");
+               ? nothing()
+               : just("right identity: (m.flatMap(m::pure).equals(m))");
     }
 
     private Maybe<String> testAssociativity(Monad<?, M> m) {
         Fn1<Object, Monad<Object, M>> f = constantly(m.pure(new Object()));
         Function<Object, Monad<Object, M>> g = constantly(m.pure(new Object()));
         return m.flatMap(f).flatMap(g).equals(m.flatMap(a -> f.apply(a).flatMap(g)))
-                ? nothing()
-                : just("associativity: (m.flatMap(f).flatMap(g).equals(m.flatMap(a -> f.apply(a).flatMap(g))))");
+               ? nothing()
+               : just("associativity: (m.flatMap(f).flatMap(g).equals(m.flatMap(a -> f.apply(a).flatMap(g))))");
+    }
+
+    private Maybe<String> testJoin(Monad<?, M> m) {
+        Monad<Monad<Object, M>, M> mma = m.pure(m.fmap(upcast()));
+        boolean equals = mma.flatMap(id()).equals(join(mma));
+        return equals
+               ? nothing()
+               : just("join: (m.pure(m).flatMap(id())).equals(Monad.join(m.pure(m)))");
     }
 }