kotlin-flow-state-event-modeling

Kotlin Flow: state and event modeling

Core principle

Pick the primitive that matches replay, fan-out, and synchronous-read requirements. StateFlow, SharedFlow, Channel-backed flows, and cold Flow differ in buffering, who sees each emission, and whether .value exists. Wrong choices drop events, leak sharing coroutines, or force fake domain sentinels into state. This project's DataProcessor.kt is the canonical example of a cold Flow produced from a suspend boundary with the catch operator for error handling.

When to use this skill

You're writing or reviewing Kotlin code involving:

• MutableStateFlow<T>(SomeSentinel) — NoUser, Empty, Loading, etc. — because the real value is async
• .stateIn(...) called inside a function rather than assigned to a property
• SharingStarted.WhileSubscribed(...) on a flow whose .value is read synchronously and must stay fresh
• MutableSharedFlow for a one-shot notification where loss would be a bug
• .map { } on a StateFlow when consumers still need synchronous .value
• MutableStateFlow.value = _state.value.copy(...) or update code that builds expensive objects inside update { ... }

SharedFlow for single-consumer fire-once events

SharedFlow defaults have no replay buffer. If nothing is collecting at the exact instant of emission, the event is gone. For a single downstream consumer handling exactly-once events — a job-completion signal, a one-shot notification — a buffered Channel exposed as a Flow often matches the semantics better:

// ❌ BAD
private val _jobEvents = MutableSharedFlow<JobEvent>()
val jobEvents: SharedFlow<JobEvent> = _jobEvents.asSharedFlow()

// ✅ GOOD
private val _jobEvents = Channel<JobEvent>(Channel.BUFFERED)
val jobEvents: Flow<JobEvent> = _jobEvents.receiveAsFlow()

Channel.receiveAsFlow() is fan-out, not broadcast: with multiple collectors, each event is delivered to one collector. Channel.BUFFERED is bounded, so sends can suspend and trySend can fail. If multiple observers must all see the same event, use explicit state, durable persistence, or a deliberately configured SharedFlow instead.