FlowMVI Documentation

In FlowMVI, application state must implement the MVIState marker interface. To ensure predictable behavior and compatibility with the framework, states must adhere to these three requirements:

1. Immutable: State objects must never be mutated after creation. Always use copy() to create new instances. Avoid var properties and ensure collections are new instances rather than just upcasting a MutableList to a List.
2. Comparable: State objects must implement a stable and valid equals and hashCode contract. Using Kotlin data class or data object is the recommended way to achieve this.
3. Scoped: Avoid using unintended objects, such as 3rd party interfaces or raw network responses, directly as a State.

If your store does not require a specific state, you can use the provided EmptyState object.

data class CounterState(
    val counter: Int = 0,
    val isLoading: Boolean = false
) : MVIState

FlowMVI provides two primary entry points for testing Stores, depending on whether you are testing lifecycle or state transitions.

1. Store.test { ... } (Lifecycle-focused)

Use this when you need to assert startup/shutdown behavior, subscription counts, or invariants regarding whether the store is alive. The receiver is a TestStore (a Store plus SubscriptionAware).

2. Store.subscribeAndTest { ... } (State/Actions-focused)

Use this to assert emitted state transitions and actions. The receiver is a StoreTestScope, which provides access to the subscription's states (StateFlow<S>) and actions (Flow<A>).

Note on Transient Subscriptions: If your store is configured with debuggable = true, ensure allowTransientSubscriptions = true is set in your configuration. Otherwise, the store may flag the automatic unsubscription at the end of the subscribeAndTest block as an error.

// Lifecycle testing
store.test {
    isActive // StoreLifecycle
    subscriberCount.value // SubscriptionAware
    emit(MyIntent)
}

// State and Action testing (using Turbine)
store.subscribeAndTest {
    states.test {
        awaitItem() shouldBe InitialState
        intent(MyIntent)
        awaitItem() shouldBe ExpectedState
    }

    actions.test {
        intent(MyIntentThatSendsAction)
        awaitItem() shouldBe ExpectedAction
    }
}

Concept

Decorators are experimental "plugins for plugins" that wrap another plugin and manage it manually.

While standard Plugins are executed automatically in a Chain of Responsibility, Decorators decide whether to call the plugin methods themselves. This allows you to:

• Wrap the entire plugin chain.
• Watch over the entire chain.
• Skip execution of specific plugins entirely.

Key Behaviors:

• Manual Invocation: If you do not call the corresponding plugin method within the decorator, that plugin (and everything it wraps) is skipped. This can be dangerous if plugins rely on onStart for resource initialization.
• Return Values: Unlike plugins where you return the "next" value, a decorator's return value is considered the "final" value. A safe pattern is to return whatever the chain invocation returns.
• Transparency: If you don't define a particular decorator callback, it remains "transparent" (it won't skip the underlying logic).
• Composition: You can decorate decorators, as decorating a plugin results in a new plugin.

val plugin = plugin<State, Intent, Action> {
    onIntent { it }
}

val decorator = decorator<State, Intent, Action> {
    name = "FilterInvalidDecorator"
    onIntent { chain, intent ->
        if (intent is InvalidIntent) return@onIntent null
        chain.run { onIntent(intent) } // returns the result of the chain
    }
}

val decoratedPlugin = decorator decorates plugin

When splitting logic in FlowMVI, choose based on these criteria:

Key Takeaways:

• Use Plugins for lightweight logic that acts on the same intents as the parent or when performance is critical (plugins avoid the coroutine/async overhead of child stores).
• Use Child Stores when state is highly complex, when you need to isolate specific blocks of a page (like a settings drawer), or when different parts of the UI need to subscribe to different pieces of state at different times.

The order in which you call plugin installation methods is critical because plugins can replace, veto, consume, or modify store events (intents, actions, or states).

Key Rules:

• Consumption: If a plugin (like a reduce plugin) consumes an intent, any plugin installed after it will not see that intent.
• Vetoing: A plugin installed earlier can veto state changes or actions intended for later stages.
• Lifecycle Timing: Plugins that hook into lifecycle events like onStart() may conflict with init blocks if the installation order is not carefully managed.

Example of incorrect ordering (Logging after Reduce): If you install a logging plugin after a reduce plugin, the logger will not capture intents because the reduce plugin has already consumed them.

// ❌ BROKEN: Logging plugin will not log any intents because they are consumed by reduce first
val broken = store(Loading) {
    reduce { 
        // ... 
    }
    enableLogging()
}

// ✅ WORKING: Logging plugin gets the intent before reduce() runs
val working = store(Loading) {
    enableLogging()
    reduce { 
        // ... 
    }
}

FlowMVI supports two distinct development styles. It is recommended to choose one and use it consistently throughout your project.

MVI Style (Strict Model-Driven)

Recommended for full use of Plugins (logging, time travel, analytics).

• Mechanism: Create an MVIIntent subclass for every event. The Store handles the logic.
• Pros: High separation of concerns, verbose/readable contracts, supports intent decomposition and delegation.
• Cons: More boilerplate, potential class explosion, harder IDE navigation.

MVVM+ Style (Functional/Lambda-Driven)

• Mechanism: Invoke functions containing business logic that send processing instructions to the store via lambdas.
• Pros: Elegant syntax, easy navigation, avoids class explosion.
• Cons: Requires the reduceLambdas Plugin, less performant than regular intents, some Plugins (logging/analytics) may not work, intents cannot be easily composed or delegated.

Note for MVVM+: You must install the reduceLambdas Plugin. To prevent leaking the Store's context to subscribers, consider using the ImmutableStore and ImmutableContainer interfaces.

// MVVM+ Style Intent Example
fun onItemClick(item: Item) = store.intent {
    updateState {
        copy(selectedItem = item)
    }
}

The metrics plugin provides over 67 numeric metrics per snapshot, covering the entire store lifecycle. The schema is versioned via MetricsSchemaVersion and rendered through a MetricSurface for compatibility.

Key Metric Categories:

• Intents: Totals, processed/dropped/undelivered counts, ops/sec, queue time, latency quantiles (p50/p90/p95/p99), inter-arrival times, bursts, buffer occupancy, and plugin overhead.
• Actions: Sent/delivered/undelivered counts, ops/sec, delivery latency quantiles, queue time, buffer metrics, and plugin overhead.
• State: Transition counts, vetoed transitions, started-in-initial-state, time-to-first state, reducer latency quantiles, and throughput.
• Subscriptions: Subscribe/unsubscribe events, current/peak subscribers, average/median lifetimes, and sampled counts.
• Lifecycle: Start/stop counters, total uptime, current/average/median lifetimes, and bootstrap latency.
• Exceptions: Total/handled counts and recovery latency (average/median).
• Meta: Schema version, window length, EMA alpha, generated-at timestamp, start time, store name/id, and run id.