fquery

If you need to access a query instance in a part of your code where you have access to BuildContext but are not inside a builder (e.g., in a scroll listener or a callback), you can use the static .of() method provided by the instance classes.

Warning: Accessing results this way via Instance.of will not trigger widget rebuilds. Use this pattern only for performing actions (like calling fetchNextPage()) rather than for rendering data that depends on the query state.

void onScroll() {
  // Access the infinite query instance using the context and its options
  final itemsQuery = InfiniteQueryInstance.of(
    context,
    itemsQueryOptions,
  );

  // Perform an action on the query
  if (scrollController.position.pixels == scrollController.position.maxScrollExtent) {
    itemsQuery.fetchNextPage();
  }
}

If you are using flutter_hooks, fquery provides a set of ready-to-use hooks to manage query states seamlessly within your widget lifecycle. These hooks allow you to access query data, loading states, and mutation controls directly within a HookWidget.

// Available hooks:
useQuery
useInfiniteQuery
useQueries
useMutation
useIsFetching

To use fquery, you must wrap your application or the relevant widget tree with a CacheProvider. This provides the QueryCache instance to your widget tree.

void main() {
  runApp(
    CacheProvider(
      cache: queryCache,
      child: CupertinoApp(
        // ...
      ),
    ),
  );
}

You can define global default behaviors for all queries by configuring the QueryCache with DefaultQueryOptions. This is passed to the CacheProvider during app initialization.

final cache = QueryCache(
  defaultQueryOptions: DefaultQueryOptions(
    cacheDuration: Duration(minutes: 20),
    refetchInterval: Duration(minutes: 5),
    refetchOnMount: RefetchOnMount.always,
    staleDuration: Duration(minutes: 3),
  ),
);

void main() {
  runApp(
    CacheProvider(
      cache: cache,
      child: CupertinoApp(
// ...

While Column or nesting can be used for a fixed number of parallel queries, QueriesBuilder is used for dynamic parallel queries where the number of queries is determined at runtime (e.g., rendering a list of items where each item needs its own query).

// no. of queries are changing according to `text`
QueriesBuilder<Post, Exception>(
  options: List<QueryOptions<Post, Exception>>.generate(
    text,
    (i) => QueryOptions(
      queryKey: QueryKey(['posts', i + 1]),
      queryFn: () => getPost(i + 1),
      refetchOnMount: RefetchOnMount.never,
    ),
  ),
  builder: (context, results) {
    // ...
  },
)

You can manually mark cached data as stale or trigger a re-fetch using invalidateQueries() on the QueryCache. This is useful when you know data has changed on the server.

To access the cache, use CacheProvider.of(context) or CacheProvider.get(context).

• Partial matching: cache.invalidateQueries(['posts']) invalidates all keys starting with ['posts'] (e.g., ['posts', 1]).
• Exact matching: cache.invalidateQueries(['posts'], exact: true) only invalidates the exact key ['posts'].

final cache = CacheProvider.of(context);

// Invalidate every query with a key that starts with `post'
cache.invalidateQueries(['posts']);

// Use `exact: true` to exactly match the query
cache.invalidateQueries(['posts'], exact: true);

If you want to update the cache without a full re-fetch (e.g., after a local mutation), use setQueryData(). It takes a queryKey and an updater function. The updater function receives the previous data (which is nullable if the key doesn't exist).

Note: The returned type must match the type of data stored in the cache, otherwise an error is thrown.

final cache = CacheProvider.get(context);

cache.setQueryData<List<Post>>(['posts'], (previous) {
  return previous?.map((post) {
    return post.copyWith(
      title: "lorem ipsum"
    );
  }).toList() ?? <Post>[];
});