Add withError and (Eager)Effect.mapError

[kyay10]

Fixes #3053
I'm not sure if mapError is the best name for it, but withError felt weird as an extension on Effect. Also, mapError's transform parameter seems too "busy" with suspend and Raise. At least the Raise<OtherError> could be removed, but then someone wanted to call a function inside that raises OtherError, they'd need to wrap in either{ ... }.merge() or something along those lines, and so I figured exposing the Raise<OtherError> might help in that case. Maybe there should be a Raise builder that merges the error and result automatically? This could be helpful especially if they're subclasses of each other.

@CLOVIS-AI

[kyay10]

A merge builder looks very neat, and is dead-simple to make:

@RaiseDSL
public inline fun <A> merge(
  @BuilderInference block: Raise<A>.() -> A,
): A = recover(block, ::identity)

// Usage
val error = eagerEffect<Error, User> { raise(Error) }
val bool = false
val a = error.mapError { merge { if(bool) "some-failure" else raise("other-failure") } } // Raise(other-failure)

Maybe this should be a thing 👀. It's useful when you have a lot of functions that use Raise, and you want to also return a value of the same error that they might raise. It can also be very useful whenever Union types become a reality because then you'll get no boxing if the returned and raised types have no intersection (however, we should probably have a union builder then that has the return and error types separately inferred, but ultimately returning a union of them).

[hoc081098]

Nice, mapError is my favorite method when using Either, Effect should have it

[CLOVIS-AI]

What is the use-case for mapError?

• withError: simple 1-1 pure mapping between error types
• recover: error management, as complex as you'd like

mapError's lambda being both Raise<OtherError> and -> OtherError seems confusing to me. Raise<OtherError> is already provided by recover, -> OtherError is provided by withError. I don't see the use case for needing both?

[kyay10]

@CLOVIS-AI mapError is meant to be Effect's analogue for withError. Think of it as the Effect version of Either.mapLeft. Its transform lambda taking Raise<OtherError> and returning OtherError is very ugly, I agree. The reason I exposed it is so that you can use functions that raise OtherError inside. However, with #3061, that need is met without the ugly signature. I'll update the PR with a better signature, especially because you can simulate merge with either { ... }.merge()

[nomisRev]

Looks good to me @kyay10! Thank you for this improvement, and @CLOVIS-AI for the original suggestions 🙏 🙌

Thanks for the very complete work, including documentation and tests 😍

[franciscodr]

Thanks for this amazing contribution, @kyay10. The code looks neat with the new functions 😍

[serras]

Very useful utility