Simple documentation added

Useful utility methods added in query_bowl

README.md

@@ -1,3 +1,123 @@
 # FL-Query
 
-Asynchronous data caching, refetching & invalidation library for Flutter. FL-Query lets you manage & distribute your data async data without touching any global state
+Asynchronous data caching, refetching & invalidation library for Flutter. FL-Query lets you manage & distribute your data async data without touching any global state
+
+# Examples
+All examples of fl-query can be found in the [packages/example/lib](https://github.com/KRTirtho/fl-query/tree/main/packages/example/lib) directory
+
+Here's a basic example:
+```dart
+void main() {
+  runApp(const MyApp());
+}
+
+class MyApp extends StatelessWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return QueryBowlScope(
+      child: MaterialApp(
+        title: 'FL-Query Demo',
+        theme: ThemeData(
+          useMaterial3: true,
+          primarySwatch: Colors.blue,
+        ),
+        home: const MyHomePage(),
+      ),
+    );
+  }
+}
+
+
+// defining jobs that'll return results
+
+// this query resolve successfully with expected Data
+final successJob = QueryJob<String, void>(
+  queryKey: "success",
+  task: (queryKey, externalData) => Future.delayed(const Duration(seconds: 2),
+      () => "Welcome ($queryKey) ${Random.secure().nextInt(100)}"),
+);
+
+// this query can fail or can be successful
+final failedJob = QueryJob<String, void>(
+  queryKey: "failure",
+  task: (queryKey, externalData) => Random().nextBool()
+      ? Future.error("[$queryKey] Failed for unknown reason")
+      : Future.value(
+          "Success, you'll get slowly ${Random().nextInt(100)}!",
+        ),
+);
+
+class MyHomePage extends StatefulWidget {
+  const MyHomePage({Key? key}) : super(key: key);
+
+  @override
+  State<MyHomePage> createState() => _MyHomePageState();
+}
+
+class _MyHomePageState extends State<MyHomePage> {
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(
+        title: const Text("Fl Query Example"),
+      ),
+      body: Column(
+        children: [
+          Row(
+            children: [
+              QueryBuilder<String, void>(
+                job: successJob,
+                // if you want to pass any external data or variable to the
+                // query/task function or just pass null
+                externalData: null,
+                builder: (context, query) {
+                  // returning based on the status of the query
+                  if (query.isLoading || query.isRefetching) {
+                    return const CircularProgressIndicator();
+                  }
+                  return TextButton(
+                    child: Text(query.data!),
+                    onPressed: () async {
+                      // refetching data forcibly
+                      await query.refetch();
+                    },
+                  );
+                },
+              ),
+              QueryBuilder<String, void>(
+                job: failedJob,
+                externalData: null,
+                builder: (context, query) {
+                  return Row(
+                    children: [
+                      if (query.hasError)
+                        Text(
+                          "${query.error}. Retrying: ${query.retryAttempts}",
+                        ),
+                      if (query.hasData)
+                        Text(
+                            "Success after ${query.retryAttempts}. Data: ${query.data}"),
+                      ElevatedButton(
+                        child: Text("Refetch ${query.queryKey}"),
+                        onPressed: () => query.refetch(),
+                      )
+                    ],
+                  );
+                },
+              ),
+            ],
+          ),
+        ],
+      ),
+    );
+  }
+}
+
+```
+
+# TODO
+
+- Invalidate Queries when Window Focus Lost
+- Invalidate Queries when Connection Lose based configure network behavior

packages/fl_query/lib/query.dart

@@ -16,6 +16,8 @@ typedef QueryListener<T> = FutureOr<void> Function(T);
 
 typedef ListenerUnsubscriber = void Function();
 
+typedef QueryUpdateFunction<T> = FutureOr<T> Function(T? oldData);
+
 class Query<T extends Object, Outside> extends ChangeNotifier {
   // all params
   final String queryKey;
@@ -224,7 +226,7 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
   ///
   /// Every time a new instance of data should be returned because of
   /// immutability
-  setQueryData(FutureOr<T> Function(T? data) updateFn) async {
+  void setQueryData(QueryUpdateFunction<T> updateFn) async {
     final newData = await updateFn(data);
     if (data == newData) {
       // TODO: Better Error handling & Error structure

packages/fl_query/lib/query_bowl.dart

@@ -1,6 +1,5 @@
 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';
@@ -115,6 +114,27 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
     });
   }
 
+  int removeQueries(List<String> queryKeys) {
+    int count = 0;
+    setState(() {
+      mutations = Set.from(
+        queries.whereNot((query) {
+          final isAboutToRip = queryKeys.contains(query.queryKey);
+          if (isAboutToRip) count++;
+          return isAboutToRip;
+        }),
+      );
+    });
+    return count;
+  }
+
+  void clear() {
+    setState(() {
+      queries = Set<Query>();
+      mutations = Set<Mutation>();
+    });
+  }
+
   @override
   Widget build(BuildContext context) {
     _disposeUpdateListeners();
@@ -122,6 +142,8 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
     return QueryBowl(
       addQuery: addQuery,
       addMutation: addMutation,
+      removeQueries: removeQueries,
+      clear: clear,
       queries: queries,
       mutations: mutations,
       staleTime: widget.staleTime,
@@ -143,6 +165,10 @@ class QueryBowl extends InheritedWidget {
   final void Function<T extends Object, V>(Mutation<T, V> mutation)
       _addMutation;
 
+  final int Function(List<String>) removeQueries;
+
+  final void Function() clear;
+
   const QueryBowl({
     required Widget child,
     required final void Function<T extends Object, Outside>(
@@ -153,6 +179,8 @@ class QueryBowl extends InheritedWidget {
     required final Set<Query> queries,
     required final Set<Mutation> mutations,
     required this.staleTime,
+    required this.removeQueries,
+    required this.clear,
     Key? key,
   })  : _addQuery = addQuery,
         _queries = queries,
@@ -160,6 +188,7 @@ class QueryBowl extends InheritedWidget {
         _addMutation = addMutation,
         super(child: child, key: key);
 
+  @protected
   Future<T?> fetchQuery<T extends Object, Outside>(
     QueryJob<T, Outside> options, {
     required Outside externalData,
@@ -197,6 +226,7 @@ class QueryBowl extends InheritedWidget {
     return await query.fetch();
   }
 
+  @protected
   Query<T, Outside> addQuery<T extends Object, Outside>(
     Query<T, Outside> query, {
     required ValueKey<String> key,
@@ -223,6 +253,7 @@ class QueryBowl extends InheritedWidget {
     return query;
   }
 
+  @protected
   Mutation<T, V> addMutation<T extends Object, V>(
     Mutation<T, V> mutation, {
     final MutationListener<T>? onData,
@@ -277,10 +308,30 @@ class QueryBowl extends InheritedWidget {
     );
   }
 
-  void resetQuery(String queryKey) {
+  void setQueryData<T extends Object, Outside>(
-    _queries
+      String queryKey, QueryUpdateFunction<T> updateCb) {
-        .firstWhereOrNull((element) => element.queryKey == queryKey)
+    getQuery<T, Outside>(queryKey)?.setQueryData(updateCb);
-        ?.reset();
+  }
+
+  void resetQueries(List<String> queryKeys) {
+    for (final query in _queries) {
+      if (!queryKeys.contains(query.queryKey)) continue;
+      query.reset();
+    }
+  }
+
+  void invalidateQueries(List<String> queryKeys) {
+    for (final query in _queries) {
+      if (!queryKeys.contains(query.queryKey)) continue;
+      // TODO: Implement Invaldiate Queries
+    }
+  }
+
+  Future<void> refetchQueries(List<String> queryKeys) async {
+    for (final query in _queries) {
+      if (!queryKeys.contains(query.queryKey)) continue;
+      await query.refetch();
+    }
   }
 
   static QueryBowl of(BuildContext context) =>