outcome/nz.adjmunro.outcome/Outcome

Outcome

sealed interface Outcome<out Ok, out Error>

Represents either a Success or Failure state.

Unlike KotlinResult, Outcome carries the Error type explicitly, so error information is never erased. Moreover, Error has no type restrictions.

Use outcomeOf to build an Outcome with structured error-raising via RaiseScope.

Parameters

The type of the successful value.

Error

The type of the error value.

Inheritors

Failure

Success

Properties

asFault

val <Error> Outcome<*, Error>.asFault: Fault<Error>

Converts any Outcome to a Fault by discarding the Success value (mapping it to Unit).

asMaybe

val <Ok> Outcome<Ok, *>.asMaybe: Maybe<Ok>

Converts any Outcome to a Maybe by discarding the Failure error (mapping it to Unit).

flatten

@get:JvmName(name = "flattenNestedFailureAlias")

val <Ok, Err, Oki : Ok, Oko : Ok> Outcome<Oko, Outcome<Oki, Err>>.flatten: Outcome<Ok, Err>

Property alias for flattenNestedFailure.

@get:JvmName(name = "flattenNestedBothAlias")

val <Ok, Err, Oks : Ok, Ers : Err, Okf : Ok, Erf : Err> Outcome<Outcome<Oks, Ers>, Outcome<Okf, Erf>>.flatten: Outcome<Ok, Err>

Property alias for flattenNestedBoth.

@get:JvmName(name = "flattenNestedSuccessAlias")

val <Ok, Err, Eri : Err, Ero : Err> Outcome<Outcome<Ok, Eri>, Ero>.flatten: Outcome<Ok, Err>

Property alias for flattenNestedSuccess.

toKotlinResult

val <Ok, Error> Outcome<Ok, Error>.toKotlinResult: KotlinResult<Ok>

Converts an Outcome to a KotlinResult.

Functions

andThen

inline fun <In, Out, Error> Outcome<In, Error>.andThen(catch: (throwable: Throwable) -> Outcome<Out, Error> = ::rethrow, scope: RaiseScope<Error> = DefaultRaiseScope(), success: RaiseScope<Error>.(In) -> Out): Outcome<Out, Error>

Transforms the Success value of this Outcome, wrapping the result with outcome error-catching semantics.

inline fun <Ok, Error> Outcome<Ok, Error>.andThen(predicate: (Ok) -> Boolean, catch: (throwable: Throwable) -> Outcome<Ok, Error> = ::rethrow, scope: RaiseScope<Error> = DefaultRaiseScope(), success: RaiseScope<Error>.(Ok) -> Ok): Outcome<Ok, Error>

Conditionally transforms the Success value, but only when predicate returns true. If predicate returns false, the Success is returned unchanged.

andThenOf

inline suspend fun <In, Out, Error> Outcome<In, Error>.andThenOf(catch: (throwable: Throwable) -> Outcome<Out, Error> = ::rethrow, scope: RaiseScope<Error> = DefaultRaiseScope(), success: suspend RaiseScope<Error>.(In) -> Out): Outcome<Out, Error>

Transforms the Success value of this Outcome, wrapping the result with outcomeOf error-catching semantics.

inline suspend fun <Ok, Error> Outcome<Ok, Error>.andThenOf(predicate: (Ok) -> Boolean, catch: (throwable: Throwable) -> Outcome<Ok, Error> = ::rethrow, scope: RaiseScope<Error> = DefaultRaiseScope(), success: RaiseScope<Error>.(Ok) -> Ok): Outcome<Ok, Error>

Conditionally transforms the Success value, but only when predicate returns true. If predicate returns false, the Success is returned unchanged.

coerceToFailure

infix inline fun <Ok, Error> Outcome<Ok, Error>.coerceToFailure(falter: (Ok) -> Error): Failure<Error>

Coerces this Outcome to a Failure.

coerceToSuccess

infix inline fun <Ok, Error> Outcome<Ok, Error>.coerceToSuccess(recover: (Error) -> Ok): Success<Ok>

Coerces this Outcome to a Success.

collapse

fun <Ancestor, Ok : Ancestor, Error : Ancestor> Outcome<Ok, Error>.collapse(): Ancestor

Extracts either the Success value or the Failure error, returning the nearest common Ancestor type.

component1

open operator fun component1(): Ok?

Returns the Ok value via destructuring, or null if this is a Failure. Note that Ok itself may be a nullable type.

component2

open operator fun component2(): Error?

Returns the Error value via destructuring, or null if this is a Success. Note that Error itself may be a nullable type.

errorOrDefault

infix fun <Ok, Error> Outcome<Ok, Error>.errorOrDefault(default: Error): Error

Returns the Failure error, or default if the outcome is a Success.

errorOrElse

infix inline fun <Ok, Error> Outcome<Ok, Error>.errorOrElse(faulter: (Ok) -> Error): Error

Returns the Failure error, or the result of faulter applied to the Success value.

errorOrNull

fun <Ok, Error> Outcome<Ok, Error>.errorOrNull(): Error?

Returns the Failure error, or null if the outcome is a Success.

errorOrRaise

context(scope: RaiseScope<OuterError>)
fun <OuterError, Ok : OuterError, InnerError> Outcome<Ok, InnerError>.errorOrRaise(): InnerError

Returns the Failure error, or short-circuits the surrounding RaiseScope with the Success value.

errorOrThrow

fun <Ok, Error> Outcome<Ok, Error>.errorOrThrow(): Error

Returns the Failure error, or throws if the outcome is a Success.

falter

infix inline fun <Ok, Error> Outcome<Ok, Error>.falter(transform: (Ok) -> Error): Failure<Error>

Infix alias for coerceToFailure.

flatMapFailure

infix inline fun <Ok, ErrorIn, ErrorOut> Outcome<Ok, ErrorIn>.flatMapFailure(transform: (ErrorIn) -> Outcome<Ok, ErrorOut>): Outcome<Ok, ErrorOut>

Transforms Outcome<Ok, ErrorIn> into Outcome<Ok, ErrorOut> by applying transform to the Failure error.

flatMapSuccess

infix inline fun <In, Out, Error> Outcome<In, Error>.flatMapSuccess(transform: (In) -> Outcome<Out, Error>): Outcome<Out, Error>

Transforms Outcome<In, Error> into Outcome<Out, Error> by applying transform to the Success value.

flattenNestedBoth

Flattens nested Outcome values from both the Success and Failure states into a single Outcome.

flattenNestedFailure

fun <OuterOk : AncestorOk, EmbeddedOk : AncestorOk, Error, AncestorOk> Outcome<OuterOk, Outcome<EmbeddedOk, Error>>.flattenNestedFailure(): Outcome<AncestorOk, Error>

Flattens a nested Outcome from inside the Failure state into a single Outcome.

flattenNestedSuccess

fun <Ok, EmbeddedError : AncestorError, OuterError : AncestorError, AncestorError> Outcome<Outcome<Ok, EmbeddedError>, OuterError>.flattenNestedSuccess(): Outcome<Ok, AncestorError>

Flattens a nested Outcome from inside the Success state into a single Outcome.

fold

inline fun <Ok, Error, Output> Outcome<Ok, Error>.fold(failure: Failure<Error>.() -> Output, success: Success<Ok>.() -> Output): Output

Applies success or failure to the receiver Outcome, returning Output.

getOrDefault

infix fun <Ok, Error> Outcome<Ok, Error>.getOrDefault(default: Ok): Ok

Returns the Success value, or default if the outcome is a Failure.

getOrElse

infix inline fun <Ok, Error> Outcome<Ok, Error>.getOrElse(recover: (Error) -> Ok): Ok

Returns the Success value, or the result of recover applied to the Failure error.

getOrNull

fun <Ok, Error> Outcome<Ok, Error>.getOrNull(): Ok?

Returns the Success value, or null if the outcome is a Failure.

getOrRaise

context(scope: RaiseScope<OuterError>)
fun <OuterError, Ok, InnerError : OuterError> Outcome<Ok, InnerError>.getOrRaise(): Ok

Returns the Success value, or short-circuits the surrounding RaiseScope with the Failure error.

getOrThrow

fun <Ok, Error> Outcome<Ok, Error>.getOrThrow(): Ok

Returns the Success value, or throws if the outcome is a Failure.

invert

fun <Ok, Error> Outcome<Ok, Error>.invert(): Outcome<Error, Ok>

Swaps the Success value and the Failure error, producing Outcome<Error, Ok>.

isFailure

fun <Ok, Error> Outcome<Ok, Error>.isFailure(): Boolean

Returns true if this Outcome is a Failure.

infix inline fun <Ok, Error> Outcome<Ok, Error>.isFailure(predicate: (Error) -> Boolean): Boolean

Returns true if this is a Failure and predicate returns true for the error.

isSuccess

fun <Ok, Error> Outcome<Ok, Error>.isSuccess(): Boolean

Returns true if this Outcome is a Success.

infix inline fun <Ok, Error> Outcome<Ok, Error>.isSuccess(predicate: (Ok) -> Boolean): Boolean

Returns true if this is a Success and predicate returns true for the value.

map

inline fun <In, Out, ErrorIn, ErrorOut> Outcome<In, ErrorIn>.map(failure: (ErrorIn) -> ErrorOut, success: (In) -> Out): Outcome<Out, ErrorOut>

Transforms both states of an Outcome, re-wrapping each result in the same kind of Outcome.

mapFailure

infix inline fun <Ok, ErrorIn, ErrorOut> Outcome<Ok, ErrorIn>.mapFailure(transform: (ErrorIn) -> ErrorOut): Outcome<Ok, ErrorOut>

Transforms Outcome<Ok, ErrorIn> into Outcome<Ok, ErrorOut> by applying transform to the Failure error.

mapSuccess

infix inline fun <In, Out, Error> Outcome<In, Error>.mapSuccess(transform: (In) -> Out): Outcome<Out, Error>

Transforms Outcome<In, Error> into Outcome<Out, Error> by applying transform to the Success value.

onFailure

infix inline fun <Ok, Error> Outcome<Ok, Error>.onFailure(block: (Error) -> Unit): Outcome<Ok, Error>

Calls block with the Failure error if this is a failure, then returns the original Outcome unchanged. No-op on Success.

onSuccess

infix inline fun <Ok, Error> Outcome<Ok, Error>.onSuccess(block: (Ok) -> Unit): Outcome<Ok, Error>

Calls block with the Success value if this is a success, then returns the original Outcome unchanged. No-op on Failure.

recover

infix inline fun <Ok, Error> Outcome<Ok, Error>.recover(transform: (Error) -> Ok): Success<Ok>

Infix alias for coerceToSuccess.

rfold

inline fun <Ok, Error, Output> Outcome<Ok, Error>.rfold(success: Success<Ok>.() -> Output, failure: Failure<Error>.() -> Output): Output

Reverse fold — identical behaviour with swapped lambda argument order.

throwIf

inline fun <Ok, Error> Outcome<Ok, Error>.throwIf(fallbackMessage: (Error) -> String = { "Outcome was Failure and throwIf predicate was true: $it" }, predicate: (Error) -> Boolean): Outcome<Ok, Error>

Throws if this is a Failure and predicate returns true for the error. Returns the original Outcome unchanged otherwise.

throwUnless

inline fun <Ok, Error> Outcome<Ok, Error>.throwUnless(fallbackMessage: (Error) -> String = { "Outcome was Failure and throwUnless predicate was false: $it" }, predicate: (Error) -> Boolean): Outcome<Ok, Error>

Throws if this is a Failure and predicate returns false for the error. Returns the original Outcome unchanged otherwise.

tryRecover

inline fun <Ok, ErrorIn, ErrorOut> Outcome<Ok, ErrorIn>.tryRecover(catch: (throwable: Throwable) -> Outcome<Ok, ErrorOut> = ::rethrow, scope: RaiseScope<ErrorOut> = DefaultRaiseScope(), failure: RaiseScope<ErrorOut>.(ErrorIn) -> Ok): Outcome<Ok, ErrorOut>

Transforms a Failure into a Success, wrapping the result with outcome error-catching semantics.

tryRecoverOf

inline suspend fun <Ok, ErrorIn, ErrorOut> Outcome<Ok, ErrorIn>.tryRecoverOf(catch: (throwable: Throwable) -> Outcome<Ok, ErrorOut> = ::rethrow, scope: RaiseScope<ErrorOut> = DefaultRaiseScope(), failure: RaiseScope<ErrorOut>.(ErrorIn) -> Ok): Outcome<Ok, ErrorOut>

Transforms a Failure into a Success, wrapping the result with outcomeOf error-catching semantics.

Outcome

Parameters

See also

Inheritors

Properties

Functions