Stats Async Notifier
Component Detail
Description
Riverpod AsyncNotifier that owns the stats loading lifecycle for a given role and time window. Triggers an initial fetch on construction and re-fetches whenever the time window parameter changes or a new activity insert event is received. Exposes AsyncValue<StatsSnapshot> to the UI layer.
stats-notifier
Summaries
The Stats Async Notifier is the engine that ensures users always see up-to-date performance metrics without manual refreshes, directly contributing to a seamless and trustworthy product experience. By automatically re-fetching statistics whenever a user logs new activity or changes their selected time window, the component eliminates stale data that would erode user confidence in the platform's accuracy. For products where engagement metrics drive user motivation and habit formation — such as fitness, learning, or productivity apps — real-time data freshness is a critical retention lever. This component reduces the operational cost of user-reported data discrepancies and supports a premium, polished user experience that justifies subscription pricing and competitive differentiation.
The Stats Async Notifier is a medium-complexity Riverpod AsyncNotifier with two upstream dependencies — the stats repository and the chapter scope resolver — both of which are on the critical path for this component's delivery. Project scheduling should account for these dependencies being completed and stable before integration testing can begin. The reactive re-fetch logic (on time window change and on activity insert events) introduces multiple state transition paths that require thorough unit testing, including edge cases like rapid window changes and concurrent insert events. The ref.listen and WidgetRef.refresh patterns must be validated against the target Riverpod version to avoid deprecation-related rework.
Plan for integration testing alongside the stats repository and budget time for state management edge case coverage.
StatsAsyncNotifier extends Riverpod's AsyncNotifier, parameterized by TimeWindow, and manages the full AsyncValue
The refresh method provides an explicit escape hatch for navigation-triggered refreshes via ref.listen or WidgetRef.refresh. Error states must be surfaced to the UI as AsyncValue.error — avoid swallowing exceptions. Ensure the notifier is family-scoped by TimeWindow to prevent cross-window state contamination.
Responsibilities
- Manage AsyncValue state for stats loading, data, and error
- Re-fetch on time window change and on new activity insert events
- Refresh on navigation using ref.listen or WidgetRef.refresh pattern
- Delegate data fetching to stats repository
Interfaces
build(TimeWindow window) Future<StatsSnapshot>
refresh()
onActivityInserted()
changeTimeWindow(TimeWindow window)
getSnapshot() AsyncValue<StatsSnapshot>
Relationships
Dependencies (2)
Components this component depends on
Dependents (3)
Components that depend on this component