Ballast

Opinionated Application State Management framework for Kotlin Multiplatform

object TodosContract { 
    data class State(
        val loading: Boolean = false, 
        val todos: List<String> = emptyList(), 
    )

    sealed interface Inputs {
        data object FetchSavedTodos : Inputs
        data class AddTodo(val text: String) : Inputs
        data class RemoveTodo(val text: String) : Inputs
    }
}

class TodosInputHandler : InputHandler<Inputs, Events, State> {
    override suspend fun InputHandlerScope<Inputs, Events, State>.handleInput(
        input: TodosContract.Inputs
    ) = when (input) {
        is FetchSavedTodos -> { 
            updateState { it.copy(loading = true) }
            val todos = todosApi.fetchTodos()
            updateState { it.copy(loading = false, todos = todos) }
        }
        is AddTodo -> {
            updateState { it.copy(todos = it.todos + input.text) }
        }
        is RemoveTodo -> {
            updateState { it.copy(todos = it.todos - input.text) }
        }
    }
}

@Composable
fun App() { 
    val coroutineScope = rememberCoroutineScope()
    val vm = remember(coroutineScope) { TodosViewModel(coroutineScope) }
    val vmState by vm.observeStates().collectAsState()

    LaunchedEffect(vm) { 
        vm.send(TodosContract.FetchSavedTodos)
    }

    TodosList(vmState) { vm.trySend(it) }
}

@Composable
fun TodosList(
    vmState: TodosContract.State,
    postInput: (TodosContract.Inputs)->Unit,
) {
    // ...
}

This snippet omits some details for brevity, to demonstrate the general idea

Supported Platforms/Features

Ballast was intentionally designed to not be tied directly to any particular platform or UI toolkit. In fact, while most Kotlin MVI libraries were initially developed for Android and show many artifacts of that initial base, Ballast started as a State Management solution for Compose Desktop.

Because Ballast was initially designed entirely in a non-Android context, it should work in any Kotlin target or platform as long as it works with Coroutines and Flows. However, the following targets are officially supported, in that they have been tested and are known to work there, or have specific features for that platform

Installation

repositories {
    mavenCentral()

    // SNAPSHOT builds are available as well at the MavenCentral Snapshots repository
    maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots")
}

// for plain JVM or Android projects
dependencies {
    implementation("io.github.copper-leaf:ballast-core:{{site.version}}")

    implementation("io.github.copper-leaf:ballast-repository:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-saved-state:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-sync:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-undo:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-navigation:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-schedules:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-crash-reporting:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-analytics:{{site.version}}")
    implementation("io.github.copper-leaf:ballast-debugger-client:{{site.version}}")

    testImplementation("io.github.copper-leaf:ballast-test:{{site.version}}")
}

// for multiplatform projects
kotlin {
    sourceSets {
        val commonMain by getting {
            dependencies {
                implementation("io.github.copper-leaf:ballast-core:{{site.version}}")

                implementation("io.github.copper-leaf:ballast-repository:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-saved-state:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-sync:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-undo:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-navigation:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-schedules:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-crash-reporting:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-analytics:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-debugger-client:{{site.version}}")=
            }
        }
        val commonTest by getting {
            dependencies {
                implementation("io.github.copper-leaf:ballast-test:{{site.version}}")
            }
        }
        val androidMain by getting {
            dependencies {
                implementation("io.github.copper-leaf:ballast-firebase-crashlytics:{{site.version}}")
                implementation("io.github.copper-leaf:ballast-firebase-analytics:{{site.version}}")
            }
        }
    }
}

Documentation

See the website for detailed documentation and usage instructions.

Community Chat

Join us at https://kotlinlang.slack.com in the #ballast channel for support, or to show off what you're building with Ballast!

https://kotlinlang.slack.com/archives/C03GTEJ9Y3E

License

Ballast is licensed under the BSD 3-Clause License, see LICENSE.md.

References

Ballast is not new, it was built upon years of experience building UI applications in Android and observing the direction UI programming has gone in the past few years. The MVI model has proven itself to be robust to a wide array of applications, and there are different implementations of the pattern that focus on different aspects of the pattern.

The following are some of the main libraries I drew inspiration from while using Ballast. If Ballast does not fit your project's needs, maybe one of these will suit you better. See the feature comparison for a better breakdown of the specific features of these libraries, to demonstrate the similarities and differences between them.

Redux: The OG of the MVI programming model. It also was not the first MVI library, but React+Redux has certainly been one of the biggest contributors to this pattern's popularity today, especially in JS, but also in many other tech spaces
Orbit MVI: A primary source of inspiration for Ballast. This library is mature and well-built, but in my opinion was built a little too closely to Android, making it less useful on other KMP targets. It also uses terminology from Redux like "reducer" and "transformer" that are intended to bridge the gap from users familiar with Redux, but are a bit confusing for developers new to MVI. It is also missing some key features that one would expect from an MVI library, like a graphical debugger.
How to write your own MVI system and why you shouldn't: An intro video to the Orbit MVI library, and one of the best introductions to the MVI model I've seen. By walking you through the thought process behind developing a simple MVI library, it reinforces the concepts of the pattern and helps you understand how to use a mature MVI library like Orbit or Ballast.

copper-leaf / ballast

readme