Docs added for Query QueryJob & QueryBowlScope

Configured favicon

Author: KRTirtho

docs/docs/basics/DynamicMutations.md

@@ -0,0 +1,4 @@
+---
+title: Dynamic Mutations
+sidebar_position: 9
+---

docs/docs/basics/DynamicQueries.md

@@ -0,0 +1,4 @@
+---
+title: Dynamic Queries
+sidebar_position: 8
+---

docs/docs/basics/LazyQuery.md

@@ -0,0 +1,4 @@
+---
+title: Lazy Query
+sidebar_position: 7
+---

docs/docs/basics/MutationJob.md

@@ -0,0 +1,4 @@
+---
+title: Mutation Job
+sidebar_position: 5
+---

docs/docs/basics/Mutations.md

@@ -0,0 +1,4 @@
+---
+title: Mutations
+sidebar_position: 6
+---

docs/docs/basics/Queries.md

@@ -0,0 +1,120 @@
+---
+title: Queries
+sidebar_position: 3
+---
+
+### QueryBuilder
+
+The defined logic in [QueryJob](/docs/basics/QueryJob) is bind to the Flutter UI using the `QueryBuilder` Widget. It's basically a `Builder` that takes a `QueryJob` through the `job` named parameter & creates/retrieves the appropriate `Query` and passes it down to the `builder` method
+
+```dart
+class Example extends StatelessWidget {
+  const Example({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return QueryBuilder<String, void>(
+      job: job,
+      externalData: null,
+      builder: (context, query) {
+        if (!query.hasData) {
+          return const CircularProgressIndicator();
+        }
+        return Text(query.data!);
+      },
+    );
+  }
+}
+```
+
+> Here `job` is the same `QueryJob` defined at the first snippet in the [Query Job](/docs/basics/QueryJob) tutorial
+
+The `externalData` parameter of the `QueryBuilder` is passed to the `task` function of the `QueryJob`. It was discussed previously in [Query Job#External Data](/docs/basics/QueryJob#external-data) section
+
+### Query
+The passed query from the `builder` callback is the appropriate `Query` created based on the logic & configuration defined in the passed `QueryJob`
+
+The `query` parameter aka `Query` contains all the useful getters, properties & methods for rendering data from the query. It contains the state of the current query, the data, the error, the loading status etc along with useful methods such as `refetch` and `setQueryData`
+
+But more importantly, it contains the status of the current `Query`. It has to types of status one is Query Progression status & another is data availability status
+
+You can access them as follows:
+- Progressive status of Query
+  - `isSuccess`: When the task function returned data successfully
+  - `isError`: When the task function returned an error
+  - `isLoading`: When the task function is running
+  - `isRefetching`: When new data is being fetched or simply the `refetch` method is executing
+  - `isIdle`: When there's no data & `Query`'s task has not been yet run
+- Data availability status of Query
+  - `hasData`: When query contains data (expired or not)
+  - `hasError`: When the query contains error
+
+
+Now the most important part of query: Data and Error. You can access the data returned from the task using `query.data` or the error `query.error`. Both the data can be null. So always check if the data/error is null before accessing it
+
+:::info
+Don't use only `query.isLoading` to check if the data is available or not as the query can be failed & at this time `data` which can cause UI Exceptions. So use `query.hasData` always to check if `data` is available yet or not or use both together
+:::
+
+Another important part of this is `refetch`. Well, you can use it to manually trigger refetch or want the query to get newest data
+
+Finally, you can use `setQueryData` to manually set the data of the query. This is useful when you want to refresh the query but the newest data is already available in the application. It can be used to reduce network traffic by saving network calls to the server. Or you can use it with `Mutations` to optimistically set data before the Mutation is executed & then update the query with actual data
+
+:::tip
+You can learn more about Optimistic Updates in the [Mutation Tutorial](/docs/basics/mutations)
+:::
+
+Here's an real-world example of `Query` & `QueryBuilder`
+
+
+```dart
+final anotherJob = QueryJob<String, Client>(
+  queryKey: "another-unique-key",
+  task: (queryKey, httpClient){
+    return httpClient
+    .get("https://jsonplaceholder.typicode.com/todos/1")
+    .then((response) => response.body);;
+  }
+);
+
+class Example extends StatelessWidget {
+  const Example({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    // getting the instance of Client provided by the [provider] package
+    final client = Provider.of<Client>(context);
+    
+    return QueryBuilder<String, void>(
+      job: job,
+      // passing the client as externalData
+      externalData: client,
+      builder: (context, query) {
+        // checking if data availability along with progressive status
+        if (!query.hasData || query.isLoading) {
+          return const CircularProgressIndicator();
+        }
+        // remember to always show a fallback widget/screen for errors too. 
+        // It keeps the user aware of status of the application their using
+        // & saves their time
+        else if(query.hasError && query.isError){
+          return Text(
+            "My disappointment is immeasurable & my day is ruined for this stupid error: $error",
+          );
+        }
+        return Row(
+          children: [
+            Text(query.data["title"]),
+            ElevatedButton(
+              child: const Text("Refetch"),
+              onPressed: () async {
+                await query.refetch();
+              },
+            ),
+          ],
+        );
+      },
+    );
+  }
+}
+```

docs/docs/basics/QueryBowlScope.md

@@ -0,0 +1,48 @@
+---
+title: QueryBowl Scope
+sidebar_position: 1
+---
+
+The first thing needed for storing any form of data is a store. QueryBowlScope is basically a `StatefulWidget` which wraps around the actual store `QueryBowl`. It is similar to `ProviderScope` in riverpod & `MultiProvider` provider. But it can be used only once at the very top level of the application
+
+You must use wrap your `MaterialApp`  or `CupertinoApp` or `FluentApp` or `MacosApp` with `QueryBowlScope`
+
+```dart
+class MyApp extends StatelessWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return QueryBowlScope(
+      child: MaterialApp(
+        title: 'Fl-Query Example',
+        home: const MyHomePage(),
+      ),
+    );
+  }
+}
+
+```
+
+`QueryBowlScope` has many properties that can be configured. You can configure refetch behaviors, thresholds, delays etc along with cache time
+
+Here I'm increasing the staleTime to 10 seconds. This means that if the data is outdated after 10 seconds & will be refetched in the background smartly when needed. The default value is 1 seconds
+
+```dart
+class MyApp extends StatelessWidget {
+  const MyApp({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return QueryBowlScope(
+      staleTime: Duration(seconds: 10),
+      child: MaterialApp(
+        title: 'Fl-Query Example',
+        home: const MyHomePage(),
+      ),
+    );
+  }
+}
+```
+
+For more information on how to use QueryBowlScope, please refer to the [QueryBowlScope](https://pub.dev/documentation/fl_query/latest/fl_query/QueryBowlScope-class.html) API Reference

docs/docs/basics/QueryJob.md

@@ -0,0 +1,87 @@
+---
+title: Query Job
+sidebar_position: 2 
+---
+
+Query Jobs are what you use to define the logic how or from where the data is fetched/queried. It is where the `task` function is defined. `QueryJob` is reusable throughout application
+
+Here's a simple example
+
+```dart
+final job = QueryJob<String, void>(
+  queryKey: "a-unique-key",
+  task: (queryKey, externalData){
+    return Future.delayed(Duration(seconds: 1), () => "Hello World");
+  }
+);
+```
+
+The `queryKey` must be unique. It is used to identify the job
+
+The `task` callback has to be asynchronous. When the `task` is run by `Query` the `queryKey` & the `externalData` passed from `QueryBuilder` is passed to it as parameters. The externalData can be anything. You can provide a Generic Type parameter for it too
+
+:::info
+If `externalData` is of an `Iterable` type (`Map`, `List`, `Set` etc), it will be compared [shallowly](https://medium.com/nerdjacking/shallow-deep-comparison-9fd74ac0f3d2)
+:::
+
+### External Data
+
+A more real-world example of `QueryJob` with `externalData`
+
+```dart
+import 'package:fl_query/fl_query.dart';
+import 'package:http/http.dart';
+
+final anotherJob = QueryJob<String, Client>(
+  queryKey: "another-unique-key",
+  task: (queryKey, httpClient){
+    return httpClient.get("https://jsonplaceholder.typicode.com/todos/1").then((response) => response.body);;
+  }
+);
+```
+
+Here `externalData` is a configured `Client` from the `http` package.
+
+By default when `externalData` changes or updates the query is not refetched but if you want it to refetch when the `externalData` changes, you can set `refetchOnExternalDataChange` property of `QueryJob` to `true`. If you want this behavior globally to be enabled then you can set `refetchOnExternalDataChange` property of [QueryBowlScope](/docs/basics/QueryBowlScope) to `true`
+
+
+```dart
+import 'package:fl_query/fl_query.dart';
+import 'package:http/http.dart';
+
+final anotherJob = QueryJob<String, Client>(
+  queryKey: "another-unique-key",
+  refetchOnExternalDataChange: true,
+  task: (queryKey, httpClient){
+    return httpClient.get("https://jsonplaceholder.typicode.com/todos/1").then((response) => response.body);;
+  }
+);
+```
+
+Now every time when the externalData changes the query will refetched.
+
+### Retries
+
+When a query returns an `Exception` or in other word, fails, the query is re-run multiple times in the background until it succeeds or the retry limit is reached. You can configure the retry behavior of query by modifying `retries` & `retryDelay` properties of `QueryJob`
+
+- `retries`: is amount of times the query will be retried before setting the status as `QueryStatus.error`. If its zero, it will not retry.
+
+- `retryDelay`: is the `Duration` between retries. That means after what amount of duration the retries will take place until it succeeds or the retry limit is reached.
+
+By default `retries` is `3` and `retryDelay` is `Duration(milliseconds: 200)`
+
+
+```dart
+final job = QueryJob<String, Client>(
+  queryKey: "exceptional-query",
+  retries: 10,
+  retryDelay: Duration(milliseconds: 200),
+  task: (queryKey, _) async {
+    throw Exception("I'm an evil Exception");
+  }
+);
+```
+
+Now the query will be retried 10 times with a delay of 200ms between each retry
+
+There are more properties of `QueryJob` that you can configure. See the API reference of [QueryJob](https://pub.dev/documentation/fl_query/latest/fl_query/QueryJob-class.html)