query reusability by QueryJob

QueryJob.task External Data Support
Query task is now pure function
Query.data is non-nullable (even the type)

packages/example/lib/another_component.dart

@@ -6,7 +6,7 @@ class AnotherComponent extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    final lol = QueryBowl.of(context).getQuery<String>("greetings");
+    final lol = QueryBowl.of(context).getQuery<String, void>("greetings");
     if (lol?.data == null) return const CircularProgressIndicator();
     return Text("${lol!.data!} from AnotherComponent");
   }

packages/example/lib/main.dart

@@ -1,8 +1,8 @@
 import 'dart:math';
 
 import 'package:example/another_component.dart';
-import 'package:fl_query/query_bowl.dart';
+import 'package:example/query_with_external_data.dart';
-import 'package:fl_query/query_builder.dart';
+import 'package:fl_query/fl_query.dart';
 import 'package:flutter/material.dart';
 import 'dart:async';
 
@@ -15,19 +15,29 @@ class MyApp extends StatelessWidget {
 
   @override
   Widget build(BuildContext context) {
-    return MaterialApp(
+    return QueryBowlScope(
-      title: 'Flutter Demo',
+      child: MaterialApp(
-      theme: ThemeData(
+        title: 'Flutter Demo',
-        primarySwatch: Colors.blue,
+        theme: ThemeData(
-      ),
+          useMaterial3: true,
-      home: const QueryBowlScope(
+          primarySwatch: Colors.blue,
-        staleTime: Duration(seconds: 10),
+        ),
-        child: MyHomePage(),
+        home: const MyHomePage(),
       ),
     );
   }
 }
 
+final successJob = QueryJob<String, void>(
+    queryKey: "greetings",
+    task: (queryKey, _) => Future.delayed(const Duration(seconds: 2),
+        () => "Welcome ($queryKey) ${Random.secure().nextInt(100)}"));
+
+final failedJob = QueryJob<String, void>(
+  queryKey: "failure",
+  task: (queryKey, _) => Future.value("[$queryKey] Failed for unknown reason"),
+);
+
 class MyHomePage extends StatefulWidget {
   const MyHomePage({Key? key}) : super(key: key);
 
@@ -46,12 +56,9 @@ class _MyHomePageState extends State<MyHomePage> {
         children: [
           Row(
             children: [
-              QueryBuilder<String>(
+              QueryBuilder<String, void>(
-                queryKey: "greetings",
+                job: successJob,
-                task: (queryKey) => Future.delayed(
+                externalData: null,
-                    const Duration(seconds: 2),
-                    () =>
-                        "Welcome ($queryKey) ${Random.secure().nextInt(100)}"),
                 builder: (context, query) {
                   if (query.isLoading || query.isRefetching) {
                     return const CircularProgressIndicator();
@@ -64,10 +71,24 @@ class _MyHomePageState extends State<MyHomePage> {
                   );
                 },
               ),
-              QueryBuilder(
+              QueryBuilder<String, void>(
-                queryKey: "failure",
+                job: successJob,
-                task: (queryKey) =>
+                externalData: null,
-                    Future.value("[$queryKey] Failed for unknown reason"),
+                builder: (context, query) {
+                  if (query.isLoading || query.isRefetching) {
+                    return const CircularProgressIndicator();
+                  }
+                  return ElevatedButton(
+                    child: Text(query.data!),
+                    onPressed: () async {
+                      await query.refetch();
+                    },
+                  );
+                },
+              ),
+              QueryBuilder<String, void>(
+                job: failedJob,
+                externalData: null,
                 builder: (context, query) {
                   if (query.hasError) return Text(query.error);
                   return Text("Failure. You're a failure ${query.data}");
@@ -75,6 +96,16 @@ class _MyHomePageState extends State<MyHomePage> {
               ),
             ],
           ),
+          ElevatedButton(
+            child: const Text("External Data Example"),
+            onPressed: () {
+              Navigator.of(context).push(
+                MaterialPageRoute(
+                  builder: (context) => const QueryWithExternalData(),
+                ),
+              );
+            },
+          ),
           const AnotherComponent(),
         ],
       ),

packages/example/lib/query_with_external_data.dart

@@ -0,0 +1,39 @@
+import 'dart:math';
+
+import 'package:fl_query/fl_query.dart';
+import 'package:flutter/material.dart';
+
+final jobWithExternalData = QueryJob<String, String>(
+    queryKey: "external_data",
+    task: (queryKey, data) {
+      return Future.delayed(const Duration(milliseconds: 500),
+          () => "Hello from $queryKey with $data");
+    });
+
+class QueryWithExternalData extends StatelessWidget {
+  const QueryWithExternalData({Key? key}) : super(key: key);
+
+  @override
+  Widget build(BuildContext context) {
+    return Scaffold(
+      appBar: AppBar(),
+      body: QueryBuilder<String, String>(
+        job: jobWithExternalData,
+        externalData: (Random().nextDouble() * 200).toString(),
+        builder: (context, query) {
+          if (query.isLoading || query.isLoading || query.data == null) {
+            return const CircularProgressIndicator();
+          }
+          return Container(
+            width: double.parse(query.externalData),
+            height: double.parse(query.externalData),
+            decoration: const BoxDecoration(
+              shape: BoxShape.circle,
+              color: Colors.blue,
+            ),
+          );
+        },
+      ),
+    );
+  }
+}

packages/fl_query/lib/fl_query.dart

@@ -1,19 +1,6 @@
 library fl_query;
 
-import 'package:flutter/material.dart';
+export 'query.dart';
-
+export 'query_bowl.dart';
-class FlQueryScope extends StatefulWidget {
+export 'query_builder.dart';
-  final Widget child;
+export 'models/query_job.dart';
-  const FlQueryScope({required this.child, Key? key}) : super(key: key);
-
-  @override
-  State<FlQueryScope> createState() => _FlQueryScopeState();
-}
-
-class _FlQueryScopeState extends State<FlQueryScope> {
-  @override
-  Widget build(BuildContext context) {
-    Theme.of(context);
-    return widget.child;
-  }
-}

packages/fl_query/lib/models/query_job.dart

@@ -0,0 +1,26 @@
+import 'package:fl_query/query.dart';
+
+class QueryJob<T extends Object, Outside> {
+  // all params
+  final String queryKey;
+  QueryTaskFunction<T, Outside> task;
+  final int? retries;
+  final Duration? retryDelay;
+  final T? initialData;
+
+  // got from global options
+  final Duration? staleTime;
+
+  final QueryListener<T>? onData;
+  final QueryListener<dynamic>? onError;
+  QueryJob({
+    required this.queryKey,
+    required this.task,
+    this.retries,
+    this.retryDelay,
+    this.initialData,
+    this.staleTime,
+    this.onData,
+    this.onError,
+  });
+}

packages/fl_query/lib/query.dart

@@ -1,5 +1,6 @@
 import 'dart:async';
 
+import 'package:fl_query/models/query_job.dart';
 import 'package:flutter/widgets.dart';
 
 enum QueryStatus {
@@ -9,16 +10,16 @@ enum QueryStatus {
   refetching;
 }
 
-typedef QueryTaskFunction<T> = FutureOr<T> Function(String);
+typedef QueryTaskFunction<T, Outside> = FutureOr<T> Function(String, Outside);
 
 typedef QueryListener<T> = FutureOr<void> Function(T);
 
 typedef ListenerUnsubscriber = void Function();
 
-class Query<T> extends ChangeNotifier {
+class Query<T extends Object, Outside> extends ChangeNotifier {
   // all params
   final String queryKey;
-  QueryTaskFunction<T> task;
+  QueryTaskFunction<T, Outside> task;
   final int retries;
   final Duration retryDelay;
   final T? _initialData;
@@ -40,10 +41,17 @@ class Query<T> extends ChangeNotifier {
   final QueryListener<T>? _onData;
   final QueryListener<dynamic>? _onError;
 
+  // externalData will always be passed to the task Callback
+  // it will change based on the presence of QueryBuilder
+  Outside _externalData;
+
+  Outside? _prevUsedExternalData;
+
   Query({
     required this.queryKey,
     required this.task,
     required Duration staleTime,
+    required Outside externalData,
     required this.retries,
     required this.retryDelay,
     T? initialData,
@@ -52,11 +60,27 @@ class Query<T> extends ChangeNotifier {
   })  : status = QueryStatus.pending,
         _staleTime = staleTime,
         _initialData = initialData,
+        _externalData = externalData,
         data = initialData,
         _onData = onData,
         _onError = onError,
         updatedAt = DateTime.now();
 
+  Query.fromOptions(QueryJob<T, Outside> options,
+      {required Outside externalData})
+      : queryKey = options.queryKey,
+        task = options.task,
+        retries = options.retries ?? 3,
+        retryDelay = options.retryDelay ?? const Duration(milliseconds: 200),
+        _staleTime = options.staleTime ?? const Duration(days: 1),
+        _initialData = options.initialData,
+        _externalData = externalData,
+        _onData = options.onData,
+        _onError = options.onError,
+        data = options.initialData,
+        status = QueryStatus.pending,
+        updatedAt = DateTime.now();
+
   // all getters & setters
   bool get hasData => data != null && error == null;
   bool get hasError =>
@@ -66,6 +90,8 @@ class Query<T> extends ChangeNotifier {
   bool get isRefetching =>
       status == QueryStatus.refetching && (data != null || error != null);
   bool get isSucceeded => status == QueryStatus.succeed && data != null;
+  Outside get externalData => _externalData;
+  Outside? get prevUsedExternalData => _prevUsedExternalData;
 
   // all methods
 
@@ -74,7 +100,8 @@ class Query<T> extends ChangeNotifier {
   Future<void> _execute() async {
     try {
       retryAttempts = 0;
-      data = await task(queryKey);
+      data = await task(queryKey, _externalData);
+      _prevUsedExternalData = _externalData;
       updatedAt = DateTime.now();
       status = QueryStatus.succeed;
       _onData?.call(data!);
@@ -90,7 +117,8 @@ class Query<T> extends ChangeNotifier {
         while (retryAttempts <= retries) {
           await Future.delayed(retryDelay);
           try {
-            data = await task(queryKey);
+            data = await task(queryKey, _externalData);
+            _prevUsedExternalData = _externalData;
             status = QueryStatus.succeed;
             _onData?.call(data!);
             notifyListeners();
@@ -149,6 +177,10 @@ class Query<T> extends ChangeNotifier {
     notifyListeners();
   }
 
+  setExternalData(Outside externalData) {
+    _externalData = externalData;
+  }
+
   void reset() {
     refetchCount = 0;
     data = _initialData;
@@ -163,4 +195,6 @@ class Query<T> extends ChangeNotifier {
     // the data has become stale
     return DateTime.now().isAfter(updatedAt.add(_staleTime));
   }
+
+  A? cast<A>() => this is A ? this as A : null;
 }

packages/fl_query/lib/query_bowl.dart

@@ -1,5 +1,6 @@
 import 'dart:async';
 
+import 'package:fl_query/models/query_job.dart';
 import 'package:fl_query/query.dart';
 import 'package:collection/collection.dart';
 import 'package:flutter/widgets.dart';
@@ -73,7 +74,7 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
     });
   }
 
-  void addQuery(Query query) {
+  void addQuery<T extends Object, Outside>(Query<T, Outside> query) {
     setState(() {
       queries = Set.from({...queries, query});
     });
@@ -81,9 +82,9 @@ class _QueryBowlScopeState extends State<QueryBowlScope> {
 
   @override
   Widget build(BuildContext context) {
+    _disposeListeners();
     _listenToQueryUpdate();
     return QueryBowl(
-      onUpdate: updateQueries,
       addQuery: addQuery,
       queries: queries,
       staleTime: widget.staleTime,
@@ -98,12 +99,14 @@ class QueryBowl extends InheritedWidget {
   final Set<Query> _queries;
   final Duration staleTime;
 
-  final void Function(Query query) _addQuery;
+  final void Function<T extends Object, Outside>(Query<T, Outside> query)
+      _addQuery;
 
   const QueryBowl({
     required Widget child,
-    required final void Function() onUpdate,
+    required final void Function<T extends Object, Outside>(
-    required final void Function(Query query) addQuery,
+            Query<T, Outside> query)
+        addQuery,
     required final Set<Query> queries,
     required this.staleTime,
     Key? key,
@@ -111,25 +114,33 @@ class QueryBowl extends InheritedWidget {
         _queries = queries,
         super(child: child, key: key);
 
-  Future<T?> fetchQuery<T>(Query<T> query) async {
+  Future<T?> fetchQuery<T extends Object, Outside>(QueryJob<T, Outside> options,
+      {required Outside externalData}) async {
     final prevQuery =
-        _queries.firstWhereOrNull((q) => q.queryKey == query.queryKey);
+        _queries.firstWhereOrNull((q) => q.queryKey == options.queryKey);
-    if (prevQuery is Query<T>) {
+    if (prevQuery is Query<T, Outside>) {
-      if (!prevQuery.hasData) {
+      // run the query if its still not called or if externalData has
+      // changed
+      final hasExternalDataChanged =
+          prevQuery.prevUsedExternalData != externalData;
+      if (!prevQuery.hasData || hasExternalDataChanged) {
+        if (hasExternalDataChanged) prevQuery.setExternalData(externalData);
         return prevQuery.fetched
             ? await prevQuery.refetch()
             : await prevQuery.fetch();
       }
       return prevQuery.data;
     }
-    _addQuery(query);
+    final query =
+        Query<T, Outside>.fromOptions(options, externalData: externalData);
+    _addQuery<T, Outside>(query);
     return await query.fetch();
   }
 
-  Query<T>? getQuery<T>(String queryKey) {
+  Query<T, Outside>? getQuery<T extends Object, Outside>(String queryKey) {
-    return _queries.firstWhereOrNull(
+    return _queries.firstWhereOrNull((query) {
-            (query) => query.queryKey == queryKey && query is Query<T>)
+      return query.queryKey == queryKey && query is Query<T, Outside>;
-        as Query<T>?;
+    })?.cast<Query<T, Outside>>();
   }
 
   int get isFetching {

packages/fl_query/lib/query_builder.dart

@@ -1,57 +1,49 @@
+import 'package:fl_query/models/query_job.dart';
 import 'package:fl_query/query.dart';
 import 'package:fl_query/query_bowl.dart';
 import 'package:flutter/widgets.dart';
 
-class QueryBuilder<T> extends StatefulWidget {
+class QueryBuilder<T extends Object, Outside> extends StatefulWidget {
-  final Widget Function(BuildContext, Query<T>) builder;
+  final Function(BuildContext, Query<T, Outside>) builder;
-  final QueryTaskFunction<T> task;
+  final QueryJob<T, Outside> job;
-  final String queryKey;
+  final Outside externalData;
-  final Duration? staleTime;
-  final int retries;
-  final T? initialData;
-  final Duration retryDelay;
-
-  final QueryListener<T>? onData;
-  final QueryListener<dynamic>? onError;
 
   const QueryBuilder({
+    required this.job,
+    required this.externalData,
     required this.builder,
-    required this.task,
-    required this.queryKey,
-    this.initialData,
-    this.staleTime,
-    this.retryDelay = const Duration(milliseconds: 200),
-    this.retries = 3,
-    this.onData,
-    this.onError,
     Key? key,
   }) : super(key: key);
 
   @override
-  State<QueryBuilder<T>> createState() => _QueryBuilderState<T>();
+  State<QueryBuilder<T, Outside>> createState() =>
+      _QueryBuilderState<T, Outside>();
 }
 
-class _QueryBuilderState<T> extends State<QueryBuilder<T>> {
+class _QueryBuilderState<T extends Object, Outside>
+    extends State<QueryBuilder<T, Outside>> {
   @override
   void initState() {
     super.initState();
     WidgetsBinding.instance.addPostFrameCallback((_) async {
-      await QueryBowl.of(context).fetchQuery(Query<T>(
+      await QueryBowl.of(context).fetchQuery<T, Outside>(widget.job,
-        queryKey: widget.queryKey,
+          externalData: widget.externalData);
-        task: widget.task,
-        staleTime: widget.staleTime ?? QueryBowl.of(context).staleTime,
-        retries: widget.retries,
-        initialData: widget.initialData,
-        retryDelay: widget.retryDelay,
-        onData: widget.onData,
-        onError: widget.onError,
-      ));
     });
   }
 
+  @override
+  void didUpdateWidget(covariant oldWidget) {
+    if (oldWidget.externalData != widget.externalData) {
+      QueryBowl.of(context)
+          .fetchQuery(widget.job, externalData: widget.externalData);
+    }
+    super.didUpdateWidget(oldWidget);
+  }
+
   @override
   Widget build(BuildContext context) {
-    final query = QueryBowl.of(context).getQuery<T>(widget.queryKey);
+    final query =
+        QueryBowl.of(context).getQuery<T, Outside>(widget.job.queryKey);
     if (query == null) return Container();
     return widget.builder(context, query);
   }