query_kit library

Asynchronous state management for Dart: fetching, caching, refetching, invalidation and mutations of server data — a port of TanStack Query's query-core that runs anywhere Dart runs, no Flutter needed.

query_kit is an entirely AI-coded project: all code, tests and documentation were written by AI coding agents (Anthropic's Claude). A human maintainer set the goals and reviews releases, but did not write the code.

query_kit is an independent community port and is not affiliated with or endorsed by TanStack. For Flutter widgets on top of it, see the query_kit_flutter package.

Quick start

A QueryClient owns the cache. Describe a query with QueryOptions — a QueryKey that identifies it and a query function that fetches it — then fetch it imperatively with QueryClient.query, or follow it with a QueryObserver, which fetches on subscribe, refetches when the data is stale and something happens (focus, reconnect, invalidation), and reports every change as a sealed QueryResult.

import 'package:query_kit/query_kit.dart';

Future<void> main() async {
  final client = QueryClient()..mount();
  final todosKey = QueryKey(['todos']);

  // Fetch once and cache.
  final todos = await client.query(QueryOptions<List<String>>(
    queryKey: todosKey,
    queryFn: (context) => fetchTodos(),
    staleTime: const StaleTime.duration(Duration(seconds: 30)),
  ));
  print(todos);

  // Observe: every change to the entry, as a sealed result.
  final observer = QueryObserver(
    client,
    QueryObserverOptions<List<String>>(
      queryKey: todosKey,
      queryFn: (context) => fetchTodos(),
    ),
  );
  final unsubscribe = observer.subscribe((result) {
    switch (result) {
      case QueryPending():
        print('loading');
      case QuerySuccess(:final data):
        print('todos: $data');
      case QueryError(:final error):
        print('failed: $error');
    }
  });

  // Mark stale and refetch what is observed.
  await client.invalidateQueries(filters: QueryFilters(queryKey: todosKey));

  unsubscribe();
  client.unmount();
  client.clear();
}

Future<List<String>> fetchTodos() async => ['Buy milk', 'Walk the dog'];

Where to go next

The API is grouped into categories:

• Client — QueryClient and its defaults.
• Queries, Options, Option values — QueryKey, QueryOptions and the sealed option values such as StaleTime, RetryPolicy and RefetchInterval.
• Results and Combining results — QueryResult and CombinedResult.
• Observers — QueryObserver, InfiniteQueryObserver, MutationObserver, QueriesObserver, MutationStateObserver.
• Mutations and Infinite queries — MutationOptions, InfiniteQueryOptions and friends.
• Caches, Filters, Structural sharing, Errors, Managers — QueryCache, MutationCache, QueryFilters, replaceEqualDeep, AppFocusManager, OnlineManager, NotifyManager.
• Advanced — the plumbing: cache events, actions, fetch behaviours.

Guides, recipes and live examples are on the documentation site: https://dualmeta-gmbh.github.io/query_kit/