amethyst: Skill for Claude Code

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.

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 navigation events, snackbars, or other one-shot emissions 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 UI consumer handling exactly-once events such as navigation or snackbars, a buffered Channel exposed as a Flow often matches the semantics better:

// ❌ BAD
private val _navEvents = MutableSharedFlow<NavigationEvent>()
val navEvents: SharedFlow<NavigationEvent> = _navEvents.asSharedFlow()

// ✅ GOOD
private val _navEvents = Channel<NavigationEvent>(Channel.BUFFERED)
val navEvents: Flow<NavigationEvent> = _navEvents.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 storage, or a deliberately configured SharedFlow instead.