bloc 0.15.0

Bloc Package

Pub Build Status codecov Flutter.io Awesome Flutter Flutter Samples Star on GitHub Gitter License: MIT


A dart package that helps implement the BLoC pattern.

This package is built to work with flutter_bloc and angular_bloc.

Overview #

Bloc Architecture

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 dispatched 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 dispatched after mapEventToState has been called but before the Bloc's state has been updated. A Transition consists of the currentState, the event which was dispatched, 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 #

initialState is the state before any events have been processed (before mapEventToState has ever been called). initialState must be implemented.

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 dispatched by the presentation layer. mapEventToState must convert that event into a new state and return the new state in the form of a Stream which is consumed by the presentation layer.

dispatch is a method that takes an event and triggers mapEventToState. dispatch may be called from the presentation layer or from within the Bloc (see examples) and notifies the Bloc of a new event.

transformEvents is a method that transforms the Stream<Event> along with a next function into a Stream<State>. Events that should be processed by mapEventToState need to be passed to next. 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.

transformStates is a method that transforms the Stream<State> into a new Stream<State>. By default transformStates returns the incoming Stream<State>. You can override transformStates 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 dispatched. 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 dispatched 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.

dispose is a method that closes the event and state streams. Dispose should be called when a Bloc is no longer needed. Once dispose is called, events that are dispatched will not be processed and will result in an error being passed to onError. In addition, if dispose is called while events are still being processed, any states yielded after are ignored and will not result in a Transition.

BlocDelegate Interface #

onEvent is a method that can be overridden to handle whenever an Event is dispatched 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> {
  @override
  int get initialState => 0;

  @override
  Stream<int> mapEventToState(CounterEvent event) async* {
    switch (event) {
      case CounterEvent.decrement:
        yield currentState - 1;
        break;
      case CounterEvent.increment:
        yield currentState + 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 dispatch events to our bloc like so:

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

  counterBloc.dispatch(CounterEvent.increment);
  counterBloc.dispatch(CounterEvent.increment);
  counterBloc.dispatch(CounterEvent.increment);

  counterBloc.dispatch(CounterEvent.decrement);
  counterBloc.dispatch(CounterEvent.decrement);
  counterBloc.dispatch(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) {
    super.onTransition(bloc, transition);
    print(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.dispatch(CounterEvent.increment); // { currentState: 0, event: CounterEvent.increment, nextState: 1 }
  counterBloc.dispatch(CounterEvent.increment); // { currentState: 1, event: CounterEvent.increment, nextState: 2 }
  counterBloc.dispatch(CounterEvent.increment); // { currentState: 2, event: CounterEvent.increment, nextState: 3 }

  counterBloc.dispatch(CounterEvent.decrement); // { currentState: 3, event: CounterEvent.decrement, nextState: 2 }
  counterBloc.dispatch(CounterEvent.decrement); // { currentState: 2, event: CounterEvent.decrement, nextState: 1 }
  counterBloc.dispatch(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 dispatched to a Bloc we can also override onEvent in our SimpleBlocDelegate.

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

  @override
  void onTransition(Bloc bloc, Transition transition) {
    super.onTransition(bloc, transition);
    print(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) {
    super.onEvent(bloc, event);
    print(event);
  }

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

  @override
  void onError(Bloc bloc, Object error, StackTrace stacktrace) {
    super.onError(bloc, error, stacktrace);
    print('$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.0.0

Examples #

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

Maintainers #

0.15.0 #

  • Removed Bloc event Stream (#326)
  • Renamed transform to transformEvents
  • Added transformStates (#382)

0.14.4 #

Additional Dependency and Documentation Updates.

0.14.3 #

Dependency and Documentation Updates.

0.14.2 #

  • Deprecated Bloc event Stream (#326)
  • Documentation Updates

0.14.1 #

Internal BlocDelegate update and Documentation Updates.

0.14.0 #

BlocDelegate initialization improvements and Documentation Updates.

  • BlocSupervisor().delegate = ... is now BlocSupervisor.delegate = ... (#304).

0.13.0 #

Bloc and BlocDelegate Improvements, new Features, and Documentation Updates.

  • Improved dispose to ignore pending events (#257).
  • Exposed event stream on Bloc similar to state stream to expose a Stream of dispatched events (#259).
  • Update to use rxdart version ^0.22.0 (#265).
  • BlocDelegate methods include a reference to the Bloc instance (#259).
  • Added onEvent to Bloc and BlocDelegate (#259).

0.12.0 #

Updated transform to enable advanced event filtering and processing and Documentation Updates.

0.11.2 #

Added BlocDelegate onError and onTransition mustCallSuper and Documentation Updates

0.11.1 #

Added dispose mustCallSuper and Documentation Updates

0.11.0 #

Update mapEventToState to remove unnecessary argument for currentState

  • Stream<S> mapEventToState(S currentState, E event) -> Stream<S> mapEventToState(E event)
  • Documentation Updates
  • Example Updates

0.10.0 #

Updated to rxdart ^0.21.0 and Documentation Updates

0.9.5 #

Minor Enhancements to Code Style and Documentation.

0.9.4 #

Calls to dispatch after dispose has been called trigger onError in the Bloc and BlocDelegate.

0.9.3 #

Restrict rxdart to ">=0.18.1 <0.21.0" due to breaking changes.

0.9.2 #

Additional Minor Updates to Documentation

0.9.1 #

Minor Updates to Documentation

0.9.0 #

Bloc and BlocDelegate Error Handling

  • Added onError to Bloc for local error handling.
  • Added onError to BlocDelegate for global error handling.

0.8.4 #

Blocs handle exceptions thrown in mapEventToState and documentation updates.

0.8.3 #

Minor Internal Improvements and Documentation Updates

0.8.2 #

Additional Minor Updates to Documentation

0.8.1 #

Minor Updates to Documentation

0.8.0 #

Blocs ignore duplicate states

0.7.8 #

Additional Minor Updates to Documentation

0.7.7 #

Additional Minor Updates to Documentation

0.7.6 #

Minor Updates to Documentation

0.7.5 #

Exposed currentState in Bloc

  • Updates to Documentation.

0.7.4 #

Updated mapEventToState parameter name

  • Stream<S> mapEventToState(S state, E event) -> Stream<S> mapEventToState(S currentState, E event)
  • Updates to Documentation.
  • Updates to Example.

0.7.3 #

Minor Updates to Documentation

0.7.2 #

Transition Fix

  • Bloc with mapEventToState which returns multiple states per event will now correctly report the Transitions.

0.7.1 #

Improvements to Bloc usage in pure Dart applications.

  • Bloc state is seeded with initialState automatically

0.7.0 #

Added BlocSupervisor and BlocDelegate.

  • BlocSupervisor notifies BlocDelegate of Transitions
  • BlocDelegate exposes onTransition which is invoked for all Bloc Transitions.

0.6.0 #

Transitions and initialState updates.

  • Added Transitions and onTransition
  • Made initialState required

0.5.2 #

Additional minor Updates to Documentation.

0.5.1 #

Minor Updates to Documentation

0.5.0 #

Moved Flutter Widgets to flutter_bloc package

0.4.2 #

Additional minor Updates to Documentation.

0.4.1 #

Minor Updates to Documentation.

0.4.0 #

Added BlocProvider.

  • BlocProvider.of(context)
  • Updates to Documentation.
  • Updates to Example.

0.3.0 #

Updated mapEventToState to take current state as an argument.

  • Stream<S> mapEventToState(E event) -> Stream<S> mapEventToState(S state, E event)
  • Updates to Documentation.
  • Updates to Example.

0.2.5 #

Additional Minor Updates to Documentation.

0.2.4 #

Additional Minor Updates to Documentation.

0.2.3 #

Additional Minor Updates to Documentation.

0.2.2 #

Additional Minor Updates to Documentation.

0.2.1 #

Minor Updates to Documentation.

0.2.0 #

Added Support for Stream Transformation

  • Includes Stream<E> transform(Stream<E> events)
  • Updates to Documentation

0.1.2 #

Additional Minor Updates to Documentation.

0.1.1 #

Minor Updates to Documentation.

0.1.0 #

Initial Version of the library.

  • Includes the ability to create a custom Bloc by extending Bloc class.
  • Includes the ability to connect presentation layer to Bloc by using the BlocBuilder Widget.

example/main.dart

import 'dart:async';

import 'package:bloc/bloc.dart';

enum CounterEvent { increment, decrement }

class CounterBloc extends Bloc<CounterEvent, int> {
  @override
  int get initialState => 0;

  @override
  Stream<int> mapEventToState(CounterEvent event) async* {
    switch (event) {
      case CounterEvent.decrement:
        // Simulating Network Latency
        await Future<void>.delayed(Duration(seconds: 1));
        yield currentState - 1;
        break;
      case CounterEvent.increment:
        // Simulating Network Latency
        await Future<void>.delayed(Duration(milliseconds: 500));
        yield currentState + 1;
        break;
      default:
        throw Exception('unhandled event: $event');
    }
  }
}

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

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

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

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

  final counterBloc = CounterBloc();

  counterBloc.dispatch(CounterEvent.increment);
  counterBloc.dispatch(CounterEvent.increment);
  counterBloc.dispatch(CounterEvent.increment);

  counterBloc.dispatch(CounterEvent.decrement);
  counterBloc.dispatch(CounterEvent.decrement);
  counterBloc.dispatch(CounterEvent.decrement);

  counterBloc.dispatch(null); // Triggers Exception

  // The exception triggers `SimpleBlocDelegate.onError` but does not impact bloc functionality.
  counterBloc.dispatch(CounterEvent.increment);
  counterBloc.dispatch(CounterEvent.decrement);
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  bloc: ^0.15.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:bloc/bloc.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
99
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
99
Learn more about scoring.

We analyzed this package on Sep 20, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.5.0
  • pana: 0.12.21

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:bloc/bloc.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
meta ^1.1.6 1.1.7
rxdart ^0.22.0 0.22.2
Dev dependencies
mockito ^4.0.0
test >=1.3.0 <2.0.0
test_coverage ^0.2.0