# API reference

> One page per main surface of query_kit and query_kit_flutter — every option, field and member with its type, default and TanStack Query name — plus where the generated dartdoc lives.

These pages list the public surface a user touches, one page per surface, in
tables: every option, field and member with its type, its default and what it
does, and the name it has in TanStack Query. Each row links to the generated
dartdoc, which has the full signature and the longer explanation.

| Page | What it covers |
|---|---|
| [QueryClient](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-client.md) | The client: fetching, reading and writing the cache, operating on many queries at once, defaults, mounting and clearing. |
| [Options](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-options.md) | `QueryOptions`, `QueryObserverOptions`, the infinite and mutation options — every field — and the sealed option values (`StaleTime`, `GcTime`, `RetryPolicy`, `RefetchOn`, …). |
| [Results](https://dualmeta-gmbh.github.io/query_kit/docs/reference/results.md) | What a reader is handed: `QueryResult` and its three cases, `QueryState`, `InfiniteData` and the paging flags, `MutationResult`, `MutationState`, `CombinedResult`. |
| [Widgets and controllers](https://dualmeta-gmbh.github.io/query_kit/docs/reference/widgets-and-controllers.md) | The Flutter binding: `QueryClientProvider`, the four call styles, listeners, collections, `OnlineStatus`. |
| [Caches and observers](https://dualmeta-gmbh.github.io/query_kit/docs/reference/caches-and-observers.md) | `QueryCache` and `MutationCache` with their events, `Query` and `Mutation`, the observers, the filters, and the focus, online and notify managers. |
| [Errors](https://dualmeta-gmbh.github.io/query_kit/docs/reference/errors.md) | Every error either package throws or records, and every check a debug build runs. |

A typical app touches them in that order: it builds a [client](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-client.md)
with some defaults, describes its queries with [options](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-options.md),
reads [results](https://dualmeta-gmbh.github.io/query_kit/docs/reference/results.md) through [a widget or a
controller](https://dualmeta-gmbh.github.io/query_kit/docs/reference/widgets-and-controllers.md), and looks at the
[caches](https://dualmeta-gmbh.github.io/query_kit/docs/reference/caches-and-observers.md) and [errors](https://dualmeta-gmbh.github.io/query_kit/docs/reference/errors.md) when something
needs explaining.

## The generated dartdoc

Every public member of both packages carries a dartdoc comment, and pub.dev
builds and hosts the reference for every published version:

- [pub.dev/documentation/query_kit](https://pub.dev/documentation/query_kit/latest/)
  — the core: client, caches, observers, options, results.
- [pub.dev/documentation/query_kit_flutter](https://pub.dev/documentation/query_kit_flutter/latest/)
  — the binding. It re-exports the core, so an app imports only this one.

`dart doc` in a package's directory writes the same reference to `doc/api/`;
open `doc/api/index.html`. For a package in your pub cache, run it there.

## Where to start reading

| If you want | Start at |
|---|---|
| the whole imperative surface | [`QueryClient`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-client.md) |
| what a widget is handed | [`QueryResult`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/results.md#queryresult), and its `QueryPending` / `QuerySuccess` / `QueryError` cases |
| every option and what unset means | [the options](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-options.md), then [the option values](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-options.md#option-values) |
| paging | [the infinite fields](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-options.md#infinite-query-fields), [`InfiniteData`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/results.md#infinitedata), [`InfiniteQueryObserver`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/caches-and-observers.md#infinitequeryobserver) |
| writes | [the mutation fields](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-options.md#mutation-fields), [`MutationResult`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/results.md#mutationresult), [`MutationController`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/widgets-and-controllers.md#mutationcontroller) |
| the caches | [`QueryCache`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/caches-and-observers.md#querycache), [`MutationCache`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/caches-and-observers.md#mutationcache), [filters](https://dualmeta-gmbh.github.io/query_kit/docs/reference/caches-and-observers.md#filters) |
| the Flutter side | [`QueryClientProvider`](https://dualmeta-gmbh.github.io/query_kit/docs/reference/widgets-and-controllers.md#queryclientprovider) and [the four call styles](https://dualmeta-gmbh.github.io/query_kit/docs/reference/widgets-and-controllers.md#the-four-call-styles-at-a-glance) |
| widget tests | nothing exported: the teardown is a documented snippet, see [Testing](https://dualmeta-gmbh.github.io/query_kit/docs/guides/testing.md) |

## Beyond signatures

- [Feature matrix](https://dualmeta-gmbh.github.io/query_kit/docs/reference/feature-matrix.md) — what exists, per TanStack Query
  feature.
- [Differences from TanStack Query](https://dualmeta-gmbh.github.io/query_kit/docs/reference/differences-from-tanstack.md) — where the
  behaviour differs, and why.
- [Troubleshooting](https://dualmeta-gmbh.github.io/query_kit/docs/reference/troubleshooting.md) — symptoms, causes and fixes.
- [Coming from React Query](https://dualmeta-gmbh.github.io/query_kit/docs/coming-from-react-query.md) — the name map.

> **Note: In React Query**
>
> TanStack Query's React reference is generated, one page per function, class
> and interface: `useQuery`, `QueryClient`, `QueryCache`, `QueryObserverOptions`,
> `QueryObserverSuccessResult` and so on. Here the pages group by surface
> instead, and the options and the results have a page each, because the four
> call styles share them.