From 435a1ce580cfeb08b5e23d890ce7dfe55af079d5 Mon Sep 17 00:00:00 2001
From: David Chambers <dc@davidchambers.me>
Date: Tue, 8 Nov 2016 12:27:14 +0100
Subject: [PATCH] =?UTF-8?q?derive=20=E2=80=98join=E2=80=99=20from=20?=
 =?UTF-8?q?=E2=80=98chain=E2=80=99?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 index.js      | 29 +++++++++++++++++++++++++++--
 test/index.js | 13 +++++++++++++
 2 files changed, 40 insertions(+), 2 deletions(-)

diff --git a/index.js b/index.js
index 9136647..35198bd 100644
--- a/index.js
+++ b/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,
diff --git a/test/index.js b/test/index.js
index 383f77f..4a96400 100644
--- a/test/index.js
+++ b/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');