Why

Compose allows the creation of fine-grained UI components that can be easily reused like Lego blocks 🧱. Well architected Android apps isolate functionality in small business logic components (like use cases, interactors, repositories, etc.) that are also reusable like Lego blocks 🧱.

Screens are built using Compose components together with business logic components, and the standard tool to connect these two types of components is a Jetpack ViewModel. Unfortunately, ViewModels can only be scoped to a whole screen (or larger scope), but not to smaller Compose components on the screen.

In practice, this means that we are gluing UI Lego blocks with business logic Lego blocks using a big glue class for the whole screen, the ViewModel 🗜.

Until now...

Installation

Just include the library (less than 5Kb):

// In module's build.gradle.kts
dependencies {
    // The latest version of the lib is available in the badget at the top from Maven Central, replace X.X.X with that version
    implementation("io.github.sebaslogen:resaca:X.X.X")
}

dependencies {
    // The latest version of the lib is available in the badget at the top from Maven Central, replace X.X.X with that version
    implementation 'io.github.sebaslogen:resaca:X.X.X'
}

Usage

Inside your @Composable function create and retrieve an object using rememberScoped to remember any type of object (except ViewModels). For ViewModels use viewModelScoped. That's all 🪄✨

Examples:

@Composable
fun DemoScopedObject() {
    val myRepository: MyRepository = rememberScoped { MyRepository() }
    DemoComposable(inputObject = myRepository)
}

@Composable
fun DemoScopedViewModel() {
    val myScopedVM: MyViewModel = viewModelScoped()
    DemoComposable(inputObject = myScopedVM)
}

@Composable
fun DemoScopedViewModelWithDependency() {
    val myScopedVM: MyViewModelWithDependencies = viewModelScoped { MyViewModelWithDependencies(myDependency) }
    DemoComposable(inputObject = myScopedVM)
}

@Composable
fun DemoViewModelWithKey() {
    val scopedVMWithFirstKey: MyViewModel = viewModelScoped("myFirstKey") { MyViewModel("myFirstKey") }
    val scopedVMWithSecondKey: MyViewModel = viewModelScoped("mySecondKey") { MyViewModel("mySecondKey") }
    // We now have 2 ViewModels of the same type with different data inside the same Composable scope
    DemoComposable(inputObject = scopedVMWithFirstKey)
    DemoComposable(inputObject = scopedVMWithSecondKey)
}

@Composable
fun DemoKoinInjectedViewModelWithDependency() {
    val myInjectedScopedVM: MyViewModelWithDependencies = viewModelScoped() { getKoin().get { parametersOf(myConstructorDependency) } }
    DemoComposable(inputObject = myInjectedScopedVM)
}

@Composable
fun DemoMetroInjectedViewModelScoped() {
    val myInjectedScopedVM: MyViewModel = metroViewModelScoped(factory = myMetroViewModelFactory)
    DemoComposable(inputObject = myInjectedScopedVM)
}

@Composable
fun DemoScopedViewModelWithClearDelay() {
    // The ViewModel will be kept in memory for 5 seconds after the Composable is disposed,
    // giving it a chance to be reused if the Composable returns to composition (e.g. quick navigation back and forth)
    val myScopedVM: MyViewModel = viewModelScoped(clearDelay = 5.seconds)
    DemoComposable(inputObject = myScopedVM)
}

@Composable
fun DemoScopedObjectWithClearDelay() {
    val myRepository: MyRepository = rememberScoped(clearDelay = 5.seconds) { MyRepository() }
    DemoComposable(inputObject = myRepository)
}

@Composable
fun DemoManyViewModelsScopedOutsideTheLazyColumn(listItems: List<Int> = (1..1000).toList()) {
    val keys = rememberKeysInScope(inputListOfKeys = listItems)
    LazyColumn() {
        items(items = listItems, key = { it }) { item ->
            val myScopedVM: MyViewModel = viewModelScoped(key = item, keyInScopeResolver = keys)
            DemoComposable(inputObject = myScopedVM)
        }
    }
}

Once you use the rememberScoped or viewModelScoped functions, the same object will be restored as long as the Composable is part of the composition, even if it temporarily leaves composition on configuration change (e.g. screen rotation, change to dark mode, etc.) or while being in the backstack.

For ViewModels, in addition to being forgotten when they're really not needed anymore, their coroutineScope will also be automatically canceled because ViewModel's onCleared method will be automatically called.

💡 Optional key: a key can be provided to the call, rememberScoped(key) { ... } or viewModelScoped(key) { ... }. This makes possible to forget an old object when there is new input data during a recomposition (e.g. a new input id for your ViewModel).

💡 Optional clearDelay: a clearDelay can be provided to delay the disposal of the scoped object after the Composable is removed from composition. This is useful when a Composable might briefly leave composition and return (e.g. quick navigation back and forth), and you want to avoid recreating expensive objects. Usage: rememberScoped(clearDelay = 5.seconds) { ... } or viewModelScoped(clearDelay = 5.seconds). If the Composable returns to composition before the delay expires, the disposal is cancelled and the same object is reused.

⚠️ Note that ViewModels remembered with viewModelScoped should not be created using any of the Compose viewModel() or ViewModelProviders factories, otherwise they will be retained in the scope of the screen regardless of viewModelScoped. Also, if a ViewModel is remembered with rememberScoped, instead of viewModelScoped, then its clean-up method won't be called, so it's always better to use viewModelScoped for ViewModels.

Sample use cases

Here are some sample use cases reported by the users of this library:

• ❤️ Isolated and stateful UI components like a favorite button that are widely used across the screens. This FavoriteViewModel can be very small, focused and only require an id to work without affecting the rest of the screen's UI and state.
• 🗪 Dialog pop-ups can have their own business-logic with state that is better to isolate in a separate ViewModel but the lifespan of these dialogs might be short, so it's important to clean-up the ViewModel associated to a Dialog after it has been closed.
• 📃 A LazyColumn with a ViewModel per list item. Each item can have its own complex logic in an isolated ViewModel that will be lazily loaded when the item is visible for the first time. The ViewModel will cleared and destroyed when the item is not part of the list in the source data or the whole LazyColumn is removed.
• 📄📄 Multiple instances of the same type of ViewModel in a screen with a view-pager. This screen will have multiple sub-pages that use the same ViewModel class with different ids. For example, a screen of holiday destinations with multiple pages and each page with its own HolidayDestinationViewModel.

Demo app

Demo app documentation can be found here.

Multiplatform support

Compose Multiplatform

Since version 4.0, Resaca supports Compose Multiplatform for Android, iOS, Desktop-JVM and Web targets. To see an example of usage and configuration check the Sample Compose Multiplatform project in the samplecmp module.

Kotlin Multiplatform

Resaca is a Kotlin Multiplatform library and can be used in any Kotlin Multiplatform project that targets Android, iOS, Desktop-JVM and Web. Nevertheless, Resaca does not make sense in a SwiftUI project because it's a Compose only library, instead, if you want to scope ViewModels to SwiftUI views, you can look at the solutions provided in the first comments of