Quick Start

Get up and running with Fasq in 5 minutes. This guide focuses on the core QueryBuilder widget, which works with any Flutter setup.

1. Simple Data Fetching

Let’s fetch a list of users and display them.


import 'package:fasq/fasq.dart';
 
class UsersScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return QueryBuilder<List<User>>(
      // 1. Unique key for caching
      queryKey: 'users'.toQueryKey(),
      
      // 2. Async function that returns Future<List<User>>
      queryFn: () => api.fetchUsers(),
      
      // 3. Builder callback
      builder: (context, state) {
        if (state.isLoading) {
          return const Center(child: CircularProgressIndicator());
        }
        
        if (state.hasError) {
          return Center(child: Text('Error: ${state.error}'));
        }
        
        if (state.hasData) {
          return ListView.builder(
            itemCount: state.data!.length,
            itemBuilder: (context, index) {
              final user = state.data![index];
              return ListTile(
                title: Text(user.name),
                subtitle: Text(user.email),
              );
            },
          );
        }
        
        return const SizedBox();
      },
    );
  }
}

2. Using Adapters (Optional)

If you use a specific state management library, you can use the corresponding adapter for a more integrated feel.

Hooks (`flutter_hooks`)


// Using fasq_hooks
class UsersScreen extends HookWidget {
  @override
  Widget build(BuildContext context) {
    final state = useQuery('users', () => api.fetchUsers());
    
    if (state.isLoading) return const CircularProgressIndicator();
    // ... same UI logic
  }
}

Note: Requires fasq_hooks package.

Bloc (`flutter_bloc`)


// Using fasq_bloc
BlocProvider(
  create: (_) => QueryCubit(key: 'users', queryFn: api.fetchUsers),
  child: BlocBuilder<QueryCubit<List<User>>, QueryState<List<User>>>(
    builder: (context, state) {
       if (state.isLoading) return const CircularProgressIndicator();
       // ...
    },
  ),
)

Note: Requires fasq_bloc package.

3. Configuration & Caching

Add caching behavior by customizing QueryOptions.


QueryBuilder<List<User>>(
  queryKey: 'users'.toQueryKey(),
  queryFn: () => api.fetchUsers(),
  options: QueryOptions(
    staleTime: Duration(minutes: 5),  // Fresh for 5 minutes (no refetch)
    cacheTime: Duration(minutes: 30), // Keep in memory for 30 minutes
  ),
  builder: (context, state) => /* ... */,
)

4. Retrying & Refreshing

Use the provided QueryClient to interact with queries manually.


// Refresh (Refetch)
QueryClient().invalidateQuery('users'.toQueryKey());
 
// Manual Retry (if error)
if (state.hasError) {
  ElevatedButton(
    onPressed: () => QueryClient().refetchQuery('users'.toQueryKey()),
    child: Text('Retry'),
  );
}

Next Steps

Core Concepts - Deep dive into how queries work
Examples - See real-world patterns
API Reference - Full details on QueryBuilder