# query_kit

> TanStack Query for Dart and Flutter, ported test for test. 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. A community port, not affiliated with or endorsed by TanStack.

query_kit is a port of TanStack Query's `query-core` to Dart (the package `query_kit`, pure Dart) with a Flutter binding on top (`query_kit_flutter`), both on pub.dev. It caches server state per query key, deduplicates and retries fetches, refetches stale data on focus, on reconnect or on an interval, and covers mutations, optimistic updates and infinite queries. Its behaviour follows TanStack Query's, proven by porting upstream's test suite; where it differs is listed on the "Differences from TanStack Query" page below.

Install with `flutter pub add query_kit_flutter` in a Flutter app, or `dart pub add query_kit` in pure Dart. Every page below is Markdown at its own URL with `.md` appended, and all of them together are https://dualmeta-gmbh.github.io/query_kit/llms-full.txt. Source: https://github.com/dualmeta-gmbh/query_kit

## Getting started

- [Overview](https://dualmeta-gmbh.github.io/query_kit/docs/overview.md): What query_kit is, the server-state problem it solves, what reading a query looks like in Flutter, and who it is for.
- [Installation](https://dualmeta-gmbh.github.io/query_kit/docs/installation.md): Which package to add, what it depends on, the Dart and Flutter floors, and the analyzer settings that make the types work for you.
- [Quick start](https://dualmeta-gmbh.github.io/query_kit/docs/quick-start.md): A provider at the root, an options function, a widget that reads it — and the mutation that invalidates it.
- [Important defaults](https://dualmeta-gmbh.github.io/query_kit/docs/important-defaults.md): What the cache does out of the box — stale at once, kept five minutes, retried three times, refetched on return to the app — and how to change each default.
- [Coming from React Query](https://dualmeta-gmbh.github.io/query_kit/docs/coming-from-react-query.md): Every JavaScript name mapped to its Dart counterpart — reading a query, the client, options, infinite queries, mutations.
- [Type safety in Dart](https://dualmeta-gmbh.github.io/query_kit/docs/dart-type-safety.md): Sealed results, one key one exact type, two options shapes, and the analyzer setting that catches the one literal inference cannot type.

## Guides & concepts

### Queries

- [Queries](https://dualmeta-gmbh.github.io/query_kit/docs/guides/queries.md): What a query is, where it lives in an app, the three result states, status versus fetchStatus, and the flags that combine them.
- [Four ways to read a query](https://dualmeta-gmbh.github.io/query_kit/docs/guides/reading-queries-in-widgets.md): context.query, QueryBuilder, QueryMixin and QueryController — four equal call styles, how to pick between them, and when a read is released.
- [Query keys](https://dualmeta-gmbh.github.io/query_kit/docs/guides/query-keys.md): QueryKey as a value type, hierarchical keys and prefix matching, key factories, and the parts that do not compare the way you expect.
- [Query functions](https://dualmeta-gmbh.github.io/query_kit/docs/guides/query-functions.md): A query function returns a Future and throws on failure — a repository on dio or package:http, error types a retry policy can read, cancellation, and what the function context carries.
- [Describing a query once](https://dualmeta-gmbh.github.io/query_kit/docs/guides/query-options.md): Options functions, the two observer options shapes, withSelect, what null means, and why options built in build are fine.
- [Parallel queries](https://dualmeta-gmbh.github.io/query_kit/docs/guides/parallel-queries.md): Several queries at once — separate reads that run side by side in every call style, QueriesBuilder for a list that changes length or order, and one loading indicator over all of them.
- [Combining queries](https://dualmeta-gmbh.github.io/query_kit/docs/guides/combining-queries.md): combine over a record or a list of results — the pending, error and data rules, optional sources, combineWith, CombineMemo and keys.
- [Dependent queries](https://dualmeta-gmbh.github.io/query_kit/docs/guides/dependent-queries.md): A query that needs another query's result waits with enabled — the pattern in each call style, Enabled.yes, Enabled.no and Enabled.when, and why it is still a waterfall.
- [Disabling queries](https://dualmeta-gmbh.github.io/query_kit/docs/guides/disabling-queries.md): Enabled.no keeps a query from fetching on its own — a query run only on demand, a search that waits for input, what a disabled query still does, and why there is no skipToken.
- [Side effects](https://dualmeta-gmbh.github.io/query_kit/docs/guides/side-effects.md): Navigation, snackbars and analytics on a change of a result — QueryListener, InfiniteQueryListener and MutationListener, mutation callbacks, and the global callbacks for the whole app.

### Refetching and the network

- [Background fetching indicators](https://dualmeta-gmbh.github.io/query_kit/docs/guides/background-fetching-indicators.md): Show that a query is refreshing without hiding the data it already has — isRefetching on one result, and IsFetchingController for an app-wide progress bar.
- [App focus refetching](https://dualmeta-gmbh.github.io/query_kit/docs/guides/window-focus-refetching.md): Stale queries refetch when the user comes back to the app — how Flutter's app lifecycle becomes focus on phones, desktop and the web, how to turn it off or narrow it, and how to bring your own focus source.
- [Network mode and offline](https://dualmeta-gmbh.github.io/query_kit/docs/guides/network-mode.md): What queries and mutations do while the client believes it is offline — online, always and offlineFirst — how paused work shows on the result, and how it resumes.
- [Connectivity](https://dualmeta-gmbh.github.io/query_kit/docs/guides/connectivity.md): Telling the client whether it is online — nothing is installed by default; OnlineStatus.fixed and OnlineStatus.stream, a connectivity_plus adapter, and a reachability probe, because a link is not the internet.
- [Polling](https://dualmeta-gmbh.github.io/query_kit/docs/guides/polling.md): refetchInterval refetches a query on a timer while a reader is on screen — fixed or computed intervals, polling in the background, stopping when the server confirms, and giving up after failures in a row.
- [Query retries](https://dualmeta-gmbh.github.io/query_kit/docs/guides/query-retries.md): A failed query is retried before the error reaches the screen — RetryPolicy and RetryDelay, not retrying a 4xx, honouring Retry-After, and showing the attempts in the UI.
- [Query cancellation](https://dualmeta-gmbh.github.io/query_kit/docs/guides/query-cancellation.md): Every query function receives a QueryCancelToken — bridging it to dio and package:http, stopping work done in steps, and what cancelQueries, a leaving screen and a refetch each do to a fetch in flight.

### Paging and early data

- [Paginated queries](https://dualmeta-gmbh.github.io/query_kit/docs/guides/paginated-queries.md): One page at a time with the page number in the key — PlaceholderData.keepPrevious keeps the last page on screen while the next loads, and a prefetch makes Next instant.
- [Infinite queries](https://dualmeta-gmbh.github.io/query_kit/docs/guides/infinite-queries.md): A list of pages behind one key — pageFn, getNextPageParam and maxPages, why paging lives on the controller, and a scrolling list with load-on-scroll and pull-to-refresh.
- [Initial query data](https://dualmeta-gmbh.github.io/query_kit/docs/guides/initial-query-data.md): InitialData seeds the cache with data the app already has — a bundled catalogue, a row from the list screen — and initialDataUpdatedAt says how old it is, so staleTime decides whether to fetch.
- [Placeholder query data](https://dualmeta-gmbh.github.io/query_kit/docs/guides/placeholder-query-data.md): PlaceholderData is shown while the real fetch runs and never written to the cache — a fixed stand-in, a row borrowed from the list, or the previous key's data — flagged isPlaceholderData so the screen can render it as provisional.
- [Scroll restoration](https://dualmeta-gmbh.github.io/query_kit/docs/guides/scroll-restoration.md): A list comes back where it was when its data is still cached, because the first build already has the rows — and what Flutter needs from you, a PageStorageKey or a restorationId, to put the position back.

### Mutations

- [Mutations](https://dualmeta-gmbh.github.io/query_kit/docs/guides/mutations.md): The four ways to read a mutation, MutationResult, mutate and mutateAsync, per-call callbacks, identity, and mutation defaults.
- [Query invalidation](https://dualmeta-gmbh.github.io/query_kit/docs/guides/query-invalidation.md): invalidateQueries marks matching queries stale and refetches the ones on screen — prefix matching, exact, predicates, refetchType and cancelRefetch.
- [Invalidations from mutations](https://dualmeta-gmbh.github.io/query_kit/docs/guides/invalidations-from-mutations.md): Invalidate the queries a write affected from its onSuccess or onSettled — which keys, which callback, and what returning the future does to the mutation's state.
- [Updates from mutation responses](https://dualmeta-gmbh.github.io/query_kit/docs/guides/updates-from-mutation-responses.md): Write what a mutation returned straight into the cache — setQueryData, updateQueryData and updateQueriesData, immutable updates, and the one-key-one-type rule.
- [Optimistic updates](https://dualmeta-gmbh.github.io/query_kit/docs/guides/optimistic-updates.md): Show a write before the server confirms it — drawn from the pending mutation's variables, or patched into the cache in onMutate and rolled back on error.
- [Mutation scopes](https://dualmeta-gmbh.github.io/query_kit/docs/guides/mutation-scopes.md): MutationScope runs the mutations that share it one at a time, in the order they were started — for writes to the same thing that must not race.
- [Cancelling mutations](https://dualmeta-gmbh.github.io/query_kit/docs/guides/cancelling-mutations.md): mutationFnWithContext, the signal cancel() cancels, and why cancelling a write fails it rather than reverting it.
- [Mutation state](https://dualmeta-gmbh.github.io/query_kit/docs/guides/mutation-state.md): MutationStateController and MutationStateObserver — every mutation matching a filter, for a "saving…" badge no widget owns, and its typed form.

### The cache and performance

- [Filters](https://dualmeta-gmbh.github.io/query_kit/docs/guides/filters.md): QueryFilters and MutationFilters — the one named filters argument every bulk operation takes, what each field matches, and how to match a query yourself.
- [Request waterfalls](https://dualmeta-gmbh.github.io/query_kit/docs/guides/request-waterfalls.md): When one request cannot start before another has answered — where waterfalls come from in a widget tree, and how hoisting, prefetching and flatter reads avoid them.
- [Prefetching](https://dualmeta-gmbh.github.io/query_kit/docs/guides/prefetching.md): client.query fetches imperatively — await it, ignore it to prefetch on tap, hover or in a route redirect, fetch only when nothing is cached, or serve the cache and revalidate behind it.
- [Caching](https://dualmeta-gmbh.github.io/query_kit/docs/guides/caching.md): How long data is fresh (StaleTime), how long an unobserved entry is kept (GcTime), and what happens to a query from its first read to garbage collection.
- [What rebuilds, and when](https://dualmeta-gmbh.github.io/query_kit/docs/guides/render-optimizations.md): select narrows what a widget reads; buildWhen narrows when it rebuilds. They are not the same tool.
- [Structural sharing](https://dualmeta-gmbh.github.io/query_kit/docs/guides/structural-sharing.md): A refetch that brings back equal data keeps the cached instances — what is shared, why a model needs ==, StructurallyShareable, and turning it off.
- [Default query function](https://dualmeta-gmbh.github.io/query_kit/docs/guides/default-query-function.md): Register a queryFn per key prefix with setQueryDefaults, so options without one derive the request from the key — its types, its mutation twin, and client-wide defaults.
- [Global callbacks](https://dualmeta-gmbh.github.io/query_kit/docs/guides/global-callbacks.md): QueryCache and MutationCache callbacks run for every query or mutation of a client — one error SnackBar for the whole app, a per-query opt-out through meta, and one invalidation rule for every write.

### Tools and architecture

- [Debugging](https://dualmeta-gmbh.github.io/query_kit/docs/guides/debugging.md): There are no devtools — what the cache can tell you instead, by subscribing to its events, reading its entries, or putting a small inspector on screen.
- [Testing](https://dualmeta-gmbh.github.io/query_kit/docs/guides/testing.md): The teardown every widget test needs, a harness that wraps it, a client without retries, and the pump rules that fake timers impose.
- [Without Flutter](https://dualmeta-gmbh.github.io/query_kit/docs/guides/pure-dart.md): Using query_kit on its own — observers, subscribe, and the one thing you have to do yourself.
- [Does this replace state management?](https://dualmeta-gmbh.github.io/query_kit/docs/guides/does-this-replace-state-management.md): Server state and client state are different problems — what moves into the cache, what stays in your state-management package, and how the two meet.

## Examples

- [Examples](https://dualmeta-gmbh.github.io/query_kit/docs/examples.md): Every feature as a live screen you can run in the browser, one whole small app that composes them, and the package's one-file example.
- [Task manager](https://dualmeta-gmbh.github.io/query_kit/docs/examples/task-manager.md): One small, whole app on query_kit — a shared list and detail, optimistic writes with rollback, and a poll that stops once the server confirms.
- [One-file tour](https://dualmeta-gmbh.github.io/query_kit/docs/examples/one-file-tour.md): The package's own example, a provider, one query read two ways and a mutation that invalidates it, in a single file with no server.

### Basics

- [Simple](https://dualmeta-gmbh.github.io/query_kit/docs/examples/simple.md): One query read in build, its three states told apart with a switch, and a refetch that keeps the data on screen.
- [Basic](https://dualmeta-gmbh.github.io/query_kit/docs/examples/basic.md): A list and a detail sharing one cache, a mark on every row the cache already holds, and a detail entry that is dropped once nobody reads it.
- [Four call styles](https://dualmeta-gmbh.github.io/query_kit/docs/examples/four-call-styles.md): One query read through context.query, QueryBuilder, QueryMixin and QueryController at once, with the listeners and the mutation and infinite-query counterparts beside them.

### Queries

- [Default query function](https://dualmeta-gmbh.github.io/query_kit/docs/examples/default-query-function.md): Queries that are nothing but a key, fetched by one function registered as a default for a key prefix, and a mutation that gets its function the same way.
- [Dependent queries](https://dualmeta-gmbh.github.io/query_kit/docs/examples/dependent-queries.md): A query that holds back until another has data, with Enabled.when, and a switch that holds it back regardless with Enabled.no.
- [Parallel queries](https://dualmeta-gmbh.github.io/query_kit/docs/examples/parallel-queries.md): Three independent queries in one screen, fetched at the same time, and the client's count of everything that is fetching.
- [Query collections](https://dualmeta-gmbh.github.io/query_kit/docs/examples/query-collections.md): A list of queries of one type that grows, shrinks and reorders at runtime, read with QueriesBuilder and again with a QueriesController.
- [Combine](https://dualmeta-gmbh.github.io/query_kit/docs/examples/combine.md): Three queries of three different types read as one sealed CombinedResult, with a retry for the failed sources only and a memo that skips the combiner when nothing changed.
- [Initial and placeholder data](https://dualmeta-gmbh.github.io/query_kit/docs/examples/initial-and-placeholder.md): Showing something before the first fetch returns, either as initial data written to the cache or as placeholder data that is only displayed.
- [Select and structural sharing](https://dualmeta-gmbh.github.io/query_kit/docs/examples/select-and-sharing.md): Five readers of one cache entry, each selecting something different, with build counters that show which changes reach which reader.

### Paging

- [Pagination](https://dualmeta-gmbh.github.io/query_kit/docs/examples/pagination.md): Page-numbered results, one cache entry per page, the previous page kept on screen while the next loads, and the next page prefetched.
- [Load more and infinite scroll](https://dualmeta-gmbh.github.io/query_kit/docs/examples/load-more.md): One infinite query that appends a page per cursor, from a button or from scrolling near the end, and whose pages outlive the list that read them.
- [Infinite query with max pages](https://dualmeta-gmbh.github.io/query_kit/docs/examples/max-pages.md): An infinite query that pages in both directions from the middle of the data and keeps a window of at most three pages.

### Mutations

- [Mutations](https://dualmeta-gmbh.github.io/query_kit/docs/examples/mutations.md): One write fired with mutate and with mutateAsync, its states and reset, the order its callbacks run in, scopes that queue writes, and a write that outlives its widget.
- [Optimistic updates](https://dualmeta-gmbh.github.io/query_kit/docs/examples/optimistic-updates.md): A new row on screen before the server confirms it, two ways — rendered from the pending mutation's variables, or written into the cache and rolled back on error.
- [Mutation context and cancel](https://dualmeta-gmbh.github.io/query_kit/docs/examples/mutation-cancel.md): An optimistic rename whose mutation function reads what onMutate kept and passes the cancel signal to its transport, and a Cancel button that fails the run so the rollback runs.
- [Mutation state](https://dualmeta-gmbh.github.io/query_kit/docs/examples/mutation-state.md): A badge that counts every running and failed write under one mutation key, read from the mutation cache by a widget that owns none of them.

### Cache

- [Prefetching](https://dualmeta-gmbh.github.io/query_kit/docs/examples/prefetching.md): Fetch a detail into the cache before its screen opens, so opening it costs no request, and the three imperative reads side by side.
- [Stale time and garbage collection](https://dualmeta-gmbh.github.io/query_kit/docs/examples/stale-and-gc.md): Every StaleTime and GcTime value on one cache entry, with a reader you can detach and attach to see when data refetches and when an unused entry is dropped.
- [Invalidation and filters](https://dualmeta-gmbh.github.io/query_kit/docs/examples/invalidation-and-filters.md): The client's bulk operations — invalidate, refetch, reset, remove, cancel and update — run over one small cache with a key prefix, exact, type, stale and predicate filters.
- [Playground](https://dualmeta-gmbh.github.io/query_kit/docs/examples/playground.md): A todo list and an editor with four live knobs — stale time, gc time, latency and error rate — turned while the queries are on screen.
- [Cache inspector](https://dualmeta-gmbh.github.io/query_kit/docs/examples/cache-inspector.md): Every entry and every event of the query and mutation caches, live, with buttons that load, refetch, invalidate and remove entries.

### Network

- [Auto refetching](https://dualmeta-gmbh.github.io/query_kit/docs/examples/auto-refetching.md): A list polled on an interval that can be switched live between off, two fixed values and one computed from the data, with and without polling in the background.
- [Retry](https://dualmeta-gmbh.github.io/query_kit/docs/examples/retry.md): Every retry policy and delay on one query, with failures scripted on the backend, and what the result reports while the retries run.
- [Cancellation](https://dualmeta-gmbh.github.io/query_kit/docs/examples/cancellation.md): A slow fetch cancelled by hand, with and without the signal reaching the transport, and search-as-you-type that cancels the needle in flight.
- [Offline](https://dualmeta-gmbh.github.io/query_kit/docs/examples/offline.md): A query and a mutation under a connection you switch off and on, compared across the three network modes, with paused mutations resuming on reconnect.
- [Focus refetch](https://dualmeta-gmbh.github.io/query_kit/docs/examples/focus-refetch.md): Every RefetchOn value for app focus and for mount, a minimum background time before a return refetches, and the provider's own focus and connectivity settings.

### Advanced

- [Filtering rebuilds](https://dualmeta-gmbh.github.io/query_kit/docs/examples/build-when.md): buildWhen on the eight keyless reads, each read twice over one entry, filtered and plain, with build counters side by side.
- [Global callbacks](https://dualmeta-gmbh.github.io/query_kit/docs/examples/global-callbacks.md): QueryCache and MutationCache callbacks logged as they fire, meta deciding which failures get a SnackBar, and meta reaching the query function.
- [Diagnostics](https://dualmeta-gmbh.github.io/query_kit/docs/examples/diagnostics.md): The errors the library raises for a read or write of the wrong type and for a mutation with no function, and the fix for each.

## Cookbook

- [Cookbook](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook.md): Recipes for tasks that combine several features — each one a complete, compiled answer to "how do I…".
- [Wiring dio or package:http](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/wiring-dio-and-http.md): One API client for every query — cancellation handed on to the transport, timeouts, and failures turned into errors a screen can show.
- [Auth and token refresh](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/auth-and-token-refresh.md): Refresh an expired token once for every request that hit it, never retry a refused request, and give each signed-in user a cache of their own.
- [List to detail, seeded](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/list-detail-seeding.md): Open a detail screen with the data the list already has — no spinner, no second request — and still refetch it when it is old.
- [Lifecycle and connectivity wiring](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/lifecycle-and-connectivity-wiring.md): One main.dart that tells the client when the app is in front and when the network is there — connectivity_plus, a reachability probe, a calmer focus refetch and a debug offline switch.
- [Pull to refresh](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/pull-to-refresh.md): A RefreshIndicator whose spinner lasts exactly as long as the refetch, keeps the list on screen when the refresh fails, and works on an empty list too.
- [Search as you type](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/search-as-you-type.md): A debounced search box that asks the server nothing while empty, cancels the request a newer keystroke replaced, and keeps the last results on screen while the next arrive.
- [Forms and server validation](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/forms-and-server-validation.md): An edit form driven by a mutation — disabled while saving, the server's field errors next to the fields, the cache updated from the response, and the screen closed on success.
- [A global error snackbar](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/global-error-snackbar.md): One place that turns failed background refreshes and failed saves into a SnackBar — once per failure, never for what a screen already shows, and with a per-query way out.
- [An infinite list view](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/infinite-list-view.md): A ListView that loads the next page as the user nears the end — once per page, with a footer that shows progress, a retry and the end of the list, and pull-to-refresh on top.
- [Testing a screen](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/testing-a-screen.md): Widget tests for screens that read queries — a fake API with latency, a harness with the teardown built in, and tests for loading, errors, seeded data, staleness and a refused save.
- [Next to Riverpod, Bloc or Provider](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/riverpod-bloc-provider.md): Keep server state in query_kit and app state in your state-management package, and connect the two through QueryController without keeping a second copy.
- [Offline first, and surviving a restart](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/offline-first-and-persistence.md): Save chosen queries and unsent writes to disk, restore them before the first frame, and let paused writes go out when the network comes back.
- [Where the client lives](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/dependency-injection.md): Create the QueryClient once, provide it with QueryClientProvider, reach it with of, maybeOf and read, and register it in get_it when code outside the tree needs it.
- [Routing with go_router](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/routing-go-router.md): Derive query keys from path parameters, prefetch before a route opens, refetch when the user comes back, and read queries in dialogs.
- [Realtime updates over a WebSocket](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/realtime-websockets.md): Let server events write to the cache or invalidate it, keep the socket's lifetime in one widget, and resynchronise after a reconnect.
- [Poll until a device confirms](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/poll-until-confirmed.md): A write the server accepts but a device confirms later, with the requested value shown at once, a poll that starts and stops itself, and a clear state for giving up.
- [Disconnecting a device](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/device-and-iot-disconnect.md): Stop every query for a device the user disconnected, with no request sent to it afterwards and no old reading left in the cache.
- [Sign out and multiple accounts](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/sign-out-and-multi-account.md): Give each signed-in user a fresh cache, empty it at sign-out without a refetch storm, warn about unsent writes, and keep several accounts apart in one client.
- [Normalised data or one key per entity](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/normalised-vs-per-entity-keys.md): When to cache a list plus one entry per item, when to cache a map by id, and how to keep unchanged items' instances either way.
- [Models with freezed and JSON](https://dualmeta-gmbh.github.io/query_kit/docs/cookbook/freezed-and-json-models.md): What a model needs to work well in the cache, how freezed and json_serializable provide it, and why a wrapper class needs StructurallyShareable to keep unchanged items.

## API reference

- [API reference](https://dualmeta-gmbh.github.io/query_kit/docs/reference/api.md): 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.
- [QueryClient](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-client.md): Every member of QueryClient — constructor, reads, writes, bulk operations, defaults and lifecycle — with its signature and what it does.
- [Options reference](https://dualmeta-gmbh.github.io/query_kit/docs/reference/query-options.md): Every field of the query, infinite-query and mutation options, with its type, its built-in default and what it does.
- [Results](https://dualmeta-gmbh.github.io/query_kit/docs/reference/results.md): Every field of what a reader is handed — QueryResult and its cases, QueryState, InfiniteData and the paging flags, MutationResult and MutationState, and CombinedResult.
- [Widgets and controllers](https://dualmeta-gmbh.github.io/query_kit/docs/reference/widgets-and-controllers.md): Every public widget, controller, extension and mixin of query_kit_flutter, with its parameters, defaults and meaning; the TanStack Query counterpart is named where there is one.
- [Caches and observers](https://dualmeta-gmbh.github.io/query_kit/docs/reference/caches-and-observers.md): The query and mutation caches, their entries and events, the five observers, the filters that select entries, and the three managers — every public member a user touches.
- [Errors](https://dualmeta-gmbh.github.io/query_kit/docs/reference/errors.md): Every error query_kit and query_kit_flutter throw or record, every debug-build check you can trip, and what to do about each.
- [Feature matrix](https://dualmeta-gmbh.github.io/query_kit/docs/reference/feature-matrix.md): What is here, and what is deliberately not in 1.0.
- [Troubleshooting](https://dualmeta-gmbh.github.io/query_kit/docs/reference/troubleshooting.md): Symptom first — what you see, why it happens, and what to do instead.
- [Differences from TanStack Query](https://dualmeta-gmbh.github.io/query_kit/docs/reference/differences-from-tanstack.md): Where query_kit behaves differently from TanStack Query on purpose — the shape of the API, the rules Dart's type system adds, and the failure cases it settles differently.

## Optional

- [Credits, and what this is not](https://dualmeta-gmbh.github.io/query_kit/docs/project/credits.md): A port of TanStack Query, with thanks — unaffiliated with TanStack, and written by AI.
- [How fidelity is proven](https://dualmeta-gmbh.github.io/query_kit/docs/project/fidelity.md): TanStack Query's suite ported case by case, what porting found, what review and real use found, and where every omission is written down.
- [How the examples are built](https://dualmeta-gmbh.github.io/query_kit/docs/project/examples.md): How the examples are built and tested — the one-file tour, the showcase against a real backend, and the acceptance demo.