when<NewT> method

NewT when<NewT>({
  1. bool skipLoadingOnReload = false,
  2. bool skipLoadingOnRefresh = true,
  3. bool skipError = false,
  4. required NewT data(
    1. ValueT data
    ),
  5. required NewT error(
    1. Object error,
    2. StackTrace stackTrace
    ),
  6. required NewT loading(),
})

Performs an action based on the state of the AsyncValue.

All cases are required, which allows returning a non-nullable value.

By default, when skips "loading" states if triggered by a Ref.refresh or Ref.invalidate (but does not skip loading states if triggered by Ref.watch).

In the event that an AsyncValue is in multiple states at once (such as when reloading a provider or emitting an error after a valid data), when offers various flags to customize whether it should call loading/error/data :

  • skipLoadingOnReload (false by default) customizes whether loading should be invoked if a provider rebuilds because of Ref.watch. In that situation, when will try to invoke either error/data with the previous state.

  • skipLoadingOnRefresh (true by default) controls whether loading should be invoked if a provider rebuilds because of Ref.refresh or Ref.invalidate. In that situation, when will try to invoke either error/data with the previous state.

  • skipError (false by default) decides whether to invoke data instead of error if a previous value is available.

Implementation

NewT when<NewT>({
  bool skipLoadingOnReload = false,
  bool skipLoadingOnRefresh = true,
  bool skipError = false,
  required NewT Function(ValueT data) data,
  required NewT Function(Object error, StackTrace stackTrace) error,
  required NewT Function() loading,
}) {
  if (isLoading) {
    bool skip;
    if (isRefreshing) {
      skip = skipLoadingOnRefresh;
    } else if (isReloading) {
      skip = skipLoadingOnReload;
    } else {
      skip = false;
    }
    if (!skip) return loading();
  }

  if (hasError && (!hasValue || !skipError)) {
    return error(this.error!, stackTrace!);
  }

  return data(requireValue);
}