Master Flutter Bloc Architecture and State Management

Implements Flutter's Bloc (Business Logic Component) pattern with a unidirectional data flow: events trigger business logic, which emits states that drive the UI. Architecture follows four principles - separation of concerns (UI only emits events and listens to states), unidirectional flow, testability (business logic isolated from widgets), and reactive programming via Dart Streams - built from four component types: Events (user interactions or system triggers), States (immutable UI-state representations, typically extending Equatable), Blocs (handle events, emit states), and Repositories (a data-layer abstraction over API calls and local storage). It writes immutable state and event class hierarchies (for example CounterInitial/CounterLoading/CounterLoaded/CounterError extending a base CounterState), Bloc classes wired with on<Event> handlers and constructor-injected repositories, and advanced async event handling using emit.onEach to stream repository results directly into state emissions.

Use it for Flutter state management that needs a clear, testable separation between UI and business logic - forms, authentication flows, data-loading screens, or any feature where events and resulting states should be independently unit-tested rather than driven by widget-local state.

Input is the feature's events and the states it should produce. Output is a full Bloc implementation: immutable state and event classes, a Bloc wired to a repository via constructor dependency injection, widget integration via BlocProvider/MultiBlocProvider at the app root plus feature-specific providers, BlocConsumer/BlocBuilder/BlocListener widgets that react to state, and bloc_test-based unit tests (blocTest with build/seed/act/expect/verify) that assert the exact state sequence a Bloc emits - for example a test that seeds CounterLoaded(0), dispatches CounterIncremented(), and expects [CounterLoaded(1)]. Repository code follows its own pattern: abstract classes define repository contracts, caching strategies live inside the repository implementation, and network exceptions are handled at the repository level rather than leaking into the Bloc.

Built on the flutter_bloc package (Bloc, BlocProvider, MultiBlocProvider, BlocConsumer, BlocBuilder, BlocListener, BlocSelector, BlocObserver), Equatable for value-based state/event comparison, bloc_test-style mocking for unit tests, and HydratedBloc for state persistence across app launches.

For Flutter developers who want state management with dependency-injected repositories, centralized logging via BlocObserver, and performance practices baked in - Equatable on every state/event for efficient rebuilds, BlocSelector for granular widget rebuilds, avoiding Bloc instantiation inside build() methods, and disciplined stream-subscription management - plus an explicit error-state hierarchy with retry-via-events and centralized error reporting.

class CounterBloc extends Bloc<CounterEvent, CounterState> {
  final CounterRepository _repository;
  
  CounterBloc({
    required CounterRepository repository,
  }) : _repository = repository,
       super(CounterInitial()) {
    on<CounterIncremented>(_onCounterIncremented);
    on<CounterDecremented>(_onCounterDecremented);
    on<CounterLoadRequested>(_onCounterLoadRequested);
  }
  
  void _onCounterIncremented(
    CounterIncremented event,
    Emitter<CounterState> emit,
  ) {
    final currentState = state;
    if (currentState is CounterLoaded) {
      emit(CounterLoaded(currentState.count + 1));
    }
  }
}