readme-old.md

Orbit 2 for Kotlin and Android

Join us at the Kotlinlang slack!

If you do not yet have an account with the Kotlinlang slack workspace, sign up here.

If you're looking for the original Orbit library, it's available here.

Documentation

• Core module and architecture overview
• Coroutines
• RxJava 1
• RxJava 2
• RxJava 3
• LiveData
• ViewModel
• Test

Overview

Orbit 2 is a simple scaffolding you can build a Redux/MVI-like architecture around.

In Orbit 2 we have taken the best features of Orbit 1 and rewritten the rest from scratch.

• Easy to use, type-safe, extensible API
• Coroutine, RxJava (1 2 & 3!) and LiveData operator support
• ViewModel support, along with SavedState!
• Unit test framework designed in step with the framework
• Built-in espresso idling resource support

And more!...

Getting started in three simple steps

implementation("com.babylon.orbit2:orbit-viewmodel:<latest-version>")

Define the contract

First, we need to define its state and declared side effects.

data class CalculatorState(
    val total: Int = 0
)

sealed class CalculatorSideEffect {
    data class Toast(val text: String) : CalculatorSideEffect()
}

The only requirement here is that the objects are comparable. We also recommend they be immutable. Therefore we suggest using a mix of data classes, sealed classes and objects.

Create the ViewModel

Using the core Orbit functionality, we can create a simple, functional ViewModel.

1. Implement the ContainerHost interface
2. Override the container field and use the ViewModel.container factory function to build an Orbit Container in your ContainerHost

class CalculatorViewModel: ContainerHost<CalculatorState, CalculatorSideEffect>, ViewModel() {

    // Include `orbit-viewmodel` for the factory function
    override val container = container<CalculatorState, CalculatorSideEffect>(CalculatorState())

    fun add(number: Int) = intent {
        postSideEffect(CalculatorSideEffect.Toast("Adding $number to ${state.total}!"))

        reduce {
            state.copy(total = state.total + number)
        }
    }
}

We have used an Android ViewModel as the most common example, but there is no requirement to do so. You can host an Orbit Container in a simple class if you wish. This makes it possible to use in simple Kotlin projects as well as lifecycle independent services.

Connect to the ViewModel in your Activity or Fragment

Now we need to wire up the ViewModel to our UI. We expose coroutine Flows through which one can conveniently subscribe to updates. Alternatively you can convert these to your preferred type using externally provided extension methods e.g. asLiveData or asObservable.

class CalculatorActivity: AppCompatActivity() {

    // Example of injection using koin, your DI system might differ
    private val viewModel by viewModel<CalculatorViewModel>()

    override fun onCreate(savedState: Bundle?) {
        ...
        addButton.setOnClickListener { viewModel.add(1234) }

        lifecycleScope.launchWhenCreated {
            viewModel.container.stateFlow.collect { render(it) }
        }
        lifecycleScope.launchWhenCreated {
            viewModel.container.sideEffectFlow.collect { handleSideEffect(it) }
        }
    }

    private fun render(state: CalculatorState) {
        ...
    }

    private fun handleSideEffect(sideEffect: CalculatorSideEffect) {
        when (sideEffect) {
            is CalculatorSideEffect.Toast -> toast(sideEffect.text)
        }
    }
}

Syntax

There are two Orbit syntaxes to choose from.

We recommend using the simple syntax if you're just starting out or using coroutines exclusively in your codebase. The strict syntax is most useful when used in a codebase with mixed RxJava and coroutines.

class MyViewModel: ContainerHost<MyState, MySideEffect>, ViewModel() {

    override val container = container<MyState, MySideEffect>(MyState())

    // Simple
    fun loadDataForId(id: Int) = intent {
        postSideEffect(MySideEffect.Toast("Loading data for $id!"))

        val result = repository.loadData(id)

        reduce {
            state.copy(data = result)
        }
    }

    // Strict
    fun loadDataForId(id: Int) = orbit {
        sideEffect { post(MySideEffect.Toast("Loading data for $id!")) }
            .transformSuspend { repository.loadData(id) }
            .reduce {
                state.copy(data = result)
            }
    }
}

Modules

Orbit 2 is a modular framework. The Core module provides basic Orbit functionality with additional features provided through optional modules.

Orbit supports using various async/stream frameworks at the same time so it is perfect for legacy codebases. For example, it can support both RxJava 2 and coroutines if you are in the process of migrating from one to the other.

At the very least you will need the orbit-core module to get started, alternatively include one of the other modules which already include orbit-core.

implementation("com.babylon.orbit2:orbit-core:<latest-version>")
implementation("com.babylon.orbit2:orbit-viewmodel:<latest-version>")

// strict syntax DSL extensions
implementation("com.babylon.orbit2:orbit-coroutines:<latest-version>")
implementation("com.babylon.orbit2:orbit-rxjava1:<latest-version>")
implementation("com.babylon.orbit2:orbit-rxjava2:<latest-version>")
implementation("com.babylon.orbit2:orbit-rxjava3:<latest-version>")
implementation("com.babylon.orbit2:orbit-livedata:<latest-version>")

testImplementation("com.babylon.orbit2:orbit-test:<latest-version>")

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE.md file for details