arc_query

The easiest way to handle async data in Flutter

arc_query is a lightweight React Query-style toolkit for Flutter. It gives you a simple, strongly typed API for loading, error, success, retry, refresh, caching, and pagination without forcing Bloc, Riverpod, Provider, or any specific app architecture.

Why This Exists

Async UI code in Flutter usually turns into repeated isLoading, try/catch, and manual refresh logic scattered across widgets and services.

arc_query keeps that flow in one place:

• one query object
• one execute call
• one source of truth for loading, error, and data
• built-in cache and stale handling
• built-in pagination support

Quick Start

import 'package:arc_query/arc_query.dart';

final userQuery = Query<User>(
  key: 'user',
  fetcher: () => api.getUser(),
);

await userQuery.execute();

if (userQuery.isLoading) {
  // show spinner
}

if (userQuery.hasError) {
  // show error
}

final user = userQuery.data;

Core Concepts

Every query exposes:

• isLoading
• isRefreshing
• isFetchingMore
• hasError
• hasData
• data
• error
• updatedAt
• isStale

Under the hood, queries move through immutable states:

• QueryIdle
• QueryLoading
• QuerySuccess
• QueryError
• QueryRefreshing
• QueryFetchingMore

Basic Example

final profileQuery = Query<Profile>(
  key: 'profile',
  staleDuration: const Duration(minutes: 5),
  fetcher: () => api.fetchProfile(),
);

await profileQuery.execute();
await profileQuery.refresh();
await profileQuery.retry();

QueryBuilder

Use QueryBuilder when you want a minimal widget wrapper around a query:

QueryBuilder<User>(
  query: userQuery,
  loadingBuilder: (_) => const CircularProgressIndicator(),
  errorBuilder: (context, error, _) => Text(error.toString()),
  dataBuilder: (context, user) => Text(user.name),
  emptyBuilder: (_) => const Text('No user'),
)

You can also use the generic builder:

QueryBuilder<User>(
  query: userQuery,
  builder: (context, state) {
    if (state is QueryLoading<User>) {
      return const CircularProgressIndicator();
    }
    if (state is QueryError<User>) {
      return Text(state.error.toString());
    }
    return Text(state.data?.name ?? 'Missing user');
  },
)

Caching

Queries cache successful results in memory by key.

final productsQuery = Query<List<Product>>(
  key: 'products',
  staleDuration: const Duration(minutes: 5),
  fetcher: () => api.fetchProducts(),
);

Behavior:

• if cached data is fresh, execute() returns cached data immediately
• if cached data is stale, the query keeps the previous value available and refetches
• QueryController can invalidate one query or clear all cached entries

final controller = QueryController();

final productsQuery = Query<List<Product>>(
  key: 'products',
  controller: controller,
  fetcher: () => api.fetchProducts(),
);

controller.invalidate('products');
await controller.refetch('products');
controller.clearCache();

Pagination

Use PaginatedQuery for list endpoints:

final postsQuery = PaginatedQuery<Post, int>(
  key: 'posts',
  initialPageParam: 1,
  pageFetcher: (page) => api.fetchPosts(page),
);

await postsQuery.execute();
await postsQuery.fetchMore();

Your fetcher returns a PageResult:

Future<PageResult<List<Post>, int>> fetchPosts(int page) async {
  final response = await api.fetchPosts(page: page);

  return PageResult<List<Post>, int>(
    data: response.items,
    nextPageParam: response.hasMore ? page + 1 : null,
    hasMore: response.hasMore,
  );
}

Pagination gives you:

• automatic list append
• hasMore
• isFetchingMore
• cached paginated results

Refresh And Retry

Refresh keeps previous data available while a request is running:

await query.refresh();

Retry re-runs the latest failed request:

await query.retry();

Comparison vs Manual Async Handling

Manual UI state usually means:

• local booleans for loading and errors
• duplicate try/catch blocks
• repeated pull-to-refresh wiring
• ad hoc cache maps
• custom pagination state per screen

With arc_query, one object owns that behavior and the widget reads from a single typed source.

Example App

The package includes a full Flutter example in example/lib/main.dart showing:

• user fetch
• retry after failure
• pull to refresh
• paginated list loading
• loading more pages

Testing

Run:

flutter test

License

MIT