derive ‘join’ from ‘chain’

index.js

@@ -1065,9 +1065,11 @@
 
   //# apFirst :: Apply f => (f a, f b) -> f a
   //.
-  //. Combine two effectful actions, keeping only the result of the first.
+  //. Combines two effectful actions, keeping only the result of the first.
   //. Equivalent to Haskell's `(<*)` function.
   //.
+  //. This function is derived from [`lift2`](#lift2).
+  //.
   //. See also [`apSecond`](#apSecond).
   //.
   //. ```javascript
@@ -1083,9 +1085,11 @@
 
   //# apSecond :: Apply f => (f a, f b) -> f b
   //.
-  //. Combine two effectful actions, keeping only the result of the second.
+  //. Combines two effectful actions, keeping only the result of the second.
   //. Equivalent to Haskell's `(*>)` function.
   //.
+  //. This function is derived from [`lift2`](#lift2).
+  //.
   //. See also [`apFirst`](#apFirst).
   //.
   //. ```javascript
@@ -1141,6 +1145,26 @@
     return Chain.methods.chain(chain)(f);
   };
 
+  //# join :: Chain m => m (m a) -> m a
+  //.
+  //. Removes one level of nesting from a nested monadic structure.
+  //.
+  //. This function is derived from [`chain`](#chain).
+  //.
+  //. ```javascript
+  //. > join([[1], [2], [3]])
+  //. [1, 2, 3]
+  //.
+  //. > join([[[1, 2, 3]]])
+  //. [[1, 2, 3]]
+  //.
+  //. > join(Identity(Identity(1)))
+  //. Identity(1)
+  //. ```
+  var join = function join(chain_) {
+    return chain(identity, chain_);
+  };
+
   //# chainRec :: ChainRec m => (TypeRep m, (a -> c, b -> c, a) -> m c, a) -> m b
   //.
   //. Function wrapper for [`fantasy-land/chainRec`][].
@@ -1319,6 +1343,7 @@
     apSecond: apSecond,
     of: of,
     chain: chain,
+    join: join,
     chainRec: chainRec,
     filter: filter,
     filterM: filterM,

test/index.js

@@ -621,6 +621,19 @@ test('chain', function() {
   eq(Z.chain(identity, Identity(Identity(0))), Identity(0));
 });
 
+test('join', function() {
+  eq(Z.join.length, 1);
+  eq(Z.join.name, 'join');
+
+  eq(Z.join([]), []);
+  eq(Z.join([[]]), []);
+  eq(Z.join([[[]]]), [[]]);
+  eq(Z.join([[1], [2], [3]]), [1, 2, 3]);
+  eq(Z.join([[[1, 2, 3]]]), [[1, 2, 3]]);
+  eq(Z.join(Identity(Identity(1))), Identity(1));
+  eq(Z.join(Identity(Identity(Identity(1)))), Identity(Identity(1)));
+});
+
 test('chainRec', function() {
   eq(Z.chainRec.length, 3);
   eq(Z.chainRec.name, 'chainRec');