composeextensions/sco.carlukesoftware.composeextensions/UiState

UiState

sealed interface UiState<out T>

A generic sealed interface representing the different states of an asynchronous operation or data loading process. Annotated with @Immutable for Jetpack Compose stability and optimal recomposition behavior.

Type Parameters

The type of data held by the Success state.

Inheritors

Idle

Success

Failure

Types

Failure

data class Failure(val throwable: Throwable) : UiState<Nothing>

Indicates an operation failure holding the thrown throwable.

Idle

data object Idle : UiState<Nothing>

Indicates the initial state before any operation has started.

data object Loading : UiState<Nothing>

Indicates that an operation is currently in progress.

Success

data class Success<out T>(val data: T) : UiState<T>

Indicates successful completion holding the resulting data.

Properties

isFailure

open val isFailure: Boolean

isIdle

open val isIdle: Boolean

isLoading

open val isLoading: Boolean

isSuccess

open val isSuccess: Boolean

Functions

Content

@Composable

inline fun <T> UiState<T>.Content(crossinline onSuccess: @Composable (data: T) -> Unit, noinline onLoading: @Composable () -> Unit? = null, noinline onIdle: @Composable () -> Unit? = null, noinline onFailure: @Composable (throwable: Throwable) -> Unit? = null)

Exhaustively renders UI content based on the current UiState.

exceptionOrNull

fun <T> UiState<T>.exceptionOrNull(): Throwable?

Returns the encapsulated throwable if this state is UiState.Failure, or null otherwise.

flatMap

inline fun <T, R> UiState<T>.flatMap(transform: (T) -> UiState<R>): UiState<R>

Transforms the UiState.Success data using the given transform function that returns a new UiState.

fold

inline fun <T, R> UiState<T>.fold(onSuccess: (data: T) -> R, onFailure: (throwable: Throwable) -> R, onLoading: () -> R, onIdle: () -> R): R

Applies onSuccess if state is UiState.Success, onFailure if UiState.Failure, onLoading if UiState.Loading, or onIdle if UiState.Idle.

getOrDefault

fun <T> UiState<T>.getOrDefault(default: T): T

Returns the encapsulated data if this state is UiState.Success, or default otherwise.

getOrElse

inline fun <T> UiState<T>.getOrElse(onFailure: (throwable: Throwable?) -> T): T

Returns the encapsulated data if this state is UiState.Success, or the result of onFailure function for non-success states.

getOrNull

fun <T> UiState<T>.getOrNull(): T?

Returns the encapsulated data if this state is UiState.Success, or null otherwise.

getOrThrow

fun <T> UiState<T>.getOrThrow(): T

Returns the encapsulated data if this state is UiState.Success, or throws the encapsulated Throwable if this state is UiState.Failure, or an IllegalStateException if UiState.Idle or UiState.Loading.

map

inline fun <T, R> UiState<T>.map(transform: (T) -> R): UiState<R>

Transforms the UiState.Success data using the given transform function. Non-success states (UiState.Idle, UiState.Loading, UiState.Failure) are passed through unchanged.

onFailure

inline fun <T> UiState<T>.onFailure(block: (throwable: Throwable) -> Unit): UiState<T>

Executes block with UiState.Failure.throwable if the UiState is UiState.Failure. Returns this to allow chaining.

onIdle

inline fun <T> UiState<T>.onIdle(block: () -> Unit): UiState<T>

Executes block if the UiState is UiState.Idle. Returns this to allow chaining.

onLoading

inline fun <T> UiState<T>.onLoading(block: () -> Unit): UiState<T>

Executes block if the UiState is UiState.Loading. Returns this to allow chaining.

onSuccess

inline fun <T> UiState<T>.onSuccess(block: (data: T) -> Unit): UiState<T>

Executes block with UiState.Success.data if the UiState is UiState.Success. Returns this to allow chaining.