Add Traverse1 typeclass (#1577)

core/src/main/scala/cats/Traverse1.scala

@@ -0,0 +1,89 @@
+package cats
+
+import simulacrum.typeclass
+
+/**
+  * Traverse1, also known as Traversable1.
+  *
+  * `Traverse1` is like a non-empty `Traverse`. In addition to the traverse and sequence
+  * methods it provides traverse1 and sequence1 methods which require an `Apply` instance instead of `Applicative`.
+  */
+@typeclass trait Traverse1[F[_]] extends Traverse[F] with Reducible[F] {
+
+  /**
+    * Given a function which returns a G effect, thread this effect
+    * through the running of this function on all the values in F,
+    * returning an F[B] in a G context.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.implicits._
+    * scala> import cats.data.NonEmptyList
+    * scala> def countWords(words: List[String]): Map[String, Int] = words.groupBy(identity).mapValues(_.length)
+    * scala> NonEmptyList.of(List("How", "do", "you", "fly"), List("What", "do", "you", "do")).traverse1(countWords)
+    * res0: Map[String,cats.data.NonEmptyList[Int]] = Map(do -> NonEmptyList(1, 2), you -> NonEmptyList(1, 1))
+    * }}}
+    */
+  def traverse1[G[_]: Apply, A, B](fa: F[A])(f: A => G[B]): G[F[B]]
+
+  /**
+    * Thread all the G effects through the F structure to invert the
+    * structure from F[G[A]] to G[F[A]].
+    *
+    * Example:
+    * {{{
+    * scala> import cats.implicits._
+    * scala> import cats.data.NonEmptyList
+    * scala> val x = NonEmptyList.of(Map("do" -> 1, "you" -> 1), Map("do" -> 2, "you" -> 1))
+    * scala> val y = NonEmptyList.of(Map("How" -> 3, "do" -> 1, "you" -> 1), Map[String,Int]())
+    * scala> x.sequence1
+    * res0: Map[String,NonEmptyList[Int]] = Map(do -> NonEmptyList(1, 2), you -> NonEmptyList(1, 1))
+    * scala> y.sequence1
+    * res1: Map[String,NonEmptyList[Int]] = Map()
+    * }}}
+    */
+  def sequence1[G[_]: Apply, A](fga: F[G[A]]): G[F[A]] =
+    traverse1(fga)(identity)
+
+
+  /**
+    * A traverse1 followed by flattening the inner result.
+    *
+    * Example:
+    * {{{
+    * scala> import cats.implicits._
+    * scala> import cats.data.NonEmptyList
+    * scala> def countWords(words: List[String]): Map[String, Int] = words.groupBy(identity).mapValues(_.length)
+    * scala> val x = NonEmptyList.of(List("How", "do", "you", "fly"), List("What", "do", "you", "do"))
+    * scala> x.flatTraverse1(_.groupByNel(identity))
+    * res0: Map[String,cats.data.NonEmptyList[String]] = Map(do -> NonEmptyList(do, do, do), you -> NonEmptyList(you, you))
+    * }}}
+    */
+  def flatTraverse1[G[_], A, B](fa: F[A])(f: A => G[F[B]])(implicit G: Apply[G], F: FlatMap[F]): G[F[B]] =
+    G.map(traverse1(fa)(f))(F.flatten)
+
+  /**
+    * Thread all the G effects through the F structure and flatten to invert the
+    * structure from F[G[F[A]]] to G[F[A]].
+    *
+    * Example:
+    * {{{
+    * scala> import cats.implicits._
+    * scala> import cats.data.NonEmptyList
+    * scala> val x = NonEmptyList.of(Map(0 ->NonEmptyList.of(1, 2)), Map(0 -> NonEmptyList.of(3)))
+    * scala> val y: NonEmptyList[Map[Int, NonEmptyList[Int]]] = NonEmptyList.of(Map(), Map(1 -> NonEmptyList.of(3)))
+    * scala> x.flatSequence1
+    * res0: Map[Int,cats.data.NonEmptyList[Int]] = Map(0 -> NonEmptyList(1, 2, 3))
+    * scala> y.flatSequence1
+    * res1: Map[Int,cats.data.NonEmptyList[Int]] = Map()
+    * }}}
+    */
+  def flatSequence1[G[_], A](fgfa: F[G[F[A]]])(implicit G: Apply[G], F: FlatMap[F]): G[F[A]] =
+    G.map(traverse1(fgfa)(identity))(F.flatten)
+
+  override def traverse[G[_] : Applicative, A, B](fa: F[A])(f: (A) => G[B]): G[F[B]] =
+    traverse1(fa)(f)
+
+
+
+}

core/src/main/scala/cats/data/NonEmptyList.scala

@@ -365,9 +365,9 @@ object NonEmptyList extends NonEmptyListInstances {
 private[data] sealed trait NonEmptyListInstances extends NonEmptyListInstances0 {
 
   implicit val catsDataInstancesForNonEmptyList: SemigroupK[NonEmptyList] with Reducible[NonEmptyList]
-      with Comonad[NonEmptyList] with Traverse[NonEmptyList] with Monad[NonEmptyList] =
+      with Comonad[NonEmptyList] with Traverse1[NonEmptyList] with Monad[NonEmptyList] =
     new NonEmptyReducible[NonEmptyList, List] with SemigroupK[NonEmptyList] with Comonad[NonEmptyList]
-      with Traverse[NonEmptyList] with Monad[NonEmptyList] {
+      with Monad[NonEmptyList] with Traverse1[NonEmptyList] {
 
       def combineK[A](a: NonEmptyList[A], b: NonEmptyList[A]): NonEmptyList[A] =
         a concat b
@@ -394,7 +394,15 @@ private[data] sealed trait NonEmptyListInstances extends NonEmptyListInstances0
 
       def extract[A](fa: NonEmptyList[A]): A = fa.head
 
-      def traverse[G[_], A, B](fa: NonEmptyList[A])(f: A => G[B])(implicit G: Applicative[G]): G[NonEmptyList[B]] =
+      def traverse1[G[_], A, B](nel: NonEmptyList[A])(f: A => G[B])(implicit G: Apply[G]): G[NonEmptyList[B]] =
+        Foldable[List].reduceRightToOption[A, G[List[B]]](nel.tail)(a => G.map(f(a))(_ :: Nil)) { (a, lglb) =>
+          G.map2Eval(f(a), lglb)(_ :: _)
+        }.map {
+          case None => G.map(f(nel.head))(NonEmptyList(_, Nil))
+          case Some(gtail) => G.map2(f(nel.head), gtail)(NonEmptyList(_, _))
+        }.value
+
+      override def traverse[G[_], A, B](fa: NonEmptyList[A])(f: A => G[B])(implicit G: Applicative[G]): G[NonEmptyList[B]] =
         fa traverse f
 
       override def foldLeft[A, B](fa: NonEmptyList[A], b: B)(f: (B, A) => B): B =

core/src/main/scala/cats/data/NonEmptyVector.scala

@@ -189,9 +189,9 @@ final class NonEmptyVector[+A] private (val toVector: Vector[A]) extends AnyVal
 private[data] sealed trait NonEmptyVectorInstances {
 
   implicit val catsDataInstancesForNonEmptyVector: SemigroupK[NonEmptyVector] with Reducible[NonEmptyVector]
-    with Comonad[NonEmptyVector] with Traverse[NonEmptyVector] with Monad[NonEmptyVector] =
+    with Comonad[NonEmptyVector] with Traverse1[NonEmptyVector] with Monad[NonEmptyVector] =
     new NonEmptyReducible[NonEmptyVector, Vector] with SemigroupK[NonEmptyVector] with Comonad[NonEmptyVector]
-      with Traverse[NonEmptyVector] with Monad[NonEmptyVector] {
+      with Monad[NonEmptyVector] with Traverse1[NonEmptyVector] {
 
       def combineK[A](a: NonEmptyVector[A], b: NonEmptyVector[A]): NonEmptyVector[A] =
         a concatNev b
@@ -226,7 +226,15 @@ private[data] sealed trait NonEmptyVectorInstances {
 
       def extract[A](fa: NonEmptyVector[A]): A = fa.head
 
-      def traverse[G[_], A, B](fa: NonEmptyVector[A])(f: (A) => G[B])(implicit G: Applicative[G]): G[NonEmptyVector[B]] =
+      def traverse1[G[_], A, B](nel: NonEmptyVector[A])(f: A => G[B])(implicit G: Apply[G]): G[NonEmptyVector[B]] =
+        Foldable[Vector].reduceRightToOption[A, G[Vector[B]]](nel.tail)(a => G.map(f(a))(_ +: Vector.empty)) { (a, lglb) =>
+          G.map2Eval(f(a), lglb)(_ +: _)
+        }.map {
+          case None => G.map(f(nel.head))(NonEmptyVector(_, Vector.empty))
+          case Some(gtail) => G.map2(f(nel.head), gtail)(NonEmptyVector(_, _))
+        }.value
+
+      override def traverse[G[_], A, B](fa: NonEmptyVector[A])(f: (A) => G[B])(implicit G: Applicative[G]): G[NonEmptyVector[B]] =
         G.map2Eval(f(fa.head), Always(Traverse[Vector].traverse(fa.tail)(f)))(NonEmptyVector(_, _)).value
 
       override def foldLeft[A, B](fa: NonEmptyVector[A], b: B)(f: (B, A) => B): B =

core/src/main/scala/cats/data/OneAnd.scala

@@ -54,6 +54,10 @@ final case class OneAnd[F[_], A](head: A, tail: F[A]) {
   def forall(p: A => Boolean)(implicit F: Foldable[F]): Boolean =
     p(head) && F.forall(tail)(p)
 
+
+  def reduceLeft(f: (A, A) => A)(implicit F: Foldable[F]): A =
+    F.foldLeft(tail, head)(f)
+
   /**
    * Left-associative fold on the structure using f.
    */
@@ -94,7 +98,7 @@ final case class OneAnd[F[_], A](head: A, tail: F[A]) {
     s"OneAnd(${A.show(head)}, ${FA.show(tail)})"
 }
 
-private[data] sealed trait OneAndInstances extends OneAndLowPriority2 {
+private[data] sealed trait OneAndInstances extends OneAndLowPriority3 {
 
   implicit def catsDataEqForOneAnd[A, F[_]](implicit A: Eq[A], FA: Eq[F[A]]): Eq[OneAnd[F, A]] =
     new Eq[OneAnd[F, A]]{
@@ -221,4 +225,22 @@ private[data] trait OneAndLowPriority2 extends OneAndLowPriority1 {
     }
 }
 
+private[data] trait OneAndLowPriority3 extends OneAndLowPriority2 {
+  implicit def catsDataTraverse1ForOneAnd[F[_]](implicit F: Traverse[F], F2: MonadCombine[F]): Traverse1[OneAnd[F, ?]] =
+    new NonEmptyReducible[OneAnd[F, ?], F] with Traverse1[OneAnd[F, ?]] {
+      def traverse1[G[_], A, B](fa: OneAnd[F, A])(f: (A) => G[B])(implicit G: Apply[G]): G[OneAnd[F, B]] = {
+        import cats.syntax.cartesian._
+
+        fa.map(a => Apply[G].map(f(a))(OneAnd(_, F2.empty[B])))(F)
+          .reduceLeft(((acc, a) => (acc |@| a).map((x: OneAnd[F, B], y: OneAnd[F, B]) => x.combine(y))))
+      }
+
+      override def traverse[G[_], A, B](fa: OneAnd[F, A])(f: (A) => G[B])(implicit G: Applicative[G]): G[OneAnd[F, B]] = {
+        G.map2Eval(f(fa.head), Always(F.traverse(fa.tail)(f)))(OneAnd(_, _)).value
+      }
+
+      def split[A](fa: OneAnd[F, A]): (A, F[A]) = (fa.head, fa.tail)
+    }
+}
+
 object OneAnd extends OneAndInstances

core/src/main/scala/cats/package.scala

@@ -32,8 +32,8 @@ package object cats {
  * encodes pure unary function application.
  */
   type Id[A] = A
-  implicit val catsInstancesForId: Bimonad[Id] with Monad[Id] with Traverse[Id] with Reducible[Id] =
-    new Bimonad[Id] with Monad[Id] with Traverse[Id] with Reducible[Id] {
+  implicit val catsInstancesForId: Bimonad[Id] with Monad[Id] with Traverse1[Id] =
+    new Bimonad[Id] with Monad[Id] with Traverse1[Id] {
       def pure[A](a: A): A = a
       def extract[A](a: A): A = a
       def flatMap[A, B](a: A)(f: A => B): B = f(a)
@@ -51,7 +51,7 @@ package object cats {
       def foldLeft[A, B](a: A, b: B)(f: (B, A) => B) = f(b, a)
       def foldRight[A, B](a: A, lb: Eval[B])(f: (A, Eval[B]) => Eval[B]): Eval[B] =
         f(a, lb)
-      def traverse[G[_], A, B](a: A)(f: A => G[B])(implicit G: Applicative[G]): G[B] =
+      def traverse1[G[_], A, B](a: A)(f: A => G[B])(implicit G: Apply[G]): G[B] =
         f(a)
       override def foldMap[A, B](fa: Id[A])(f: A => B)(implicit B: Monoid[B]): B = f(fa)
       override def reduce[A](fa: Id[A])(implicit A: Semigroup[A]): A =

core/src/main/scala/cats/syntax/all.scala

@@ -42,6 +42,7 @@ trait AllSyntax
     with StrongSyntax
     with TraverseFilterSyntax
     with TraverseSyntax
+    with Traverse1Syntax
     with TupleSyntax
     with ValidatedSyntax
     with VectorSyntax

core/src/main/scala/cats/syntax/package.scala

@@ -41,6 +41,7 @@ package object syntax {
   object strong extends StrongSyntax
   object monadTrans extends MonadTransSyntax
   object traverse extends TraverseSyntax
+  object traverse1 extends Traverse1Syntax
   object traverseFilter extends TraverseFilterSyntax
   object tuple extends TupleSyntax
   object validated extends ValidatedSyntax

core/src/main/scala/cats/syntax/reducible.scala

@@ -1,6 +1,7 @@
 package cats
 package syntax
 
+
 trait ReducibleSyntax extends Reducible.ToReducibleOps {
   implicit final def catsSyntaxNestedReducible[F[_]: Reducible, G[_], A](fga: F[G[A]]): NestedReducibleOps[F, G, A] =
     new NestedReducibleOps[F, G, A](fga)
@@ -9,3 +10,4 @@ trait ReducibleSyntax extends Reducible.ToReducibleOps {
 final class NestedReducibleOps[F[_], G[_], A](val fga: F[G[A]]) extends AnyVal {
   def reduceK(implicit F: Reducible[F], G: SemigroupK[G]): G[A] = F.reduceK(fga)
 }
+

core/src/main/scala/cats/syntax/traverse1.scala

@@ -0,0 +1,4 @@
+package cats
+package syntax
+
+trait Traverse1Syntax extends Traverse1.ToTraverse1Ops

laws/src/main/scala/cats/laws/Traverse1Laws.scala

@@ -0,0 +1,73 @@
+package cats.laws
+
+
+import cats.{Apply, Id, Semigroup, Traverse1}
+import cats.data.{Const, Nested}
+import cats.syntax.traverse1._
+import cats.syntax.reducible._
+
+trait Traverse1Laws[F[_]] extends TraverseLaws[F] with ReducibleLaws[F] {
+  implicit override def F: Traverse1[F]
+
+  def traverse1Identity[A, B](fa: F[A], f: A => B): IsEq[F[B]] = {
+    fa.traverse1[Id, B](f) <-> F.map(fa)(f)
+  }
+
+  def traverse1SequentialComposition[A, B, C, M[_], N[_]](
+                                                          fa: F[A],
+                                                          f: A => M[B],
+                                                          g: B => N[C]
+                                                        )(implicit
+                                                          N: Apply[N],
+                                                          M: Apply[M]
+                                                        ): IsEq[Nested[M, N, F[C]]] = {
+
+    val lhs = Nested(M.map(fa.traverse1(f))(fb => fb.traverse1(g)))
+    val rhs = fa.traverse1[Nested[M, N, ?], C](a => Nested(M.map(f(a))(g)))
+    lhs <-> rhs
+  }
+
+  def traverse1ParallelComposition[A, B, M[_], N[_]](
+                                                     fa: F[A],
+                                                     f: A => M[B],
+                                                     g: A => N[B]
+                                                   )(implicit
+                                                     N: Apply[N],
+                                                     M: Apply[M]
+                                                   ): IsEq[(M[F[B]], N[F[B]])] = {
+    type MN[Z] = (M[Z], N[Z])
+    implicit val MN = new Apply[MN] {
+      def ap[X, Y](f: MN[X => Y])(fa: MN[X]): MN[Y] = {
+        val (fam, fan) = fa
+        val (fm, fn) = f
+        (M.ap(fm)(fam), N.ap(fn)(fan))
+      }
+      override def map[X, Y](fx: MN[X])(f: X => Y): MN[Y] = {
+        val (mx, nx) = fx
+        (M.map(mx)(f), N.map(nx)(f))
+      }
+      override def product[X, Y](fx: MN[X], fy: MN[Y]): MN[(X, Y)] = {
+        val (mx, nx) = fx
+        val (my, ny) = fy
+        (M.product(mx, my), N.product(nx, ny))
+      }
+    }
+    val lhs: MN[F[B]] = fa.traverse1[MN, B](a => (f(a), g(a)))
+    val rhs: MN[F[B]] = (fa.traverse1(f), fa.traverse1(g))
+    lhs <-> rhs
+  }
+
+  def reduceMapDerived[A, B](
+                            fa: F[A],
+                            f: A => B
+                          )(implicit B: Semigroup[B]): IsEq[B] = {
+    val lhs: B = fa.traverse1[Const[B, ?], B](a => Const(f(a))).getConst
+    val rhs: B = fa.reduceMap(f)
+    lhs <-> rhs
+  }
+}
+
+object Traverse1Laws {
+  def apply[F[_]](implicit ev: Traverse1[F]): Traverse1Laws[F] =
+    new Traverse1Laws[F] { def F: Traverse1[F] = ev }
+}

laws/src/main/scala/cats/laws/discipline/Traverse1Tests.scala

@@ -0,0 +1,59 @@
+package cats.laws.discipline
+
+
+import org.scalacheck.{Arbitrary, Cogen, Prop}
+import Prop.forAll
+import cats.{Applicative, Eq, Monoid, Traverse1}
+import cats.laws.Traverse1Laws
+
+
+trait Traverse1Tests[F[_]] extends TraverseTests[F] with ReducibleTests[F] {
+  def laws: Traverse1Laws[F]
+
+  def traverse1[G[_]: Applicative, A: Arbitrary, B: Arbitrary, C: Arbitrary, M: Arbitrary, X[_]: Applicative, Y[_]: Applicative](implicit
+    ArbFA: Arbitrary[F[A]],
+    ArbXB: Arbitrary[X[B]],
+    ArbYB: Arbitrary[Y[B]],
+    ArbYC: Arbitrary[Y[C]],
+    ArbFB: Arbitrary[F[B]],
+    ArbFGA: Arbitrary[F[G[A]]],
+    ArbGB: Arbitrary[G[B]],
+    CogenA: Cogen[A],
+    CogenB: Cogen[B],
+    CogenC: Cogen[C],
+    CogenM: Cogen[M],
+    M: Monoid[M],
+    MB: Monoid[B],
+    EqFA: Eq[F[A]],
+    EqFC: Eq[F[C]],
+    EqG: Eq[G[Unit]],
+    EqM: Eq[M],
+    EqA: Eq[A],
+    EqB: Eq[B],
+    EqXYFC: Eq[X[Y[F[C]]]],
+    EqXFB: Eq[X[F[B]]],
+    EqYFB: Eq[Y[F[B]]],
+    EqOptionA: Eq[Option[A]]
+  ): RuleSet = {
+    implicit def EqXFBYFB : Eq[(X[F[B]], Y[F[B]])] = new Eq[(X[F[B]], Y[F[B]])] {
+      override def eqv(x: (X[F[B]], Y[F[B]]), y: (X[F[B]], Y[F[B]])): Boolean =
+        EqXFB.eqv(x._1, y._1) && EqYFB.eqv(x._2, y._2)
+    }
+    new RuleSet {
+      def name: String = "traverse1"
+      def bases: Seq[(String, RuleSet)] = Nil
+      def parents: Seq[RuleSet] = Seq(traverse[A, B, C, M, X, Y], reducible[G, A, B])
+      def props: Seq[(String, Prop)] = Seq(
+        "traverse1 identity" -> forAll(laws.traverse1Identity[A, C] _),
+        "traverse1 sequential composition" -> forAll(laws.traverse1SequentialComposition[A, B, C, X, Y] _),
+        "traverse1 parallel composition" -> forAll(laws.traverse1ParallelComposition[A, B, X, Y] _),
+        "traverse1 derive reduceMap" -> forAll(laws.reduceMapDerived[A, M] _)
+      )
+    }
+  }
+}
+
+object Traverse1Tests {
+  def apply[F[_]: Traverse1]: Traverse1Tests[F] =
+    new Traverse1Tests[F] { def laws: Traverse1Laws[F] = Traverse1Laws[F] }
+}

tests/src/test/scala/cats/tests/NonEmptyListTests.scala

@@ -4,7 +4,7 @@ package tests
 import cats.kernel.laws.{GroupLaws, OrderLaws}
 
 import cats.data.NonEmptyList
-import cats.laws.discipline.{ComonadTests, SemigroupKTests, MonadTests, SerializableTests, TraverseTests, ReducibleTests}
+import cats.laws.discipline.{ComonadTests, SemigroupKTests, MonadTests, SerializableTests, Traverse1Tests, ReducibleTests}
 import cats.laws.discipline.arbitrary._
 
 class NonEmptyListTests extends CatsSuite {
@@ -14,8 +14,8 @@ class NonEmptyListTests extends CatsSuite {
 
   checkAll("NonEmptyList[Int]", OrderLaws[NonEmptyList[Int]].order)
 
-  checkAll("NonEmptyList[Int] with Option", TraverseTests[NonEmptyList].traverse[Int, Int, Int, Int, Option, Option])
-  checkAll("Traverse[NonEmptyList[A]]", SerializableTests.serializable(Traverse[NonEmptyList]))
+  checkAll("NonEmptyList[Int] with Option", Traverse1Tests[NonEmptyList].traverse1[Option, Int, Int, Int, Int, Option, Option])
+  checkAll("Traverse1[NonEmptyList[A]]", SerializableTests.serializable(Traverse1[NonEmptyList]))
 
   checkAll("NonEmptyList[Int]", ReducibleTests[NonEmptyList].reducible[Option, Int, Int])
   checkAll("Reducible[NonEmptyList]", SerializableTests.serializable(Reducible[NonEmptyList]))