Cache

QoraOptions(
  staleTime: Duration(minutes: 5),   // données fraîches pendant 5 minutes
  gcTime: Duration(minutes: 10),  // données inutilisées conservées 10 min en cache
)

// staleTime : 5 minutes

// t = 0:00 → fetch déclenché, Success stocké
// t = 0:01 → fetchQuery → Cache HIT (frais) : pas d'appel réseau
// t = 5:01 → fetchQuery → Cache HIT (périmé) : retourne les données en cache + revalide
// t = 5:01 → requête réseau déclenchée en arrière-plan
// t = 5:02 → Success mis à jour, abonnés au stream notifiés

// Données de configuration : valides pendant 1 heure
options: QoraOptions(staleTime: Duration(hours: 1)),

// Profil utilisateur : valide pendant 10 minutes
options: QoraOptions(staleTime: Duration(minutes: 10)),

// Prix en direct : toujours périmé (défaut)
options: QoraOptions(staleTime: Duration.zero),

// L'utilisateur quitte → dernier abonné annule → timer GC démarre
// L'utilisateur revient dans gcTime → entrée toujours en cache → affichage instantané
// L'utilisateur revient après gcTime → entrée évincée → fetch complet requis

// Liste de posts : conserver en cache 2 minutes après avoir quitté la page
options: QoraOptions(gcTime: Duration(minutes: 2)),

// Sans partage structurel : chaque fetch crée une nouvelle référence,
// ce qui oblige tous les widgets consommant cette requête à se reconstruire.
//
// Avec partage structurel (défaut) : si les données retournées sont
// structurellement identiques aux données en cache, l'ancienne référence
// est conservée. Les widgets qui vérifient identical(oldData, newData)
// ou == ignorent le rendu.

final client = QoraClient();
await client.fetchQuery<Map<String, dynamic>>(
  key: ['config'],
  fetcher: () => api.getConfig(),
  options: QoraOptions(structuralSharing: true),
);

final oldData = {'user': {'name': 'Alice', 'roles': ['admin']}};
final newData = {'user': {'name': 'Alice', 'roles': ['admin']}};

// structuralShare retourne oldData, elles sont profondément égales.
// Tout widget détenant oldData verra identical(oldData, newData) == true.

QoraOptions(structuralSharing: false),

fetchQuery<User>(
  key: ['users', userId],
  fetcher: () => api.getUser(userId),  // retourne Map<String, dynamic>
  options: QoraOptions(
    transform: (raw) => User.fromJson(raw as Map<String, dynamic>),
  ),
);

fetchQuery<Post>(
  key: ['post', postId],
  fetcher: () => api.getPost(postId),
  options: QoraOptions(
    transformError: (error) => AppError.fromException(error),
  ),
);

fetchQuery<List<Post>>(
  key: ['posts', 'page', page],
  fetcher: () => api.getPosts(page: page, limit: 20),
  options: QoraOptions(
    keepPreviousData: true,
    staleTime: Duration.zero,
  ),
);

final client = QoraClient(
  config: QoraClientConfig(maxCacheSize: 100),
);

// Obtenir uniquement les données (null si pas Success / pas de previousData)
final user = client.getQueryData<User>(['users', userId]);

// Obtenir l'état complet
final state = client.getQueryState<User>(['users', userId]);

// Inspecter toutes les clés en cache
for (final key in client.cachedKeys) {
  print(key);
}

// Injecter des données directement : tous les streams watchQuery actifs sont notifiés
client.setQueryData<User>(['users', userId], updatedUser);

// Rollback vers un snapshot précédent
final snapshot = client.getQueryData<User>(['users', userId]);
client.setQueryData(['users', userId], optimisticUser);

try {
  await api.updateUser(userId, payload);
} catch (_) {
  client.restoreQueryData(['users', userId], snapshot);
}

// Clé unique : les streams actifs passent immédiatement à Loading
client.invalidate(['users', userId]);

// Plusieurs clés via prédicat
client.invalidateWhere((key) => key.firstOrNull == 'users');

// Basée sur des tags : revalider toutes les requêtes fournissant le tag 'post'
client.invalidateTags([QueryTag('post')]);

// Ressource spécifique : revalider uniquement les requêtes avec QueryTag('post', '123')
client.invalidateTags([QueryTag('post', '123')]);

options: QoraOptions(
  providesTags: [QueryTag('post'), QueryTag('user', userId)],
)

// Supprimer une entrée unique (GC immédiat)
client.removeQuery(['users', userId]);

// Vider le cache entier (ex. lors d'une déconnexion)
client.clear();

final client = QoraClient(
  config: QoraClientConfig(
    onCacheEvict: (key) {
      analytics.track('cache_evict', {'key': key.toString()});
    },
  ),
);

print(client.debugInfo());
// {
//   total_queries: 12,
//   active_queries: 3,
//   inactive_queries: 9,
//   non_success_queries: 1,
//   pending_requests: 2,
//   max_size: 100,
//   keys: [['users', 1], ['posts'], ...]
// }

final client = QoraClient(
  config: QoraClientConfig(
    defaultOptions: QoraOptions(
      staleTime: Duration(minutes: 5),  // défaut global
      gcTime: Duration(minutes: 10),
    ),
  ),
);

// Cette requête surcharge uniquement staleTime
await client.fetchQuery<Config>(
  key: ['config'],
  fetcher: api.getConfig,
  options: QoraOptions(staleTime: Duration(hours: 1)),
  // gcTime hérite toujours des 10 minutes du global
);