State Management API
Provider-based reactive state with an optional BLoC alternative.
EventProvider
lib/state/providers/event_provider.dart
The primary state holder for events. Extends ChangeNotifier and provides an O(1) indexed event list.
Key Design Decisions
- Unmodifiable list exposure —
eventsreturnsUnmodifiableListViewto prevent external mutation - O(1) lookups — internal
_idIndexmap enables constant-timegetEventById(),removeEvent(), andupdateEvent() - Index rebuild strategy — bulk ops (
setEvents,clearEvents) rebuild the index; single-item ops maintain it incrementally
Properties
| Property | Type | Description |
|---|---|---|
events | UnmodifiableListView<EventModel> | Read-only view of all events |
eventCount | int | Number of events |
isEmpty | bool | Whether event list is empty |
Methods
| Method | Signature | Description |
|---|---|---|
setEvents | (List<EventModel>) → void | Replace entire list + rebuild index. Used during initial load. |
addEvent | (EventModel) → void | Append event, update index incrementally. |
removeEvent | (String id) → void | Remove by ID using O(1) index lookup. Rebuilds index after removal (indices shift). |
updateEvent | (EventModel) → void | Replace event at its indexed position. O(1). |
getEventById | (String id) → EventModel? | O(1) lookup via index map. |
clearEvents | () → void | Remove all events and clear index. |
Usage
// In a widget
final provider = context.watch<EventProvider>();
// Read events (reactive — triggers rebuild on change)
for (final event in provider.events) {
print(event.title);
}
// Look up specific event
final event = provider.getEventById('uuid-123');
// Mutate (triggers notifyListeners → widget rebuild)
context.read<EventProvider>().addEvent(newEvent);
UserProvider
lib/state/providers/user_provider.dart
Manages the current user session. Set by AuthGate on successful authentication.
Properties & Methods
| Member | Type | Description |
|---|---|---|
currentUser | UserModel? | Currently authenticated user (null if logged out) |
setUser(user) | void | Set the current user and notify listeners |
clearUser() | void | Clear user session |
EventBloc
lib/state/blocs/event_bloc.dart
Alternative state management using the BLoC pattern via Cubit. Provides a state machine approach that can coexist with the Provider-based approach.
States
| State | Description |
|---|---|
EventInitial | Before any events have been loaded |
EventLoaded | Contains the current list of events |
EventError | Error state with message (reserved for future use) |
Methods
| Method | Description |
|---|---|
loadEvents(List<EventModel>) | Transition to EventLoaded with the given events |
addEvent(EventModel) | Append event (only in EventLoaded state, no-op otherwise) |
removeEvent(String id) | Remove event by ID (only in EventLoaded state) |
State Transitions
EventInitial ─── loadEvents() ──→ EventLoaded
↕ addEvent() / removeEvent()
EventLoaded (new list)
When to Use Which?
✅ Use EventProvider when…
- You need O(1) ID-based lookups
- You're in a standard widget tree
- You want simple reactive updates
- You're pairing with EventService for persistence
✅ Use EventBloc when…
- You prefer explicit state transitions
- You want to use BlocBuilder/BlocListener
- You need testable state machines
- You're integrating with complex async flows