Merge branch 'main' into docs

docs/docs/basics/DynamicMutations.md

@@ -1,4 +1,27 @@
 ---
 title: Dynamic Mutations
 sidebar_position: 9
----
+---
+
+Just like [Dynamic Queries](/docs/basics/DynamicQueries), `MutationJob.withVariableKey` makes the mutation dynamic. Both of them are completely same
+
+```dart
+final mutationVariableKeyJob = MutationJob.withVariableKey<String, double>(
+  preMutationKey: "mutation-example",
+  task: (mutationKey, variables) {
+    return MyAPI.submit({...variables, id: getVariable(mutationKey)});
+  },
+);
+```
+
+In the case of Mutation, we've `preMutationKey` instead of `preQueryKey`
+
+You can use the dynamic Mutation Job just like any other `MutationJob` except you've to invoke the defined dynamic mutation & pass the `variable-mutation-key` as the first argument.
+
+
+```dart
+MutationBuilder<String, double>(
+  job: mutationVariableKeyJob(id),
+  builder: (context, mutation) {...},
+)
+```

docs/docs/basics/DynamicQueries.md

@@ -1,4 +1,66 @@
 ---
 title: Dynamic Queries
 sidebar_position: 8
----
+---
+
+All this time we've using queries by defining a Query Key in the `QueryJob`. But what if your widget needs to fetch data from of a dynamic id that is only known at runtime? This is where `QueryJob.withVariableKey` comes to play. It allows you to define query-key at runtime. It makes a query dynamic
+
+```dart
+final queryVariableKeyJob =
+    QueryJob.withVariableKey<String, void>(
+      prevQueryKey: "variable-query",
+      task: (queryKey, externalData) {
+      return Future.delayed(
+          const Duration(milliseconds: 500),
+          () => "QueryKey:${getVariable(queryKey)}",
+        );
+      },
+);
+```
+
+Optionally, we can provide a `prevQueryKey` to make the QueryJob distinguishable from other dynamic Queries or just to keep them in a group. If you use `prevQueryKey`, you can use `getVariable` to extract the value of the variable from the `queryKey`.
+
+:::warning
+Don't use `externalData` to make a query dynamic. Using `externalData` & `refetchOnExternalDataChange: true`, you may be able to achieve similar result but it'll replace the previously fetched data with the new data instead of creating a separate `Query` instance for the new variable-query-key & it's data
+:::
+
+Now, let's use the Job with a QueryBuilder inside an actual widget:
+
+```dart
+class ExampleState extends State<Example>{
+  late double id;
+  @override
+  void initState() {
+    super.initState();
+    id = Random().nextDouble() * 200;
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return QueryBuilder<String, void>(
+      job: queryVariableKeyJob(id.toString()),
+      externalData: null,
+      builder: (context, query) {
+        if (!query.hasData) {
+          return const CircularProgressIndicator();
+        }
+        return Row(
+          children: [
+            Text("Query Result: ${query.data}"),
+            ElevatedButton(
+              child: const Text("New Id"),
+              onPressed: () {
+                setState(() {
+                  id = Random().nextDouble() * 200;
+                });
+              },
+            ),
+          ],
+        );
+      },
+    );
+  }
+}
+```
+
+Here, everything is same except to pass the `variable-query-key` to the dynamic `Query` you'll have to invoke the defined job (in this case it's `queryVariableKeyJob`) & pass the `variable-query-key` as an argument.

packages/fl_query/example/lib/components/query_variable_key.dart

@@ -3,13 +3,15 @@ import 'dart:math';
 import 'package:fl_query/fl_query.dart';
 import 'package:flutter/material.dart';
 
-final queryVariableKeyJob =
-    QueryJob.withVariableKey<String, void>(task: (queryKey, externalData) {
-  return Future.delayed(
-    const Duration(milliseconds: 500),
-    () => "QueryKey:${queryKey.split("#").last}",
-  );
-});
+final queryVariableKeyJob = QueryJob.withVariableKey<String, void>(
+  preQueryKey: "variable-query",
+  task: (queryKey, externalData) {
+    return Future.delayed(
+      const Duration(milliseconds: 500),
+      () => "QueryKey:${queryKey.split("#").last}",
+    );
+  },
+);
 
 class QueryVariableKeyExample extends StatefulWidget {
   const QueryVariableKeyExample({Key? key}) : super(key: key);
@@ -37,7 +39,7 @@ class _QueryVariableKeyExampleState extends State<QueryVariableKeyExample> {
           style: Theme.of(context).textTheme.headline5,
         ),
         QueryBuilder<String, void>(
-          job: queryVariableKeyJob("variable-query#$id"),
+          job: queryVariableKeyJob(id.toString()),
           externalData: null,
           builder: (context, query) {
             if (query.isLoading || query.isRefetching || !query.hasData) {