added lazy query support

fixed possible race condition of simultanous refetches of the same query

packages/example/lib/lazy_query.dart

@@ -0,0 +1,36 @@
+import 'package:fl_query/fl_query.dart';
+import 'package:flutter/material.dart';
+
+final lazyQueryJob = QueryJob<String, String>(
+    queryKey: "non_enabled_query",
+    enabled: false,
+    task: (queryKey, data) {
+      return Future.delayed(const Duration(milliseconds: 500),
+          () => "Hello from $queryKey with $data");
+    });
+
+class LazyQuery extends StatelessWidget {
+  const LazyQuery({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(),
+      body: QueryBuilder<String, String>(
+        job: lazyQueryJob,
+        externalData: "Love",
+        builder: (context, query) {
+          return Column(
+            children: [
+              Text("Query Data::: ${query.data ?? "Loading"}"),
+              ElevatedButton(
+                child: const Text("Fetch Query"),
+                onPressed: () => query.refetch(),
+              ),
+            ],
+          );
+        },
+      ),
+    );
+  }
+}

packages/example/lib/main.dart

@@ -1,6 +1,7 @@
 import 'dart:math';
 
 import 'package:example/another_component.dart';
+import 'package:example/lazy_query.dart';
 import 'package:example/query_with_external_data.dart';
 import 'package:fl_query/fl_query.dart';
 import 'package:flutter/material.dart';
@@ -35,7 +36,9 @@ final successJob = QueryJob<String, void>(
 
 final failedJob = QueryJob<String, void>(
   queryKey: "failure",
-  task: (queryKey, _) => Future.value("[$queryKey] Failed for unknown reason"),
+  task: (queryKey, _) => Random().nextBool()
+      ? Future.error("[$queryKey] Failed for unknown reason")
+      : Future.value("Success, you'll get slowly ${Random().nextInt(100)}!"),
 );
 
 class MyHomePage extends StatefulWidget {
@@ -90,8 +93,20 @@ class _MyHomePageState extends State<MyHomePage> {
                 job: failedJob,
                 externalData: null,
                 builder: (context, query) {
-                  if (query.hasError) return Text(query.error);
-                  return Text("Failure. You're a failure ${query.data}");
+                  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(),
+                      )
+                    ],
+                  );
                 },
               ),
             ],
@@ -106,6 +121,17 @@ class _MyHomePageState extends State<MyHomePage> {
               );
             },
           ),
+          const SizedBox(height: 10),
+          ElevatedButton(
+            child: const Text("Non Enabled Query Example"),
+            onPressed: () {
+              Navigator.of(context).push(
+                MaterialPageRoute(
+                  builder: (context) => const LazyQuery(),
+                ),
+              );
+            },
+          ),
           const AnotherComponent(),
         ],
       ),

packages/fl_query/lib/models/query_job.dart

@@ -8,6 +8,10 @@ class QueryJob<T extends Object, Outside> {
   final Duration? retryDelay;
   final T? initialData;
 
+  /// If set to false then the initial fetch will not be called & to
+  /// start the process the user has to call the refetch first
+  final bool? enabled;
+
   // got from global options
   final Duration? staleTime;
 
@@ -22,5 +26,6 @@ class QueryJob<T extends Object, Outside> {
     this.staleTime,
     this.onData,
     this.onError,
+    this.enabled,
   });
 }

packages/fl_query/lib/query.dart

@@ -20,6 +20,9 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
   // all params
   final String queryKey;
   QueryTaskFunction<T, Outside> task;
+
+  /// The number of times the query should refetch in the time of error
+  /// before giving up
   final int retries;
   final Duration retryDelay;
   final T? _initialData;
@@ -31,9 +34,13 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
   T? data;
   dynamic error;
   QueryStatus status;
+
+  /// total count of how many times the query retried to get a successful
+  /// result
   int retryAttempts = 0;
   DateTime updatedAt;
   int refetchCount = 0;
+  bool enabled;
 
   @protected
   bool fetched = false;
@@ -55,6 +62,7 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
     required this.retries,
     required this.retryDelay,
     T? initialData,
+    this.enabled = true,
     QueryListener<T>? onData,
     QueryListener<dynamic>? onError,
   })  : status = QueryStatus.pending,
@@ -69,6 +77,7 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
   Query.fromOptions(QueryJob<T, Outside> options,
       {required Outside externalData})
       : queryKey = options.queryKey,
+        enabled = options.enabled ?? true,
         task = options.task,
         retries = options.retries ?? 3,
         retryDelay = options.retryDelay ?? const Duration(milliseconds: 200),
@@ -90,6 +99,7 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
   bool get isRefetching =>
       status == QueryStatus.refetching && (data != null || error != null);
   bool get isSucceeded => status == QueryStatus.succeed && data != null;
+  bool get isIdle => isSucceeded && error == null;
   Outside get externalData => _externalData;
   Outside? get prevUsedExternalData => _prevUsedExternalData;
 
@@ -140,6 +150,7 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
   Future<T?> fetch() async {
     status = QueryStatus.pending;
     notifyListeners();
+    if (!enabled) return null;
     if (!isStale && hasData) {
       return data;
     }
@@ -149,11 +160,16 @@ class Query<T extends Object, Outside> extends ChangeNotifier {
     });
   }
 
-  Future<T?> refetch() {
+  Future<T?> refetch() async {
+    // cannot let run multiple refetch at the same time. It can cause
+    // race-condition
+    if (isRefetching) return null;
     status = QueryStatus.refetching;
     refetchCount++;
+    // disabling the lazy query bound when query was actually called
+    if (!enabled) enabled = false;
     notifyListeners();
-    return _execute().then((_) => data);
+    return await _execute().then((_) => data);
   }
 
   /// can be used to update the data manually. Can be useful when used