feat: added query onError & onComplete callbacks

Author: fabis94

packages/graphql/lib/src/core/observable_query.dart

@@ -87,6 +87,9 @@ class ObservableQuery<TParsed> {
   /// callbacks registered with [onData]
   List<OnData<TParsed>> _onDataCallbacks = [];
 
+  /// same as [_onDataCallbacks], but not removed after invocation
+  Set<OnData<TParsed>> _notRemovableOnDataCallbacks = Set();
+
   /// call [queryManager.maybeRebroadcastQueries] after all other [_onDataCallbacks]
   ///
   /// Automatically appended as an [OnData]
@@ -273,9 +276,24 @@ class ObservableQuery<TParsed> {
   /// result that [QueryResult.isConcrete],
   /// handling the resolution of [lifecycle] from
   /// [QueryLifecycle.sideEffectsBlocking] to [QueryLifecycle.completed]
-  /// as appropriate
-  void onData(Iterable<OnData<TParsed>> callbacks) =>
-      _onDataCallbacks.addAll(callbacks);
+  /// as appropriate, unless if [removeAfterInvocation] is set to false.
+  ///
+  /// Returns a function for removing the added callbacks
+  void Function() onData(
+    Iterable<OnData<TParsed>> callbacks, {
+    bool removeAfterInvocation = true,
+  }) {
+    _onDataCallbacks.addAll(callbacks);
+
+    if (!removeAfterInvocation) {
+      _notRemovableOnDataCallbacks.addAll(callbacks);
+    }
+
+    return () {
+      _onDataCallbacks.removeWhere((cb) => callbacks.contains(cb));
+      _notRemovableOnDataCallbacks.removeWhere((cb) => callbacks.contains(cb));
+    };
+  }
 
   /// Applies [onData] callbacks at the end of [addResult]
   ///
@@ -300,7 +318,8 @@ class ObservableQuery<TParsed> {
 
     if (result!.isConcrete) {
       // avoid removing new callbacks
-      _onDataCallbacks.removeWhere((cb) => callbacks.contains(cb));
+      _onDataCallbacks.removeWhere((cb) =>
+          callbacks.contains(cb) && !_notRemovableOnDataCallbacks.contains(cb));
 
       // if there are new callbacks, there is maybe another inflight mutation
       if (_onDataCallbacks.isEmpty) {

packages/graphql/lib/src/core/query_options.dart

@@ -1,3 +1,5 @@
+import 'dart:async';
+
 import 'package:graphql/src/core/_base_options.dart';
 import 'package:graphql/src/core/result_parser.dart';
 import 'package:graphql/src/utilities/helpers.dart';
@@ -7,6 +9,10 @@ import 'package:gql/ast.dart';
 import 'package:graphql/client.dart';
 import 'package:meta/meta.dart';
 
+typedef OnQueryComplete = FutureOr<void> Function(Map<String, dynamic> data);
+
+typedef OnQueryError = FutureOr<void> Function(OperationException? error);
+
 /// Query options.
 @immutable
 class QueryOptions<TParsed extends Object?> extends BaseOptions<TParsed> {
@@ -21,6 +27,8 @@ class QueryOptions<TParsed extends Object?> extends BaseOptions<TParsed> {
     this.pollInterval,
     Context? context,
     ResultParserFn<TParsed>? parserFn,
+    this.onComplete,
+    this.onError,
   }) : super(
           fetchPolicy: fetchPolicy,
           errorPolicy: errorPolicy,
@@ -33,13 +41,18 @@ class QueryOptions<TParsed extends Object?> extends BaseOptions<TParsed> {
           parserFn: parserFn,
         );
 
+  final OnQueryComplete? onComplete;
+  final OnQueryError? onError;
+
   /// The time interval on which this query should be re-fetched from the server.
   final Duration? pollInterval;
 
   @override
   List<Object?> get properties => [
         ...super.properties,
         pollInterval,
+        onComplete,
+        onError,
       ];
 
   QueryOptions<TParsed> withFetchMoreOptions(
@@ -335,3 +348,39 @@ extension WithType on Request {
   bool get isMutation => type == OperationType.mutation;
   bool get isSubscription => type == OperationType.subscription;
 }
+
+/// Handles execution of query callbacks
+class QueryCallbackHandler<TParsed> {
+  final QueryOptions<TParsed> options;
+
+  QueryCallbackHandler({required this.options});
+
+  Iterable<OnData<TParsed>> get callbacks {
+    var callbacks = List<OnData<TParsed>?>.empty(growable: true);
+    callbacks.addAll([onCompleted, onError]);
+    // FIXME: can we remove the type in whereType?
+    return callbacks.whereType<OnData<TParsed>>();
+  }
+
+  OnData<TParsed>? get onCompleted {
+    if (options.onComplete != null) {
+      return (QueryResult? result) {
+        if (!result!.isLoading && !result.isOptimistic) {
+          return options.onComplete!(result.data ?? {});
+        }
+      };
+    }
+    return null;
+  }
+
+  OnData<TParsed>? get onError {
+    if (options.onError != null && options.errorPolicy != ErrorPolicy.ignore) {
+      return (QueryResult? result) {
+        if (!result!.isLoading && result.hasException) {
+          return options.onError!(result.exception);
+        }
+      };
+    }
+    return null;
+  }
+}

packages/graphql_flutter/lib/src/widgets/hooks/query.dart

@@ -40,6 +40,15 @@ QueryHookResult<TParsed> useQueryOnClient<TParsed>(
     query.stream,
     initialData: query.latestResult,
   );
+
+  useEffect(() {
+    final cleanup = query.onData(
+      QueryCallbackHandler(options: options).callbacks,
+      removeAfterInvocation: false,
+    );
+    return cleanup;
+  }, [options, query]);
+
   return QueryHookResult(
     result: snapshot.data!,
     refetch: query.refetch,

packages/graphql_flutter/test/widgets/query_test.dart

@@ -1,3 +1,4 @@
+import 'dart:convert';
 import 'dart:io';
 
 import 'package:flutter/material.dart';
@@ -52,12 +53,20 @@ class Page extends StatefulWidget {
   final FetchPolicy? fetchPolicy;
   final ErrorPolicy? errorPolicy;
 
-  Page({
-    Key? key,
-    this.variables,
-    this.fetchPolicy,
-    this.errorPolicy,
-  }) : super(key: key);
+  /// Query onComplete callback
+  final OnQueryComplete? onQueryComplete;
+
+  /// Query onError callbacks
+  final OnQueryError? onQueryError;
+
+  Page(
+      {Key? key,
+      this.variables,
+      this.fetchPolicy,
+      this.errorPolicy,
+      this.onQueryComplete,
+      this.onQueryError})
+      : super(key: key);
 
   @override
   State<StatefulWidget> createState() => PageState();
@@ -102,6 +111,8 @@ class PageState extends State<Page> {
         variables: variables,
         fetchPolicy: fetchPolicy,
         errorPolicy: errorPolicy,
+        onComplete: widget.onQueryComplete,
+        onError: widget.onQueryError,
       ),
       builder: (result, {Refetch? refetch, FetchMore? fetchMore}) =>
           Container(),
@@ -370,5 +381,58 @@ void main() {
       await tester.pump();
       verifyNoMoreInteractions(mockHttpClient);
     });
+
+    testWidgets('invokes onComplete callback once when completed',
+        (WidgetTester tester) async {
+      var onCompleteHits = 0;
+      final page = Page(
+        variables: {'foo': 1},
+        onQueryComplete: (a) {
+          onCompleteHits++;
+        },
+      );
+
+      await tester.pumpWidget(GraphQLProvider(
+        client: client,
+        child: page,
+      ));
+
+      expect(onCompleteHits, equals(1));
+    });
+
+    testWidgets('invokes onError callback once when error thrown',
+        (WidgetTester tester) async {
+      var errorMsg = "Something bad has happened!";
+      List<GraphQLError> errors = [];
+
+      final page = Page(
+        variables: {'foo': 1},
+        onQueryError: (a) {
+          errors.addAll(a?.graphqlErrors ?? []);
+        },
+      );
+
+      when(mockHttpClient.send(captureAny))
+          .thenAnswer((_) => Future<http.StreamedResponse>.value(
+                http.StreamedResponse(
+                  Stream.value(utf8.encode(jsonEncode({
+                    "data": null,
+                    "errors": [
+                      {"message": errorMsg}
+                    ],
+                  }))),
+                  200,
+                ),
+              ));
+
+      await tester.pumpWidget(GraphQLProvider(
+        client: client,
+        child: page,
+      ));
+
+      expect(errors, isNotEmpty);
+      expect(errors.map((e) => e.message).join(), contains(errorMsg));
+      expect(errors, hasLength(1));
+    });
   });
 }