async_cubits

Description:

async cubits

async_cubits #


A package that provides set of cubits for making asynchronous operations in simpler, consistent way.
Inspiration #
This package is inspired by Riverpod's FutureProvider and StreamProvider. The AsyncValue class is mostly the same as in riverpod package. Please check great work done in the riverpod package.
Installation 💻 #
❗ In order to start using Async Cubits you must have the Flutter SDK installed on your
machine.
flutter pub add async_cubits
copied to clipboard

Usage 🚀 #
Importing the package #
import 'package:async_cubits/async_cubits.dart';
copied to clipboard
Using a FutureCubit #
FutureCubits are a type of Cubit that can be used to make asynchronous operations that return a value.
E.g. fetching data from API.
class GetUserCubit extends FutureCubit<User> {
final UserRepository _userRepository;

GetUserCubit(this._userRepository);

@override
Future<User> future() => _userRepository.getUser();
}
copied to clipboard
Load the async data
To trigger the async data fetching, use load() method.
When the load() is called, the cubit emits AsyncValue<T> in following order:

AsyncValue.loading()
if the operation succeeds and data is avaialable AsyncValue.data(fetchedData)
if the operation fails - AsyncValue.error(error, stackTrace)

In your UI you can use BlocProvider and BlocBuilder to load and access the data.
BlocProvider(
create: (context) => GetUserCubit(
context.read<UserRepository>(),
)..load(), // load the data when the cubit is created
child: BlocBuilder<GetUserCubit, AsyncState<User>>(
builder: (context, state) {
return state.when(
loading: () => CircularProgressIndicator(),
error: (error) => Text(error),
data: (user) => Text(user.name),
);
},
),
);
copied to clipboard
Triggering refresh
If you want to trigger refresh of the data you can call the refresh method on the cubit.
ElevatedButton(
onPressed: () => context.read<GetUserCubit>().refresh(),
child: Text('Refresh'),
),
copied to clipboard
When the refresh() is called, the cubit emits AsyncValue<T> in following order that:

isLoading is true and value contains the previously loaded value, which helps to show the UI with previously loaded content, then immediately switch to new value without showing loading indicator. If you want to show loading indicator instead, set skipLoadingOnRefresh to false when using AsyncValue.when
if the operation succeeds and new value is available, then the state's isLoading changes to false and value contains new value
if the operation fails - state's isLoading changes to false, error and stackTrace is not null, and value contains previously loaded value. That behavior enables showing UI with previously loaded content with a refresh error message (to achieve that, use skipError in AsyncValue.when method)

So according to the example above, if the data was fetched successfully, the Text(user.name) will be rendered
and no loading indicator will be shown when the cubit is refreshed.
Loading/refreshing with new arguments
To load/refresh the data with new arguments that are passed to the future method, use FutureWithArgsCubit. The behaviour of this cubit is similar to FutureCubit.
class GetUserByIdCubit extends FutureWithArgsCubit<int, User> {
final UserRepository _userRepository;

GetUserCubit(this._userRepository);

@override
Future<User> future(int id) => _userRepository.getUserById(id);
}
copied to clipboard
and then call load or refresh with the arguments.
context.read<GetUserByIdCubit>().load(1);
copied to clipboard
or
context.read<GetUserByIdCubit>().refresh(1);
copied to clipboard
Using a StreamCubit #
StreamCubits are a type of Cubit that can be used to listen to async stream of events.
E.g. listening to a stream of data from a websocket.
class NewMessageCubit extends StreamCubit<Message> {
final MessageRepository _messageRepository;

GetMessagesCubit(this._messageRepository);

@override
Stream<Message> dataStream() => _messageRepository.newMessageStream();
}
copied to clipboard
StreamCubit emits AsyncValue<T>, so listening to state changes is similar to that in FutureCubit
class NewMessageWidget extends StatelessWidget {
@override
Widget build(BuildContext context) {
final cubit = context.watch<NewMessageCubit>();
final state = cubit.state;

return state.when(
loading: LoadingWidget.new,
error: (error, stackTrace) => ErrorWidget(error),
data: (data) => LoadedMessage(data),
);
}
}
copied to clipboard
Using a MutationCubit #
The MutationCubit is a specialized cubit designed to handle asynchronous mutations. It facilitates the execution of asynchronous tasks, managing various states throughout the process, including loading, success, and failure. Typically it's used to mutate the state of the backend, local database, etc.
Example:
class MyMutationCubit extends MutationCubit<String, int> {
@override
Future<int> mutation(String input) async {
// Perform asynchronous mutation logic here
// e.g., make an API call, update database, etc.
return 42; // Replace with actual result
}
}
copied to clipboard
To invoke the mutation, use invoke method:
cubit.invoke('input');
copied to clipboard
MutationCubit emits MutationState which can be:

Idle State: Initially, the cubit is in the MutationState.idle state, indicating that the mutation has not been invoked.
Loading State: When the mutation method is called, the cubit transitions to the MutationState.loading state.
Success State: Upon successful completion of the mutation, the cubit enters the MutationState.success state.
Failure State: If the mutation encounters an error, the cubit transitions to the MutationState.failure state.