We will get to the one-time event state handling in a second. The main takeaway from this code snippet is the collection of the MainViewState held by the MainViewModel.

Additionally to mention is that we wrap the MainContent in a Scaffold to introduce a SnackbarHost that will be later used to invoke the Snackbar on each of the one-time events.

One-Time-Event Anti-Pattern

Before we come to the Compose State Events way of implementing one-time events, let’s have a look at what the anti-pattern looks like that Manuel Vivo talked about in the article mentioned at the beginning.

As explained in the introduction, the anti-pattern is to call your unique events without ensuring that they are actually consumed, which can lead to unexpected behavior.

To showcase this, let’s take a look at an implementation for our screen with that anti-pattern:

class AntiPatternViewModel : ViewModel() {

    private val _viewState = MutableStateFlow(MainViewState())
    val viewState = _viewState.asStateFlow()

    private val _onProcessSuccessWithTimestamp = MutableSharedFlow<String>()
    val onProcessSuccessWithTimestamp = _onProcessSuccessWithTimestamp.asSharedFlow()

    private val _onProcessSuccess = MutableSharedFlow<Unit>()
    val onProcessSuccess = _onProcessSuccess.asSharedFlow()

    fun startProcess(useTimestamp: Boolean) {

        viewModelScope.launch {

            _viewState.update { currentState -> currentState.copy(isLoading = true) }

            delay(3_000)

            _viewState.update { currentState -> currentState.copy(isLoading = false) }

            if (useTimestamp) {
                _onProcessSuccessWithTimestamp.emit(SimpleDateFormat.getTimeInstance().format(Date()))
            } else {
                _onProcessSuccess.emit(Unit)
            }
        }
    }
}

As you can see, for calling the one-time events we make use of SharedFlow. We have two separate flows. One for the process finished without and one for the case with a timestamp.

Of course, you could merge both into one, but for the sake of clarity we leave that away for now.

The startProcess(..) function is called from each of our button callbacks with the respective input parameter for either delivering a timestamp on process finish or not.

To consume these events, we extend the previously shown MainScreen composable with a new LaunchedEffect that on the other hand collects both of our SharedFlow streams in a repeatOnLifecycle(..) body.

@Composable
private fun MainScreen(viewModel: AntiPatternViewModel = viewModel()) {

    val viewState: MainViewState by viewModel.viewState.collectAsStateWithLifecycle()

    val snackbarHostState = remember { SnackbarHostState() }

    val lifecycle = LocalLifecycleOwner.current.lifecycle

    LaunchedEffect(key1 = Unit) {
        lifecycle.repeatOnLifecycle(state = Lifecycle.State.STARTED) {
            launch {
                viewModel.onProcessSuccess.collectLatest {
                    snackbarHostState.showSnackbar("Event success")
                }
            }
            launch {
                viewModel.onProcessSuccessWithTimestamp.collectLatest { timestamp: String ->
                    snackbarHostState.showSnackbar("Event success at: $timestamp")
                }
            }
        }
    }
    ..
  }

The respective Snackbar is then shown by calling the SnackbarHostState which acts as input for the previously shown Scaffold that wraps the MainContent.

Using Compose State Events

Now that we saw the anti-pattern, let’s take a look at how we can implement the suggested way by using the Compose State Events library.

Setup

To use the library make sure to include the following dependency in your app-level build.gradle file. At the time of writing the library, version is at 1.1.0:

dependencies {
    ..
    implementation 'com.github.leonard-palm:compose-state-events:1.1.0'
}

Compose State Events

The purpose of the library is essential to facilitate the process of moving these one-time events away from their own streams into the view state of the respective ViewModel class.

Therefore the library introduces two new classes.

• StateEvent: Can be used for simple one-time event state representations, in our sample use case if the process has finished without further state implications.
• StateEventWithContent<T>: Can be used for one-time event state representations in which you need to pass a result object. In our sample use case that is if the process has finished and we want to know the timestamp.

Each of the classes can be in either the consumed or triggered state.

By using the approach of integrating one-time events into your view state object, you always have the case of the state representation and telling the view model that it got consumed.

Because in Jetpack Compose you will handle this case with the LaunchedEffect, the library comes with a handy wrapper called EventEffect that automatically handles this process.

It only requires the following two input parameters:

• event: The StateEvent or StateEventWithContent reference from your respective view state.
• onConsumed: The function reference the view model function that will mark the event as consumed.

The implementation

Now that you heard about the basics of the library, let’s take a look at how we can migrate the anti-pattern example to use the Compose State Events library.

As a first step, let’s extend the MainViewState that currently only holds the loading state with the Compose State Events objects for both of our one-time events.

import de.palm.composestateevents.StateEvent
import de.palm.composestateevents.StateEventWithContent
import de.palm.composestateevents.consumed

data class MainViewState(
    val isLoading: Boolean = false,
    val processSuccessEvent: StateEvent = consumed,
    val processSuccessWithTimestampEvent: StateEventWithContent<String> = consumed(),
)

Now that we updated the MainViewState, let’s migrate the ViewModel class accordingly:

class MainViewModel : ViewModel() {

    private val _viewState = MutableStateFlow(MainViewState())
    val viewState = _viewState.asStateFlow()

    fun startProcess(useTimestamp: Boolean) {

        viewModelScope.launch {

            _viewState.update { currentState -> currentState.copy(isLoading = true) }

            delay(3_000)

            if (useTimestamp) {
                _viewState.update { currentState ->
                    currentState.copy(
                        messageWithTimestampEvent = triggered(SimpleDateFormat.getTimeInstance().format(Date())),
                        isLoading = false
                    )
                }
            } else {
                _viewState.update { currentState ->
                    currentState.copy(
                        messageEvent = triggered,
                        isLoading = false
                    )
                }
            }
        }
    }

    fun setShowMessageConsumed() {
        _viewState.update { currentState ->
            currentState.copy(
                messageEvent = consumed,
                messageWithTimestampEvent = consumed()
            )
        }
    }
}

Instead of emitting standalone SharedFlow streams individually, we now use the MainViewState wrapped in the StateFlow not only to update view states but also to call our one-time events.

To set them in the “invoked” state, we set the StateEvent objects to the triggered state.

We also introduced a new function that sets our StateEvent functions back to the consumed value.

In a real-world example, you would want to use two individual functions for setting this consumption state.

Now let’s see how we can adapt the anti-pattern version of the MainScreen to consume our StateEvents.

@Composable
private fun MainScreen(viewModel: MainViewModel = viewModel()) {

    val viewState: MainViewState by viewModel.viewState.collectAsStateWithLifecycle()

    val snackbarHostState = remember { SnackbarHostState() }

    EventEffect(
        event = viewState.processSuccessEvent,
        onConsumed = viewModel::setShowMessageConsumed
    ) {
        snackbarHostState.showSnackbar("Event success")
    }

    EventEffect(
        event = viewState.processSuccessWithTimestampEvent,
        onConsumed = viewModel::setShowMessageConsumed
    ) { timestamp: String ->
        snackbarHostState.showSnackbar("Event success at: $timestamp")
    }
    
    ..
}