# bloc 3.0.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:3.0.0'
```
Published: 2019-12-25T17:20:41.668721Z
Expected archive SHA-256: ccc49d51be007d6bcf4cd113bd4a3ed70ebd31eb74359335366d07df8261ada4
Available in cache; verification: upstream_checksum
## Direct dependencies
- meta: ^1.1.6
- rxdart: ^0.23.0
## Package README (untrusted upstream documentation)
[](https://pub.dev/packages/bloc)
[](https://travis-ci.com/felangel/bloc)
[](https://codecov.io/gh/felangel/bloc)
[](https://github.com/tenhobi/effective_dart)
[](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://discord.gg/Hc5KD3g)
[](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.dev/packages/flutter_bloc) and [angular_bloc](https://pub.dev/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 `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 `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 `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` 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 `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` into a new `Stream`. By default `transformStates` returns the incoming `Stream`. 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 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:
```dart
class CounterBloc extends Bloc {
@override
int get initialState => 0;
@override
Stream 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:
```dart
enum CounterEvent { increment, decrement }
```
Then we can add events to our bloc like so:
```dart
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`.
```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.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`.
```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.6.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
# 3.0.0
- Upgrade to `rxdart ^0.23.0`
- Upgrade to `Dart >= 2.6.0`
# 3.0.0-dev.1
- Upgrade to `rxdart ^0.23.0`
# 2.0.0
- Allow blocs to finish processing pending events on `close` ([#639](https://github.com/felangel/bloc/issues/639))
- Documentation Updates
# 1.0.1
- Bugfix: Exceptions thrown in `onTransition` are passed to `onError` and should not break bloc functionality ([#641](https://github.com/felangel/bloc/issues/641))
- Adhere to [effective dart](https://dart.dev/guides/language/effective-dart) ([#561](https://github.com/felangel/bloc/issues/561))
- Documentation and Example Updates
# 1.0.0
- `dispatch` and `dispose` removed
- Documentation Updates
# 0.16.1
- Minor Documentation Updates
# 0.16.0
- Bloc extends `Stream` ([#558](https://github.com/felangel/bloc/issues/558))
- `bloc.state.listen` -> `bloc.listen`
- `bloc.currentState` -> `bloc.state`
- Bloc implements `Sink` ([#558](https://github.com/felangel/bloc/issues/558))
- `dispatch` deprecated in favor of `add`
- `dispose` deprecated in favor of `close`
- Documentation and Example Updates
# 0.15.0
- Removed Bloc `event` Stream ([#326](https://github.com/felangel/bloc/issues/326))
- Renamed `transform` to `transformEvents`
- Added `transformStates` ([#382](https://github.com/felangel/bloc/issues/382))
# 0.14.4
Additional Dependency and Documentation Updates.
# 0.14.3
Dependency and Documentation Updates.
# 0.14.2
- Deprecated Bloc `event` Stream ([#326](https://github.com/felangel/bloc/issues/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](https://github.com/felangel/bloc/issues/304)).
# 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.