Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/adrielcafe/dalek
:robot: UI driven state machine for Android & JVM that will exterminate your bugs
https://github.com/adrielcafe/dalek
android android-library android-ui kotlin kotlin-android kotlin-library state-machine state-management
Last synced: 6 days ago
JSON representation
:robot: UI driven state machine for Android & JVM that will exterminate your bugs
- Host: GitHub
- URL: https://github.com/adrielcafe/dalek
- Owner: adrielcafe
- License: mit
- Created: 2020-01-24T17:01:30.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2021-08-09T02:27:43.000Z (over 3 years ago)
- Last Synced: 2024-11-07T13:38:20.102Z (9 days ago)
- Topics: android, android-library, android-ui, kotlin, kotlin-android, kotlin-library, state-machine, state-management
- Language: Kotlin
- Homepage:
- Size: 263 KB
- Stars: 26
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
- awesome-list - adrielcafe/dalek - :robot: UI driven state machine for Android & JVM that will exterminate your bugs (Kotlin)
README
[](https://jitpack.io/#adrielcafe/dalek)
[](https://github.com/adrielcafe/dalek/actions)
[](https://android-arsenal.com/api?level=16)
[](https://kotlinlang.org/)
[](https://ktlint.github.io/)
[](https://opensource.org/licenses/MIT)
# Dalek
Dalek is a [tiny](https://github.com/adrielcafe/Dalek/blob/master/dalek/src/main/java/cafe/adriel/dalek/Dalek.kt) (~10 LOC) [finite state machine](https://en.wikipedia.org/wiki/Finite-state_machine) that helps you manage the UI state of your app when running async/breakable tasks.
It's powered by [Coroutines Flow](https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/) and works on Android & JVM.
#### Why *Dalek*?
[Daleks](https://en.wikipedia.org/wiki/Dalek) are a fictional extraterrestrial race of mutants portrayed in [Doctor Who](https://en.wikipedia.org/wiki/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:
```kotlin
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 :robot:
## 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>`, where `T` is the output of your code (you can return `null`, `Unit` and `Any`, I won't judge you).
```kotlin
class MyViewModel(private val repository: PostRepository) : ViewModel() {
fun getPost(id: String): Flow> =
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
```kotlin
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:
```gradle
allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}
```
2. Next, add the library to your module:
```gradle
dependencies {
implementation "com.github.adrielcafe:dalek:$currentVersion"
}
```
Current version: [](https://jitpack.io/#adrielcafe/dalek)