Added a resolve function to Either. (#237)

* Added a resolve function to Either.

* Processed some review comments.

* Added docs for catch and resolve functions.

* Improved docs for the resolve function.

* Inlined catch and resolve functions.

* Changed the implementation of the resolve function to not use default values for function parameters so that all function parameters can be inlined.

* Changed the handleItSafely function into catchAndFlatten.

* Made small improvement to tests.

Author: joramnv

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/core/Either.kt

@@ -314,6 +314,121 @@ import arrow.typeclasses.Show
  * }
  * ```
  *
+ * ## Either.catch exceptions
+ *
+ * Sometimes you do need to interact with code that can potentially throw exceptions. In such cases, you should mitigate the possibility that an exception can be thrown. You can do so by using the `catch` function.
+ *
+ * Example:
+ *
+ * ```kotlin:ank:playground
+ * import arrow.core.Either
+ *
+ * //sampleStart
+ * fun potentialThrowingCode(): String = throw RuntimeException("Blow up!")
+ *
+ * suspend fun makeSureYourLogicDoesNotHaveSideEffects(): Either<Error, String> =
+ *   Either.catch { potentialThrowingCode() }.mapLeft { Error.SpecificError }
+ * //sampleEnd
+ * suspend fun main() {
+ *   println("makeSureYourLogicDoesNotHaveSideEffects().isLeft() = ${makeSureYourLogicDoesNotHaveSideEffects().isLeft()}")
+ * }
+ *
+ * sealed class Error {
+ *   object SpecificError : Error()
+ * }
+ * ```
+ *
+ * ## Resolve Either into one type of value
+ * In some cases you can not use Either as a value. For instance, when you need to respond to an HTTP request. To resolve Either into one type of value, you can use the resolve function.
+ * In the case of an HTTP endpoint you most often need to return some (framework specific) response object which holds the result of the request. The result can be expected and positive, this is the success flow.
+ * Or the result can be expected but negative, this is the error flow. Or the result can be unexpected and negative, in this case an unhandled exception was thrown.
+ * In all three cases, you want to use the same kind of response object. But probably you want to respond slightly different in each case. This can be achieved by providing specific functions for the success, error and throwable cases.
+ *
+ * Example:
+ *
+ * ```kotlin:ank:playground
+ * import arrow.core.Either
+ * import arrow.core.flatMap
+ * import arrow.core.left
+ * import arrow.core.right
+ *
+ * //sampleStart
+ * suspend fun httpEndpoint(request: String = "Hello?") =
+ *   Either.resolve(
+ *     f = {
+ *       if (request == "Hello?") "HELLO WORLD!".right()
+ *       else Error.SpecificError.left()
+ *     },
+ *     success = { a -> handleSuccess({ a: Any -> log(Level.INFO, "This is a: $a") }, a) },
+ *     error = { e -> handleError({ e: Any -> log(Level.WARN, "This is e: $e") }, e) },
+ *     throwable = { throwable -> handleThrowable({ throwable: Throwable -> log(Level.ERROR, "Log the throwable: $throwable.") }, throwable) },
+ *     unrecoverableState = { _ -> Unit.right() }
+ *   )
+ * //sampleEnd
+ * suspend fun main() {
+ *  println("httpEndpoint().status = ${httpEndpoint().status}")
+ * }
+ *
+ * @Suppress("UNUSED_PARAMETER")
+ * suspend fun <A> handleSuccess(log: suspend (a: A) -> Either<Throwable, Unit>, a: A): Either<Throwable, Response> =
+ *   Either.catch {
+ *     Response.Builder(HttpStatus.OK)
+ *       .header(CONTENT_TYPE, CONTENT_TYPE_APPLICATION_JSON)
+ *       .body(a)
+ *       .build()
+ *   }
+ *
+ * @Suppress("UNUSED_PARAMETER")
+ * suspend fun <E> handleError(log: suspend (e: E) -> Either<Throwable, Unit>, e: E): Either<Throwable, Response> =
+ *   createErrorResponse(HttpStatus.NOT_FOUND, ErrorResponse("$ERROR_MESSAGE_PREFIX $e"))
+ *
+ * suspend fun handleThrowable(log: suspend (throwable: Throwable) -> Either<Throwable, Unit>, throwable: Throwable): Either<Throwable, Response> =
+ *   log(throwable)
+ *     .flatMap { createErrorResponse(HttpStatus.INTERNAL_SERVER_ERROR, ErrorResponse("$THROWABLE_MESSAGE_PREFIX $throwable")) }
+ *
+ * suspend fun createErrorResponse(httpStatus: HttpStatus, errorResponse: ErrorResponse): Either<Throwable, Response> =
+ *   Either.catch {
+ *     Response.Builder(httpStatus)
+ *       .header(CONTENT_TYPE, CONTENT_TYPE_APPLICATION_JSON)
+ *       .body(errorResponse)
+ *       .build()
+ *   }
+ *
+ * suspend fun log(level: Level, message: String): Either<Throwable, Unit> =
+ *   Unit.right() // Should implement logging.
+ *
+ * enum class HttpStatus(val value: Int) { OK(200), NOT_FOUND(404), INTERNAL_SERVER_ERROR(500) }
+ *
+ * class Response private constructor(
+ *   val status: HttpStatus,
+ *   val headers: Map<String, String>,
+ *   val body: Any?
+ * ) {
+ *
+ *   data class Builder(
+ *     val status: HttpStatus,
+ *     var headers: Map<String, String> = emptyMap(),
+ *     var body: Any? = null
+ *   ) {
+ *     fun header(key: String, value: String) = apply { this.headers = this.headers + mapOf<String, String>(key to value) }
+ *     fun body(body: Any?) = apply { this.body = body }
+ *     fun build() = Response(status, headers, body)
+ *   }
+ * }
+ *
+ * val CONTENT_TYPE = "Content-Type"
+ * val CONTENT_TYPE_APPLICATION_JSON = "application/json"
+ * val ERROR_MESSAGE_PREFIX = "An error has occurred. The error is:"
+ * val THROWABLE_MESSAGE_PREFIX = "An exception was thrown. The exception is:"
+ * sealed class Error {
+ *   object SpecificError : Error()
+ * }
+ * data class ErrorResponse(val errorMessage: String)
+ * enum class Level { INFO, WARN, ERROR }
+ * ```
+ *
+ * There are far more use cases for the resolve function, the HTTP endpoint example is just one of them.
+ *
  * ## Syntax
  *
  * Either can also map over the `left` value with `mapLeft`, which is similar to map, but applies on left instances.
@@ -912,20 +1027,46 @@ sealed class Either<out A, out B> : EitherOf<A, B> {
     inline fun <L, R> conditionally(test: Boolean, ifFalse: () -> L, ifTrue: () -> R): Either<L, R> =
       if (test) right(ifTrue()) else left(ifFalse())
 
-    suspend fun <R> catch(f: suspend () -> R): Either<Throwable, R> =
+    suspend inline fun <R> catch(f: suspend () -> R): Either<Throwable, R> =
       try {
         f().right()
       } catch (t: Throwable) {
         t.nonFatalOrThrow().left()
       }
 
+    suspend inline fun <R> catchAndFlatten(f: suspend () -> Either<Throwable, R>): Either<Throwable, R> =
+      catch(f).fold({ it.left() }, { it })
+
     @Deprecated("Use catch with mapLeft instead", ReplaceWith("catch(f).mapLeft(fe)"))
     suspend fun <L, R> catch(fe: (Throwable) -> L, f: suspend () -> R): Either<L, R> =
       try {
         f().right()
       } catch (t: Throwable) {
         fe(t.nonFatalOrThrow()).left()
       }
+
+    /**
+     * The resolve function can resolve any suspended function that yields an Either into one type of value.
+     *
+     * @param f the function that needs to be resolved.
+     * @param success the function to apply if [f] yields a success of type [A].
+     * @param error the function to apply if [f] yields an error of type [E].
+     * @param throwable the function to apply if [f] throws a [Throwable].
+     * Throwing any [Throwable] in the [throwable] function will render the [resolve] function nondeterministic.
+     * @param unrecoverableState the function to apply if [resolve] is in an unrecoverable state.
+     * @return the result of applying the [resolve] function.
+     */
+    suspend inline fun <E, A, B> resolve(
+      f: suspend () -> Either<E, A>,
+      success: suspend (a: A) -> Either<Throwable, B>,
+      error: suspend (e: E) -> Either<Throwable, B>,
+      throwable: suspend (throwable: Throwable) -> Either<Throwable, B>,
+      unrecoverableState: suspend (throwable: Throwable) -> Either<Throwable, Unit>
+    ): B =
+      catch(f)
+        .fold({ t: Throwable -> throwable(t) }, { it.fold({ e: E -> catchAndFlatten { error(e) } }, { a: A -> catchAndFlatten { success(a) } }) })
+        .fold({ t: Throwable -> throwable(t) }, { b: B -> b.right() })
+        .fold({ t: Throwable -> unrecoverableState(t); throw t }, { b: B -> b })
   }
 }
 

arrow-libs/core/arrow-core-data/src/test/kotlin/arrow/core/EitherTest.kt

@@ -26,11 +26,17 @@ import arrow.core.extensions.monoid
 import arrow.core.extensions.order
 import arrow.core.extensions.show
 import arrow.core.test.UnitSpec
+import arrow.core.test.generators.any
 import arrow.core.test.generators.either
 import arrow.core.test.generators.genK
 import arrow.core.test.generators.genK2
 import arrow.core.test.generators.id
 import arrow.core.test.generators.intSmall
+import arrow.core.test.generators.suspendFunThatReturnsAnyLeft
+import arrow.core.test.generators.suspendFunThatReturnsAnyRight
+import arrow.core.test.generators.suspendFunThatReturnsEitherAnyOrAnyOrThrows
+import arrow.core.test.generators.suspendFunThatThrows
+import arrow.core.test.generators.suspendFunThatThrowsFatalThrowable
 import arrow.core.test.generators.throwable
 import arrow.core.test.laws.BicrosswalkLaws
 import arrow.core.test.laws.BifunctorLaws
@@ -48,6 +54,8 @@ import arrow.typeclasses.Eq
 import io.kotlintest.properties.Gen
 import io.kotlintest.properties.forAll
 import io.kotlintest.shouldBe
+import io.kotlintest.shouldThrow
+import kotlinx.coroutines.runBlocking
 
 class EitherTest : UnitSpec() {
 
@@ -238,5 +246,135 @@ class EitherTest : UnitSpec() {
       suspend fun loadFromNetwork(): Int = throw exception
       Either.catch { loadFromNetwork() } shouldBe Left(exception)
     }
+
+    "catchAndFlatten should return Right(result) when f does not throw" {
+      suspend fun loadFromNetwork(): Either<Throwable, Int> = Right(1)
+      Either.catchAndFlatten { loadFromNetwork() } shouldBe Right(1)
+    }
+
+    "catchAndFlatten should return Left(result) when f throws" {
+      val exception = Exception("Boom!")
+      suspend fun loadFromNetwork(): Either<Throwable, Int> = throw exception
+      Either.catchAndFlatten { loadFromNetwork() } shouldBe Left(exception)
+    }
+
+    "resolve should yield a result when deterministic functions are used as handlers" {
+      forAll(
+        Gen.suspendFunThatReturnsEitherAnyOrAnyOrThrows(),
+        Gen.any()
+      ) { f: suspend () -> Either<Any, Any>,
+          returnObject: Any ->
+
+        runBlocking {
+          val result =
+            Either.resolve(
+              f = f,
+              success = { a -> handleWithPureFunction(a, returnObject) },
+              error = { e -> handleWithPureFunction(e, returnObject) },
+              throwable = { t -> handleWithPureFunction(t, returnObject) },
+              unrecoverableState = ::handleWithPureFunction
+            )
+          result == returnObject
+        }
+      }
+    }
+
+    "resolve should throw a Throwable when a fatal Throwable is thrown" {
+      forAll(
+        Gen.suspendFunThatThrowsFatalThrowable(),
+        Gen.any()
+      ) { f: suspend () -> Either<Any, Any>,
+          returnObject: Any ->
+
+        runBlocking {
+          shouldThrow<Throwable> {
+            Either.resolve(
+              f = f,
+              success = { a -> handleWithPureFunction(a, returnObject) },
+              error = { e -> handleWithPureFunction(e, returnObject) },
+              throwable = { t -> handleWithPureFunction(t, returnObject) },
+              unrecoverableState = ::handleWithPureFunction
+            )
+          }
+        }
+        true
+      }
+    }
+
+    "resolve should yield a result when an exception is thrown in the success supplied function" {
+      forAll(
+        Gen.suspendFunThatReturnsAnyRight(),
+        Gen.any()
+      ) { f: suspend () -> Either<Any, Any>,
+          returnObject: Any ->
+
+        runBlocking {
+          val result =
+            Either.resolve(
+              f = f,
+              success = ::throwException,
+              error = { e -> handleWithPureFunction(e, returnObject) },
+              throwable = { t -> handleWithPureFunction(t, returnObject) },
+              unrecoverableState = ::handleWithPureFunction
+            )
+          result == returnObject
+        }
+      }
+    }
+
+    "resolve should yield a result when an exception is thrown in the error supplied function" {
+      forAll(
+        Gen.suspendFunThatReturnsAnyLeft(),
+        Gen.any()
+      ) { f: suspend () -> Either<Any, Any>,
+          returnObject: Any ->
+
+        runBlocking {
+          val result =
+            Either.resolve(
+              f = f,
+              success = { a -> handleWithPureFunction(a, returnObject) },
+              error = ::throwException,
+              throwable = { t -> handleWithPureFunction(t, returnObject) },
+              unrecoverableState = ::handleWithPureFunction
+            )
+          result == returnObject
+        }
+      }
+    }
+
+    "resolve should throw a Throwable when any exception is thrown in the throwable supplied function" {
+      forAll(
+        Gen.suspendFunThatThrows()
+      ) { f: suspend () -> Either<Any, Any> ->
+
+        runBlocking {
+          shouldThrow<Throwable> {
+            Either.resolve(
+              f = f,
+              success = ::throwException,
+              error = ::throwException,
+              throwable = ::throwException,
+              unrecoverableState = ::handleWithPureFunction
+            )
+          }
+        }
+        true
+      }
+    }
   }
 }
+
+@Suppress("RedundantSuspendModifier", "UNUSED_PARAMETER")
+suspend fun handleWithPureFunction(a: Any, b: Any): Either<Throwable, Any> =
+  b.right()
+
+@Suppress("RedundantSuspendModifier", "UNUSED_PARAMETER")
+suspend fun handleWithPureFunction(throwable: Throwable): Either<Throwable, Unit> =
+  Unit.right()
+
+@Suppress("RedundantSuspendModifier", "UNUSED_PARAMETER")
+private suspend fun <A> throwException(
+  a: A
+): Either<Throwable, Any> =
+  throw RuntimeException("An Exception is thrown while handling the result of the supplied function.")

arrow-libs/core/arrow-core-test/src/main/kotlin/arrow/core/test/generators/Generators.kt

@@ -31,6 +31,8 @@ import arrow.core.extensions.listk.semialign.semialign
 import arrow.core.extensions.sequencek.semialign.semialign
 import arrow.core.fix
 import arrow.core.k
+import arrow.core.left
+import arrow.core.right
 import arrow.core.toOption
 import arrow.typeclasses.Applicative
 import arrow.typeclasses.ApplicativeError
@@ -201,3 +203,41 @@ private fun <A, B, R> Gen<A>.alignWith(genB: Gen<B>, transform: (Ior<A, B>) -> R
         alignWith(this@alignWith.random().k(), genB.random().k(), transform)
       }.fix()
   }
+
+fun Gen.Companion.suspendFunThatReturnsEitherAnyOrAnyOrThrows(): Gen<suspend () -> Either<Any, Any>> =
+  oneOf(
+    suspendFunThatReturnsAnyRight(),
+    suspendFunThatReturnsAnyLeft(),
+    suspendFunThatThrows()
+  )
+
+fun Gen.Companion.suspendFunThatReturnsAnyRight(): Gen<suspend () -> Either<Any, Any>> =
+  any().map { suspend { it.right() } }
+
+fun Gen.Companion.suspendFunThatReturnsAnyLeft(): Gen<suspend () -> Either<Any, Any>> =
+  any().map { suspend { it.left() } }
+
+fun Gen.Companion.suspendFunThatThrows(): Gen<suspend () -> Either<Any, Any>> =
+  throwable().map { suspend { throw it } } as Gen<suspend () -> Either<Any, Any>>
+
+fun Gen.Companion.suspendFunThatThrowsFatalThrowable(): Gen<suspend () -> Either<Any, Any>> =
+  fatalThrowable().map { suspend { throw it } } as Gen<suspend () -> Either<Any, Any>>
+
+fun Gen.Companion.any(): Gen<Any> =
+  oneOf(
+    string() as Gen<Any>,
+    int() as Gen<Any>,
+    long() as Gen<Any>,
+    float() as Gen<Any>,
+    double() as Gen<Any>,
+    bool() as Gen<Any>,
+    uuid() as Gen<Any>,
+    file() as Gen<Any>,
+    localDate() as Gen<Any>,
+    localTime() as Gen<Any>,
+    localDateTime() as Gen<Any>,
+    period() as Gen<Any>,
+    throwable() as Gen<Any>,
+    fatalThrowable() as Gen<Any>,
+    unit() as Gen<Any>
+  )