Merge pull request #55 from leancodepl/feat/LMG-356-request-state-mapping-refactor

[LMG-356] RequestState mapping reimagination

Author: KamilSztandur

packages/leancode_cubit_utils/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 * **BREAKING CHANGE**: Remove `map` and `isEmpty` methods from `RequestCubit`.
 * **BREAKING CHANGE**: Remove `TData` generic parameter from `RequestCubit`.
+* Add `map` method to `RequestState`.
+* Add `onRefreshing` callback to `RequestCubitBuilder`.
+* **BREAKING CHANGE**: Rename `RequestRefreshState` to `RequestRefreshingState`
+* **BREAKING CHANGE**: Make `data` in `RequestRefreshingState` non-nullable.
+* **BREAKING CHANGE**: Add `data` to `RequestEmptyState`.
 
 ## 0.4.2
 

packages/leancode_cubit_utils/README.md

@@ -96,15 +96,51 @@ The cubit itself handles the things like:
 
 If you call `refresh()` on `ArgsRequestCubit` it will perform a request with the last used arguments. They are also available under `lastRequestArgs` field.
 
+### `RequestState`
+
+`RequestState` represents the state of a request and can be one of the following:
+- `RequestInitialState` - the request has not been started yet,
+- `RequestLoadingState` - the request is currently being performed,
+- `RequestSuccessState<TOut>` - the request completed successfully with data,
+- `RequestErrorState<TError>` - the request failed with an error,
+- `RequestRefreshingState<TOut>` - the request is being refreshed while previous data is still available,
+- `RequestEmptyState<TOut>` - the request completed successfully but returned empty data.
+
+#### `map` method
+
+`RequestState` provides a `map` method that allows you to transform the state into a value of any type. This is useful when you need to derive a value based on the current state without building a widget. The method accepts the following parameters:
+
+- `T Function()? initial` - called when the request is in its initial state. If not provided, falls back to `loading`,
+- `T Function() loading` - called when the request is loading (required),
+- `T Function(TOut? data) success` - called when the request completed successfully (required),
+- `T Function(TError? err, Object? exception, StackTrace? st) error` - called when the request failed (required),
+- `T Function(TOut data)? refreshing` - called when the request is refreshing with previous data. If not provided, falls back to `success`,
+- `T Function(TOut? data)? empty` - called when the request completed successfully but returned empty data. If not provided, falls back to `success`.
+
+Example usage:
+
+```dart
+Scaffold(
+  appBar: state.map<AppBar>(
+    loading: () => const LoadingAppBar(),
+    success: (data) => SuccessAppBar(data: data),
+    error: (err, exception, st) => const ErrorAppBar(error: err),
+  ),
+  body: YourPageContent(),
+)
+```
+
 ### `RequestCubitBuilder`
 
-`RequestCubitBuilder` is a widget that builds a widget based on the current state of `BaseRequestCubit`. It takes a numerous builders for each state:
-- `WidgetBuilder? onInitial` - use it to show a widget before invoking the request for the first time,
+`RequestCubitBuilder` is a widget that builds a widget based on the current state of `BaseRequestCubit`. It takes numerous builders for each state:
+- `WidgetBuilder? onInitial` - use it to show a widget before invoking the request for the first time.
 - `WidgetBuilder? onLoading` - use it to show a loader widget while the request is being performed,
 - `WidgetBuilder? onError` - use it to show error widget when processing the request fails,
-- `RequestWidgetBuilder<TOut> onSuccess` - use it to build a page when the data is successfully loaded. 
+- `RequestWidgetBuilder<TOut> onSuccess` - use it to build a page when the data is successfully loaded (required),
+- `WidgetBuilder? onEmpty` - use it to show a widget when the request returns empty data. If not provided, falls back to global config or empty widget,
+- `RequestWidgetBuilder<TOut>? onRefreshing` - use it to show a widget while refreshing with previous data still available. If not provided, falls back to `onSuccess`.
 
-Other than builders, you also need to provide the cubit based on which the `RequestCubitBuilder` will be rebuilt. And you can also pass `onErrorCallback` which allows you to pass a callback to error widget builder. You may want to use it to implement retry button.
+Other than builders, you also need to provide the cubit based on which the `RequestCubitBuilder` will be rebuilt. You can also pass `onErrorCallback` which allows you to pass a callback to error widget builder. You may want to use it to implement a retry button.
 
 Example usage of `RequestCubitBuilder`:
 ```dart
@@ -135,10 +171,31 @@ RequestCubitBuilder(
           },
         );
       },
+      onRefreshing: (context, data) {
+        return Stack(
+          children: [
+            ListView.builder(
+              itemCount: data.assignments.length,
+              itemBuilder: (context, index) {
+                final assignment = data.assignments[index];
+                return ListTile(
+                  title: AppText(assignment.id),
+                );
+              },
+            ),
+            const Positioned(
+              top: 0,
+              left: 0,
+              right: 0,
+              child: LinearProgressIndicator(),
+            ),
+          ],
+        );
+      },
     )
 ```
 
-As you may see `onInitial`, `onLoading` and `onError` are marked as optional parameter. In many projects each of those widgets are the same for each page. So in order to eliminate even more boilerplate code, instead of passing them all each time you want to use `RequestCubitBuilder`, you can define them globally and provide in the whole app using [`RequestLayoutConfigProvider`](#requestlayoutconfigprovider).
+As you may see `onLoading`, `onEmpty` and `onError` are marked as optional parameters. In many projects each of those widgets are the same for each page. So in order to eliminate even more boilerplate code, instead of passing them all each time you want to use `RequestCubitBuilder`, you can define them globally and provide in the whole app using [`RequestLayoutConfigProvider`](#requestlayoutconfigprovider).
 
 ### `RequestLayoutConfigProvider`
 

packages/leancode_cubit_utils/example/lib/pages/request/request_page.dart

@@ -41,8 +41,9 @@ class RequestPage extends StatelessWidget {
             Center(
               child: RequestCubitBuilder(
                 cubit: context.read<UserRequestCubit>(),
-                onSuccess: (context, data) =>
-                    Text('${data.name} ${data.surname}'),
+                onSuccess: (context, data) => Text(
+                  '${data.name} ${data.surname}',
+                ),
               ),
             ),
             const SizedBox(height: 16),

packages/leancode_cubit_utils/lib/src/request/request_cubit.dart

@@ -67,15 +67,11 @@ abstract class BaseRequestCubit<TRes, TOut, TError>
           }
       }
 
-      if (isRefresh) {
+      if (state
+          case RequestSuccessState(:final data) ||
+              RequestRefreshingState(:final data) when isRefresh) {
         logger.info('Refreshing request.');
-        emit(
-          RequestRefreshState(switch (state) {
-            RequestSuccessState(:final data) => data,
-            RequestRefreshState(:final data) => data,
-            _ => null,
-          }),
-        );
+        emit(RequestRefreshingState(data));
       } else {
         logger.info('Request started.');
         emit(RequestLoadingState());
@@ -170,7 +166,50 @@ abstract class ArgsRequestCubit<TArgs, TRes, TOut, TError>
 }
 
 /// Represents the state of a request.
-sealed class RequestState<TOut, TError> with EquatableMixin {}
+sealed class RequestState<TOut, TError> with EquatableMixin {
+  /// Maps the current request state to a value of type [T].
+  ///
+  /// * [initial] - returns a [T] value when the request is in
+  ///   its initial state (not yet started). **If not provided, falls back to
+  ///   [loading]**.
+  /// * [loading] - returns a [T] value when the request is loading.
+  /// * [success] - returns a [T] value when the request completed
+  ///   successfully with data.
+  /// * [error] - returns a [T] value when the request failed with an error.
+  /// * [refreshing] - returns a [T] value when the request is refreshing with
+  ///   previous data still available. **If not provided, falls back to
+  ///   [success].**
+  /// * [empty] - returns a [T] value when the request completed successfully
+  ///   but returned empty data. **If not provided, falls back to [success].**
+  ///
+  /// ## Example
+  ///
+  /// ```dart
+  /// Scaffold(
+  ///   appBar: state.map<AppBar>(
+  ///     onLoading: () => const LoadingAppBar(),
+  ///     onSuccess: (data) => SuccessAppBar(data: data),
+  ///     onError: (err, exception, st) => const ErrorAppBar(error: err),
+  ///   ),
+  /// );
+  /// ```
+  T map<T>({
+    T Function()? initial,
+    required T Function() loading,
+    required T Function(TOut data) success,
+    required T Function(TError? err, Object? exception, StackTrace? st) error,
+    T Function(TOut data)? refreshing,
+    T Function(TOut data)? empty,
+  }) => switch (this) {
+    RequestInitialState() => (initial ?? loading)(),
+    RequestLoadingState() => loading(),
+    RequestSuccessState(:final data) => success(data),
+    RequestErrorState(error: final err, :final exception, :final stackTrace) =>
+      error(err, exception, stackTrace),
+    RequestRefreshingState(:final data) => (refreshing ?? success)(data),
+    RequestEmptyState(:final data) => (empty ?? success)(data),
+  };
+}
 
 /// Represents the initial state of a request.
 final class RequestInitialState<TOut, TError>
@@ -190,13 +229,13 @@ final class RequestLoadingState<TOut, TError>
 }
 
 /// Represents the refresh state of a request.
-final class RequestRefreshState<TOut, TError>
+final class RequestRefreshingState<TOut, TError>
     extends RequestState<TOut, TError> {
-  /// Creates a new [RequestRefreshState] with the previous [data].
-  RequestRefreshState([this.data]);
+  /// Creates a new [RequestRefreshingState] with the previous [data].
+  RequestRefreshingState(this.data);
 
   /// The previous data.
-  final TOut? data;
+  final TOut data;
 
   @override
   List<Object?> get props => [data];
@@ -215,13 +254,17 @@ final class RequestSuccessState<TOut, TError>
   List<Object?> get props => [data];
 }
 
-/// Represents a successful request with empty data.
+/// Represents a successful request with empty data. [TOut] has to be nullable
+/// if you cannot provide any meaningful data for the empty state.
 final class RequestEmptyState<TOut, TError> extends RequestState<TOut, TError> {
-  /// Creates a new [RequestEmptyState]..
-  RequestEmptyState();
+  /// Creates a new [RequestEmptyState].
+  RequestEmptyState(this.data);
+
+  /// The data returned by the request.
+  final TOut data;
 
   @override
-  List<Object?> get props => [];
+  List<Object?> get props => [data];
 }
 
 /// Represents a failed request.

packages/leancode_cubit_utils/lib/src/request/request_cubit_builder.dart

@@ -26,6 +26,7 @@ class RequestCubitBuilder<TOut, TError> extends StatelessWidget {
     this.onInitial,
     this.onLoading,
     this.onEmpty,
+    this.onRefreshing,
     this.onError,
     this.onErrorCallback,
   });
@@ -45,6 +46,9 @@ class RequestCubitBuilder<TOut, TError> extends StatelessWidget {
   /// The builder that creates a widget when request returns empty data.
   final WidgetBuilder? onEmpty;
 
+  /// The builder that creates a widget when request is refreshing.
+  final RequestWidgetBuilder<TOut>? onRefreshing;
+
   /// The builder that creates a widget when request failed.
   final RequestErrorBuilder<TError>? onError;
 
@@ -55,37 +59,37 @@ class RequestCubitBuilder<TOut, TError> extends StatelessWidget {
   Widget build(BuildContext context) {
     final config = context.read<RequestLayoutConfig>();
 
+    final effectiveOnLoading = onLoading ?? config.onLoading;
+    final effectiveOnEmpty = onEmpty ?? config.onEmpty;
+    final effectiveOnError = onError ?? config.onError;
+
     return BlocBuilder<
       BaseRequestCubit<dynamic, TOut, TError>,
       RequestState<TOut, TError>
     >(
       bloc: cubit,
-      builder: (context, state) {
-        return switch (state) {
-          RequestInitialState() =>
-            onInitial?.call(context) ??
-                onLoading?.call(context) ??
-                config.onLoading(context),
-          RequestLoadingState() =>
-            onLoading?.call(context) ?? config.onLoading(context),
-          RequestSuccessState(:final data) => onSuccess(context, data),
-          RequestRefreshState(:final data) =>
-            data != null
-                ? onSuccess(context, data)
-                : onLoading?.call(context) ?? config.onLoading(context),
-          RequestEmptyState() =>
-            onEmpty?.call(context) ??
-                config.onEmpty?.call(context) ??
-                const SizedBox(),
-          RequestErrorState() =>
-            onError?.call(context, state, onErrorCallback ?? cubit.refresh) ??
-                config.onError(
-                  context,
-                  state,
-                  onErrorCallback ?? cubit.refresh,
-                ),
-        };
-      },
+      builder: (context, state) => state.map(
+        initial: switch (onInitial) {
+          final onInitial? => () => onInitial(context),
+          _ => null,
+        },
+        loading: () => effectiveOnLoading(context),
+        success: (data) => onSuccess(context, data),
+        empty: switch (effectiveOnEmpty) {
+          final onEmpty? => (_) => onEmpty(context),
+          _ => null,
+        },
+        refreshing: switch (onRefreshing) {
+          final onRefreshing? => (data) => onRefreshing(context, data),
+          null => null,
+        },
+        error: (err, _, _) {
+          final errorState = state as RequestErrorState<TOut, TError>;
+          final callback = onErrorCallback ?? cubit.refresh;
+
+          return effectiveOnError(context, errorState, callback);
+        },
+      ),
     );
   }
 }

packages/leancode_cubit_utils/test/request_cubit_builder_test.dart

@@ -10,6 +10,34 @@ import 'utils/http_status_codes.dart';
 import 'utils/mocked_http_client.dart';
 import 'utils/test_request_cubit.dart';
 
+class FakeRequestCubit extends RequestCubit<http.Response, String, int>
+    with RequestResultHandler<String> {
+  FakeRequestCubit.success() : super('FakeRequestCubit') {
+    emit(RequestSuccessState(fakeResult));
+  }
+
+  FakeRequestCubit.error() : super('FakeRequestCubit') {
+    emit(RequestErrorState(error: 1));
+  }
+
+  FakeRequestCubit.empty() : super('FakeRequestCubit') {
+    emit(RequestEmptyState(fakeResult));
+  }
+
+  FakeRequestCubit.loading() : super('FakeRequestCubit') {
+    emit(RequestLoadingState());
+  }
+
+  FakeRequestCubit.refresh() : super('FakeRequestCubit') {
+    emit(RequestRefreshingState(fakeResult));
+  }
+
+  static const fakeResult = 'Result';
+
+  @override
+  Future<http.Response> request() async => http.Response('', 1);
+}
+
 class TestPage extends StatelessWidget {
   const TestPage({super.key, required this.child});
 
@@ -158,5 +186,45 @@ void main() {
       expect(find.text('Success, data: Result'), findsOneWidget);
       await tester.pumpAndSettle();
     });
+
+    testWidgets('shows custom refresh widget when onRefreshing is provided', (
+      tester,
+    ) async {
+      final cubit = FakeRequestCubit.refresh();
+
+      await tester.pumpWidget(
+        TestPage(
+          child: RequestCubitBuilder(
+            cubit: cubit,
+            onRefreshing: (context, data) => const Text('Refreshing'),
+            onSuccess: (context, data) => const Text('Success'),
+          ),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.text('Refreshing'), findsOneWidget);
+    });
+
+    testWidgets('onRefreshing not provided does not cause an error', (
+      tester,
+    ) async {
+      final cubit = FakeRequestCubit.refresh();
+
+      const key = Key('request_cubit_builder');
+
+      await tester.pumpWidget(
+        TestPage(
+          child: RequestCubitBuilder(
+            key: key,
+            cubit: cubit,
+            onSuccess: (context, data) => const SizedBox(),
+          ),
+        ),
+      );
+      await tester.pumpAndSettle();
+
+      expect(find.byKey(key), findsOneWidget);
+    });
   });
 }