State Management (BLoC Default)

When to use

• BLoC: default for feature flows, async orchestration, and business-facing UI state.

• Cubit: small UI-only state (toggles, selected tab) where events/transformers are unnecessary.

• Provider: a lightweight UI controller (e.g., filters) when it stays UI-scoped and does not contain business logic.

Steps

1. Choose the right tool

Quick rule:

• If it coordinates async work and talks to repositories: BLoC.

• If it only holds ephemeral UI state: Cubit.

• If it’s a tiny widget-scoped controller and BLoC would be noise: Provider.

State-shape rule:

• Prefer sealed states when each state has distinct payloads (Loading/Loaded/Error ).

• For progressive forms where previously entered values must survive status changes, use one immutable state + enum status + copyWith .

2. Define events (sealed, manual)

part of 'orders_bloc.dart';

sealed class OrdersEvent { const OrdersEvent(); }

final class OrdersStartedEvent extends OrdersEvent { const OrdersStartedEvent(); }

final class OrdersRefreshEvent extends OrdersEvent { const OrdersRefreshEvent(); }

3. Define states (sealed, minimal, Equatable only when needed)

part of 'orders_bloc.dart';

sealed class OrdersState { const OrdersState(); }

final class OrdersInitialState extends OrdersState { const OrdersInitialState(); }

final class OrdersLoadingState extends OrdersState { const OrdersLoadingState(); }

final class OrdersLoadedState extends OrdersState with EquatableMixin { const OrdersLoadedState({required this.orders});

final List<OrderDto> orders;

@override List<Object?> get props => [orders]; }

final class OrdersErrorState extends OrdersState with EquatableMixin { const OrdersErrorState({ required this.message, this.error, this.stackTrace, });

final String? message; final Object? error; final StackTrace? stackTrace;

@override List<Object?> get props => [message, error, stackTrace]; }

4. Implement the BLoC with explicit concurrency

Pick the transformer intentionally:

• droppable() for “tap spam should not queue”

• restartable() for “latest wins” (search, refresh)

• sequential() for strict ordering

Example with restartable() :

import 'package:bloc/bloc.dart'; import 'package:bloc_concurrency/bloc_concurrency.dart'; import 'package:equatable/equatable.dart';

part 'orders_event.dart'; part 'orders_state.dart';

final class OrdersBloc extends Bloc<OrdersEvent, OrdersState> { OrdersBloc({required this.repository}) : super(const OrdersInitialState()) { on<OrdersEvent>( (event, emit) => switch (event) { OrdersStartedEvent() => _load(emit), OrdersRefreshEvent() => _load(emit), }, transformer: restartable(), ); }

final IOrdersRepository repository;

Future<void> _load(Emitter<OrdersState> emit) async { emit(const OrdersLoadingState()); try { final orders = await repository.getOrders(); emit(OrdersLoadedState(orders: orders)); // Known exceptions: catch specifically, emit error state, do NOT call onError. // Unexpected exceptions: fall through to outer catch, call onError(e, st). } catch (e, st) { handleException( exception: e, stackTrace: st, onError: (message, _, _, _) => emit( OrdersErrorState(message: message, error: e, stackTrace: st), ), ); } } }

5. Keep business logic out of widgets

BLoC orchestrates UI state; business rules live in repositories/services (or in small injected helpers).

If the BLoC grows because of data formatting:

• move formatting to DTO extensions

• move procedural logic to an injected service

6. Test BLoCs at the boundary

Use bloc_test and mock repositories. Cover:

• success path

• expected failures (network/timeout/cache)

• concurrency behavior (e.g., restartable cancels previous)

• order-sensitive event tests (insert await Future<void>.delayed(Duration.zero) between add(...) calls when needed)

Example:

import 'package:bloc_test/bloc_test.dart'; import 'package:flutter_test/flutter_test.dart'; import 'package:mocktail/mocktail.dart';

class _OrdersRepositoryMock extends Mock implements IOrdersRepository {}

void main() { late IOrdersRepository repo;

setUp(() => repo = _OrdersRepositoryMock());

blocTest<OrdersBloc, OrdersState>( 'emits [Loading, Loaded] on success', build: () { when(() => repo.getOrders()).thenAnswer((_) async => const []); return OrdersBloc(repository: repo); }, act: (bloc) => bloc.add(const OrdersStartedEvent()), expect: () => [ const OrdersLoadingState(), const OrdersLoadedState(orders: []), ], ); }

7. Verify anti-patterns are avoided

Before finishing, check:

• No ShowDialog , Navigate* , or other UI-command states emitted from the BLoC. Side effects belong in BlocListener in the widget layer.

• No direct BLoC dependencies in the constructor. BLoC-to-BLoC synchronization must go through the widget layer.

• Error handling uses two tiers: known exceptions → emit error state only; unexpected exceptions → emit error state AND call onError(e, st) .

• BLoC is not managing simple UI-only state. If it is a toggle or a filter with no async work, downgrade to Cubit or ValueNotifier .

• If the success listener needs to distinguish why success was reached, lastEvent is stored in the state.