Bloc

abstract class Bloc<S : Any, E : Any>(initialState: S) : StateEmitter<S>

Business Logic Component — the core state-management class.

A Bloc receives typed events, routes each one to a registered handler via on, and emits new states through emit. Every state change is observable via stateFlow.

// 1. Define events
sealed class CounterEvent {
    data object Increment : CounterEvent()
    data object Decrement : CounterEvent()
}

// 2. Create the Bloc
class CounterBloc : Bloc<Int, CounterEvent>(initialState = 0) {
    init {
        on<CounterEvent.Increment> { _, emit -> emit(state + 1) }
        on<CounterEvent.Decrement> { _, emit -> emit(state - 1) }
    }
}

// 3. Send events
counterBloc.send(CounterEvent.Increment)

Handler signature

typealias Handler<E, S> = suspend (event: E, emit: (S) -> Unit) -> Unit

Type Parameters

State type — must implement equals (data class or primitive recommended).

Event type — sealed class / interface recommended.

Inheritors

HydratedBloc

Constructors

Bloc

constructor(initialState: S)

Properties

errorsFlow

open override val errorsFlow: SharedFlow<Throwable>

Hot SharedFlow of errors surfaced via addError().

eventsFlow

val eventsFlow: SharedFlow<E>

Hot stream of every dispatched event, in arrival order.

isClosed

open override val isClosed: Boolean

true after close has been called. Further emissions become no-ops.

state

open override val state: S

The current state snapshot.

stateFlow

open override val stateFlow: StateFlow<S>

Hot StateFlow that replays the latest state to new collectors.

Functions

addError

fun addError(error: Throwable)

Signals an error without encoding it into the state type. Broadcasts to errorsFlow, then calls onError and BlocObserver.onError.

open override fun close()

Closes this Bloc: cancels the scope, cancels all active jobs, and marks it closed. After calling close, send and emit become no-ops.

emit

open fun emit(nextState: S)

Emits a new nextState.

onChange

open fun onChange(change: Change<S>)

Called after every emit. Always call super.onChange(change) to forward to BlocObserver.onChange.

onClose

open fun onClose()

Called when close completes. Cancel any background coroutines here. Always call super.onClose() to forward to BlocObserver.onClose.

onError

open fun onError(error: Throwable)

Called whenever addError is invoked. Always call super.onError(error) to forward to BlocObserver.onError.

onEvent

open fun onEvent(event: E)

Called immediately before an event is dispatched to its handler. Always call super.onEvent(event) to forward to BlocObserver.onEvent.

onTransition

open fun onTransition(transition: Transition<E, S>)

Called after a synchronous emit that has an active event context. Always call super.onTransition(transition) to forward to BlocObserver.onTransition.

send

fun send(event: E)

Dispatches event to the first registered handler whose predicate matches.