commonMain.progressive.Builder.kt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of state Show documentation
Progress-aware failure states
The newest version!
package opensavvy.state.progressive

import opensavvy.progress.ExperimentalProgressApi
import opensavvy.progress.Progress
import opensavvy.progress.Progressive
import opensavvy.progress.done
import opensavvy.state.ExperimentalProgressiveRaiseApi
import opensavvy.state.outcome.Outcome
import opensavvy.state.progressive.ProgressiveOutcome.Unsuccessful

/**
 * Adds [progress] information to this outcome to make it a [ProgressiveOutcome].
 *
 * Because regular outcomes cannot be unfinished, this function never returns [ProgressiveOutcome.Incomplete].
 */
fun  Outcome.withProgress(progress: Progress = done()) = when (this) {
	is Outcome.Success -> ProgressiveOutcome.Success(value, progress)
	is Outcome.Failure -> ProgressiveOutcome.Failure(failure, progress)
}

/**
 * Replaces the [progress] information from this progressive outcome.
 */
fun  ProgressiveOutcome.copy(progress: Progress.Loading) = when (this) {
	is ProgressiveOutcome.Incomplete -> ProgressiveOutcome.Incomplete(progress)
	is ProgressiveOutcome.Failure -> ProgressiveOutcome.Failure(failure, progress)
	is ProgressiveOutcome.Success -> ProgressiveOutcome.Success(value, progress)
}

/**
 * Convenience function to instantiate a [ProgressiveOutcome.Success].
 */
@Deprecated("The 'success' factory has been replaced by 'successfulWithProgress'.", replaceWith = ReplaceWith("successfulWithProgress(progress)", "opensavvy.state.progressive.successfulWithProgress"))
fun  Value.success(progress: Progress = done()) = ProgressiveOutcome.Success(this, progress)

/**
 * Convenience function to instantiate a [ProgressiveOutcome.Failure].
 */
@Deprecated("The 'failed' factory has been replaced by 'failedWithProgress'.", replaceWith = ReplaceWith("failedWithProgress(progress)", "opensavvy.state.progressive.failedWithProgress"))
fun  Failure.failed(progress: Progress = done()) = ProgressiveOutcome.Failure(this, progress)

/**
 * Convenience function to instantiate a [ProgressiveOutcome.Success].
 */
fun  Value.successfulWithProgress(progress: Progress = done()) = ProgressiveOutcome.Success(this, progress)

/**
 * Convenience function to instantiate a [ProgressiveOutcome.Failure].
 */
fun  Failure.failedWithProgress(progress: Progress = done()) = ProgressiveOutcome.Failure(this, progress)

/**
 * Type-safe way to convert between an [Unsuccessful] and a [ProgressiveOutcome].
 *
 * In theory, this would be an implicit upcast. However, [ProgressiveOutcome] is a `class`,
 * and [Unsuccessful] is an `interface`, so the subtype relationship cannot be declared to the compiler.
 */
@ExperimentalProgressiveRaiseApi
fun  Unsuccessful.upcast(): ProgressiveOutcome =
	when (this) {
		is ProgressiveOutcome.Failure -> this
		is ProgressiveOutcome.Incomplete -> this
	}

// region Conversion with Progress' Progressive

/**
 * Converts an [Outcome] nested in a [Progressive] into a [ProgressiveOutcome].
 *
 * @see explode Reverse operation.
 */
@ExperimentalProgressApi
fun  Progressive>.flatten(): ProgressiveOutcome =
	value.withProgress(progress)

/**
 * Converts a [ProgressiveOutcome] into a [Progressive] [Outcome].
 *
 * In the case where in the input [ProgressiveOutcome] is [Incomplete][ProgressiveOutcome.Incomplete], `null` is returned.
 *
 * @see flatten Reverse operation.
 */
@ExperimentalProgressApi
fun  ProgressiveOutcome.explode(): Progressive?> =
	Progressive(asOutcome(), progress)

// endregion