arrow-core/arrow.core.raise/Raise

Raise

interface Raise<in R>

The Raise DSL allows you to work with logical failures of type R. A logical failure does not necessarily mean that the computation has failed, but that it has stopped or short-circuited.

The Raise DSL allows you to raise logical failure of type R, and you can recover from them.

fun Raise<String>.failure(): Int = raise("failed")

fun Raise<Nothing>.recovered(): Int =
  recover({ failure() }) { _: String -> 1 }
Content copied to clipboard

Above we defined a function failure that raises a logical failure of type String with value "failed". And in the function recovered we recover from the failure by providing a fallback value, and resolving the error type String to Nothing. Meaning we can track that we recovered from the error in the type.

Since we defined programs in terms of Raise they seamlessly work with any of the builders available in Arrow, or any you might build for your custom types.

suspend fun test() {
  val either: Either<String, Int> =
    either { failure() }

  val effect: Effect<String, Int> =
    effect { failure() }

  val ior: Ior<String, Int> =
    ior(Semigroup.string()) { failure() }

  either shouldBe Either.Left("failed")
  effect.toEither() shouldBe Either.Left("failed")
  ior shouldBe Ior.Left("failed")
}
Content copied to clipboard

And we can apply the same technique to recover from the failures using the Raise DSL based error handlers available in Arrow.

fun test() {
  val either = either { failure() }
    .recover { _: String -> recovered() }

  either shouldBe Either.Right(1)
}
Content copied to clipboard

Functions

Link copied to clipboard
open suspend fun <E, A> attempt(f: suspend EffectScope<E>.() -> A): Effect<E, A>
Link copied to clipboard
open fun <A> Either<R, A>.bind(): A

Extract the Either.Right value of an Either. Any encountered Either.Left will be raised as a logical failure in this Raise context. You can wrap the bind call in recover if you want to attempt to recover from any logical failure.

open fun <A> Validated<R, A>.bind(): A
open suspend fun <B> EagerEffect<R, B>.bind(): B
open suspend fun <B> Effect<R, B>.bind(): B
open fun <A> EagerEffect<R, A>.bind(): A
open suspend fun <A> Effect<R, A>.bind(): A

open fun <A> Option<A>.bind(transform: Raise<R>.(None) -> A): A

Extract the Some value out of Option, because Option works with None as its error type you need to transform to R.

open fun <A> Result<A>.bind(transform: (Throwable) -> R): A

Extract the Result.success value out of Result, because Result works with Throwable as its error type you need to transform to R.

Link copied to clipboard
open infix suspend fun <E, A> Effect<E, A>.catch(recover: suspend Raise<R>.(E) -> A): A
open fun <A> EagerEffect<R, A>.catch(catch: Raise<R>.(Throwable) -> A): A
open suspend fun <A> Effect<R, A>.catch(catch: suspend Raise<R>.(Throwable) -> A): A
Link copied to clipboard
open operator fun <A> EagerEffect<R, A>.invoke(): A

Invoke an EagerEffect inside this Raise context. Any logical failure is raised in this Raise context, and thus short-circuits the computation.

open suspend operator fun <A> Effect<R, A>.invoke(): A

Invoke an Effect inside this Raise context. Any logical failure raised are raised in this Raise context, and thus short-circuits the computation.

Link copied to clipboard
open fun <A, B> Iterable<A>.mapOrAccumulate(semigroup: Semigroup<@UnsafeVariance R>, block: Raise<R>.(A) -> B): List<B>

Accumulate the errors obtained by executing the block over every element of this using the given semigroup.

Link copied to clipboard
abstract fun raise(r: R): Nothing

Raise a logical failure of type R

Link copied to clipboard
open infix fun <E, A> EagerEffect<E, A>.recover(resolve: Raise<R>.(E) -> A): A
open infix suspend fun <E, A> Effect<E, A>.recover(resolve: suspend Raise<R>.(E) -> A): A

open suspend fun <E, A> Effect<E, A>.recover(action: suspend Raise<E>.() -> A, recover: suspend Raise<R>.(E) -> A, catch: suspend Raise<R>.(Throwable) -> A): A

Execute the Effect resulting in A, and recover from any logical error of type E, and Throwable, by providing a fallback value of type A, or raising a new error of type R.

Link copied to clipboard
open fun <B> shift(r: R): B
Link copied to clipboard
open fun <A, B, C> zipOrAccumulate(semigroup: Semigroup<@UnsafeVariance R>, action1: Raise<R>.() -> A, action2: Raise<R>.() -> B, block: Raise<R>.(A, B) -> C): C

Accumulate the errors from running both action1 and action2 using the given semigroup.

open fun <A, B, C, D> zipOrAccumulate(semigroup: Semigroup<@UnsafeVariance R>, action1: Raise<R>.() -> A, action2: Raise<R>.() -> B, action3: Raise<R>.() -> C, block: Raise<R>.(A, B, C) -> D): D

Accumulate the errors from running action1, action2, and action3 using the given semigroup.

open fun <A, B, C, D, E> zipOrAccumulate(semigroup: Semigroup<@UnsafeVariance R>, action1: Raise<R>.() -> A, action2: Raise<R>.() -> B, action3: Raise<R>.() -> C, action4: Raise<R>.() -> D, block: Raise<R>.(A, B, C, D) -> E): E

Accumulate the errors from running action1, action2, action3, and action4 using the given semigroup.

Inheritors

Link copied to clipboard
Link copied to clipboard
Link copied to clipboard
Link copied to clipboard

Extensions

Link copied to clipboard
inline fun <R, A> Raise<R>.catch(action: Raise<R>.() -> A, catch: Raise<R>.(Throwable) -> A): A
@JvmName(name = "catchReified")
inline fun <T : Throwable, R, A> Raise<R>.catch(action: Raise<R>.() -> A, catch: Raise<R>.(T) -> A): A
Link copied to clipboard
inline fun <R> Raise<R>.ensure(condition: Boolean, raise: () -> R)
Link copied to clipboard
inline fun <R, B : Any> Raise<R>.ensureNotNull(value: B?, raise: () -> R): B
Link copied to clipboard
inline fun <R, A> Raise<NonEmptyList<R>>.mapErrorNel(crossinline block: Raise<R>.() -> A): A
Link copied to clipboard
inline fun <R, A, B> Raise<NonEmptyList<R>>.mapOrAccumulate(list: Iterable<A>, crossinline block: Raise<R>.(A) -> B): List<B>

Accumulate the errors obtained by executing the block over every element of list.

Link copied to clipboard
inline fun <R, E, A> Raise<R>.recover(action: Raise<E>.() -> A, recover: Raise<R>.(E) -> A): A

Execute the Raise context function resulting in A or any logical error of type E, and recover by providing a fallback value of type A or raising a new error of type R.

inline fun <R, E, A> Raise<R>.recover(action: Raise<E>.() -> A, recover: Raise<R>.(E) -> A, catch: Raise<R>.(Throwable) -> A): A
Link copied to clipboard
inline fun <R, A, B, C> Raise<NonEmptyList<R>>.zipOrAccumulate(crossinline action1: Raise<R>.() -> A, crossinline action2: Raise<R>.() -> B, crossinline block: Raise<R>.(A, B) -> C): C

Accumulate the errors from running both action1 and action2.

inline fun <R, A, B, C, D> Raise<NonEmptyList<R>>.zipOrAccumulate(crossinline action1: Raise<R>.() -> A, crossinline action2: Raise<R>.() -> B, crossinline action3: Raise<R>.() -> C, crossinline block: Raise<R>.(A, B, C) -> D): D

Accumulate the errors from running action1, action2, and action3.

inline fun <R, A, B, C, D, E> Raise<NonEmptyList<R>>.zipOrAccumulate(crossinline action1: Raise<R>.() -> A, crossinline action2: Raise<R>.() -> B, crossinline action3: Raise<R>.() -> C, crossinline action4: Raise<R>.() -> D, crossinline block: Raise<R>.(A, B, C, D) -> E): E

Accumulate the errors from running action1, action2, action3, and action4.