LoadState<Value>

Represents the different states involved in loading data of type Value.

Table of contents

1. States
   1. Idle
   2. Loading
   3. Loaded<Value>
   4. Failure
2. State Checks
   1. isIdle()
   2. isLoading()
   3. isLoaded()
   4. isFailure()
3. Reactive Callbacks
   1. onIdle
   2. onLoading
   3. onLoaded
   4. onFailure
4. Value Access
   1. valueOrNull()
   2. valueOrThrow()
5. Exception Access
   1. exceptionOrNull()
   2. exceptionOrThrow()
6. Transformation
   1. map
   2. fold

---

States

Idle

Represents the idle state, before any data has been loaded.

val idleState = LoadState.Idle

Loading

Represents the loading state, indicating that data is currently being loaded.

val loadingState = LoadState.Loading

Loaded<Value>

Represents the loaded state of data. Supports the invoke() operator to access the value directly.

val loadedState = LoadState.Loaded("Hello")
val value = loadedState() // "Hello"

Failure

Represents the failure state, containing an exception. Supports the invoke() operator to access the exception directly.

val failureState = LoadState.Failure(RuntimeException("Something went wrong"))
val exception = failureState() // RuntimeException

---

State Checks

All state check functions use Kotlin contracts for smart casting.

isIdle()

val state = LoadState.Idle
state.isIdle() // true

isLoading()

val state = LoadState.Loading
state.isLoading() // true

isLoaded()

val state = LoadState.Loaded(Unit)
state.isLoaded() // true

isFailure()

val state = LoadState.Failure(RuntimeException())
state.isFailure() // true

---

Reactive Callbacks

onIdle

Executes the given block if the current state is Idle.

val state = LoadState.Idle
state.onIdle { println("Idle state reached") }
// Output: Idle state reached

onLoading

Executes the given block if the current state is Loading.

val state = LoadState.Loading
state.onLoading { println("Loading state reached") }
// Output: Loading state reached

onLoaded

Executes the given block with the loaded value if the current state is Loaded.

val state = LoadState.Loaded("data")
state.onLoaded { value -> println("Loaded: $value") }
// Output: Loaded: data

onFailure

Executes the given block with the exception if the current state is Failure.

val state = LoadState.Failure(RuntimeException("error"))
state.onFailure { throwable -> println("Failed: ${throwable.message}") }
// Output: Failed: error

---

Value Access

valueOrNull()

Returns the value if Loaded, or null otherwise.

LoadState.Loaded("value").valueOrNull()  // "value"
LoadState.Failure(RuntimeException()).valueOrNull()  // null

valueOrThrow()

Returns the value if Loaded, or throws IllegalStateException.

LoadState.Loaded("value").valueOrThrow()  // "value"
LoadState.Failure(RuntimeException()).valueOrThrow()  // throws IllegalStateException

---

Exception Access

exceptionOrNull()

Returns the exception if Failure, or null otherwise.

LoadState.Failure(RuntimeException()).exceptionOrNull()  // RuntimeException
LoadState.Loaded(Unit).exceptionOrNull()  // null

exceptionOrThrow()

Returns the exception if Failure, or throws IllegalStateException.

LoadState.Failure(RuntimeException()).exceptionOrThrow()  // RuntimeException
LoadState.Loaded(Unit).exceptionOrThrow()  // throws IllegalStateException

---

Transformation

map

Maps the value of a Loaded state to a new value. Other states are passed through unchanged.

val state = LoadState.Loaded("value")
val mapped = state.map { it.length }  // LoadState.Loaded(5)

val state = LoadState.Idle
val mapped = state.map { it.length }  // LoadState.Idle

fold

Folds the state into a single value by providing handlers for each state.

val state: LoadState<String> = LoadState.Loaded("value")
val result = state.fold(
    onIdle = { "Idle" },
    onLoading = { "Loading..." },
    onLoaded = { value -> "Got: $value" },
    onFailure = { error -> "Error: ${error.message}" }
)
// result = "Got: value"