adrielcafe / dalek

:robot: UI driven state machine for Android & JVM that will exterminate your bugs

Dalek

Dalek is a tiny (~10 LOC) finite state machine that helps you manage the UI state of your app when running async/breakable tasks.

It's powered by Coroutines Flow and works on Android & JVM.

Why Dalek?

Daleks are a fictional extraterrestrial race of mutants portrayed in Doctor Who.

They are creatures that live inside a tank-like robotic shell, and this is basically how this library works: your code (the "creature") is wrapped and executed inside a state machine (the "robotic shell").

"EXTERMINATE! EXTERMINATE! EXTERMINATE!"
(Any Dalek will say that)

Motivation

Let's imagine the following scenario: you need to retrieve a Post object from a REST API, something like:

class PostRepository {

    suspend fun getPost(id: String): Post {
        // async api call
        // serialization
        // error handling
    }
}

It's an asynchronous operation that can take a while to complete and can fail (TimeoutException, IOException, SerializationException...). But wait, there's more: you need to keep the UI updated so your user knows what's going on.

This is a nightmare, right? Calm down! Dalek is here to help 🤖

Usage

1. Wrap your code inside Dalek

To start using Dalek, you just need to wrap your existing code inside it.

Dalek will run your code inside a suspend fun and return a Flow<DalekEvent<T>>, where T is the output of your code (you can return null, Unit and Any, I won't judge you).

class MyViewModel(private val repository: PostRepository) : ViewModel() {

    fun getPost(id: String): Flow<DalekEvent<Post>> =
        Dalek(Dispatchers.IO) {
            repository.getPost(id)
        }
}

2. Handle the UI events

Dalek will emit the following events:

• Start: always emitted
• Success(value: T): only emitted when your code is successfully executed
• Failure(exception: Throwable): only emitted when an exception is thrown
• Finish: always emitted

class MyActivity : AppCompatActivity() {

    private fun loadPost(id: String) {
        viewModel.getPost(id)
            .collectIn(lifecycleScope) { event ->
                when (event) {
                    is Start -> setLoading(true)
                    is Success -> showPost(event.value)
                    is Failure -> showError(event.exception)
                    is Finish -> setLoading(false)
                }
            }
    }
}

Import to your project

1. Add the JitPack repository in your root build.gradle at the end of repositories:

allprojects {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

2. Next, add the library to your module:

dependencies {
    implementation "com.github.adrielcafe:dalek:$currentVersion"
}

Current version: