
Extension library enabling Compose-style presenters with Flow or State actions, event channels, nested presenters, ViewModel-managed lifecycles, and resolution of native integration conflicts.
Molecule Util is a Kotlin Multiplatform utility library for using CashApp Molecule presenters with AndroidX Lifecycle ViewModel.
It provides a small set of Compose helpers that keep Molecule presenters and UI event channels scoped to a ViewModel.
Supported targets:
implementation("io.github.aleyn97:molecule-util:version")| API | Purpose | Return value |
|---|---|---|
rememberModelPresenter |
State-only presenter | Model |
rememberEventPresenter |
Presenter to UI events | Pair<Model, Flow<Event>> |
rememberActionPresenter |
UI actions and presenter events | Triple<Model, Flow<Event>, SendChannel<Action>> |
rememberNestedPresenter |
Composition-scoped nested presenter | Pair<T, SendChannel<E>> |
Flow.collectEvent |
Collect presenter events | Nothing |
Flow.collectAction |
Collect UI action flow inside a presenter | Nothing |
All ViewModel-backed presenters are scoped to the current ViewModelStoreOwner. They survive
configuration changes and are cancelled when that owner is cleared.
Use rememberModelPresenter when the presenter only exposes state.
data class CounterState(
val count: Int,
)
@Composable
fun CounterPresenter(): CounterState {
var count by remember { mutableIntStateOf(0) }
return CounterState(count)
}
@Composable
fun CounterScreen() {
val state = rememberModelPresenter {
CounterPresenter()
}
Text("Clicked ${state.count} times")
}A presenter can also expose actions directly through its model. This keeps the
rememberModelPresenter API and avoids creating a separate action channel.
sealed interface CounterAction {
data object Increment : CounterAction
data object Decrement : CounterAction
}
data class CounterState(
val count: Int,
val action: (CounterAction) -> Unit,
)
@Composable
fun CounterPresenter(): CounterState {
var count by remember { mutableIntStateOf(0) }
return CounterState(
count = count,
action = { action ->
when (action) {
CounterAction.Increment -> count++
CounterAction.Decrement -> if (count > 0) count--
}
},
)
}
@Composable
fun CounterScreen() {
val state = rememberModelPresenter {
CounterPresenter()
}
Column {
Text("Clicked ${state.count} times")
Button(
onClick = {
state.action(CounterAction.Increment)
},
) {
Text("+")
}
Button(
onClick = {
state.action(CounterAction.Decrement)
},
) {
Text("-")
}
}
}This pattern is best for synchronous UI actions that only update presenter state. If actions need
buffering, backpressure, or asynchronous processing, use rememberActionPresenter instead.
Function properties take part in data-class equality. If model equality matters, keep the callback
stable with remember or use the action-channel API.
Use rememberActionPresenter when the UI sends actions to the presenter and the presenter emits
one-off events back to the UI.
sealed interface CounterAction {
data object Increment : CounterAction
data object Decrement : CounterAction
}
sealed interface CounterEvent {
data object LimitReached : CounterEvent
}
data class CounterState(
val count: Int,
)
@Composable
fun CounterPresenter(
actions: Flow<CounterAction>,
events: SendChannel<CounterEvent>,
): CounterState {
var count by remember { mutableIntStateOf(0) }
actions.collectAction {
when (this) {
CounterAction.Increment -> {
if (count < 10) {
count++
} else {
events.send(CounterEvent.LimitReached)
}
}
CounterAction.Decrement -> {
if (count > 0) count--
}
}
}
return CounterState(count)
}Consume it from Compose:
@Composable
fun CounterScreen() {
val (state, events, actions) = rememberActionPresenter { action, event ->
CounterPresenter(action, event)
}
events.collectEvent {
when (this) {
CounterEvent.LimitReached -> {
// Show a Snackbar, navigate, etc.
}
}
}
Column {
Text("Count: ${state.count}")
Button(
onClick = {
actions.trySend(CounterAction.Increment)
},
) {
Text("Increment")
}
}
}If the presenter only emits events and does not receive actions, use
rememberEventPresenter:
val (state, events) = rememberEventPresenter { event ->
TimerPresenter(event)
}
events.collectEvent {
// Handle TimerEvent
}SendChannel<Event>.Flow<Event> backed by Channel.receiveAsFlow().send() applies backpressure and suspends while the buffer is full.trySend() is non-suspending and can fail when the buffer is full.collectAction.Do not use the event flow as a broadcast stream. If multiple UI consumers need the same data, model it as state or introduce an explicit broadcast layer.
val state = rememberModelPresenter(
key = "profile",
) {
ProfilePresenter()
}The default key = null follows the standard AndroidX ViewModel behavior. Because the public APIs
wrap presenters in generic ViewModel classes, the following contract applies:
rememberModelPresenter per ViewModelStoreOwner when no key is supplied.rememberEventPresenter per owner when no key is supplied.rememberActionPresenter per owner when no key is supplied.key when multiple presenters of the same API type must coexist under one owner.A ViewModel-backed presenter is created once for a given key. Keep the following stable for the lifetime of that presenter:
keybodyuseImmediateClockIf the input to a presenter changes over time, pass it through a flow instead of capturing a new
value in body.
useImmediateClock defaults to false and is intended for tests or other non-frame-driven use
cases. Normal Compose UI should keep the default behavior.
val state = rememberModelPresenter(
key = "test",
useImmediateClock = true,
) {
CounterPresenter()
}rememberNestedPresenter is composition-scoped. It does not create a ViewModel and must only be
used from inside a Molecule presenter composition.
@Composable
fun ParentPresenter(): ParentState {
val (childState, childActions) = rememberNestedPresenter<ChildState, ChildAction> { actions ->
ChildPresenter(actions)
}
return ParentState(
child = childState,
)
}The nested presenter state and channel are discarded when the surrounding Molecule composition leaves. If the presenter must survive configuration changes, use one of the ViewModel-backed APIs instead.
ViewModel scope.ViewModelStoreOwner survives.NavBackStackEntry.Molecule Util is a Kotlin Multiplatform utility library for using CashApp Molecule presenters with AndroidX Lifecycle ViewModel.
It provides a small set of Compose helpers that keep Molecule presenters and UI event channels scoped to a ViewModel.
Supported targets:
implementation("io.github.aleyn97:molecule-util:version")| API | Purpose | Return value |
|---|---|---|
rememberModelPresenter |
State-only presenter | Model |
rememberEventPresenter |
Presenter to UI events | Pair<Model, Flow<Event>> |
rememberActionPresenter |
UI actions and presenter events | Triple<Model, Flow<Event>, SendChannel<Action>> |
rememberNestedPresenter |
Composition-scoped nested presenter | Pair<T, SendChannel<E>> |
Flow.collectEvent |
Collect presenter events | Nothing |
Flow.collectAction |
Collect UI action flow inside a presenter | Nothing |
All ViewModel-backed presenters are scoped to the current ViewModelStoreOwner. They survive
configuration changes and are cancelled when that owner is cleared.
Use rememberModelPresenter when the presenter only exposes state.
data class CounterState(
val count: Int,
)
@Composable
fun CounterPresenter(): CounterState {
var count by remember { mutableIntStateOf(0) }
return CounterState(count)
}
@Composable
fun CounterScreen() {
val state = rememberModelPresenter {
CounterPresenter()
}
Text("Clicked ${state.count} times")
}A presenter can also expose actions directly through its model. This keeps the
rememberModelPresenter API and avoids creating a separate action channel.
sealed interface CounterAction {
data object Increment : CounterAction
data object Decrement : CounterAction
}
data class CounterState(
val count: Int,
val action: (CounterAction) -> Unit,
)
@Composable
fun CounterPresenter(): CounterState {
var count by remember { mutableIntStateOf(0) }
return CounterState(
count = count,
action = { action ->
when (action) {
CounterAction.Increment -> count++
CounterAction.Decrement -> if (count > 0) count--
}
},
)
}
@Composable
fun CounterScreen() {
val state = rememberModelPresenter {
CounterPresenter()
}
Column {
Text("Clicked ${state.count} times")
Button(
onClick = {
state.action(CounterAction.Increment)
},
) {
Text("+")
}
Button(
onClick = {
state.action(CounterAction.Decrement)
},
) {
Text("-")
}
}
}This pattern is best for synchronous UI actions that only update presenter state. If actions need
buffering, backpressure, or asynchronous processing, use rememberActionPresenter instead.
Function properties take part in data-class equality. If model equality matters, keep the callback
stable with remember or use the action-channel API.
Use rememberActionPresenter when the UI sends actions to the presenter and the presenter emits
one-off events back to the UI.
sealed interface CounterAction {
data object Increment : CounterAction
data object Decrement : CounterAction
}
sealed interface CounterEvent {
data object LimitReached : CounterEvent
}
data class CounterState(
val count: Int,
)
@Composable
fun CounterPresenter(
actions: Flow<CounterAction>,
events: SendChannel<CounterEvent>,
): CounterState {
var count by remember { mutableIntStateOf(0) }
actions.collectAction {
when (this) {
CounterAction.Increment -> {
if (count < 10) {
count++
} else {
events.send(CounterEvent.LimitReached)
}
}
CounterAction.Decrement -> {
if (count > 0) count--
}
}
}
return CounterState(count)
}Consume it from Compose:
@Composable
fun CounterScreen() {
val (state, events, actions) = rememberActionPresenter { action, event ->
CounterPresenter(action, event)
}
events.collectEvent {
when (this) {
CounterEvent.LimitReached -> {
// Show a Snackbar, navigate, etc.
}
}
}
Column {
Text("Count: ${state.count}")
Button(
onClick = {
actions.trySend(CounterAction.Increment)
},
) {
Text("Increment")
}
}
}If the presenter only emits events and does not receive actions, use
rememberEventPresenter:
val (state, events) = rememberEventPresenter { event ->
TimerPresenter(event)
}
events.collectEvent {
// Handle TimerEvent
}SendChannel<Event>.Flow<Event> backed by Channel.receiveAsFlow().send() applies backpressure and suspends while the buffer is full.trySend() is non-suspending and can fail when the buffer is full.collectAction.Do not use the event flow as a broadcast stream. If multiple UI consumers need the same data, model it as state or introduce an explicit broadcast layer.
val state = rememberModelPresenter(
key = "profile",
) {
ProfilePresenter()
}The default key = null follows the standard AndroidX ViewModel behavior. Because the public APIs
wrap presenters in generic ViewModel classes, the following contract applies:
rememberModelPresenter per ViewModelStoreOwner when no key is supplied.rememberEventPresenter per owner when no key is supplied.rememberActionPresenter per owner when no key is supplied.key when multiple presenters of the same API type must coexist under one owner.A ViewModel-backed presenter is created once for a given key. Keep the following stable for the lifetime of that presenter:
keybodyuseImmediateClockIf the input to a presenter changes over time, pass it through a flow instead of capturing a new
value in body.
useImmediateClock defaults to false and is intended for tests or other non-frame-driven use
cases. Normal Compose UI should keep the default behavior.
val state = rememberModelPresenter(
key = "test",
useImmediateClock = true,
) {
CounterPresenter()
}rememberNestedPresenter is composition-scoped. It does not create a ViewModel and must only be
used from inside a Molecule presenter composition.
@Composable
fun ParentPresenter(): ParentState {
val (childState, childActions) = rememberNestedPresenter<ChildState, ChildAction> { actions ->
ChildPresenter(actions)
}
return ParentState(
child = childState,
)
}The nested presenter state and channel are discarded when the surrounding Molecule composition leaves. If the presenter must survive configuration changes, use one of the ViewModel-backed APIs instead.
ViewModel scope.ViewModelStoreOwner survives.NavBackStackEntry.