ProgressiveOutcome

sealed class ProgressiveOutcome<out Failure, out Value>

A Outcome with integrated Progress management.

There are three possible cases:

• Incomplete if the task has started but no value is currently available,

• Success if a successful result is available (see Success.value),

• Failure if a failed result is available (see Failure.failure).

Note that in cases, a progressive outcome may be currently loading.

• Incomplete must be loading,

• Success may be loading if the task is currently querying a newer value than the one it stores,

• Failure may be loading if the task is currently retrying the operation.

To access the inner outcome and progression, you can use the destructuring operator:

val (out, progression) = /* ProgressiveOutcome */

To create progressive outcomes from computations, use the successfulWithProgress and failedWithProgress factories.

Inheritors

• Incomplete
• Success
• Failure

Types

Failure

data class Failure<Failure>(val failure: Failure, val progress: Progress = done()) : ProgressiveOutcome<Failure, Nothing> , ProgressiveOutcome.Unsuccessful<Failure> 

The latest known result of the operation was a failure, available as failure.

Incomplete

data class Incomplete(val progress: Progress.Loading = loading()) : ProgressiveOutcome<Nothing, Nothing> , ProgressiveOutcome.Unsuccessful<Nothing> 

The operation is ongoing, but we do not know if it will be successful or a failure.

Success

data class Success<Value>(val value: Value, val progress: Progress = done()) : ProgressiveOutcome<Nothing, Value> 

The latest known result of the operation was a success, available as value.

Unsuccessful

sealed interface Unsuccessful<out Failure>

Operations that are not successful; common supertype of Incomplete and Failure.

Properties

failure

val <Failure> ProgressiveOutcome<Failure, Nothing>.failure: Failure

Returns Failure.failure.

failureOrNull

val <Failure> ProgressiveOutcome<Failure, *>.failureOrNull: Failure?

Returns Failure.failure, or null if this outcome is not a failure.

progress

abstract val progress: Progress

The current progression of this outcome.

For more information, see ProgressiveOutcome.

value

val <Value> ProgressiveOutcome<Nothing, Value>.value: Value

Returns Success.value.

valueOrNull

val <Value : Any> ProgressiveOutcome<*, Value>.valueOrNull: Value?

Returns Success.value, or null if this outcome is not successful.

Functions

asOutcome

fun <Failure, Value> ProgressiveOutcome<Failure, Value>.asOutcome(): Outcome<Failure, Value>?

Converts this progressive outcome into a regular outcome.

Because regular outcomes do not have a concept of progression, the progress information is lost. To access both the outcome and the progression information, consider using destructuration instead:

val (outcome, progression) = /* ProgressiveOutcome */

component1

operator fun <Failure, Value> ProgressiveOutcome<Failure, Value>.component1(): Outcome<Failure, Value>?

Syntax sugar for asOutcome.

component2

operator fun ProgressiveOutcome<*, *>.component2(): Progress

Syntax sugar for ProgressiveOutcome.progress.

copy

fun <Failure, Value> ProgressiveOutcome<Failure, Value>.copy(progress: Progress.Loading): ProgressiveOutcome<Failure, Value>

Replaces the progress information from this progressive outcome.

explode

@ExperimentalProgressApi
fun <Failure, Value> ProgressiveOutcome<Failure, Value>.explode(): Progressive<Outcome<Failure, Value>?>

Converts a ProgressiveOutcome into a Progressive.

In the case where in the input ProgressiveOutcome is Incomplete, null is returned.

See also

• flatten: Reverse operation.

map

inline fun <Failure, InputValue, OutputValue> ProgressiveOutcome<Failure, InputValue>.map(transform: (InputValue) -> OutputValue): ProgressiveOutcome<Failure, OutputValue>

If this outcome is successful, replaces its value using transform.

If this outcome isn't successful, does nothing.

See also

• mapFailure: Map the failure state instead of the success state.

mapFailure

inline fun <InputFailure, Value, OutputFailure> ProgressiveOutcome<InputFailure, Value>.mapFailure(transformFailure: (InputFailure) -> OutputFailure): ProgressiveOutcome<OutputFailure, Value>

If this outcome is failed, replaces its failure using transformFailure.

If this outcome isn't failed, does nothing.

See also

• map: Map the success state instead of the failure state.

onFailure

inline fun <Failure> ProgressiveOutcome<Failure, *>.onFailure(block: (Failure) -> Unit)

Executes block if this outcome is a failure.

Otherwise, does nothing.

onIncomplete

inline fun ProgressiveOutcome<*, *>.onIncomplete(block: () -> Unit)

Executes block if this outcome is incomplete.

Otherwise, does nothing.

onLoading

inline fun ProgressiveOutcome<*, *>.onLoading(block: (Progress.Loading) -> Unit)

Executes block if this outcome is loading (its ProgressiveOutcome.progress is Progress.Loading).

Note that this isn't synonymous with this outcome being in the Incomplete state: successful or failed outcomes may still be loading. For more information, see ProgressiveOutcome.

Otherwise, does nothing.

onSuccess

inline fun <Value> ProgressiveOutcome<*, Value>.onSuccess(block: (Value) -> Unit)

Executes block if this outcome is successful.

Otherwise, does nothing.

toEither

fun <Failure, Value> ProgressiveOutcome<Failure, Value>.toEither(): Either<Failure, Value>?

Converts a ProgressiveOutcome into a typed Either.