Venant de TanStack Query

Qora partage le même modèle conceptuel que TanStack Query : clés de requête, stale-while-revalidate, refetch en arrière-plan, hooks de cycle de vie des mutations et pause-et-replay hors-ligne. La plupart des concepts se traduisent directement. Cette page met en correspondance ce que vous connaissez déjà avec l'API Qora.

Correspondance des concepts

Référence API : requêtes

Options

Valeurs de retour

Référence API : mutations

Options

Valeurs de retour / state

Référence API : QueryClient vers QoraClient

Différences clés

Les classes scellées remplacent les chaînes de statut

TanStack Query retourne des objets simples avec des champs status sous forme de chaîne et des raccourcis booléens (isLoading, isError, etc.). Qora retourne une classe scellée QoraState<T>. La correspondance de motifs exhaustive de Dart 3 est appliquée à la compilation, éliminant les branches d'état non gérées :

// 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!),
};

Le bras _ couvre Success, Loading(previousData != null) et Failure(previousData != null) : tous les cas où les données sont disponibles.

previousData est toujours présent

TanStack Query v5 conserve les données précédentes avec placeholderData: keepPreviousData. Dans Qora, Loading<T> et Failure<T> portent toujours previousData: T? : les données périmées restent accessibles pendant les rafraîchissements en arrière-plan et après une erreur, sans aucune option.

// Afficher les données périmées avec un indicateur pendant un rafraîchissement
case Loading(:final previousData) when previousData != null:
  return Stack(children: [
    UserCard(previousData),
    const LinearProgressIndicator(minHeight: 2),
  ]);

Si vous préférez que l'entrée reste en Success pendant le refetch, par exemple pour garder un tableau paginé stable, utilisez keepPreviousData: true.

select filtre les rebuilds, il ne transforme pas

Dans TanStack Query, select transforme les données renvoyées au composant. Dans Qora, select sur QoraBuilder et useQuery décide quand le widget se reconstruit : uniquement quand le type d'état ou la valeur sélectionnée change. L'état reçu est toujours l'état complet.

Pour transformer les données, Qora propose deux outils :

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

// Qora : transformer une fois, dans le cache (tous les abonnés voient le résultat)
QoraOptions(transform: (raw) => User.fromJson(raw as Map<String, dynamic>));

// Qora : transformer par consommateur, sur l'état
final nameState = userState.map((user) => user.name);
// QoraState<User> → QoraState<String>, previousData compris

// Qora : reconstruire uniquement quand le nom change
QoraBuilder<User>(
  queryKey: ['users', id],
  fetcher: () => api.getUser(id),
  select: (user) => user.name,
  builder: (context, state, _) => Text(state.dataOrNull?.name ?? ''),
);

gcTime remplace cacheTime

Qora utilise le nom de TanStack Query v5. gcTime est la durée pendant laquelle une entrée inactive reste en mémoire après l'annulation de son dernier abonné.

API Widget vs API Hook

L'API principale de React Query est basée sur les hooks (useQuery, useMutation). Qora fournit les deux :

• QoraBuilder<T> et QoraMutationBuilder fonctionnent dans tout StatelessWidget ou StatefulWidget.
• useQuery<T> et useMutation nécessitent HookWidget de flutter_hooks.

Les deux partagent le même cache QoraClient. Si un QoraBuilder a déjà récupéré ['users', id], useQuery l'obtient au premier frame depuis la même entrée.

QoraScope est un StatefulWidget, pas un Provider

TanStack Query utilise QueryClientProvider (contexte React). Qora utilise QoraScope, un StatefulWidget qui expose le client à son sous-arbre via un InheritedWidget interne. Accéder au client depuis n'importe quel descendant via context.qora ou QoraScope.of(context).

La persistance nécessite un enregistrement explicite des sérialiseurs

Les plugins de persistance de TanStack Query (ex. createSyncStoragePersister) utilisent JSON.stringify / JSON.parse sur le cache de requêtes complet. Qora nécessite un enregistrement explicite des sérialiseurs par type car Dart n'a pas de réflexion à l'exécution :

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

La chaîne name doit être stable entre les versions de l'application et les modes de build (y compris les builds obfusqués).

Pas d'équivalent React Suspense

TanStack Query supporte suspense: true pour s'intégrer avec React Suspense. Flutter n'a pas de mécanisme équivalent. Tout état asynchrone est géré via la correspondance de motifs sur QoraState<T> dans l'arbre de widgets.

Requêtes infinies

DevTools

Les DevTools de TanStack Query sont un panneau navigateur installé comme composant React. L'équivalent dans Qora est un overlay intégré à l'application : installez qora_devtools_overlay et enveloppez l'application avec QoraInspector. Il montre les requêtes, les mutations et une timeline, et n'affiche rien en build release.

Voir Vue d'ensemble des DevTools pour les instructions de configuration.

Liens connexes

• Qu'est-ce que Qora : vue d'ensemble conceptuelle
• Démarrage rapide : configuration en cinq minutes
• QoraState : référence de la classe scellée
• QoraOptions : référence complète des options par requête
• QoraClientConfig : référence de la configuration globale