QueryCubit

The QueryCubit is an abstract base class that wraps a Fasq query, emitting QueryState changes. Extend QueryCubit to create your own query cubits with type-safe, structured state management.

Basic Usage

Extend QueryCubit and implement the required getters:

import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:fasq_bloc/fasq_bloc.dart';

class UsersQueryCubit extends QueryCubit<List<User>> {
  @override
  QueryKey get queryKey => 'users'.toQueryKey();

  @override
  Future<List<User>> Function() get queryFn => () => api.fetchUsers();
}

class UsersScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Users')),
      body: BlocProvider(
        create: (context) => UsersQueryCubit(),
        child: BlocBuilder<UsersQueryCubit, QueryState<List<User>>>(
          builder: (context, state) {
            if (state.isLoading) {
              return 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));
                },
              );
            }

            return Center(child: Text('No users found.'));
          },
        ),
      ),
    );
  }
}

Cubit Configuration

Configure query behavior by overriding the options getter:

class UsersQueryCubit extends QueryCubit<List<User>> {
  @override
  QueryKey get queryKey => 'users'.toQueryKey();

  @override
  Future<List<User>> Function() get queryFn => () => api.fetchUsers();

  @override
  QueryOptions? get options => QueryOptions(
    staleTime: Duration(minutes: 5),
    cacheTime: Duration(minutes: 10),
    enabled: true,
    onSuccess: () {
      print('Users fetched successfully');
    },
    onError: (error) {
      print('Error fetching users: $error');
    },
  );
}

Advanced Features

Cancellation

Cancel an in-flight query without closing the Cubit. This is cooperative cancellation, meaning your queryFn must check the cancellation token.

context.read<UsersQueryCubit>().cancel();

Manual Cache Updates (Optimistic UI)

You can manually set the data for a query immediately. This is useful for optimistic UI patterns or syncing local state.

final newUser = User(id: '123', name: 'New User');
context.read<UsersQueryCubit>().setData([newUser]);

Dynamic Configuration

Update query options at runtime (e.g., enable/disable fetching, change stale time). This will automatically swap the underlying query if necessary.

// Pause fetching
context.read<UsersQueryCubit>().updateOptions(
  newOptions: QueryOptions(enabled: false),
);

// Resume fetching with new stale time
context.read<UsersQueryCubit>().updateOptions(
  newOptions: QueryOptions(
    enabled: true,
    staleTime: Duration(seconds: 30),
  ),
);

Parameterized Queries

Use constructor parameters or fields for dynamic query keys:

class UserProfileQueryCubit extends QueryCubit<User> {
  final String userId;

  UserProfileQueryCubit(this.userId);

  @override
  QueryKey get queryKey => 'user:$userId'.toQueryKey();

  @override
  Future<User> Function() get queryFn => () => api.fetchUser(userId);
}

Conditional Queries

Disable queries based on conditions using the enabled option:

class UserProfileQueryCubit extends QueryCubit<User?> {
  final String? userId;

  UserProfileQueryCubit(this.userId);

  @override
  QueryKey get queryKey => 'user:$userId'.toQueryKey();

  @override
  Future<User?> Function() get queryFn => () => api.fetchUser(userId!);

  @override
  QueryOptions? get options => QueryOptions(
    enabled: userId != null,
  );
}

Manual Refetching

Trigger manual refetches using the Cubit:

context.read<UsersQueryCubit>().refetch();

Next Steps

• MutationCubit - Learn about mutations
• Composition - Manage multiple queries
• Bloc Patterns - Best practices
• Examples - Complete working examples