State preservation (aka SavedStateHandle)¶

Sometimes it might be necessary to preserve some persistent state or data in a component when it gets destroyed (e.g. killed by the system). A very common use case is Android Activity recreation due to configuration changes, or process death on Android or iOS. Many Android developers are used to AndroidX SavedStateHandle, however Decompose takes a different approach. The ComponentContext interface extends the StateKeeperOwner interface, which provides the StateKeeper API - a multiplatform abstraction for state preservation. It is provided by Essenty library (from the same author).

The decompose module adds Essenty's state-keeper module as api dependency, so you don't need to explicitly add it to your project. Please familiarise yourself with Essenty library, especially with the StateKeeper API.

Decompose relies on kotlinx-serialization library, which makes it easy to save and restore the state on all platforms.

Usage examples¶

Saving state in a component

import com.arkivanov.decompose.ComponentContext import kotlinx.serialization.Serializable class SomeComponent(componentContext: ComponentContext) : ComponentContext by componentContext {  // Either restore the previously saved state or create a new (initial) one  private var state: State = stateKeeper.consume(key = "SAVED_STATE", strategy = State.serializer()) ?: State()  init {  stateKeeper.register(key = "SAVED_STATE", strategy = State.serializer()) {  state // Called when it's time to save the state  }  }  @Serializable // Comes from kotlinx-serialization  private class State(val someValue: Int = 0) }

Saving state of a retained instance

import com.arkivanov.decompose.ComponentContext import com.arkivanov.essenty.instancekeeper.InstanceKeeper import com.arkivanov.essenty.instancekeeper.getOrCreate import com.arkivanov.sample.shared.SomeStatefulEntity.State import kotlinx.serialization.Serializable class SomeComponent(componentContext: ComponentContext) : ComponentContext by componentContext {  private val statefulEntity =  instanceKeeper.getOrCreate {  SomeStatefulEntity(savedState = stateKeeper.consume(key = "SAVED_STATE", strategy = State.serializer()))  }  init {  stateKeeper.register(key = "SAVED_STATE", strategy = State.serializer(), supplier = statefulEntity::state)  } } class SomeStatefulEntity(savedState: State?) : InstanceKeeper.Instance {  var state: State = savedState ?: State()  private set  @Serializable  data class State(val someValue: Int = 0) }

Simplified state preservation¶

Warning

The saveable API is experimental since version 3.2.0-alpha02.

import com.arkivanov.decompose.ComponentContext import com.arkivanov.essenty.statekeeper.saveable import kotlinx.serialization.Serializable class SomeComponent(componentContext: ComponentContext) : ComponentContext by componentContext {  private var state: State by saveable(serializer = State.serializer(), init = ::State)  @Serializable // Comes from kotlinx-serialization  private data class State(val someValue: Int = 0) }

Simplified state preservation of a retained instance¶

Warning

The retainedInstance API is experimental since version 3.2.0-alpha02, stable since 3.2.0.

import com.arkivanov.decompose.ComponentContext import com.arkivanov.essenty.instancekeeper.InstanceKeeper import com.arkivanov.essenty.instancekeeper.retainedInstance import com.arkivanov.essenty.statekeeper.saveable import com.arkivanov.sample.shared.SomeStatefulEntity.State import kotlinx.serialization.Serializable class SomeComponent(componentContext: ComponentContext) : ComponentContext by componentContext {  private val statefulEntity by saveable(serializer = State.serializer(), state = { it.state }) { savedState ->  retainedInstance {  SomeStatefulEntity(savedState = savedState)  }  } } class SomeStatefulEntity(savedState: State?) : InstanceKeeper.Instance {  var state: State = savedState ?: State()  private set  @Serializable  data class State(val someValue: Int = 0) }

Saving state on non-Android targets¶

Thanks to kotlinx-serialization the state can be serialized as JSON string and encoded as usual via NSCoder (iOS), file system (JVM), localStorage (Web), etc.