Introduction
vm_result is a minimal, production-grade MVVM (Model-View-ViewModel) state management library for Flutter. It is designed to completely eliminate the repetitive boilerplate associated with managing asynchronous operations (such as loading, data, and error lifecycles).
By combining Flutter's native ChangeNotifier and ValueListenable with robust functional Result<T> state encapsulation, vm_result provides a lightweight, performant, and beginner-friendly alternative to heavy state management frameworks.
Why vm_result?
When developing feature screens in Flutter, you frequently fetch data from an API, database, or WebSocket. Typically, this requires you to write code to:
- Show a loading indicator.
- Execute the async operation.
- Catch and log exceptions, showing an error card with a retry option.
- Render the successful data on the screen.
- Prevent duplicate concurrent requests (deduplication).
In most frameworks, you have to write sealed classes, yield/emit state transitions, or build complex providers for every single screen. vm_result automates all of this through simple, safe async guard methods.
Core Features
- Sealed State Encapsulation: A
Result<T>sealed class that guarantees you can never forget to handle loading or error states. - Built-in Async Guards: Methods like
run(),runOptimistic(),runLatest(), andrunStream()that handle state transitions, try-catch blocks, and warning logs automatically. - Automatic Deduplication: Guards drop concurrent duplicate inputs by default, keeping your API endpoints safe from accidental double-taps.
- Cancel-and-Replace Semantics:
runLatest()provides search-as-you-type support out-of-the-box, automatically discarding stale responses. - One-Shot UI Effects:
VMResultEffectandEffectListenerlet you handle transient UI side-effects (like showing snackbars or navigation) cleanly. - Pluggable Logging: Fully customizable logger support (
VMResultLogger) allowing you to redirect package logs to your favorite logging framework (e.g. Talker).
Comparison with other State Management Solutions
Here is how vm_result compares conceptually with other popular Flutter state management libraries:
| Dimension | vm_result | BLoC / Cubit | Riverpod |
|---|---|---|---|
| Boilerplate | 🟢 Extremely Low (Guards handle lifecycle automatically) | 🔴 High (Must declare Events, States, and map transitions) | 🟡 Moderate (Uses code generation and custom providers) |
| Learning Curve | 🟢 Minimal (Uses standard, native ChangeNotifier concepts) | 🔴 Steep (Requires understanding streams and event loops) | 🟡 Moderate (Requires learning WidgetRef and provider graph APIs) |
| Async State Handling | 🟢 Built-in (Standardized Result<T> lifecycle) | 🔴 Manual (Must define separate Loading/Error states manually) | 🟢 Built-in (Uses built-in AsyncValue class) |
| Deduplication / debounce | 🟢 Out-of-the-box (Guards drop duplicate calls naturally) | 🟡 Manual / Custom (Requires writing custom EventTransformers) | 🟡 Manual / Custom (Requires custom debounce debounce helpers) |
| Best Used For | UI/API screens, standard CRUD features, and robust MVVM architectures | Large teams, complex event streams, and strict state auditing | Highly nested dependency graphs and global reactive state sharing |
Next Steps
Get started with vm_result by checking out: