repository·master·Indexed 41 days ago
https://github.com/arttttt/simplemviA lightweight, type-safe MVI (Model-View-Intent) library for Kotlin Multiplatform (KMP) applications. It provides a predictable unidirectional data flow for managing state and domain logic across Android, iOS, macOS, and Wasm JS using Kotlin Coroutines. Key components include the Store, Actor, Intent, State, Side Effect, and StorePlugin, with support for OOP, functional DSL, and composition-based actor implementations.
An Actor is the core component of the Store architecture responsible for implementing application logic. Its primary responsibilities are to:
Intent: Receive incoming actions from the user or system.SideEffect: Emit one-time events (e.g., navigation, showing a toast).State: Update the application state based on processed intents.An Actor must be part of a Store and is managed by it. It operates within an ActorScope which provides access to the current state, a CoroutineScope for asynchronous work, and methods to reduce state, emit sideEffects, or dispatch new intents.
A StorePlugin is an active participant that extends a Store without modifying its Actor. Plugins can observe the store's lifecycle, transform or block intents, hydrate the initial state, and react to state changes or side effects.
Key characteristics:
Context.scope provided in the Context.// Plugins are registered via createStore
val store = createStore(
name = storeName<MyStore>(),
initialState = MyState(),
actor = myActor,
plugins = listOf(
analyticsPlugin,
rateLimitPlugin,
persistedStatePlugin,
),
)Every Store requires an Actor. The Actor is the component responsible for containing all the core business logic and handling the Intent objects passed to the Store via accept().
Threading and Background Work:
When performing background work within an Actor, you should use coroutines with the provided CoroutineScope to ensure proper lifecycle management and threading.
The Store is the central component for implementing unidirectional data flow and a single source of truth in an application. It encapsulates application logic by managing a specific State, accepting Intent objects to trigger changes, and emitting SideEffect objects for one-time events.
To use a Store, you must follow its lifecycle:
Store.init() to prepare the store for use.Store.accept(intent) to pass intents into the system.Store.destroy() when the store is no longer needed to free up resources. Note: A store cannot be used after destroy() has been called.// Conceptual lifecycle usage
val store = MyStore()
store.init()
store.accept(MyIntent.DoSomething)
// When finished
store.destroy()SimpleMVI is built on the principles of a Single Source of Truth and Immutable State. The architecture ensures a strict separation between the UI layer and the domain logic layer.
State management is centralized in a Store, and all state changes must be performed through pure functions to maintain predictability.
A StorePlugin allows you to intercept and extend the behavior of a Store. Plugins are notified of various lifecycle events and can participate in the intent processing pipeline.
Plugin Capabilities:
Intent before it reaches the Actor.onStateChanged whenever a new state is emitted.onSideEffect whenever a side effect is emitted.Actor using coroutines to ensure the UI remains responsive.To maintain a scalable codebase, follow these structural guidelines:
Avoid 'God Objects'. Each Store should have a single, well-defined responsibility.
AuthStore, ProfileStore, SettingsStore.AppStore containing all application logic.State should be easy to reason about and impossible to mutate directly.
data class UserState(val isLoading: Boolean = false, val user: User? = null)var for properties or MutableMap/MutableList inside the state class.Intents should represent explicit user actions or system events.
UserIntent.Login(email, password), UserIntent.Logout.UserIntent.DoStuff(data).SimpleMVI consists of several key abstractions that work together to manage application logic:
Intents and produces state changes.Intents before they reach the Actor. Common uses include logging, analytics, intent transformation, and state persistence.In SimpleMVI, SideEffect should represent domain events (what happened in the business logic) rather than UI actions (instructions on what the UI should do).
LoginSucceeded), and each platform decides how to present it (e.g., a Toast on Android vs. an Alert on iOS).sealed interface UserSideEffect {
data object LoginSucceeded : UserSideEffect
data class LoginFailed(val reason: String) : UserSideEffect
data object SessionExpired : UserSideEffect
}sealed interface UserSideEffect {
data object NavigateToHome : UserSideEffect // UI navigation
data object ShowToast(val message: String) : UserSideEffect // UI presentation
data object ShowLoadingDialog : UserSideEffect // UI state
}sealed interface UserSideEffect {
data object LoginSucceeded : UserSideEffect
data class LoginFailed(val reason: String) : UserSideEffect
data object SessionExpired : UserSideEffect
}The delegatedActor function allows you to explicitly compose intent handlers. This provides maximum flexibility and is the foundation for modular code organization.
Features:
When to use:
val counterActor = delegatedActor<CounterIntent, CounterState, CounterSideEffect>(
initHandler = InitHandler {
// Optional: initialization logic
},
intentHandlers = listOf(
intentHandler<CounterIntent, CounterState, CounterSideEffect, CounterIntent.Increment> {
reduce { copy(count = count + 1) }
},
intentHandler<CounterIntent, CounterState, CounterSideEffect, CounterIntent.Decrement> {
reduce { copy(count = count - 1) }
},
intentHandler<CounterIntent, CounterState, CounterSideEffect, CounterIntent.Reset> {
reduce { CounterState() }
sideEffect(CounterSideEffect.CounterReset)
}
),
destroyHandler = DestroyHandler {
// Optional: cleanup logic
}
)