atom_notifier

Description:

atom notifier

Atom #
An easy to use Flutter's Value Notifier wrapper with some sugar syntax. It provides a more friendly and semantic syntax for your project's state management.
Getting started #
Add atom as a dependency:
atom_notifier: 1.1.1
copied to clipboard
Or running following command on terminal:
flutter pub add atom_notifier
copied to clipboard
Then you can import it
import 'package:atom_notifier/atom_notifier.dart';
copied to clipboard
Atoms #
An atom is a Value Notifier wrapper, which it means it holds a single value for each atom object, native or not.
final atom = AtomNotifier<int>(1);
copied to clipboard
Unlikely value notifiers atoms have different methods, but the same effect as expected, see in the examples below:
Setting a value #
// With ValueNotifier
final notifier = ValueNotifier(0);
notifier.value = 1;

// With Atom
final atom = AtomNotifier<int>(1);
atom.set(2);
copied to clipboard
Setting Listeners #
By default, listen() already get the atom value as an argument, so there's no need to get it with atom.value everytime you want to listen to changes
// With ValueNotifier
final notifier = ValueNotifier(0);
notifier.addListener((){
final value = notifier.value;
doSomething();
});

// With Atom
final atom = AtomNotifier<int>(1);
atom.listen((value){
doSomething();
});

// With Getx Atom
final atom = GetxAtomNotifier<int>(1);
atom.listen((value){
doSomething();
});
copied to clipboard
Listening to specific state #
// With ValueNotifier
final notifier = ValueNotifier(0);
notifier.addListener((){
final value = notifier.value;
if(value is MyType){
doSomething();
}
});

// With Atom
final atom = AtomNotifier<int>(1);
atom.on<MyType>((value){
doSomething();
});

// With Getx Atom
final atom = GetxAtomNotifier<int>(1);
atom.on<MyType>((value){
doSomething();
});
copied to clipboard
Debouncing listeners #
atom.debounce(
(value) => doSomething(value),
interval: const Duration(
milliseconds: 500,
),
);
copied to clipboard
Observers #
Observer is a widget which rebuilds everytime your atom value changes.
Observing a single atom #
The most basic way to observe your state within a widget would be using AtomObserver.
AtomObserver<int>(
atom: counterAtom,
builder: (context, state) {
return Text(state.toString());
},
);
copied to clipboard
But, there will be cases where you have more complexes states, a async request status can be a good example, so, with value notifier you usually would need to check your state type and return a widget according to it, but with atom you can use PolymorphicAtomObserver
abstract class FutureStatus{}
class InitialState implements FutureStatus{}
class LoadingState implements FutureStatus{}
class SuccessState implements FutureStatus{}
class ErrorState implements FutureStatus{}

PolymorphicAtomObserver<FutureStatus>(
atom: myAtom,
defaultBuilder: (value) => const Text("Initial or Error"),
types: [
TypedAtomHandler<LoadingState>(
builder: (context, value) => const CircularProgressIndicator(),
),
TypedAtomHandler<SuccessState>(
builder: (context, value) => const Text("Success, dude!"),
),
],
);
copied to clipboard
Observing multiple atoms at once #
You can use MultiAtomObserver to handle more than one atom at once in the same widget, this way, everyime an atom inside atoms prop has it value changed it rebulds
MultiAtomObserver(
atoms: [index, character],
builder: (context) {
final name = character.value;
final id = index.value;
return Text("$id: $name");
},
),
copied to clipboard
Application States #
Usually your controllers will have some kind of behaviour just like the example I showed on PolymorphicAtomObserver, where you want your UI to reflect the usecase/service/whatever status. You can use
AtomAppState which by default has an extension that makes it easier to add listeners to it.
final atom = AtomNotifier<AtomAppState<String, int>>(InitialState());
atom.onState(
onError: (e) => counter++,
onSuccess: (e) => counter--,
onLoading: () => counter = counter * 2,
);
copied to clipboard