mutation support added

multiple data, error/mutate listeners on query

packages/fl_query/lib/models/mutation_job.dart

@@ -0,0 +1,17 @@
+import 'package:fl_query/mutation.dart';
+
+class MutationJob<T extends Object, V> {
+  final String mutationKey;
+  MutationTaskFunction<T, V> task;
+  final int? retries;
+  final Duration? retryDelay;
+  final Duration? cacheTime;
+
+  MutationJob({
+    required this.mutationKey,
+    required this.task,
+    this.retries,
+    this.retryDelay,
+    this.cacheTime,
+  });
+}

packages/fl_query/lib/mutation.dart

@@ -0,0 +1,189 @@
+import 'dart:async';
+
+import 'package:fl_query/models/mutation_job.dart';
+import 'package:flutter/widgets.dart';
+
+enum MutationStatus {
+  failed,
+  succeed,
+  pending,
+}
+
+typedef MutationListener<T> = FutureOr<void> Function(T);
+
+typedef MutationTaskFunction<T, V> = FutureOr<T> Function(String, V);
+
+class Mutation<T extends Object, V> extends ChangeNotifier {
+  // all params
+  final String mutationKey;
+  MutationTaskFunction<T, V> task;
+  final int retries;
+  final Duration retryDelay;
+  final Duration _cacheTime;
+
+  // all properties
+  T? data;
+  dynamic error;
+  MutationStatus status;
+
+  /// total count of how many times the query retried to get a successful
+  /// result
+  int retryAttempts = 0;
+  DateTime updatedAt;
+
+  /// used for keeping track of mutation activity. If the are no mounts &
+  /// the passed cached time is over than the mutation is removed from
+  /// storage/cache
+  Set<Widget> _mounts = {};
+
+  @protected
+  final Set<MutationListener<T>> onDataListeners = {};
+  @protected
+  final Set<MutationListener<dynamic>> onErrorListeners = {};
+  @protected
+  final Set<MutationListener<V>> onMutateListeners = {};
+
+  Mutation({
+    required this.mutationKey,
+    required this.task,
+    required this.retries,
+    required this.retryDelay,
+    required Duration cacheTime,
+    MutationListener<T>? onData,
+    MutationListener<dynamic>? onError,
+    MutationListener<V>? onMutate,
+  })  : status = MutationStatus.pending,
+        updatedAt = DateTime.now(),
+        _cacheTime = cacheTime {
+    if (onData != null) onDataListeners.add(onData);
+    if (onError != null) onErrorListeners.add(onError);
+    if (onMutate != null) onMutateListeners.add(onMutate);
+  }
+
+  Mutation.fromOptions(
+    MutationJob<T, V> options, {
+    MutationListener<T>? onData,
+    MutationListener<dynamic>? onError,
+    MutationListener<V>? onMutate,
+  })  : mutationKey = options.mutationKey,
+        task = options.task,
+        retries = options.retries ?? 3,
+        retryDelay = options.retryDelay ?? const Duration(milliseconds: 200),
+        _cacheTime = options.cacheTime ?? const Duration(minutes: 5),
+        status = MutationStatus.pending,
+        updatedAt = DateTime.now() {
+    if (onData != null) onDataListeners.add(onData);
+    if (onError != null) onErrorListeners.add(onError);
+  }
+
+  // all getters & setters
+  bool get hasData => data != null && error == null;
+  bool get hasError =>
+      status == MutationStatus.failed && error != null && data == null;
+  bool get isLoading =>
+      status == MutationStatus.pending && data == null && error == null;
+  bool get isSucceeded => status == MutationStatus.succeed && data != null;
+  bool get isIdle => isSucceeded && error == null;
+  bool get isInactive => _mounts.isEmpty;
+  // all methods
+
+  void mount(Widget widget) {
+    _mounts.add(widget);
+  }
+
+  void unmount(Widget widget) {
+    if (_mounts.length == 1) {
+      Future.delayed(_cacheTime, () {
+        _mounts.remove(widget);
+        // for letting know QueryBowl that this one's time has come for
+        // getting crushed
+        notifyListeners();
+      });
+    } else {
+      _mounts.remove(widget);
+    }
+  }
+
+  /// Calls the task function & doesn't check if there's already
+  /// cached data available
+  Future<void> _execMutation(V variables) async {
+    try {
+      retryAttempts = 0;
+      for (final onMutate in onMutateListeners) {
+        onMutate(variables);
+      }
+      data = await task(mutationKey, variables);
+      updatedAt = DateTime.now();
+      status = MutationStatus.succeed;
+      for (final onData in onDataListeners) {
+        onData(data!);
+      }
+      notifyListeners();
+    } catch (e) {
+      if (retries == 0) {
+        status = MutationStatus.failed;
+        error = e;
+        for (final onError in onErrorListeners) {
+          onError(error);
+        }
+        notifyListeners();
+      } else {
+        // retrying for retry count if failed for the first time
+        while (retryAttempts <= retries) {
+          await Future.delayed(retryDelay);
+          try {
+            for (final onMutate in onMutateListeners) {
+              onMutate(variables);
+            }
+            data = await task(mutationKey, variables);
+            status = MutationStatus.succeed;
+            for (final onData in onDataListeners) {
+              onData(data!);
+            }
+            notifyListeners();
+            break;
+          } catch (e) {
+            if (retryAttempts == retries) {
+              status = MutationStatus.failed;
+              error = e;
+              for (final onError in onErrorListeners) {
+                onError(error);
+              }
+              notifyListeners();
+            }
+            retryAttempts++;
+          }
+        }
+      }
+    }
+  }
+
+  void mutate(
+    V variables, {
+    MutationListener<T>? onData,
+    MutationListener<dynamic>? onError,
+  }) {
+    if (onData != null) onDataListeners.add(onData);
+    if (onError != null) onErrorListeners.add(onError);
+    _execMutation(variables).then((_) {
+      onDataListeners.remove(onData);
+      onErrorListeners.remove(onError);
+    });
+  }
+
+  Future<T?> mutateAsync(V variables) async {
+    return await _execMutation(variables).then((_) => data);
+  }
+
+  reset() {
+    data = null;
+    retryAttempts = 0;
+    updatedAt = DateTime.now();
+    onDataListeners.clear();
+    onErrorListeners.clear();
+    status = MutationStatus.pending;
+    onMutateListeners.clear();
+  }
+
+  A? cast<A>() => this is A ? this as A : null;
+}

packages/fl_query/lib/mutation_builder.dart

@@ -0,0 +1,73 @@
+import 'package:fl_query/models/mutation_job.dart';
+import 'package:fl_query/mutation.dart';
+import 'package:fl_query/query_bowl.dart';
+import 'package:flutter/widgets.dart';
+
+class MutationBuilder<T extends Object, V> extends StatefulWidget {
+  final Function(BuildContext, Mutation<T, V>) builder;
+  final MutationJob<T, V> job;
+
+  /// Called when the query returns new data, on query
+  /// refetch or query gets expired
+  final MutationListener<T>? onData;
+
+  /// Called when the query returns error
+  final MutationListener<dynamic>? onError;
+
+  /// called right before the mutation is about to run
+  ///
+  /// perfect scenario for doing optimistic updates
+  final MutationListener<V>? onMutate;
+
+  const MutationBuilder({
+    required this.job,
+    required this.builder,
+    this.onData,
+    this.onError,
+    this.onMutate,
+    Key? key,
+  }) : super(key: key);
+
+  @override
+  State<MutationBuilder<T, V>> createState() => _MutationBuilderState<T, V>();
+}
+
+class _MutationBuilderState<T extends Object, V>
+    extends State<MutationBuilder<T, V>> {
+  late QueryBowl queryBowl;
+
+  @override
+  void initState() {
+    super.initState();
+    WidgetsBinding.instance.addPostFrameCallback((_) {
+      queryBowl = QueryBowl.of(context);
+      queryBowl.addMutation<T, V>(
+        widget.job,
+        onData: widget.onData,
+        onError: widget.onError,
+        onMutate: widget.onMutate,
+        mount: widget,
+      );
+    });
+  }
+
+  @override
+  void dispose() {
+    final mutation = queryBowl.getMutation(widget.job.mutationKey);
+    mutation?.unmount(widget);
+    if (widget.onData != null) mutation?.onDataListeners.remove(widget.onData);
+    if (widget.onError != null)
+      mutation?.onErrorListeners.remove(widget.onError);
+    if (widget.onMutate != null)
+      mutation?.onMutateListeners.remove(widget.onMutate);
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    queryBowl = QueryBowl.of(context);
+    final mutation = queryBowl.getMutation<T, V>(widget.job.mutationKey);
+    if (mutation == null) return Container();
+    return widget.builder(context, mutation);
+  }
+}

packages/fl_query/lib/query.dart

@@ -46,8 +46,11 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
   @protected
   bool fetched = false;
 
-  final QueryListener<T>? _onData;
-  final QueryListener<dynamic>? _onError;
+  @protected
+  final Set<QueryListener<T>> onDataListeners = Set<QueryListener<T>>();
+  @protected
+  final Set<QueryListener<dynamic>> onErrorListeners =
+      Set<QueryListener<dynamic>>();
 
   // externalData will always be passed to the task Callback
   // it will change based on the presence of QueryBuilder
@@ -78,9 +81,10 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
         _initialData = initialData,
         _externalData = externalData,
         data = initialData,
-        _onData = onData,
-        _onError = onError,
-        updatedAt = DateTime.now();
+        updatedAt = DateTime.now() {
+    if (onData != null) onDataListeners.add(onData);
+    if (onError != null) onErrorListeners.add(onError);
+  }
 
   Query.fromOptions(
     QueryJob<T, Outside> options, {
@@ -96,11 +100,12 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
         _cacheTime = options.cacheTime ?? const Duration(minutes: 5),
         _initialData = options.initialData,
         _externalData = externalData,
-        _onData = onData,
-        _onError = onError,
         data = options.initialData,
         status = QueryStatus.pending,
-        updatedAt = DateTime.now();
+        updatedAt = DateTime.now() {
+    if (onData != null) onDataListeners.add(onData);
+    if (onError != null) onErrorListeners.add(onError);
+  }
 
   // all getters & setters
   bool get hasData => data != null && error == null;
@@ -144,13 +149,17 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
       _prevUsedExternalData = _externalData;
       updatedAt = DateTime.now();
       status = QueryStatus.succeed;
-      _onData?.call(data!);
+      for (final onData in onDataListeners) {
+        onData(data!);
+      }
       notifyListeners();
     } catch (e) {
       if (retries == 0) {
         status = QueryStatus.failed;
         error = e;
-        _onError?.call(e);
+        for (final onError in onErrorListeners) {
+          onError(error);
+        }
         notifyListeners();
       } else {
         // retrying for retry count if failed for the first time
@@ -160,14 +169,18 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
             data = await task(queryKey, _externalData);
             _prevUsedExternalData = _externalData;
             status = QueryStatus.succeed;
-            _onData?.call(data!);
+            for (final onData in onDataListeners) {
+              onData(data!);
+            }
             notifyListeners();
             break;
           } catch (e) {
             if (retryAttempts == retries) {
               status = QueryStatus.failed;
               error = e;
-              _onError?.call(e);
+              for (final onError in onErrorListeners) {
+                onError(error);
+              }
               notifyListeners();
             }
             retryAttempts++;
@@ -234,6 +247,9 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
     fetched = false;
     status = QueryStatus.pending;
     retryAttempts = 0;
+    onDataListeners.clear();
+    onErrorListeners.clear();
+    _mounts.clear();
   }
 
   bool get isStale {

packages/fl_query/lib/query_bowl.dart

@@ -1,6 +1,8 @@
 import 'dart:async';
 
+import 'package:fl_query/models/mutation_job.dart';
 import 'package:fl_query/models/query_job.dart';
+import 'package:fl_query/mutation.dart';
 import 'package:fl_query/query.dart';
 import 'package:collection/collection.dart';
 import 'package:flutter/widgets.dart';
@@ -27,6 +29,7 @@ class QueryBowlScope extends StatefulWidget {
 
 class _QueryBowlScopeState extends State<QueryBowlScope> {
   late Set<Query> queries;
+  late Set<Mutation> mutations;
 
   late Timer refreshIntervalTimer;
 
@@ -34,6 +37,7 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
   void initState() {
     super.initState();
     queries = {};
+    mutations = {};
     refreshIntervalTimer = Timer.periodic(
       widget.refreshInterval,
       _checkAndUpdateStaleQueriesOnBg,
@@ -43,7 +47,7 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
   @override
   void dispose() {
     refreshIntervalTimer.cancel();
-    _disposeListeners();
+    _disposeUpdateListeners();
     super.dispose();
   }
 
@@ -55,16 +59,22 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
     }
   }
 
-  void _listenToQueryUpdate() {
+  void _listenToUpdates() {
     for (final query in queries) {
       query.addListener(() => updateQueries(query));
     }
+    for (final mutation in mutations) {
+      mutation.addListener(() => updateMutations(mutation));
+    }
   }
 
-  void _disposeListeners() {
+  void _disposeUpdateListeners() {
     for (final query in queries) {
       query.removeListener(() => updateQueries(query));
     }
+    for (final mutation in mutations) {
+      mutation.removeListener(() => updateMutations(mutation));
+    }
   }
 
   void updateQueries(Query query) {
@@ -79,19 +89,41 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
     });
   }
 
+  void updateMutations(Mutation mutation) {
+    setState(() {
+      // checking & not including inactive mutations
+      // basically garbage collecting mutations
+      mutations = Set.from(
+        mutation.isInactive
+            ? mutations.where(
+                (el) => el.mutationKey != mutation.mutationKey,
+              )
+            : mutations,
+      );
+    });
+  }
+
   void addQuery<T extends Object, Outside>(Query<T, Outside> query) {
     setState(() {
       queries = Set.from({...queries, query});
     });
   }
 
+  void addMutation<T extends Object, V>(Mutation<T, V> mutation) {
+    setState(() {
+      mutations = Set.from({...mutations, mutation});
+    });
+  }
+
   @override
   Widget build(BuildContext context) {
-    _disposeListeners();
-    _listenToQueryUpdate();
+    _disposeUpdateListeners();
+    _listenToUpdates();
     return QueryBowl(
       addQuery: addQuery,
+      addMutation: addMutation,
       queries: queries,
+      mutations: mutations,
       staleTime: widget.staleTime,
       child: widget.child,
     );
@@ -102,21 +134,30 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
 /// Its responsible for creating/updating/delete queries
 class QueryBowl extends InheritedWidget {
   final Set<Query> _queries;
+  final Set<Mutation> _mutations;
   final Duration staleTime;
 
   final void Function<T extends Object, Outside>(Query<T, Outside> query)
       _addQuery;
 
+  final void Function<T extends Object, V>(Mutation<T, V> mutation)
+      _addMutation;
+
   const QueryBowl({
     required Widget child,
     required final void Function<T extends Object, Outside>(
             Query<T, Outside> query)
         addQuery,
+    required final void Function<T extends Object, V>(Mutation<T, V> mutation)
+        addMutation,
     required final Set<Query> queries,
+    required final Set<Mutation> mutations,
     required this.staleTime,
     Key? key,
   })  : _addQuery = addQuery,
         _queries = queries,
+        _mutations = mutations,
+        _addMutation = addMutation,
         super(child: child, key: key);
 
   Future<T?> fetchQuery<T extends Object, Outside>(
@@ -134,6 +175,8 @@ class QueryBowl extends InheritedWidget {
       final hasExternalDataChanged =
           prevQuery.prevUsedExternalData != externalData;
       if (mount != null) prevQuery.mount(mount);
+      if (onData != null) prevQuery.onDataListeners.add(onData);
+      if (onError != null) prevQuery.onErrorListeners.add(onError);
       if (!prevQuery.hasData || hasExternalDataChanged) {
         if (hasExternalDataChanged) prevQuery.setExternalData(externalData);
         return prevQuery.fetched
@@ -154,12 +197,44 @@ class QueryBowl extends InheritedWidget {
     return await query.fetch();
   }
 
+  void addMutation<T extends Object, V>(
+    MutationJob<T, V> options, {
+    final MutationListener<T>? onData,
+    final MutationListener<dynamic>? onError,
+    final MutationListener<V>? onMutate,
+    Widget? mount,
+  }) {
+    final prevMutation = _mutations.firstWhereOrNull(
+        (mutation) => mutation.mutationKey == options.mutationKey);
+    if (prevMutation != null && prevMutation is Mutation<T, V>) {
+      if (onData != null) prevMutation.onDataListeners.add(onData);
+      if (onError != null) prevMutation.onErrorListeners.add(onError);
+      if (onMutate != null) prevMutation.onMutateListeners.add(onMutate);
+      if (mount != null) prevMutation.mount(mount);
+    } else {
+      final mutation = Mutation.fromOptions(
+        options,
+        onData: onData,
+        onError: onError,
+        onMutate: onMutate,
+      );
+      if (mount != null) mutation.mount(mount);
+      _addMutation(mutation);
+    }
+  }
+
   Query<T, Outside>? getQuery<T extends Object, Outside>(String queryKey) {
     return _queries.firstWhereOrNull((query) {
       return query.queryKey == queryKey && query is Query<T, Outside>;
     })?.cast<Query<T, Outside>>();
   }
 
+  Mutation<T, V>? getMutation<T extends Object, V>(String mutationKey) {
+    return _mutations.firstWhereOrNull((mutation) {
+      return mutation.mutationKey == mutationKey && mutation is Mutation<T, V>;
+    })?.cast<Mutation<T, V>>();
+  }
+
   int get isFetching {
     return _queries.fold<int>(
       0,
@@ -170,6 +245,16 @@ class QueryBowl extends InheritedWidget {
     );
   }
 
+  int get isMutating {
+    return _mutations.fold<int>(
+      0,
+      (acc, mutation) {
+        if (mutation.isLoading) acc++;
+        return acc;
+      },
+    );
+  }
+
   void resetQuery(String queryKey) {
     _queries
         .firstWhereOrNull((element) => element.queryKey == queryKey)
@@ -181,6 +266,8 @@ class QueryBowl extends InheritedWidget {
 
   @override
   bool updateShouldNotify(QueryBowl oldWidget) {
-    return oldWidget.staleTime != staleTime || oldWidget._queries != _queries;
+    return oldWidget.staleTime != staleTime ||
+        oldWidget._queries != _queries ||
+        oldWidget._mutations != _mutations;
   }
 }

packages/fl_query/lib/query_builder.dart

@@ -68,7 +68,10 @@ class _QueryBuilderState<T extends Object, Outside>
 
   @override
   void dispose() {
-    queryBowl.getQuery(widget.job.queryKey)?.unmount(widget);
+    final query = queryBowl.getQuery(widget.job.queryKey);
+    query?.unmount(widget);
+    if (widget.onData != null) query?.onDataListeners.remove(widget.onData);
+    if (widget.onError != null) query?.onErrorListeners.remove(widget.onError);
     super.dispose();
   }