Coming from TanStack Query

Qora shares the same conceptual model as TanStack Query: query keys, stale-while-revalidate, background refetch, mutation lifecycle hooks, and offline pause-and-replay. Most concepts translate directly. This page maps what you already know to the Qora API.

Concept Map

API Reference: Queries

Options

Return values

API Reference: Mutations

Options

Return values / state

API Reference: QueryClient → QoraClient

Key Differences

Sealed classes replace status strings

TanStack Query returns plain objects with string status fields and boolean shortcuts (isLoading, isError, etc.). Qora returns a sealed class QoraState<T>. Dart 3 pattern matching makes exhaustive handling compile-time enforced:

// TanStack Query (React)
if (isLoading) return <Spinner />;
if (isError) return <Error error={error} />;
return <UserCard user={data} />;

// Qora (Dart 3)
return switch (state) {
  Initial() || Loading(previousData: null) => const CircularProgressIndicator(),
  Failure(:final error, previousData: null) => ErrorScreen(error),
  _ => UserCard(state.dataOrNull!),
};

The _ arm covers Success, Loading(previousData != null), and Failure(previousData != null): all cases where data is available.

previousData is always present

TanStack Query v5 keeps the previous data with placeholderData: keepPreviousData. In Qora, Loading<T> and Failure<T> always carry previousData: T?, so stale data stays accessible during background refreshes and after errors without any option.

// Show stale data with a progress indicator during a background refresh
case Loading(:final previousData) when previousData != null:
  return Stack(children: [
    UserCard(previousData),
    const LinearProgressIndicator(minHeight: 2),
  ]);

If you prefer the entry to stay in Success while it refetches, for example to keep a paginated table stable, set keepPreviousData: true.

select filters rebuilds, it does not transform

In TanStack Query, select transforms the data returned to the component. In Qora, select on QoraBuilder and useQuery decides when the widget rebuilds: only when the state kind or the selected value changes. The state you receive is always the full one.

To transform data, Qora offers two tools:

// TanStack Query
useQuery({ queryKey, queryFn, select: (data) => data.name });

// Qora: transform once, in the cache (every subscriber sees the result)
QoraOptions(transform: (raw) => User.fromJson(raw as Map<String, dynamic>));

// Qora: transform per consumer, on the state
final nameState = userState.map((user) => user.name);
// QoraState<User> → QoraState<String>, previousData included

// Qora: rebuild only when the name changes
QoraBuilder<User>(
  queryKey: ['users', id],
  fetcher: () => api.getUser(id),
  select: (user) => user.name,
  builder: (context, state, _) => Text(state.dataOrNull?.name ?? ''),
);

gcTime replaces cacheTime

Qora uses the TanStack Query v5 name. gcTime is the time an inactive entry stays in memory after its last subscriber cancels.

Widget API vs hook API

React Query's primary API is hooks (useQuery, useMutation). Qora provides both a widget API and a hook API:

• QoraBuilder<T> and QoraMutationBuilder work in any StatelessWidget or StatefulWidget.
• useQuery<T> and useMutation require HookWidget from flutter_hooks.

Both share the same QoraClient cache. If a QoraBuilder already fetched ['users', id], useQuery gets it on the first frame from the same entry.

QoraScope is a StatefulWidget, not a Provider

TanStack Query uses QueryClientProvider (React context). Qora uses QoraScope, a StatefulWidget that exposes the client to its subtree via an internal InheritedWidget. Access the client from any descendant via context.qora or QoraScope.of(context).

Persistence requires explicit serializer registration

TanStack Query's persistence plugins (e.g. createSyncStoragePersister) use JSON.stringify / JSON.parse on the full query cache. Qora requires explicit serializer registration per type because Dart has no runtime reflection:

// Required before hydrate()
client.registerSerializer<User>(
  QoraSerializer(toJson: (u) => u.toJson(), fromJson: User.fromJson),
  name: 'User',
);
await client.hydrate();

The name string must be stable across app versions and build modes (including obfuscated builds).

No React Suspense equivalent

TanStack Query supports suspense: true to integrate with React Suspense. Flutter has no equivalent mechanism. All async state is handled through QoraState<T> pattern matching in the widget tree.

Infinite Queries

DevTools

TanStack Query DevTools is a browser panel installed as a React component. Qora's equivalent is an in-app overlay: install qora_devtools_overlay and wrap the app with QoraInspector. It shows queries, mutations and a timeline, and renders nothing in release builds.

See DevTools overview for setup instructions.

Related

• What is Qora: conceptual overview
• Quick Start: five-minute setup
• QoraState: sealed class reference
• QoraOptions: full per-query option reference
• QoraClientConfig: global configuration reference