mvvmate
0.2.3indexedMinimal state management library enhances Compose projects with MVVM architecture, offering base classes for managing UI state, handling actions, and emitting side effects efficiently.
6
Stars
—
Used by
dependents
—
Health
/ 100
MVVMate
A minimal, type-safe state management library for Compose Multiplatform, built on the MVI (Model-View-Intent) pattern.
Why MVVMate?
- Zero boilerplate — define State + Action + ViewModel and you're done
- Type-safe — compiler-enforced contracts with typed error model ()
Modules
Platform Support
| Platform | Status |
|---|---|
| Android | ✅ |
| iOS (arm64, x64, simulatorArm64) | ✅ |
Installation
Add the modules you need to your build.gradle.kts:
kotlin {
sourceSets {
commonMain.dependencies {
// Core (required)
implementation("com.helloanwar.mvvmate:core:<version>")
// Optional modules — pick what you need
implementation("com.helloanwar.mvvmate:network:<version>")
implementation("com.helloanwar.mvvmate:actions:<version>")
implementation("com.helloanwar.mvvmate:network-actions:<version>")
}
}
}
Check Maven Central for the latest version.
Quick Start
1. Define your contracts
data class CounterState(
val count: Int = 0,
val isLoading: Boolean = false
) : UiState
sealed interface CounterAction : UiAction {
Increment : CounterAction
Decrement : CounterAction
Reset : CounterAction
}
2. Create your ViewModel
class CounterViewModel : BaseViewModel<CounterState, CounterAction>(
initialState = CounterState()
) {
override suspend fun onAction(action: CounterAction) {
when (action) {
CounterAction.Increment -> updateState { copy(count = count + 1) }
CounterAction.Decrement -> updateState { copy(count = count - 1) }
CounterAction.Reset -> updateState { copy(count = ) }
}
}
}
3. Connect to your Composable
@Composable
fun CounterScreen(viewModel: CounterViewModel = viewModel()) {
val state by viewModel.state.collectAsState()
Column(horizontalAlignment = Alignment.CenterHorizontally) {
Text("Count: ${state.count}", style = MaterialTheme.typography.headlineLarge)
Row {
Button(onClick = { viewModel.handleAction(CounterAction.Decrement) }) {
Text("-")
}
Button(onClick = { viewModel.handleAction(CounterAction.Increment) }) {
Text()
}
}
TextButton(onClick = { viewModel.handleAction(CounterAction.Reset) }) {
Text()
}
}
}
Architecture Diagram
┌─────────────────────────────────────────────┐
│ Composable UI │
│ ┌──────────┐ ┌──────────────────┐ │
│ │ state │◄────────│ collectAsState() │ │
│ └──────────┘ └──────────────────┘ │
│ ▲ │ │
│ │ handleAction() │
│ │ ▼ │
│ ┌────┴─────────────────────────────┐ │
│ │ ViewModel │ │
│ │ ┌─────────┐ ┌─────────────┐ │ │
│ │ │ State │ │ onAction() │ │ │
│ │ │ Flow │◄──│ (reducer) │ │ │
│ │ └─────────┘ └─────────────┘ │ │
│ │ ┌──────────────────────────┐ │ │
│ │ │ Side Effects (opt.) │───┼───────│
│ │ └──────────────────────────┘ │ │
│ └──────────────────────────────────┘ │
└─────────────────────────────────────────────┘
Side Effects Example
For one-time events like navigation, toasts, or dialogs:
class LoginViewModel : BaseViewModelWithEffect<LoginState, LoginAction, LoginEffect>(
initialState = LoginState()
) {
override suspend {
(action) {
LoginAction.Submit -> {
updateState { copy(isLoading = ) }
success = authRepo.login(action.email, action.password)
updateState { copy(isLoading = ) }
(success) {
emitSideEffect(LoginEffect.NavigateToHome)
} {
emitSideEffect(LoginEffect.ShowError())
}
}
}
}
}
Testing
MVVMate provides a robust flow-testing DSL based on CashApp's Turbine framework using the testing artifact.
Add the optional dependency:
kotlin {
sourceSets {
commonTest.dependencies {
implementation("com.helloanwar.mvvmate:testing:<version>")
}
}
}
Standard ViewModel Testing
For a simple BaseViewModel containing only states and actions:
@Test
fun testCounterViewModel() = runTest {
val viewModel = CounterViewModel()
viewModel.test {
// Automatically skips the initial emitted state or you can assert it:
expectStateEquals(CounterState(count = 0))
dispatchAction(CounterAction.Increment)
expectStateEquals(CounterState(count = 1))
dispatchAction(CounterAction.Decrement)
expectState { it.count == 0 } // Assert lambda
}
}
Side Effect Testing
For a BaseViewModelWithEffect, you can assert State and Effect emissions in chronological order:
@Test
fun testLoginViewModel() = runTest {
val viewModel = LoginViewModel()
viewModel.testEffects {
// Assert initial state
expectState { !it.isLoading }
// Start operation
dispatchAction(LoginAction.Submit("test@test.com", "pass"))
expectState { it.isLoading }
// Wait for the simulated effect, assert exact type
val effect = expectEffectClass<LoginEffect.NavigateToHome>()
// Assert ending state
expectState { !it.isLoading }
}
}
Form Validation
MVVMate provides a declarative, type-safe validation system through the forms module.
kotlin {
sourceSets {
commonMain.dependencies {
implementation("com.helloanwar.mvvmate:forms:<version>")
}
}
}
1. Define Form State
Use FormField<T> inside your UiState:
data class RegistrationState(
val email: FormField<String> = FormField(""),
val age: FormField<String> = FormField(""),
val isSubmitting: Boolean = false
) : UiState {
val isFormValid: Boolean get() = email.isValid && age.isValid
}
2. Update and Validate
Use setValue and built-in validators to cleanly update state and run validation rules inline:
Network Call Example
Detailed Guides
Logger Setup
MVVMate includes a pluggable logging system. Enable it during development:
// In your Application.onCreate() or main():
MvvMate.logger = PrintLogger // Built-in console logger
MvvMate.isDebug = true // Enable state change logging
AI Crash Logger
You can use the built-in MvvMateAiLogger to maintain a secure, GDPR-compliant ring buffer of chronological actions, states, networking, and side effects. If a crash occurs, you instantly get a perfect, human-readable timeline to feed into an LLM or logging service:
val aiLogger = MvvMateAiLogger(
delegate = PrintLogger, // also print to console
maxHistorySize = 50,
// Safely redacts emails, tokens, and credit cards from the final string output
redactor = RegexPrivacyRedactor(RegexPrivacyRedactor.DefaultPatterns())
)
MvvMate.logger = aiLogger
// When a crash occurs:
val crashContextString = aiLogger.takeRedactedSnapshotString()
LLM Autopilot Bridge (Agentic UI)
Want to let an AI "drive" your app? The AiActionBridge connects an LLM directly to your BaseViewModel.
It includes a strict AiActionPolicy to ensure the LLM can only execute safe, whitelisted actions, preventing it from doing things like deleting accounts or triggering payments.
// 1. Define a security policy
val safePolicy = object : AiActionPolicy<MyState, MyAction> {
override fun : {
action ! MyAction.DeleteAccount && action ! MyAction.Checkout
}
}
bridge = AiActionBridge(
viewModel = myViewModel,
policy = safePolicy,
parser = MyJsonActionParser()
)
bridge.dispatch(llmJsonOutput)
Or implement MvvMateLogger interface for custom integrations (Timber, Napier, etc.).
See Best Practices → Logging for details.
API Documentation
Full API docs generated by Dokka: anwarpro.github.io/mvvmate
Contributing
Contributions are welcome! Please see the issues tab for areas where help is needed.