# bloc 0.13.0
A predictable state management library that helps implement the BLoC (Business Logic Component) design pattern.
## Installing
```
export PUB_HOSTED_URL=https://pub.mirror.p-hatan.ir
flutter pub add 'bloc:0.13.0'
```
Published: 2019-05-04T19:39:29.917933Z
Expected archive SHA-256: cfcc09c3bdc24ba252e3ecbdb43191fc8ed7b14738c2cfb3bd3bedd0e419ba3c
Available in cache; verification: upstream_checksum
## Direct dependencies
- meta: ^1.1.6
- rxdart: ^0.22.0
## Package README (untrusted upstream documentation)
[](https://pub.dartlang.org/packages/bloc)
[](https://travis-ci.org/felangel/bloc)
[](https://codecov.io/gh/felangel/bloc)
[](https://flutter.io/docs/development/data-and-backend/state-mgmt/options#bloc--rx)
[](https://github.com/Solido/awesome-flutter#standard)
[](http://fluttersamples.com)
[](https://github.com/felangel/bloc)
[](https://gitter.im/bloc_package/Lobby)
[](https://opensource.org/licenses/MIT)
---
A dart package that helps implement the [BLoC pattern](https://www.didierboelens.com/2018/08/reactive-programming---streams---bloc).
This package is built to work with [flutter_bloc](https://pub.dartlang.org/packages/flutter_bloc) and [angular_bloc](https://pub.dartlang.org/packages/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 `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 `Bloc`s and delegates to `BlocDelegate`.
**BlocDelegate** handles events from all `Bloc`s 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`.
**transform** is a method that transforms the `Stream` along with a `next` function into a `Stream`. 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 `transform` for advanced usage in order to manipulate the frequency and specificity with which `mapEventToState` is called as well as which events are processed.
**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:
```dart
class CounterBloc extends Bloc {
@override
int get initialState => 0;
@override
Stream 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:
```dart
enum CounterEvent { increment, decrement }
```
Then we can dispatch events to our bloc like so:
```dart
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`.
```dart
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`.
```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`.
```dart
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`.
```dart
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](https://github.com/felangel/Bloc/tree/master/packages/bloc/example) - an example of how to create a `CounterBloc` in a pure Dart app.
### Maintainers
- [Felix Angelov](https://github.com/felangel)
## Changelog
# 0.13.0
`Bloc` and `BlocDelegate` Improvements, new Features, and Documentation Updates.
- Improved `dispose` to ignore pending events ([#257](https://github.com/felangel/bloc/issues/257)).
- Exposed `event` stream on `Bloc` similar to `state` stream to expose a `Stream` of `dispatched` events ([#259](https://github.com/felangel/bloc/issues/259)).
- Update to use `rxdart` version `^0.22.0` ([#265](https://github.com/felangel/bloc/issues/265)).
- `BlocDelegate` methods include a reference to the `Bloc` instance ([#259](https://github.com/felangel/bloc/issues/259)).
- Added `onEvent` to `Bloc` and `BlocDelegate` ([#259](https://github.com/felangel/bloc/issues/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 mapEventToState(S currentState, E event)` -> `Stream 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 mapEventToState(S state, E event)` -> `Stream 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 `Transition`s 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 mapEventToState(E event)` -> `Stream 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 transform(Stream 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.