Best Practices: Handling loading/error mutation states

[chimon2000]

Recently read @bizz84's article on handling loading/error states when executing asynchronous actions. In it, he describes creating controllers per action that update their AsyncValue as they perform an action. For example:

class PaymentButton extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    // 1. listen for errors
    ref.listen<AsyncValue<void>>(
      paymentButtonControllerProvider,
      (_, state) => state.whenOrNull(
        error: (error) {
          // show snackbar if an error occurred
          ScaffoldMessenger.of(context).showSnackBar(
            SnackBar(content: Text(error)),
          );
        },
      ),
    );
    // 2. use the loading state in the child widget
    final paymentState = ref.watch(paymentButtonControllerProvider);
    final isLoading = paymentState is AsyncLoading<void>;
    return PrimaryButton(
      text: 'Pay',
      isLoading: isLoading,
      onPressed: isLoading
        ? null
        : () => ref.read(paymentButtonControllerProvider.notifier).pay(),
    );
  }
}

class PaymentButtonController extends StateNotifier<AsyncValue<void>> {
  PaymentButtonController({required this.checkoutService})
      // initialize state
      : super(const AsyncValue.data(null));
  final CheckoutService checkoutService;

  Future<void> pay() async {
    try {
      // set state to `loading` before starting the asynchronous work
      state = const AsyncValue.loading();
      // do the async work
      await checkoutService.pay();
    } catch (e) {
      // if the payment failed, set the error state
      state = const AsyncValue.error('Could not place order');
    } finally {
      // set state to `data(null)` at the end (both for success and failure)
      state = const AsyncValue.data(null);
    }
  }
}
}

final paymentButtonControllerProvider =
    StateNotifierProvider<PaymentButtonController, AsyncValue<void>>((ref) {
  final checkoutService = ref.watch(checkoutServiceProvider);
  return PaymentButtonController(checkoutService: checkoutService);
});

I also put together a very simple generic version of this:

class IncrementButton extends ConsumerWidget {
  const IncrementButton({
    Key? key,
    required this.mutationProvider,
  }) : super(key: key);

  final StateNotifierProvider<ActionController, AsyncValue<void>>
      mutationProvider;

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final actionState = ref.watch(mutationProvider);
    final isLoading = actionState is AsyncLoading<void>;

    return FloatingActionButton(
      onPressed: isLoading
          ? null
          : () => ref.read(mutationProvider.notifier).execute(),
      tooltip: 'Increment',
      child: const Icon(Icons.add),
      disabledElevation: 0,
    );
  }
}

final incrementButtonControllerProvider =
    StateNotifierProvider.family<ActionController, AsyncValue<void>, ActionFn>(
        (ref, actionFn) {
  return ActionController(actionFn);
});

class ActionController extends StateNotifier<AsyncValue<void>> {
  ActionController(this.actionFn) : super(const AsyncValue.data(null));

  final ActionFn actionFn;

  Future<void> execute() async {
    try {
      state = const AsyncValue.loading();
      state = await AsyncValue.guard(actionFn);
    } finally {
      state = const AsyncValue.data(null);
    }
  }
}

typedef ActionFn = Future<void> Function();

1. Wondering what alternatives to this pattern have been used?
2. How can the generic ActionController be improved or simplified?

Thanks in advance for the feedback!

[rrousselGit]

Riverpod currently is unopinionated on the matter. The reasoning is that there's not really an ideal solution with the current state of Dart.

For Riverpod to do something about this use case, it'll have to wait until metaprogramming is released. At which point, Riverpod will have built-in support for this

My current plan for Riverpod+metaprogramming is to support:

@provider
class _$TodoListController {
  Future<List<Todo>> create() async {
    // can use ref.watch here if desired
    return <some HTTP request>
  }

  @mutation
  Future<void> add(Todo todo) async {
    await http.post('api/todos/add', todo.toJson();
     // <somehow update the list of todos>
  }
}


// in some widget:

Widget build(context, ref) {
  AsyncValue<List<Todo>> todos = ref.watch(TodoListController);
  // as usual

  Mutation add = ref.watch(TodoListController.add);
  // for mutations like you defined, which allows:

  return Column(
    children: [
      if (add.hasError) Text('failed to add todo ${add.error}'),

      ElevatedButton(
        onTap: () => add(Todo('new todo')),
        child: Text('submit'),
      ),      
    ],
  );
}

[chimon2000]

Very interesting @rrousselGit. So each function with a mutation decorator is essentially mapped to an AsyncValue under the covers?

[rrousselGit]

No, we'd likely want to support synchronous mutations too

[rrousselGit]

For reference, here are more example of what I have in mind, including some family samples:

// functional provider:
@provider
Future<Response> _$networkRequest(Ref ref) {
  return http.get('...');
}

// usage:
AsyncValue<Response> value = ref.watch(NetworkRequest);


// functional "family"
@provider
Future<Response> _$networkRequest(Ref ref, String name, {int page = 0}) {
  return http.get('api.com/users?name=name&page=$page');
}

// usage:
AsyncValue<Response> value = ref.watch(NetworkRequest('John', page: 42));


// class-based "family":
@provider
class _$NetworkRequest {
  Future<Response> create(String name, {int page = 0}) async {
    // can use ref.watch here if desired
    return http.get('api.com/users?name=name&page=$page');
  }

  @mutation
  Future<void> add(User user) async {
    final List<User> users = await http.post('api/users/add', user.toJson());
    ref.invalidateSelf(); // causes `create` to be executed
  }
}

// usage:
AsyncValue<Response> value = ref.watch(NetworkRequest('John', page: 42));
final add = ref.watch(NetworkRequest('John', page: 42).add);

Button(onTap: () => add(User(...));

[rrousselGit]

I wish we could get rid of those _$ but they may have to stay – metaprogramming likely won't allow remove them in those specific cases.

But it's still a huge improvement over the current syntax, and would add support for provider hot-reload

[bizz84]

I've been thinking about my approach and the generic version by @chimon2000.

In essence, I always do this in the use case above:

• create a StateNotifier subclass that calls some async code and sets the widget state (loading/data/error)
• create a provider for that subclass
• listen for errors in the build() method and use the state in the UI as needed

It seems acceptable to repeat this for new widgets, though I was wondering if this is something that can be simplified further with Flutter Hooks? (I'll admit I haven't used them extensively so I need to get a better feel for what use cases they solve effectively)

[rrousselGit]

Hooks could help. To begin with, ref.watch is a form of hook
What I don't like is that at the moment, it's difficult to have the action logic located outside of a widget.

But if you don't mind, you could do:

final addTodo = useMutation();

if (mutation.hasError) return Text('failed to post');

return Button(
  onTap: () {
    addTodo(() => postSomething());
  },
);

[andrySD]

What would happen if I have several CRUDs? Imagine you have two entities to CRUD, would you have to have 8 different controllers? One for each possible action that the user performs with its specific message so that the user knows what operation is being performed and if it was completed or not.

[joanofdart]

What I usually did was to create a provider and set it up as a snackbar to show any error.

in some view_model:

    } on UserException catch (e) {
      _read(snackBarProvider.notifier).update(
        (state) => SnackBarMessage(
          message: e.message ?? 'Something went wrong',
        ),
      );
      rethrow;
    }

inside a widget

    ref.listen<SnackBarMessage>(
      snackBarProvider,
      (previous, value) {
        timerSnackbar(
          context: context,
          contentText: value.message,
          onTimerComplete: value.callback,
        );
      },
    );

[alvindrakes]

@joanofdart Your implementation actually looks great! But is this considered having UI codes in the data layer though?

I am used to riverpod but still feeling unsure too on side effects state.
If we always model our state to be initial, loading, success, error.

We also need to add more side effects states to determine when to show a snackbar , or when to show an error UI.
So we will have something like initial, loading, success, error, errorSnackbar, errorButton to show maybe error text only for a button etc.

Everything I am doing at the moment feels kinda hacky.

For my flutter_redux implementation, everything are just normalized states, and all side effects are being keep tracked in the redux epics.

So maybe I am forced to combine data layer like your implementation atm.

Happy to receive more guidance on this! @rrousselGit

[joanofdart]

@alvindrakes SnackbarMessage is just a normal class, so no UI is mixed up with the logic (unless I am seeing something different here).
the ref.listen part its indeed intended to be inside a widget.

[joanofdart]

@alvindrakes updated the first post, I mixed up what I wanted to write 😄

[andrySD]

@joanofdart Could you provide a minimal example to see how exacly you do to update your ui?

[ahmadjz]

another possible way I saw on @vandadnp 's course is to make a consumer in the root of you widgets that listens to a loading provider

 Consumer(
           builder: (context, ref, child) {
             ref.listen<bool>(
               isLoadingProvider,
               (_, isLoading) {
                 if (isLoading) {
                   LoadingScreen.instance().show(
                     context: context,
                   );
                 } else {
                   LoadingScreen.instance().hide();
                 }
               },
             );
             return HomePage();

and IsLoadingProvider is combined of listening for loading of multiple providers of type StateNotifierProvider and their state is the loading value

 @riverpod
 bool isLoading(IsLoadingRef ref) {
   final authState = ref.watch(authStateProvider);
   final isUploadingImage = ref.watch(imageUploaderProvider);
   final isSendingComment = ref.watch(sendCommentProvider);
   final isDeletingComment = ref.watch(deleteCommentProvider);
   final isDeletingPost = ref.watch(deletePostProvider);
   return authState.isLoading ||
       isUploadingImage ||
       isSendingComment ||
       isDeletingComment ||
       isDeletingPost;
 }

It's working fine but I was thinking about another states such as initial, loading, success, error, errorSnackbar, errorButton and so on...
So is it okay to make a provider for each state and put it in the root of my app?

[INFINITUS-GAUSOFT]

What if some of them need params?

[TekExplorer]

Consider checking out my https://pub.dev/packages/riverpod_mutations_generator

It tries to fit remi's own preferred api for when macros come out, and as far as i can tell, seems to work well enough.