Test and document result.orElse, update Cats typeclasses docs, rename category implicits to arrow implicits

Author: MateuszKubuszok

chimney-cats/src/main/scala/io/scalaland/chimney/cats/CatsPartialTransformerImplicits.scala

@@ -9,7 +9,7 @@ import io.scalaland.chimney.PartialTransformer
 trait CatsPartialTransformerImplicits {
 
   /** @since 1.0.0 */
-  implicit final val catsCategoryForPartialTransformer
+  implicit final val catsArrowForPartialTransformer
       : ArrowChoice[PartialTransformer] & CommutativeArrow[PartialTransformer] =
     new ArrowChoice[PartialTransformer] with CommutativeArrow[PartialTransformer] {
       override def lift[A, B](f: A => B): PartialTransformer[A, B] = PartialTransformer.fromFunction(f)

chimney-cats/src/main/scala/io/scalaland/chimney/cats/CatsTotalTransformerImplicits.scala

@@ -7,7 +7,7 @@ import io.scalaland.chimney.Transformer
 trait CatsTotalTransformerImplicits {
 
   /** @since 1.0.0 */
-  implicit final val catsCategoryForTransformer: ArrowChoice[Transformer] & CommutativeArrow[Transformer] =
+  implicit final val catsArrowForTransformer: ArrowChoice[Transformer] & CommutativeArrow[Transformer] =
     new ArrowChoice[Transformer] with CommutativeArrow[Transformer] {
       override def lift[A, B](f: A => B): Transformer[A, B] = f(_)
 

chimney-cats/src/test/scala/io/scalaland/chimney/cats/PartialResultLaws.scala

@@ -29,6 +29,8 @@ class PartialResultLaws extends ChimneySpec with utils.ArbitraryUtils {
       UnorderedTraverseTests[partial.Result].unorderedTraverse[Int, Long, Double, Const[Unit, *], Const[Int, *]]
     )
     checkLawsAsTests(TraverseTests[partial.Result].traverse[Int, Long, Double, Byte, Const[Unit, *], Const[Int, *]])
+    checkLawsAsTests(SemigroupKTests[partial.Result].semigroupK[Int])
+    checkLawsAsTests(MonoidKTests[partial.Result].monoidK[Int])
     checkLawsAsTests(AlternativeTests[partial.Result].alternative[Int, String, Double])
   }
 }

chimney-cats/src/test/scala/io/scalaland/chimney/cats/PartialTransformerLaws.scala

@@ -32,6 +32,8 @@ class PartialTransformerLaws extends ChimneySpec with utils.ArbitraryUtils {
       MonadErrorTests[PartialTransformer[String, *], partial.Result.Errors].monadError[Int, String, Double]
     )
     checkLawsAsTests(CoflatMapTests[PartialTransformer[String, *]].coflatMap[Int, String, Double])
+    checkLawsAsTests(SemigroupKTests[PartialTransformer[String, *]].semigroupK[Int])
+    checkLawsAsTests(MonoidKTests[PartialTransformer[String, *]].monoidK[Int])
     checkLawsAsTests(AlternativeTests[PartialTransformer[String, *]].alternative[Int, String, Double])
   }
 

chimney/src/main/scala/io/scalaland/chimney/partial/Result.scala

@@ -140,6 +140,24 @@ sealed trait Result[+A] {
     case _: Result.Errors    => this.asInstanceOf[Result[B]]
   }
 
+  /** Prepends a [[io.scalaland.chimney.partial.PathElement]] to all errors represented by this result.
+    *
+    * @tparam B the element type of the returned result
+    * @param result lazy [[io.scalaland.chimney.partial.Result]] to compute as a fallback if this one has errors
+    * @return a [[io.scalaland.chimney.partial.Result]] with the first successful value or a failure combining errors
+    *         from both results
+    *
+    * @since 1.0.0
+    */
+  final def orElse[B >: A](result: => Result[B]): Result[B] = this match {
+    case _: Result.Value[?] => this
+    case e: Result.Errors =>
+      result match {
+        case r: Result.Value[?] => r
+        case e2: Result.Errors  => Result.Errors.merge(e, e2)
+      }
+  }
+
   /** Prepends a [[io.scalaland.chimney.partial.PathElement]] to all errors represented by this result.
     *
     * @param pathElement [[io.scalaland.chimney.partial.PathElement]] to be prepended

chimney/src/test/scala/io/scalaland/chimney/PartialResultSpec.scala

@@ -135,6 +135,38 @@ class PartialResultSpec extends ChimneySpec {
     result2.asErrorPathMessageStrings ==> Iterable("" -> """For input string: "error2"""")
   }
 
+  test("orElse fallbacks on another Result on error, aggregating errors if both Results fail") {
+    var used = false
+    val result = partial.Result.fromValue(1).orElse {
+      used = true
+      partial.Result.fromValue(2)
+    }
+    result.asOption ==> Some(1)
+    result.asEither ==> Right(1)
+    result.asErrorPathMessageStrings ==> Iterable()
+    used ==> false
+
+    var used2 = false
+    val result2 = partial.Result.fromEmpty[Int].orElse {
+      used2 = true
+      partial.Result.fromValue(2)
+    }
+    result2.asOption ==> Some(2)
+    result2.asEither ==> Right(2)
+    result2.asErrorPathMessageStrings ==> Iterable()
+    used2 ==> true
+
+    var used3 = false
+    val result3 = partial.Result.fromEmpty[Int].orElse {
+      used3 = true
+      partial.Result.fromEmpty[Int]
+    }
+    result3.asOption ==> None
+    result3.asEither.isLeft ==> true
+    result3.asErrorPathMessageStrings ==> Iterable("" -> """empty value""", "" -> """empty value""")
+    used3 ==> true
+  }
+
   test("fromFunction converts function into function returning Result") {
     partial.Result.fromFunction[Int, Int](_ * 2).apply(3) ==> partial.Result.fromValue(6)
   }

docs/docs/cookbook.md

@@ -295,20 +295,21 @@ Cats integration module contains the following utilities:
      - for `Transformer` type class:
         - `ArrowChoice[Transformer] & CommutativeArrow[Transformer]` (implementing also `Arrow`, `Choice`, `Category`,
           `Compose`, `Strong`, `Profunctor`)
-        - `[Source] => Monad[Transformer[Source, *]] with CoflatMap[Transformer[Source, *]]` (implementing also `Monad`,
-          `Applicative`, `Functor`)
+        - `[Source] => Monad[Transformer[Source, *]] & CoflatMap[Transformer[Source, *]]`
+          (implementing also `Monad`, `Applicative`, `Functor`)
         - `[Target] => Contravariant[Transformer[*, Target]]` (implementing also `Invariant`)
      - for `PartialTransformer` type class:
         - `ArrowChoice[PartialTransformer] & CommutativeArrow[PartialTransformer]` (implementing also `Arrow`, `Choice`,
           `Category`,`Compose`, `Strong`, `Profunctor`)
-        - `[Source] => MonadError[PartialTransformer[Source, *], partial.Result.Errors] with CoflatMap[PartialTransformer[Source, *]]`
-          (implementing also `Monad`, `Applicative`, `Functor`, `ApplicativeError`)
+        - `[Source] => MonadError[PartialTransformer[Source, *], partial.Result.Errors] & CoflatMap[PartialTransformer[Source, *]] & Alternative[PartialTransformer[Source, *]]`
+          (implementing also `Monad`, `Applicative`, `Functor`, `ApplicativeError`, `NonEmptyAlternative`, `MonoidK`,
+          `SemigroupK`)
         - `[Source] => Parallel[PartialTransformer[Source, *]]` (implementing also `NonEmptyParallel`)
         - `[Target] => Contravariant[Transformer[*, Target]]` (implementing also `Invariant`)
      - for `partial.Result` data type:
-        - `MonadError[partial.Result, partial.Result.Errors] & CoflatMap[partial.Result] & Traverse[partial.Result]`
+        - `MonadError[partial.Result, partial.Result.Errors] & CoflatMap[partial.Result] & Traverse[partial.Result] $ Alternative[partial.Result]`
           (implementing also `Monad`, `Applicative`, `Functor`, `ApplicativeError`, `UnorderedTraverse`, `Foldable`,
-          `UnorderedFoldable`, `Invariant[partial.Result]`, `Semigriupal[partial.Result]`, ...)
+          `UnorderedFoldable`, `Invariant`, `Semigriupal`, `NonEmptyAlternative`, `SemigroupK`, `MonoidK`)
         - `Parallel[partial.Result]` (implementing also`NonEmptyParallel`)
         - `Semigroup[partial.Result.Errors]`