💥 Add Emitter receiver to mapEventToState method

Previously, Bloc implementations could emit from anywhere, making it hard to enforce correct usage.

This commit removes the emit method from BlocBase and moves it to a new Emitter interface, which is used as the receiver for mapEventToState.

This allows us to enforce the pattern whereby Blocs can only emit within the mapEventToState method.

Additionally, Cubits now implement the Emitter interface, maintaining their ability to emit from anywhere.

Author: Peter Bryant

compose/src/test/java/com/ptrbrynt/kotlin_bloc/compose/blocs/CounterBloc.kt

@@ -1,11 +1,12 @@
 package com.ptrbrynt.kotlin_bloc.compose.blocs
 
 import com.ptrbrynt.kotlin_bloc.core.Bloc
+import com.ptrbrynt.kotlin_bloc.core.Emitter
 
 enum class CounterEvent { Increment, Decrement }
 
 class CounterBloc : Bloc<CounterEvent, Int>(0) {
-    override suspend fun mapEventToState(event: CounterEvent) {
+    override suspend fun Emitter<Int>.mapEventToState(event: CounterEvent) {
         when (event) {
             CounterEvent.Increment -> emit(state + 1)
             CounterEvent.Decrement -> emit(state - 1)

core/src/main/java/com/ptrbrynt/kotlin_bloc/core/Bloc.kt

@@ -21,12 +21,22 @@ abstract class Bloc<Event, State>(initial: State) : BlocBase<State>(initial) {
     private val transitionFlow = eventFlow
         .onEach { onEvent(it) }
         .transformEvents()
-        .onEach { mapEventToState(it) }
+        .onEach { emitter.mapEventToState(it) }
         .zip(mutableChangeFlow) { event, change ->
             Transition(change.state, event, change.newState)
         }
         .onEach { onTransition(it) }
 
+    private val emitter = object : Emitter<State> {
+        override suspend fun emit(state: State) {
+            mutableChangeFlow.emit(Change(this@Bloc.state, state))
+        }
+
+        override suspend fun emitEach(states: Flow<State>) {
+            states.onEach { emit(it) }.launchIn(blocScope)
+        }
+    }
+
     init {
         transitionFlow.launchIn(blocScope)
     }
@@ -39,8 +49,11 @@ abstract class Bloc<Event, State>(initial: State) : BlocBase<State>(initial) {
      * set of [State]s.
      *
      * [mapEventToState] can emit zero, one, or multiple [State]s for each [event].
+     *
+     * [mapEventToState] receives this [Bloc]s [Emitter], which allows [mapEventToState] to call
+     * the [Emitter.emit] method to trigger a state change.
      */
-    abstract suspend fun mapEventToState(event: Event)
+    abstract suspend fun Emitter<State>.mapEventToState(event: Event)
 
     /**
      * Notifies the [Bloc] of a new [event], which triggers [mapEventToState].

core/src/main/java/com/ptrbrynt/kotlin_bloc/core/BlocBase.kt

@@ -34,13 +34,6 @@ abstract class BlocBase<State>(initial: State) {
      */
     val stateFlow = mutableChangeFlow.map { it.newState }
 
-    /**
-     * Causes this to emit a new [state].
-     */
-    protected suspend fun emit(state: State) {
-        mutableChangeFlow.emit(Change(this@BlocBase.state, state))
-    }
-
     /**
      * The current [State]
      */

core/src/main/java/com/ptrbrynt/kotlin_bloc/core/Cubit.kt

@@ -1,5 +1,9 @@
 package com.ptrbrynt.kotlin_bloc.core
 
+import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.launchIn
+import kotlinx.coroutines.flow.onEach
+
 /**
  * A [Cubit] is similar to a [Bloc] but has no notion of events,
  * instead relying on methods to [emit] [State]s.
@@ -18,4 +22,12 @@ package com.ptrbrynt.kotlin_bloc.core
  * @see Bloc
  */
 
-abstract class Cubit<State>(initial: State) : BlocBase<State>(initial)
+abstract class Cubit<State>(initial: State) : BlocBase<State>(initial), Emitter<State> {
+    override suspend fun emit(state: State) {
+        mutableChangeFlow.emit(Change(this.state, state))
+    }
+
+    override suspend fun emitEach(states: Flow<State>) {
+        states.onEach { emit(it) }.launchIn(blocScope)
+    }
+}

core/src/main/java/com/ptrbrynt/kotlin_bloc/core/Emitter.kt

@@ -0,0 +1,18 @@
+package com.ptrbrynt.kotlin_bloc.core
+
+import kotlinx.coroutines.flow.Flow
+
+/**
+ * Interface which can be implemented on any object which can [emit] a [State].
+ */
+interface Emitter<State> {
+    /**
+     * Emit a new [State]
+     */
+    suspend fun emit(state: State)
+
+    /**
+     * [emit] each [State] which is emitted by the [states] [Flow].
+     */
+    suspend fun emitEach(states: Flow<State>)
+}

core/src/test/java/com/ptrbrynt/kotlin_bloc/core/blocs/CounterBloc.kt

@@ -1,6 +1,7 @@
 package com.ptrbrynt.kotlin_bloc.core.blocs
 
 import com.ptrbrynt.kotlin_bloc.core.Bloc
+import com.ptrbrynt.kotlin_bloc.core.Emitter
 import com.ptrbrynt.kotlin_bloc.core.Transition
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.filter
@@ -11,7 +12,7 @@ open class CounterBloc(
     private val onTransitionCallback: ((Transition<CounterEvent, Int>) -> Unit)? = null,
     private val onEventCallback: ((CounterEvent) -> Unit)? = null,
 ) : Bloc<CounterEvent, Int>(0) {
-    override suspend fun mapEventToState(event: CounterEvent) {
+    override suspend fun Emitter<Int>.mapEventToState(event: CounterEvent) {
         when (event) {
             CounterEvent.Increment -> emit(state + 1)
             CounterEvent.Decrement -> emit(state - 1)

core/src/test/java/com/ptrbrynt/kotlin_bloc/core/blocs/MultiFlowBloc.kt

@@ -1,10 +1,9 @@
 package com.ptrbrynt.kotlin_bloc.core.blocs
 
 import com.ptrbrynt.kotlin_bloc.core.Bloc
+import com.ptrbrynt.kotlin_bloc.core.Emitter
 import kotlinx.coroutines.ExperimentalCoroutinesApi
 import kotlinx.coroutines.flow.MutableStateFlow
-import kotlinx.coroutines.flow.launchIn
-import kotlinx.coroutines.flow.onEach
 
 sealed class MultiFlowEvent
 
@@ -17,9 +16,9 @@ data class MultiFlowNumberAdded(val number: Int) : MultiFlowEvent()
 class MultiFlowBloc : Bloc<MultiFlowEvent, List<Int>>(emptyList()) {
     private val numbers = MutableStateFlow(emptyList<Int>())
 
-    override suspend fun mapEventToState(event: MultiFlowEvent) {
+    override suspend fun Emitter<List<Int>>.mapEventToState(event: MultiFlowEvent) {
         when (event) {
-            is MultiFlowInitialized -> numbers.onEach { emit(it) }.launchIn(blocScope)
+            is MultiFlowInitialized -> emitEach(numbers)
             is MultiFlowNumberAdded -> {
                 numbers.tryEmit(numbers.value + event.number)
             }

core/src/test/java/com/ptrbrynt/kotlin_bloc/core/blocs/SeededBloc.kt

@@ -1,9 +1,10 @@
 package com.ptrbrynt.kotlin_bloc.core.blocs
 
 import com.ptrbrynt.kotlin_bloc.core.Bloc
+import com.ptrbrynt.kotlin_bloc.core.Emitter
 
 class SeededBloc(private val seed: List<Int>, initial: Int) : Bloc<String, Int>(initial) {
-    override suspend fun mapEventToState(event: String) {
+    override suspend fun Emitter<Int>.mapEventToState(event: String) {
         for (value in seed) {
             emit(value)
         }

docs/bloc-compose.md

@@ -69,7 +69,7 @@ Let's take a look at how to use `BlocComposer` to hook up a `Counter` widget to
 enum class CounterEvent { Incremented }
 
 class CounterBloc: Bloc<CounterEvent, Int>(0) {
-  override suspend fun mapEventToState(event: CounterEvent) {
+  override suspend fun Emitter<Int>.mapEventToState(event: CounterEvent) {
     when (event) {
       is CounterEvent.Incremented -> emit(state + 1)
     }

docs/core-concepts.md

@@ -140,19 +140,21 @@ Using `Bloc` requires us to override the `mapEventToState` method. This will be
 enum class CounterEvent { Incremented }
 
 class CounterBloc: Bloc<CounterEvent, Int>(0) {
-  override suspend fun mapEventToState(event: CounterEvent) {
+  override suspend fun Emitter<Int>.mapEventToState(event: CounterEvent) {
 
   }
 }
 ```
 
+?> The `mapEventToState` method receives an `Emitter`, which provides the `emit` and `emitEach` methods we'll use below. This means that, while a `Cubit` can `emit` from anywhere, a `Bloc` can only `emit` from within the `mapEventToState` method.
+
 We can then update `mapEventToState` to handle the `CounterEvent.Incremented` event:
 
 ```kotlin
 enum class CounterEvent { Incremented }
 
 class CounterBloc: Bloc<CounterEvent, Int>(0) {
-  override suspend fun mapEventToState(event: CounterEvent) {
+  override suspend fun Emitter<Int>.mapEventToState(event: CounterEvent) {
     when (event) {
       CounterEvent.Incremented -> emit(state + 1)
     }
@@ -273,7 +275,7 @@ class CounterCubit : Cubit<Int>(0) {
 enum class CounterEvent { Increment }
 
 class CounterBloc : Bloc<CounterEvent, Int>(0) {
-  override suspend fun mapEventToState(event: CounterEvent) {
+  override suspend fun Emitter<Int>.mapEventToState(event: CounterEvent) {
     when (event) {
       is CounterEvent.Increment -> emit(state + 1)
     }

docs/tutorials/todo-list.md

@@ -148,12 +148,12 @@ Now we have our events and states, we can create our `TodosBloc` class:
 
 ```kotlin
 class TodosBloc(private val todoDao: TodoDao) : Bloc<TodosEvent, TodosState>(TodosLoading) {
-    override suspend fun mapEventToState(event: TodosEvent) {
+    override suspend fun Emitter<TodosState>.mapEventToState(event: TodosEvent) {
         when (event) {
             is TodosInitialized -> {
-                todoDao.getAllTodos()
-                    .onEach { emit(TodosLoadSuccess(it)) }
-                    .launchIn(blocScope)
+                emitEach(
+                  todoDao.getAllTodos().map { TodosLoadSuccess(it) },
+                )
             }
             is TodoAdded -> {
                 todoDao.addTodo(Todo(name = event.name))
@@ -177,9 +177,9 @@ class TodosBloc(private val todoDao: TodoDao) : Bloc<TodosEvent, TodosState>(Tod
 
 Let's briefly talk through how this works.
 
-1. When the `TodosInitialized` event is added, the `TodosBloc` will get a `Flow` containing the current `List<Todo>` from our DAO using the `getAllTodos()` method. Room has built-in support for [observable queries](https://developer.android.com/training/data-storage/room/async-queries#flow-coroutines) using Flow.
-2. We are then adding an `onEach` call to this Flow, which `emit`s the current value provided by `getAllTodos()`. We then launch this flow using the `launchIn` method, and pass in the `blocScope` which is provided by the Bloc library.
-3. For all other events, we are simply calling the relevant DAO method. Thanks to Room's observable query, we don't need to manually retrieve and emit the new list of Todos, as this will be handled by the observable query we set up in steps 1 and 2.
+1. When the `TodosInitialized` event is added, the `TodosBloc` gets a `Flow` of the current list of `Todo`s using the `getAllTodos()` method on the DAO. It then `map`s this flow into `TodosLoadSuccess` states containing the current value.
+2. This flow of states is then passed into the `emitEach` method, which provided by the `Emitter` receiver. This will listen to the provided flow and emit each value.
+3. For all other events, we are simply calling the relevant DAO method. Thanks to Room's observable query, we don't need to manually retrieve and emit the new list of Todos, as this will be handled by the `emitEach` call we set up in steps 1 and 2.
 
 ## Koin Module
 

sample/src/main/java/com/ptrbrynt/kotlin_bloc/sample/ui/blocs/CounterBloc.kt

@@ -1,11 +1,12 @@
 package com.ptrbrynt.kotlin_bloc.sample.ui.blocs
 
 import com.ptrbrynt.kotlin_bloc.core.Bloc
+import com.ptrbrynt.kotlin_bloc.core.Emitter
 
 enum class CounterEvent { Increment, Decrement }
 
 class CounterBloc : Bloc<CounterEvent, Int>(0) {
-    override suspend fun mapEventToState(event: CounterEvent) {
+    override suspend fun Emitter<Int>.mapEventToState(event: CounterEvent) {
         when (event) {
             CounterEvent.Increment -> emit(state + 1)
             CounterEvent.Decrement -> emit(state - 1)