Add Monoidal type class (#1327)

* Add Monoidal type class

* Add Monoidal instances

* Add Monoidal documentation

* Run Semigroupal test in Monoidal tests

* Fix Monoidal documentation

* Remove unused import

Author: juliankotrba

modules/core/arrow-core-data/src/test/kotlin/arrow/core/OptionTest.kt

@@ -8,7 +8,7 @@ import arrow.core.extensions.option.applicative.applicative
 import arrow.core.extensions.option.eq.eq
 import arrow.core.extensions.option.hash.hash
 import arrow.core.extensions.option.monoid.monoid
-import arrow.core.extensions.option.semigroupal.semigroupal
+import arrow.core.extensions.option.monoidal.monoidal
 import arrow.core.extensions.option.show.show
 import arrow.core.extensions.tuple2.eq.eq
 import arrow.mtl.extensions.option.monadFilter.monadFilter
@@ -49,7 +49,7 @@ class OptionTest : UnitSpec() {
       TraverseFilterLaws.laws(Option.traverseFilter(), Option.applicative(), ::Some, Eq.any()),
       MonadFilterLaws.laws(Option.monadFilter(), ::Some, Eq.any()),
       HashLaws.laws(Option.hash(Int.hash()), Option.eq(Int.eq())) { it.some() },
-      SemigroupalLaws.laws(Option.semigroupal(), ::Some, ::bijection, associativeSemigroupalEq)
+      MonoidalLaws.laws(Option.monoidal(), ::Some, Eq.any(), ::bijection, associativeSemigroupalEq)
     )
 
     "fromNullable should work for both null and non-null values of nullable types" {

modules/core/arrow-core-extensions/src/main/kotlin/arrow/core/extensions/option.kt

@@ -32,6 +32,11 @@ interface OptionSemigroupal : Semigroupal<ForOption> {
     fb.fix().ap(this.map { a:A -> { b: B -> Tuple2(a,b)} })
 }
 
+@extension
+interface OptionMonoidal : Monoidal<ForOption>, OptionSemigroupal {
+  override fun <A> identity(): Kind<ForOption, A> = None
+}
+
 @extension
 interface OptionMonoid<A> : Monoid<Option<A>>, OptionSemigroup<A> {
   override fun SG(): Semigroup<A>

modules/core/arrow-extras-data/src/test/kotlin/arrow/data/ListKTest.kt

@@ -10,8 +10,8 @@ import arrow.data.extensions.listk.applicative.applicative
 import arrow.data.extensions.listk.eq.eq
 import arrow.data.extensions.listk.hash.hash
 import arrow.data.extensions.listk.monoidK.monoidK
+import arrow.data.extensions.listk.monoidal.monoidal
 import arrow.data.extensions.listk.semigroupK.semigroupK
-import arrow.data.extensions.listk.semigroupal.semigroupal
 import arrow.data.extensions.listk.show.show
 import arrow.data.extensions.listk.traverse.traverse
 import arrow.mtl.extensions.listk.monadCombine.monadCombine
@@ -34,7 +34,7 @@ class ListKTest : UnitSpec() {
     testLaws(
       ShowLaws.laws(ListK.show(), eq) { listOf(it).k() },
       SemigroupKLaws.laws(ListK.semigroupK(), applicative, Eq.any()),
-      SemigroupalLaws.laws(ListK.semigroupal(), { ListK.just(it) }, this::bijection, associativeSemigroupalEq),
+      MonoidalLaws.laws(ListK.monoidal(), applicative, ListK.eq(Tuple2.eq(Int.eq(), Int.eq())), this::bijection, associativeSemigroupalEq),
       MonoidKLaws.laws(ListK.monoidK(), applicative, Eq.any()),
       TraverseLaws.laws(ListK.traverse(), applicative, { n: Int -> ListK(listOf(n)) }, Eq.any()),
       MonadCombineLaws.laws(ListK.monadCombine(),

modules/core/arrow-extras-data/src/test/kotlin/arrow/data/SequenceKTest.kt

@@ -10,7 +10,7 @@ import arrow.data.extensions.sequencek.hash.hash
 import arrow.data.extensions.sequencek.monad.monad
 import arrow.data.extensions.sequencek.monoid.monoid
 import arrow.data.extensions.sequencek.monoidK.monoidK
-import arrow.data.extensions.sequencek.semigroupal.semigroupal
+import arrow.data.extensions.sequencek.monoidal.monoidal
 import arrow.data.extensions.sequencek.traverse.traverse
 import arrow.test.UnitSpec
 import arrow.test.generators.sequenceK
@@ -36,6 +36,11 @@ class SequenceKTest : UnitSpec() {
         this.toList() == b.toList()
     }
 
+    val tuple2Eq: Eq<Kind<ForSequenceK, Tuple2<Int, Int>>> = object : Eq<Kind<ForSequenceK, Tuple2<Int, Int>>> {
+      override fun Kind<ForSequenceK, Tuple2<Int, Int>>.eqv(b: Kind<ForSequenceK, Tuple2<Int, Int>>): Boolean =
+              toList() == b.toList()
+    }
+
     val show: Show<Kind<ForSequenceK, Int>> = object : Show<Kind<ForSequenceK, Int>> {
       override fun Kind<ForSequenceK, Int>.show(): String =
         toList().toString()
@@ -46,7 +51,7 @@ class SequenceKTest : UnitSpec() {
       MonadLaws.laws(SequenceK.monad(), eq),
       MonoidKLaws.laws(SequenceK.monoidK(), SequenceK.applicative(), eq),
       MonoidLaws.laws(SequenceK.monoid(), Gen.sequenceK(Gen.int()), eq),
-      SemigroupalLaws.laws(SequenceK.semigroupal(), { SequenceK.just(it) }, this::bijection, associativeSemigroupalEq),
+      MonoidalLaws.laws(SequenceK.monoidal(), { SequenceK.just(it) }, tuple2Eq, this::bijection, associativeSemigroupalEq),
       TraverseLaws.laws(SequenceK.traverse(), SequenceK.applicative(), { n: Int -> SequenceK(sequenceOf(n)) }, eq),
       HashLaws.laws(SequenceK.hash(Int.hash()), SequenceK.eq(Int.eq())) { sequenceOf(it).k() }
     )

modules/core/arrow-extras-data/src/test/kotlin/arrow/data/SetKTest.kt

@@ -9,8 +9,8 @@ import arrow.data.extensions.setk.eq.eq
 import arrow.data.extensions.setk.foldable.foldable
 import arrow.data.extensions.setk.hash.hash
 import arrow.data.extensions.setk.monoidK.monoidK
+import arrow.data.extensions.setk.monoidal.monoidal
 import arrow.data.extensions.setk.semigroupK.semigroupK
-import arrow.data.extensions.setk.semigroupal.semigroupal
 import arrow.data.extensions.setk.show.show
 import arrow.test.UnitSpec
 import arrow.test.laws.*
@@ -36,7 +36,7 @@ class SetKTest : UnitSpec() {
     testLaws(
       ShowLaws.laws(SetK.show(), EQ) { SetK.just(it) },
       SemigroupKLaws.laws(SetK.semigroupK(), { SetK.just(it) }, Eq.any()),
-      SemigroupalLaws.laws(SetK.semigroupal(), { SetK.just(it) }, this::bijection, associativeSemigroupalEq),
+      MonoidalLaws.laws(SetK.monoidal(), { SetK.just(it) }, Eq.any(), this::bijection, associativeSemigroupalEq),
       MonoidKLaws.laws(SetK.monoidK(), { SetK.just(it) }, Eq.any()),
       FoldableLaws.laws(SetK.foldable(), { SetK.just(it) }, Eq.any()),
       HashLaws.laws(SetK.hash(Int.hash()), SetK.eq(Int.eq())) { SetK.just(it) }

modules/core/arrow-extras-extensions/src/main/kotlin/arrow/data/extensions/listk.kt

@@ -135,6 +135,11 @@ interface ListKSemigroupal : Semigroupal<ForListK> {
     fb.fix().ap(this.map { a:A -> { b: B -> Tuple2(a,b)} })
 }
 
+@extension
+interface ListKMonoidal : Monoidal<ForListK>, ListKSemigroupal {
+  override fun <A> identity(): Kind<ForListK, A> = ListK.empty()
+}
+
 @extension
 interface ListKMonoidK : MonoidK<ForListK> {
   override fun <A> empty(): ListK<A> =

modules/core/arrow-extras-extensions/src/main/kotlin/arrow/data/extensions/sequence.kt

@@ -23,6 +23,11 @@ interface SequenceKSemigroupal : Semigroupal<ForSequenceK> {
     fb.fix().ap(this.map { a: A -> { b: B -> Tuple2(a, b)} })
 }
 
+@extension
+interface SequenceKMonoidal : Monoidal<ForSequenceK>, SequenceKSemigroupal {
+  override fun <A> identity(): Kind<ForSequenceK, A> = SequenceK.empty()
+}
+
 @extension
 interface SequenceKMonoid<A> : Monoid<SequenceK<A>> {
   override fun SequenceK<A>.combine(b: SequenceK<A>): SequenceK<A> = (this.sequence + b.sequence).k()

modules/core/arrow-extras-extensions/src/main/kotlin/arrow/data/extensions/setk.kt

@@ -66,6 +66,11 @@ interface SetKSemigroupal: Semigroupal<ForSetK> {
     fb.fix().flatMap { b -> this.fix().map { a -> Tuple2(a,b) } }.toSet().k()
 }
 
+@extension
+interface SetKMonoidal : Monoidal<ForSetK>, SetKSemigroupal {
+  override fun <A> identity(): Kind<ForSetK, A> = SetK.empty()
+}
+
 @extension
 interface SetKMonoidK : MonoidK<ForSetK> {
   override fun <A> empty(): SetK<A> =

modules/core/arrow-test/src/main/kotlin/arrow/test/laws/MonoidalLaws.kt

@@ -0,0 +1,46 @@
+package arrow.test.laws
+
+import arrow.Kind
+import arrow.core.Tuple2
+import arrow.typeclasses.Applicative
+import arrow.typeclasses.Eq
+import arrow.typeclasses.Monoidal
+import io.kotlintest.properties.Gen
+import io.kotlintest.properties.forAll
+
+object MonoidalLaws {
+
+  fun <F> laws(
+          MDAL: Monoidal<F>,
+          AP: Applicative<F>,
+          EQ: Eq<Kind<F,  Tuple2<Int, Int>>>,
+          BIJECTION: (Kind<F, Tuple2<Tuple2<Int, Int>, Int>>) -> (Kind<F, Tuple2<Int, Tuple2<Int, Int>>>),
+          ASSOCIATIVE_SEMIGROUPAL_EQ: Eq<Kind<F, Tuple2<Int, Tuple2<Int, Int>>>>
+  ): List<Law> =
+    SemigroupalLaws.laws(MDAL, AP::just, BIJECTION, ASSOCIATIVE_SEMIGROUPAL_EQ) + listOf(
+      Law("Monoidal Laws: Left identity") { MDAL.monoidalLeftIdentity(AP::just, EQ) },
+      Law("Monoidal Laws: Right identity") { MDAL.monoidalRightIdentity(AP::just, EQ) }
+    )
+
+  fun <F> laws(
+          MDAL: Monoidal<F>,
+          f: (Int) -> Kind<F, Int>,
+          EQ: Eq<Kind<F, Tuple2<Int, Int>>>,
+          BIJECTION: (Kind<F, Tuple2<Tuple2<Int, Int>, Int>>) -> (Kind<F, Tuple2<Int, Tuple2<Int, Int>>>),
+          ASSOCIATIVE_SEMIGROUPAL_EQ: Eq<Kind<F, Tuple2<Int, Tuple2<Int, Int>>>>
+  ): List<Law> =
+    SemigroupalLaws.laws(MDAL, f, BIJECTION, ASSOCIATIVE_SEMIGROUPAL_EQ) + listOf(
+      Law("Monoidal Laws: Left identity") { MDAL.monoidalLeftIdentity(f, EQ) },
+      Law("Monoidal Laws: Right identity") { MDAL.monoidalRightIdentity(f, EQ) }
+    )
+
+  private fun <F> Monoidal<F>.monoidalLeftIdentity(f: (Int) -> Kind<F, Int>, EQ: Eq<Kind<F, Tuple2<Int, Int>>>): Unit =
+    forAll(Gen.int().map(f)) { fa: Kind<F, Int> ->
+      identity<Int>().product(fa).equalUnderTheLaw(identity(), EQ)
+    }
+
+  private fun <F> Monoidal<F>.monoidalRightIdentity(f: (Int) -> Kind<F, Int>, EQ: Eq<Kind<F, Tuple2<Int, Int>>>): Unit =
+    forAll(Gen.int().map(f)) { fa: Kind<F, Int> ->
+      fa.product(identity<Int>()).equalUnderTheLaw(identity(), EQ)
+    }
+}

modules/core/arrow-typeclasses/src/main/kotlin/arrow/typeclasses/Monoidal.kt

@@ -0,0 +1,107 @@
+package arrow.typeclasses
+
+import arrow.Kind
+import arrow.core.Option
+
+/**
+ * ank_macro_hierarchy(arrow.typeclasses.Monoidal)
+ *
+ * The [Monoidal] type class adds an identity element to the [Semigroupal] type class by defining the function [identity].
+ *
+ * [identity] returns a specific identity `Kind<F, A>` value for a given type [F] and [A].
+ *
+ * This type class complies with the following law:
+ *
+ * ```kotlin
+ * fa.product(identity) == identity.product(fa) == identity
+ * ```
+ *
+ * In addition, the laws of the [Semigroupal] type class also apply.
+ *
+ * Currently, [Monoidal] instances are defined for [Option], [ListK], [SequenceK] and [SetK].
+ *
+ * ### Examples
+ *
+ * ```kotlin:ank:playground:extension
+ * _imports_
+ *
+ * fun main(args: Array<String>) {
+ *   val result =
+ *   //sampleStart
+ *   _extensionFactory_
+ *   //sampleEnd
+ *   println(result)
+ * }
+ * ```
+ *
+ * The following examples show the identity elements for the already defined [Monoidal] instances:
+ *
+ * ```kotlin:ank:playground
+ * import arrow.core.Option
+ * import arrow.core.extensions.option.monoidal.monoidal
+ *
+ * fun main(args: Array<String>) {
+ *   val result =
+ *   //sampleStart
+ *   Option.monoidal().run {
+ *     identity<Any>()
+ *   }
+ *   //sampleEnd
+ *   println(result)
+ * }
+ * ```
+ *
+ * ```kotlin:ank:playground
+ * import arrow.data.ListK
+ * import arrow.data.extensions.listk.monoidal.monoidal
+ *
+ * fun main(args: Array<String>) {
+ *   val result =
+ *   //sampleStart
+ *   ListK.monoidal().run {
+ *     identity<Any>()
+ *   }
+ *   //sampleEnd
+ *   println(result)
+ * }
+ * ```
+ *
+ * ```kotlin:ank:playground
+ * import arrow.data.SetK
+ * import arrow.data.extensions.setk.monoidal.monoidal
+ *
+ * fun main(args: Array<String>) {
+ *   val result =
+ *   //sampleStart
+ *   SetK.monoidal().run {
+ *     identity<Any>()
+ *   }
+ *   //sampleEnd
+ *   println(result)
+ * }
+ * ```
+ *
+ * ```kotlin:ank:playground
+ * import arrow.data.SequenceK
+ * import arrow.data.extensions.sequencek.monoidal.monoidal
+ *
+ * fun main(args: Array<String>) {
+ *   val result =
+ *   //sampleStart
+ *   SequenceK.monoidal().run {
+ *     identity<Any>()
+ *   }
+ *   //sampleEnd
+ *   println(result)
+ * }
+ * ```
+ */
+interface Monoidal<F> : Semigroupal<F> {
+
+  /**
+   * Given a type [A], create an "identity" for a F<A> value.
+   */
+  fun <A> identity(): Kind<F, A>
+
+  companion object
+}