Simplify recover, and catch APIs. Add getOrElse

[nomisRev]

Draft changes related to #2948 to facilitate the discussion. Also closes #2953

cc\ @freynder

Description about changes (copied from comments in #2948)

The lambda Raise<R>.() -> A allows to bind, or unwrap, Option and in the case None is encountered it will invoke the lambda. The lambda allows to raise a value of R into the outer interface Raise<R>, or fallback to a value of A.

1. The Raise<R> lambda receiver is redundant because we're already inside the context of interface Raise<R>, so even without the lambda receiver we can call raise(r).
2. Without Raise<R>, we have () -> A which matches the already existing Option API of getOrElse.
3. Since this function is defined inside of an interface, it cannot be inline so it's inferior to the already existing getOrElse which is inline and thus allows for suspend to pass through.

So this API can be completely replaced by getOrElse and simplifies the examples of the KDoc above.

suspend fun test() {
  val empty: Option<Int> = None
  either {
-    val x: Int = empty.bind { _: None -> 1 }
+    val x: Int = empty.getOrElse { 1 }
-    val y: Int = empty.bind { _: None -> raise("Something bad happened: Boom!") }
+    val y: Int = empty.getOrElse { raise("Something bad happened: Boom!") }
-    val z: Int = empty.recover { _: None ->
+    val z: Int = empty.getOrElse {
      delay(10)
      1
-    }.bind { raise("Something bad happened: Boom!") }
+   }
    x + y + z
  } shouldBe Either.Left("Something bad happened: Boom!")
}

As the example shows we can now call suspend fun delay directly into the getOrElse lambda, and we can also still call raise & co from inside the getOrElse lambda.

The same applies for Result#bind. Since none of this code has yet been released, we can still remove these APIs in favour of the simpler inline methods on the original APIs. Fixing this issue also requires some other small changes in Builders.kt.

---

There is multiple benefits to this actually, and we should review the current signatures in arrow.core.raise.* to see how we can simplify them.

Looking for example at recover:

@RaiseDSL
- public inline fun <R, E, A> Raise<R>.recover(
+ public inline fun <E, A> recover(
  @BuilderInference action: Raise<E>.() -> A,
-  @BuilderInference recover: Raise<R>.(E) -> A,
+  recover: (E) -> A,
): A {
  contract {
    callsInPlace(action, EXACTLY_ONCE)
    callsInPlace(recover, AT_MOST_ONCE)
  }
  return fold<E, A, A>({ action(this) }, { throw it }, { recover(it) }, { it })
}

Besides still supporting the current use-cases it also makes this function more general purpose, because you can now use it to execute Raise<E> based programs and resolve the error completely without having to stick to Raise<E>.

---

[github-actions]

Kover Report

File	Coverage [68.95%]
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/Option.kt	52.56%
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/raise/Builders.kt	97.92%
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/raise/Effect.kt	66.67%
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/raise/ErrorHandlers.kt	95.65%
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/raise/Fold.kt	100.00%
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/raise/Mappers.kt	100.00%
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/raise/Raise.kt	70.00%

Total Project Coverage	43.85%

[nomisRev]

This also what we usedand needed in Gh Alerts Project to wrap side-effect APIs like PSQLException -> UserAlreadyExists and would allow easily writing type-safe integration libraries for JDBC or PSQL.

Wondering if this should be on Raise companion similar to Either.catch 🤔 They're basically the duality of each-other. Similarly, does Either.catch need a reified variant?

[kyay10]

Raise sort of feels like much more of a primitive than Either, and thus it feels like catch makes more sense than Raise.catch. The name Raise.catch also just feels weird from a language standpoint

[nomisRev]

Raise sort of feels like much more of a primitive than Either

It absolutely is!

The name Raise.catch also just feels weird from a language standpoint

Thanks for the feedback ☺️ catch is also applicable outside of Raise, so that makes sense!

[serras]

Amazing simplification!

[raulraja]

Looks great @nomisRev !

[nomisRev]

Merging this PR, all feedback and suggestions are still very welcome 🙏