QueryBuilder

The QueryBuilder widget is the heart of fetching data in Fasq. It turns asynchronous data sources into reactive UI states.

Usage

import 'package:fasq/fasq.dart';

QueryBuilder<List<Todo>>(
  queryKey: 'todos'.toQueryKey(),
  queryFn: () => fetchTodos(),
  builder: (context, state) {
    // 1. Loading State
    if (state.isLoading) {
      return const CircularProgressIndicator();
    }

    // 2. Error State
    if (state.hasError) {
      return Text('Error: ${state.error}');
    }

    // 3. Success State
    return ListView(
      children: state.data!.map((todo) => Text(todo.title)).toList(),
    );
  },
)

API

Parameters

Name	Type	Required	Description
queryKey	QueryKey	Yes	Unique identifier for caching and sharing the query. Use 'key'.toQueryKey().
queryFn	Future<T> Function()	No	The function that fetches the data. Required if queryFnWithToken is not provided.
queryFnWithToken	Future<T> Function(CancellationToken)	No	Function that fetches data with a cancellation token. Required if queryFn is not provided.
builder	Widget Function(BuildContext, QueryState<T>)	Yes	Builds the UI based on the current state.
options	QueryOptions?	No	Configuration for caching, refetching, and side effects.
dependsOn	QueryKey?	No	Key of a parent query. If the parent is disposed, this query is cancelled.

QueryState Properties

The state object passed to the builder contains:

Property	Type	Description
data	T?	The data returned from the query function. null if not loaded or errored.
error	Object?	The error object if the query failed.
status	QueryStatus	Current status: loading, success, or error.
isLoading	bool	True if the query is performing the initial fetch (hard loading).
isFetching	bool	True if the query is fetching, including background refetches.
hasData	bool	True if data is not null.
hasError	bool	True if error is not null.

Examples

Customizing Configuration (Options)

You can pass QueryOptions to customize how the query behaves.

QueryBuilder<User>(
  queryKey: 'user:1'.toQueryKey(),
  queryFn: () => fetchUser(1),
  options: const QueryOptions(
    staleTime: Duration(minutes: 5), // Data remains fresh for 5 mins
    refetchOnResume: true,           // Refetch when app comes to foreground
  ),
  builder: (context, state) {
    if (state.hasData) return UserProfile(state.data!);
    return const LoadingSpinner();
  },
)

Background Refetching Indicators

Distinguish between initial loading and background updates.

QueryBuilder<List<Post>>(
  queryKey: 'feed'.toQueryKey(),
  queryFn: () => fetchFeed(),
  builder: (context, state) {
    if (state.isLoading) return const ShimmerList();

    return Column(
      children: [
        // Show a small loader when refreshing in background
        if (state.isFetching) const LinearProgressIndicator(),

        Expanded(
          child: ListView.builder(
            itemCount: state.data?.length ?? 0,
            itemBuilder: (_, i) => PostTile(state.data![i]),
          ),
        ),
      ],
    );
  },
)

Dependent Queries

Queries can depend on variables. FASQ handles key changes automatically.

class UserPosts extends StatelessWidget {
  final String userId;

  const UserPosts({required this.userId});

  @override
  Widget build(BuildContext context) {
    return QueryBuilder<List<Post>>(
      // The key includes the userId. If userId changes,
      // Fasq automatically fetches data for the new user.
      queryKey: 'posts:$userId'.toQueryKey(),
      queryFn: () => fetchPostsForUser(userId),
      builder: (context, state) {
         // ... build UI
      },
    );
  }
}

Request Cancellation

Fasq supports cancelling in-flight requests when a query is disposed or re-fetched. use queryFnWithToken to access the cancellation token.

/// Example using Dio
QueryBuilder<List<Todo>>(
  queryKey: 'todos'.toQueryKey(),
  // Use queryFnWithToken instead of queryFn
  queryFnWithToken: (token) async {
    final cancelToken = CancelToken();

    // Register cancellation callback
    token.onCancel(() => cancelToken.cancel());

    try {
      final response = await dio.get(
        '/todos',
        cancelToken: cancelToken,
      );
      return (response.data as List).map((e) => Todo.fromJson(e)).toList();
    } on DioException catch (e) {
      // Fasq handles cancellations silently if they throw exceptions
      // matching your client's cancellation error type.
      // If you rethrow properly, Fasq will recognize it.
      rethrow;
    }
  },
  builder: (context, state) {
    if (state.isLoading) return const CircularProgressIndicator();
    return TodoList(state.data!);
  },
)

/// Example using http package
QueryBuilder<String>(
  queryKey: 'data'.toQueryKey(),
  queryFnWithToken: (token) async {
    final client = http.Client();

    // Close client on cancellation
    token.onCancel(() => client.close());

    try {
      final response = await client.get(Uri.parse('https://example.com'));
      return response.body;
    } finally {
      // Clean up if not cancelled via token
      if (!token.isCancelled) {
        client.close();
      }
    }
  },
  builder: (context, state) => Text(state.data ?? 'Loading...'),
)