Orbit Multiplatform

CI status
codecov
Download
License

Logo

Get in touch

slack logo
twitter logo

What is Orbit

Orbit is a Redux/MVI-like library – but without the baggage. It’s so simple we
think of it as MVVM+.

  • Simple, type-safe, coroutine-style, extensible API
  • Multiplatform, targetting Android and iOS (iOS support is in alpha and being
    actively worked on)
  • Full support for Kotlin Coroutines (it’s built on top of them after all)
  • Lifecycle-safe collection of infinite flows
  • ViewModel support, along with SavedState
  • Optional, simple unit test library
  • Built-in espresso idling resource support
  • Compatible with RxJava, LiveData
    etc. through coroutine wrappers
  • And more…

Documentation

Articles & Talks

Getting started

Download

implementation("org.orbit-mvi:orbit-core:<latest-version>")
// or, if on Android:
implementation("org.orbit-mvi:orbit-viewmodel:<latest-version>")

// Tests
testImplementation("org.orbit-mvi:orbit-test:<latest-version>")

Define the contract

data class CalculatorState(
    val total: Int = 0
)

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

Create the 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.

Connect to the ViewModel in your Activity or Fragment

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) }

        viewModel.observe(state = ::render, sideEffect = ::handleSideEffect)
    }

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

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

With Jetpack Compose wire up the ViewModel as follows:

@Composable
fun CalculatorScreen(viewModel: CalculatorViewModel) {

    val state = viewModel.container.stateFlow.collectAsState().value

    LaunchedEffect(viewModel) {
        launch {
            viewModel.container.sideEffectFlow.collect { handleSideEffect(navController, it) }
        }
    }

    // render UI using data from 'state'
    ...
}

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

Contributing

Please read contributing
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

License

This project is licensed under the Apache License, Version 2.0 – see the
license file for details

GitHub

https://github.com/orbit-mvi/orbit-mvi