Merge branch 'main' into docs

.vscode/launch.json

@@ -5,21 +5,41 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "example fl_query",
-      "cwd": "packages/example",
+      "name": "fl_query",
+      "cwd": "packages/fl_query/example",
       "request": "launch",
       "type": "dart"
     },
     {
-      "name": "example fl_query (profile mode)",
-      "cwd": "packages/example",
+      "name": "fl_query (profile mode)",
+      "cwd": "packages/fl_query/example",
       "request": "launch",
       "type": "dart",
       "flutterMode": "profile"
     },
     {
-      "name": "example fl_query (release mode)",
-      "cwd": "packages/example",
+      "name": "fl_query (release mode)",
+      "cwd": "packages/fl_query/example",
+      "request": "launch",
+      "type": "dart",
+      "flutterMode": "release"
+    },
+    {
+      "name": "hooks fl_query",
+      "cwd": "packages/fl_query_hooks/example",
+      "request": "launch",
+      "type": "dart"
+    },
+    {
+      "name": "hooks fl_query (profile mode)",
+      "cwd": "packages/fl_query_hooks/example",
+      "request": "launch",
+      "type": "dart",
+      "flutterMode": "profile"
+    },
+    {
+      "name": "hooks fl_query (release mode)",
+      "cwd": "packages/fl_query_hooks/example",
       "request": "launch",
       "type": "dart",
       "flutterMode": "release"

docs/docs/basics/OptimisticUpdates.md

@@ -1,5 +1,5 @@
 ---
-title: Optimistic Updates (Still WIP)
+title: Optimistic Updates
 sidebar_position: 10
 ---
 
@@ -34,6 +34,7 @@ return MutationBuilder(
 return MutationBuilder(
   job: mutationJob,
   onMutate: (variable) {
+    final data = QueryBowl.of(context).getQuery(successJob.queryKey)?.data;
     QueryBowl.of(context)
         .setQueryData<Map<String, dynamic>, void>(successJob.queryKey, (oldData) {
       // replacing the soon to be expired data with updated data
@@ -44,6 +45,15 @@ return MutationBuilder(
     // of the intended query data which can be used when 
     // an error occurs in mutation & we can rollback to a previous
     // data set
+    return data;
+  },
+  onData: (data, variables, context) {
+    print("Passed Variable: $variables");
+    print("Safe Previous Value: $context");
+  },
+  onError: (data, variables, context) {
+    print("Passed Variable: $variables");
+    print("Safe Previous Value: $context");
   }
 );
 ```

docs/docs/basics/PaginatedQuery.md

@@ -0,0 +1,99 @@
+---
+title: Paginated/Lagged Query
+sidebar_position: 10
+---
+
+
+Rendering paginated data is a very common UI pattern and in Fl-Query, it "just works" by including the page information in the query key:
+
+```dart
+final queryVariableKeyJob = QueryJob.withVariableKey<String, void>(
+      task: (queryKey, externalData) {
+        return MyAPI.getData(id: getVariable(queryKey));
+      },
+);
+
+/// inside a widget build method
+QueryBuilder(
+  job: queryVariableKeyJob(id),
+  externalData: null,
+  builder: (context, query){...}
+)
+```
+
+However, if you run this simple example, you might notice something strange:
+
+**The UI jumps in and out of the `success` and `loading` states because each new page is treated like a brand new query.**
+
+This experience is not optimal and unfortunately is how many tools today insist on working. But not Fl-Query! As you may have guessed, Fl-Query comes with an awesome feature called `keepPreviousData` that allows us to get around this.
+
+## Better Paginated Queries with `keepPreviousData`
+
+Consider the following example where we would ideally want to increment a pageIndex (or cursor) for a query. If we were to use just `QueryJob.withVariableKey`, **it would still technically work fine**, but the UI would jump in and out of the `success` and `loading` states as different queries are created and destroyed for each page or cursor. By setting `keepPreviousData` to `true` we get a few new things:
+
+- **The data from the last successful fetch available while new data is being requested, even though the query key has changed**.
+- When the new data arrives, the previous `data` is seamlessly swapped to show the new data.
+- `isPreviousData` is made available to know what data the query is currently providing you
+
+```dart
+final todoJob = QueryJob.withVariableKey<Map, void>(
+  preQueryKey: "todo",
+  task: (queryKey, _) async {
+    final res = await http.get(
+      Uri.parse(
+          "https://jsonplaceholder.typicode.com/todos/${getVariable(queryKey)}"),
+    );
+    return jsonDecode(res.body);
+  },
+  keepPreviousData: true,
+);
+
+class QueryPreviousDataExample extends StatefulWidget {
+  const QueryPreviousDataExample({Key? key}) : super(key: key);
+
+  @override
+  State<QueryPreviousDataExample> createState() =>
+      _QueryPreviousDataExampleState();
+}
+
+class _QueryPreviousDataExampleState extends State<QueryPreviousDataExample> {
+  int id = 1;
+
+  @override
+  Widget build(BuildContext context) {
+    return Column(
+      crossAxisAlignment: CrossAxisAlignment.start,
+      children: [
+        QueryBuilder(
+            job: todoJob(id.toString()),
+            externalData: null,
+            builder: (context, query) {
+              if (query.hasError) return Text(query.error.toString());
+              if (!query.hasData) return const CircularProgressIndicator();
+              return Text(jsonEncode(query.data ?? {}));
+            }),
+        Row(
+          children: [
+            IconButton(
+              icon: const Icon(Icons.remove),
+              onPressed: () {
+                setState(() {
+                  id -= 1;
+                });
+              },
+            ),
+            IconButton(
+              icon: const Icon(Icons.add),
+              onPressed: () {
+                setState(() {
+                  id += 1;
+                });
+              },
+            ),
+          ],
+        )
+      ],
+    );
+  }
+}
+```

docs/docs/getting-started/installation.md

@@ -9,7 +9,7 @@ Fl-Query is just another Flutter "package" so no extra installation step needed
 $ flutter pub add fl_query
 ```
 
-### For using with `flutter_hooks`
+### Using with `flutter_hooks`
 
 If you're an ELITE `flutter_hooks` user or want to use `fl_query_hooks` you'll need the `flutter_hooks` & `fl_query_hooks` package
 

packages/fl_query/.flutter-plugins-dependencies

@@ -1 +1 @@
-{"info":"This is a generated file; do not edit or check into version control.","plugins":{"ios":[{"name":"connectivity_plus","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus-2.3.5/","native_build":true,"dependencies":[]}],"android":[{"name":"connectivity_plus","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus-2.3.5/","native_build":true,"dependencies":[]}],"macos":[{"name":"connectivity_plus_macos","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus_macos-1.2.4/","native_build":true,"dependencies":[]}],"linux":[{"name":"connectivity_plus_linux","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus_linux-1.3.1/","native_build":false,"dependencies":[]}],"windows":[{"name":"connectivity_plus_windows","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus_windows-1.2.2/","native_build":true,"dependencies":[]}],"web":[{"name":"connectivity_plus_web","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus_web-1.2.2/","dependencies":[]}]},"dependencyGraph":[{"name":"connectivity_plus","dependencies":["connectivity_plus_linux","connectivity_plus_macos","connectivity_plus_web","connectivity_plus_windows"]},{"name":"connectivity_plus_linux","dependencies":[]},{"name":"connectivity_plus_macos","dependencies":[]},{"name":"connectivity_plus_web","dependencies":[]},{"name":"connectivity_plus_windows","dependencies":[]}],"date_created":"2022-07-20 12:20:16.617434","version":"3.0.1"}
+{"info":"This is a generated file; do not edit or check into version control.","plugins":{"ios":[{"name":"connectivity_plus","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus-2.3.5/","native_build":true,"dependencies":[]}],"android":[{"name":"connectivity_plus","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus-2.3.5/","native_build":true,"dependencies":[]}],"macos":[{"name":"connectivity_plus_macos","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus_macos-1.2.4/","native_build":true,"dependencies":[]}],"linux":[{"name":"connectivity_plus_linux","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus_linux-1.3.1/","native_build":false,"dependencies":[]}],"windows":[{"name":"connectivity_plus_windows","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus_windows-1.2.2/","native_build":true,"dependencies":[]}],"web":[{"name":"connectivity_plus_web","path":"/home/krtirtho/.pub-cache/hosted/pub.dartlang.org/connectivity_plus_web-1.2.2/","dependencies":[]}]},"dependencyGraph":[{"name":"connectivity_plus","dependencies":["connectivity_plus_linux","connectivity_plus_macos","connectivity_plus_web","connectivity_plus_windows"]},{"name":"connectivity_plus_linux","dependencies":[]},{"name":"connectivity_plus_macos","dependencies":[]},{"name":"connectivity_plus_web","dependencies":[]},{"name":"connectivity_plus_windows","dependencies":[]}],"date_created":"2022-08-07 10:53:50.758755","version":"3.0.1"}

packages/example/.metadata → packages/fl_query/example/.metadata

@@ -15,9 +15,24 @@ migration:
     - platform: root
       create_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
       base_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+    - platform: android
+      create_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+      base_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+    - platform: ios
+      create_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+      base_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
     - platform: linux
       create_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
       base_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+    - platform: macos
+      create_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+      base_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+    - platform: web
+      create_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+      base_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+    - platform: windows
+      create_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
+      base_revision: fb57da5f945d02ef4f98dfd9409a72b7cce74268
 
   # User provided section
 

packages/example/android/app/build.gradle → packages/fl_query/example/android/app/build.gradle

@@ -44,7 +44,7 @@ android {
 
     defaultConfig {
         // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
-        applicationId "com.github.KRTirtho.example"
+        applicationId "com.example.example"
         // You can update the following values to match your application needs.
         // For more information, see: https://docs.flutter.dev/deployment/android#reviewing-the-build-configuration.
         minSdkVersion flutter.minSdkVersion

packages/example/android/app/src/profile/AndroidManifest.xml → packages/fl_query/example/android/app/src/debug/AndroidManifest.xml

@@ -1,5 +1,5 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.github.KRTirtho.example">
+    package="com.example.example">
     <!-- The INTERNET permission is required for development. Specifically,
          the Flutter tool needs it to communicate with the running application
          to allow setting breakpoints, to provide hot reload, etc.

packages/example/android/app/src/main/AndroidManifest.xml → packages/fl_query/example/android/app/src/main/AndroidManifest.xml

@@ -1,5 +1,5 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.github.KRTirtho.example">
+    package="com.example.example">
    <application
         android:label="example"
         android:name="${applicationName}"

packages/example/android/app/src/main/kotlin/com/github/KRTirtho/example/MainActivity.kt → packages/fl_query/example/android/app/src/main/kotlin/com/example/example/MainActivity.kt

@@ -1,4 +1,4 @@
-package com.github.KRTirtho.example
+package com.example.example
 
 import io.flutter.embedding.android.FlutterActivity
 

packages/example/android/app/src/debug/AndroidManifest.xml → packages/fl_query/example/android/app/src/profile/AndroidManifest.xml

@@ -1,5 +1,5 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
-    package="com.github.KRTirtho.example">
+    package="com.example.example">
     <!-- The INTERNET permission is required for development. Specifically,
          the Flutter tool needs it to communicate with the running application
          to allow setting breakpoints, to provide hot reload, etc.