MutationState<Value>

Represents the different states involved in mutating data of type Value. Each state tracks both the original and updated values, providing granular control over the mutation lifecycle.

Table of contents

1. States
   1. Idle<Value>
   2. Mutating<Value>
   3. Mutated<Value>
   4. Failure<Value>
2. State Checks
   1. isIdle()
   2. isMutating()
   3. isMutated()
   4. isFailure()
3. Reactive Callbacks
   1. onIdle
   2. onMutating
   3. onMutated
   4. onFailure
4. Value Access
   1. activeValue()
   2. attemptedValue()
5. Exception Access
   1. exceptionOrNull()

---

States

Idle<Value>

Represents the idle state, before any mutation has been initiated.

val idleState = MutationState.Idle(UserProfile("Alice"))

Mutating<Value>

Represents the mutating state, indicating that a mutation is in progress. Tracks both the original and updated values.

val mutatingState = MutationState.Mutating(
    original = UserProfile("Alice"),
    updated = UserProfile("Bob")
)

// Convenience constructor when original == updated
val mutatingState = MutationState.Mutating(UserProfile("Alice"))

Mutated<Value>

Represents the mutated state, indicating the mutation completed successfully.

val mutatedState = MutationState.Mutated(
    original = UserProfile("Alice"),
    updated = UserProfile("Bob")
)

// Convenience constructor when original == updated
val mutatedState = MutationState.Mutated(UserProfile("Bob"))

Failure<Value>

Represents the failure state, containing the original value, the attempted update, and the exception.

val failureState = MutationState.Failure(
    original = UserProfile("Alice"),
    updated = UserProfile("Bob"),
    exception = RuntimeException("Network error")
)

// Convenience constructor when original == updated
val failureState = MutationState.Failure(
    value = UserProfile("Alice"),
    exception = RuntimeException("Network error")
)

---

State Checks

All state check functions use Kotlin contracts for smart casting.

isIdle()

MutationState.Idle(Unit).isIdle() // true

isMutating()

MutationState.Mutating(original = Unit, updated = Unit).isMutating() // true

isMutated()

MutationState.Mutated(original = Unit, updated = Unit).isMutated() // true

isFailure()

MutationState.Failure(original = Unit, updated = Unit, exception = RuntimeException()).isFailure() // true

---

Reactive Callbacks

onIdle

MutationState.Idle("value").onIdle { value ->
    println("Idle with: $value")
}
// Output: Idle with: value

onMutating

MutationState.Mutating(original = "old", updated = "new").onMutating { original, updated ->
    println("Mutating from $original to $updated")
}
// Output: Mutating from old to new

onMutated

MutationState.Mutated(original = "old", updated = "new").onMutated { original, updated ->
    println("Mutated from $original to $updated")
}
// Output: Mutated from old to new

onFailure

MutationState.Failure(
    original = "old", updated = "new", exception = RuntimeException("error")
).onFailure { original, updated, exception ->
    println("Failed to mutate from $original to $updated: ${exception.message}")
}
// Output: Failed to mutate from old to new: error

---

Value Access

activeValue()

Returns the current truth based on the state:

State	Returns
Idle	value
Mutating	original (mutation not confirmed yet)
Mutated	updated (mutation succeeded)
Failure	original (mutation failed, reverted)

MutationState.Idle("initial").activeValue()  // "initial"
MutationState.Mutating(original = "current", updated = "target").activeValue()  // "current"
MutationState.Mutated(original = "old", updated = "new").activeValue()  // "new"
MutationState.Failure(original = "current", updated = "failed", exception = RuntimeException()).activeValue()  // "current"

attemptedValue()

Returns what was or is being changed to:

State	Returns
Idle	value
Mutating	updated
Mutated	updated
Failure	updated

MutationState.Idle("initial").attemptedValue()  // "initial"
MutationState.Mutating(original = "current", updated = "target").attemptedValue()  // "target"
MutationState.Mutated(original = "old", updated = "new").attemptedValue()  // "new"
MutationState.Failure(original = "current", updated = "failed", exception = RuntimeException()).attemptedValue()  // "failed"

---

Exception Access

exceptionOrNull()

Returns the exception if Failure, or null otherwise.

MutationState.Failure(original = Unit, updated = Unit, exception = RuntimeException()).exceptionOrNull()  // RuntimeException
MutationState.Mutated(original = Unit, updated = Unit).exceptionOrNull()  // null