Readme

Pub build codecov style: effective dart Flutter Website Awesome Flutter Flutter Samples Star on GitHub Discord License: MIT

A dart package that helps implement the BLoC pattern.

This package is built to work with flutter_bloc and angular_bloc.

Overview

The goal of this package is to make it easy to implement the BLoC Design Pattern (Business Logic Component).

This design pattern helps to separate presentation from business logic. Following the BLoC pattern facilitates testability and reusability. This package abstracts reactive aspects of the pattern allowing developers to focus on converting events into states.

Glossary

Events are the input to a Bloc. They are commonly UI events such as button presses. Events are added to the Bloc and then converted to States.

States are the output of a Bloc. Presentation components can listen to the stream of states and redraw portions of themselves based on the given state (see BlocBuilder for more details).

Transitions occur when an Event is added after mapEventToState has been called but before the Bloc's state has been updated. A Transition consists of the currentState, the event which was added, and the nextState.

BlocSupervisor oversees Blocs and delegates to BlocDelegate.

BlocDelegate handles events from all Blocs which are delegated by the BlocSupervisor. Can be used to intercept all Bloc events, transitions, and errors. It is a great way to handle logging/analytics as well as error handling universally.

Bloc Interface

mapEventToState is a method that must be implemented when a class extends Bloc. The function takes the incoming event as an argument. mapEventToState is called whenever an event is added. mapEventToState must convert that event into a new state and return the new state in the form of a Stream.

add is a method that takes an event and triggers mapEventToState. If close has already been called, any subsequent calls to add will be delegated to the onError method which can be overriden at the Bloc as well as the BlocDelegate level.

transformEvents is a method that transforms the Stream<Event> along with a transition function, transitionFn, into a Stream<Transition>. Events that should be processed by mapEventToState need to be passed to transitionFn. By default asyncExpand is used to ensure all events are processed in the order in which they are received. You can override transformEvents for advanced usage in order to manipulate the frequency and specificity with which mapEventToState is called as well as which events are processed.

transformTransitions is a method that transforms the Stream<Transition> into a new Stream<Transition>. By default transformTransitions returns the incoming Stream<Transition>. You can override transformTransitions for advanced usage in order to manipulate the frequency and specificity at which transitions (state changes) occur.

onEvent is a method that can be overridden to handle whenever an Event is added. It is a great place to add bloc-specific logging/analytics.

onTransition is a method that can be overridden to handle whenever a Transition occurs. A Transition occurs when a new Event is added and mapEventToState is called. onTransition is called before a Bloc's state has been updated. It is a great place to add bloc-specific logging/analytics.

onError is a method that can be overridden to handle whenever an Exception is thrown. By default all exceptions will be ignored and Bloc functionality will be unaffected. It is a great place to add bloc-specific error handling.

close is a method that closes the event and state streams. close should be called when a Bloc is no longer needed. Once close is called, events that are added will not be processed and will result in an error being passed to onError. In addition, if close is called while events are still being processed the bloc will continue to process the pending events to completion.

BlocDelegate Interface

onEvent is a method that can be overridden to handle whenever an Event is added to any Bloc. It is a great place to add universal logging/analytics.

onTransition is a method that can be overridden to handle whenever a Transition occurs in any Bloc. It is a great place to add universal logging/analytics.

onError is a method that can be overriden to handle whenever an Exception is thrown from any Bloc. It is a great place to add universal error handling.

Usage

For simplicity we can create a CounterBloc like:

class CounterBloc extends Bloc<CounterEvent, int> {
  CounterBloc() : super(initialState: 0);

  @override
  Stream<int> mapEventToState(CounterEvent event) async* {
    switch (event) {
      case CounterEvent.decrement:
        yield state - 1;
        break;
      case CounterEvent.increment:
        yield state + 1;
        break;
    }
  }
}

Our CounterBloc converts CounterEvents to integers.

As a result, we need to define our CounterEvent like:

enum CounterEvent { increment, decrement }

Then we can add events to our bloc like so:

void main() {
  final counterBloc = CounterBloc();

  counterBloc.add(CounterEvent.increment);
  counterBloc.add(CounterEvent.increment);
  counterBloc.add(CounterEvent.increment);

  counterBloc.add(CounterEvent.decrement);
  counterBloc.add(CounterEvent.decrement);
  counterBloc.add(CounterEvent.decrement);
}

As our app grows and relies on multiple Blocs, it becomes useful to see the Transitions for all Blocs. This can easily be achieved by implementing a BlocDelegate.

class SimpleBlocDelegate extends BlocDelegate {
  @override
  void onTransition(Bloc bloc, Transition transition) {
    print(transition);
    super.onTransition(bloc, transition);
  }
}

Now that we have our SimpleBlocDelegate, we just need to tell the BlocSupervisor to use our delegate in our main.dart.

void main() {
  BlocSupervisor.delegate = SimpleBlocDelegate();

  final counterBloc = CounterBloc();

  counterBloc.add(CounterEvent.increment); // { currentState: 0, event: CounterEvent.increment, nextState: 1 }
  counterBloc.add(CounterEvent.increment); // { currentState: 1, event: CounterEvent.increment, nextState: 2 }
  counterBloc.add(CounterEvent.increment); // { currentState: 2, event: CounterEvent.increment, nextState: 3 }

  counterBloc.add(CounterEvent.decrement); // { currentState: 3, event: CounterEvent.decrement, nextState: 2 }
  counterBloc.add(CounterEvent.decrement); // { currentState: 2, event: CounterEvent.decrement, nextState: 1 }
  counterBloc.add(CounterEvent.decrement); // { currentState: 1, event: CounterEvent.decrement, nextState: 0 }
}

At this point, all Bloc Transitions will be reported to the SimpleBlocDelegate and we can see them in the console after running our app.

If we want to be able to handle any incoming Events that are added to a Bloc we can also override onEvent in our SimpleBlocDelegate.

class SimpleBlocDelegate extends BlocDelegate {
  @override
  void onEvent(Bloc bloc, Object event) {
    print(event);
    super.onEvent(bloc, event);
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    print(transition);
    super.onTransition(bloc, transition);
  }
}

If we want to be able to handle any Exceptions that might be thrown in a Bloc we can also override onError in our SimpleBlocDelegate.

class SimpleBlocDelegate extends BlocDelegate {
  @override
  void onEvent(Bloc bloc, Object event) {
    print(event);
    super.onEvent(bloc, event);
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    print(transition);
    super.onTransition(bloc, transition);
  }

  @override
  void onError(Bloc bloc, Object error, StackTrace stackTrace) {
    print('$error, $stackTrace');
    super.onError(bloc, error, stackTrace);
  }
}

At this point, all Bloc Exceptions will also be reported to the SimpleBlocDelegate and we can see them in the console.

Dart Versions

• Dart 2: >= 2.6.0

Examples

• Counter - an example of how to create a CounterBloc in a pure Dart app.

Maintainers

• Felix Angelov