bloc 0.5.1

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • new90
Bloc Package

Build Status codecov Pub License: MIT Gitter


A dart package that helps implement the Bloc pattern.

This package is built to work with RxDart.dart 0.18.1+.

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).

Bloc Interface

mapEventToState is a method that must be implemented when a class extends Bloc. The function takes two arguments: state and event. mapEventToState is called whenever an event is dispatched by the presentation layer. mapEventToState must convert that event, along with the current state, 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.

initialState is the state before any events have been processed (before mapEventToState has ever been called). initialState is an optional getter. If unimplemented, initialState will be null.

transform is a method that can be overridden to transform the Stream<Event> before mapEventToState is called. This allows for operations like distinct() and debounce() to be used.

Usage

For simplicity we can create a Bloc that always returns a stream of static strings in response to any event. That would look something like:

class SimpleBloc extends Bloc<dynamic, String> {
  @override
  Stream<String> mapEventToState(String state, dynamic event) async* {
    yield 'data';
  }
}

That isn't a very realistic use-case so let's take something more practical like a login flow.

We're going to need to define what our different LoginStates are going to be. For simplicity, let's say we only have 4 states:

  • initial
  • loading
  • failure
  • success
class LoginState {
  final bool isLoading;
  final bool isLoginButtonEnabled;
  final String error;
  final String token;

  const LoginState({
    @required this.isLoading,
    @required this.isLoginButtonEnabled,
    @required this.error,
    @required this.token,
  });

  factory LoginState.initial() {
    return LoginState(
      isLoading: false,
      isLoginButtonEnabled: true,
      error: '',
      token: '',
    );
  }

  factory LoginState.loading() {
    return LoginState(
      isLoading: true,
      isLoginButtonEnabled: false,
      error: '',
      token: '',
    );
  }

  factory LoginState.failure(String error) {
    return LoginState(
      isLoading: false,
      isLoginButtonEnabled: true,
      error: error,
      token: '',
    );
  }

  factory LoginState.success(String token) {
    return LoginState(
      isLoading: false,
      isLoginButtonEnabled: true,
      error: '',
      token: token,
    );
  }
}

Next we need to define the different events that our Bloc will respond to. Again, for simplicity, let's say there is just a single event we will handle: LoginButtonPressed.

abstract class LoginEvent {}

class LoginButtonPressed extends LoginEvent {
  final String username;
  final String password;

  LoginButtonPressed({@required this.username, @required this.password});
}

Now that we've identified our states and events, our LoginBloc should look something like:

class LoginBloc extends Bloc<LoginEvent, LoginState> {
  LoginState get initialState => LoginState.initial();

  void onLoginButtonPressed({String username, String password}) {
    dispatch(
      LoginButtonPressed(
        username: username,
        password: password,
      ),
    );
  }

  @override
  Stream<LoginState> mapEventToState(LoginState state, LoginEvent event) async* {
    if (event is LoginButtonPressed) {
      yield LoginState.loading();

      try {
        final token = await _authenticate(event.username, event.password);
        yield LoginState.success(token);
      } catch (error) {
        yield LoginState.failure(error.toString());
      }
    }
  }
}

Dart Versions

  • Dart 2: >= 2.0.0

Examples

Contributors

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.

0.1.1

Minor Updates to Documentation.

0.1.2

Additional Minor Updates to Documentation.

0.2.0

Added Support for Stream Transformation

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

0.2.1

Minor Updates to Documentation.

0.2.2

Additional Minor Updates to Documentation.

0.2.3

Additional Minor Updates to Documentation.

0.2.4

Additional Minor Updates to Documentation.

0.2.5

Additional Minor Updates to Documentation.

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.4.0

Added BlocProvider.

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

0.4.1

Minor Updates to Documentation.

0.4.2

Additional minor Updates to Documentation.

0.5.0

Moved Flutter Widgets to flutter_bloc package

0.5.1

Minor Updates to Documentation

example/lib/main.dart

import 'dart:async';

import 'package:bloc/bloc.dart';

abstract class CounterEvent {}

class IncrementCounter extends CounterEvent {}

class DecrementCounter extends CounterEvent {}

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

  void increment() {
    dispatch(IncrementCounter());
  }

  void decrement() {
    dispatch(DecrementCounter());
  }

  @override
  Stream<int> mapEventToState(int state, CounterEvent event) async* {
    print('event: ${event.runtimeType}');

    if (event is IncrementCounter) {
      yield state + 1;
    }
    if (event is DecrementCounter) {
      yield state - 1;
    }
  }
}

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

  counterBloc.state.listen((state) {
    print('state: ${state.toString()}');
  });

  print('initialState: ${counterBloc.initialState}');

  // Increment Phase
  counterBloc.dispatch(IncrementCounter());
  await Future<void>.delayed(Duration(seconds: 1));

  counterBloc.dispatch(IncrementCounter());
  await Future<void>.delayed(Duration(seconds: 1));

  counterBloc.dispatch(IncrementCounter());
  await Future<void>.delayed(Duration(seconds: 1));

  // Decrement Phase
  counterBloc.dispatch(DecrementCounter());
  await Future<void>.delayed(Duration(seconds: 1));

  counterBloc.dispatch(DecrementCounter());
  await Future<void>.delayed(Duration(seconds: 1));

  counterBloc.dispatch(DecrementCounter());
  await Future<void>.delayed(Duration(seconds: 1));
}

Use this package as a library

1. Depend on it

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


dependencies:
  bloc: ^0.5.1

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages 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';
  
Version Uploaded Documentation Archive
0.5.1 Oct 23, 2018 Go to the documentation of bloc 0.5.1 Download bloc 0.5.1 archive
0.5.0 Oct 23, 2018 Go to the documentation of bloc 0.5.0 Download bloc 0.5.0 archive
0.4.2 Oct 16, 2018 Go to the documentation of bloc 0.4.2 Download bloc 0.4.2 archive
0.4.1 Oct 16, 2018 Go to the documentation of bloc 0.4.1 Download bloc 0.4.1 archive
0.4.0 Oct 16, 2018 Go to the documentation of bloc 0.4.0 Download bloc 0.4.0 archive
0.3.0 Oct 14, 2018 Go to the documentation of bloc 0.3.0 Download bloc 0.3.0 archive
0.2.5 Oct 11, 2018 Go to the documentation of bloc 0.2.5 Download bloc 0.2.5 archive
0.2.4 Oct 9, 2018 Go to the documentation of bloc 0.2.4 Download bloc 0.2.4 archive
0.2.3 Oct 9, 2018 Go to the documentation of bloc 0.2.3 Download bloc 0.2.3 archive
0.2.2 Oct 8, 2018 Go to the documentation of bloc 0.2.2 Download bloc 0.2.2 archive

All 15 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
79
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]
90
Learn more about scoring.

We analyzed this package on Oct 23, 2018, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.0.0
  • pana: 0.12.4

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-dev.28.0 <3.0.0
rxdart >=0.18.1 <1.0.0 0.19.0
Dev dependencies
test >=1.3.0 <2.0.0
test_coverage ^0.2.0