QoraClientConfig

Vue d'ensemble

QoraClientConfig est passé au constructeur de QoraClient et définit les défauts pour chaque requête pendant toute la durée de vie du client. Les requêtes individuelles peuvent remplacer n'importe quel champ via QoraOptions.

final client = QoraClient(
  config: QoraClientConfig(
    defaultOptions: QoraOptions(
      staleTime: Duration(minutes: 5),
      gcTime: Duration(minutes: 10),
      retryCount: 3,
    ),
    debugMode: kDebugMode,
    maxCacheSize: 200,
    refetchOnMount: true,
    errorMapper: (error, stack) => QoraException(
      '$error',
      originalError: error,
      stackTrace: stack,
    ),
  ),
);

Constructeur

const QoraClientConfig({
  QoraOptions defaultOptions = const QoraOptions(),
  QoraException Function(Object error, StackTrace? stackTrace)? errorMapper,
  bool debugMode = false,
  int? maxCacheSize,
  void Function(List<dynamic> key)? onCacheEvict,
  void Function(Object error, StackTrace? stackTrace, List<dynamic> queryKey)? onBackgroundFetchError,
  bool refetchOnMount = true,
  ReconnectStrategy reconnectStrategy = const ReconnectStrategy(),
})

Champs

defaultOptions

final QoraOptions defaultOptions

Défaut : QoraOptions() (tous les défauts)

Le QoraOptions de référence appliqué à chaque requête. Les options par requête sont fusionnées par-dessus via QoraOptions.merge().

defaultOptions: QoraOptions(
  staleTime: Duration(minutes: 5),
  gcTime: Duration(minutes: 10),
  retryCount: 3,
  retryDelay: Duration(seconds: 1),
),

Voir QoraOptions pour tous les champs disponibles.

errorMapper

final QoraException Function(Object error, StackTrace? stackTrace)? errorMapper

Défaut : null (les erreurs sont stockées telles quelles)

Transforme les erreurs brutes en QoraException avant qu'elles soient stockées dans les états Failure. Utiliser pour normaliser les types d'erreurs spécifiques à l'API en une forme cohérente dans l'application :

errorMapper: (error, stackTrace) {
  if (error is DioException) {
    return QoraException(
      error.message ?? 'Erreur réseau',
      originalError: error,
      stackTrace: stackTrace,
    );
  }
  return QoraException('$error', originalError: error, stackTrace: stackTrace);
},

Quand défini, toutes les valeurs Failure.error seront des instances de QoraException, donnant un type unique à vérifier dans les gestionnaires d'erreur.

debugMode

final bool debugMode

Défaut : false

Active la journalisation print verbeuse vers la console. Journalise :

• Les hits de cache (frais et périmés)
• Les miss de cache
• Les tentatives de fetch et délais de retry
• Les événements de déduplication
• L'éviction paresseuse et les suppressions GC
• Les appels setQueryData et invalidate
• La destruction du client

// Activer uniquement en builds debug
debugMode: kDebugMode,

maxCacheSize

final int? maxCacheSize

Défaut : null (illimité)

Nombre maximum d'entrées de requête dans le cache. Quand la limite est atteinte, l'entrée inactive la moins récemment utilisée est évincée pour faire de la place. Les entrées actives (celles avec des abonnés watchQuery) ne sont jamais évincées de force.

maxCacheSize: 100,  // limiter l'usage mémoire dans les apps avec de nombreuses listes

onCacheEvict

final void Function(List<dynamic> key)? onCacheEvict

Défaut : null

Callback invoqué chaque fois qu'une entrée de cache est évincée : via pression LRU, timer GC, removeQuery ou clear. Reçoit la clé normalisée de l'entrée évincée.

onCacheEvict: (key) {
  // Journaliser ou synchroniser avec le stockage persistant
  print('[Cache] évincé : $key');
  persistentStore.delete(key.toString());
},

onBackgroundFetchError

final void Function(Object error, StackTrace? stackTrace, List<dynamic> queryKey)? onBackgroundFetchError

Défaut : null

Callback invoqué quand un fetch en arrière-plan déclenché par watchQuery échoue. Les fetchs en arrière-plan s'exécutent dans des futures unawaited et sans ce callback, l'erreur relancée ferait crasher la Zone asynchrone courante.

L'erreur a déjà été stockée dans l'état Failure de la requête au moment où ce callback est appelé. Utiliser ce callback pour la journalisation, la télémétrie ou le rapport de crash, et pas pour la récupération d'erreur.

onBackgroundFetchError: (error, stackTrace, key) {
  crashReporter.record(error, stackTrace);
},

refetchOnMount

final bool refetchOnMount

Défaut : true

Défaut global pour indiquer si watchQuery doit déclencher un fetch au premier abonnement, même quand des données en cache existent déjà.

• true : toujours recharger au montage (recommandé pour la plupart des apps)
• false : fetch uniquement si aucune donnée n'existe ; ignorer si un état en cache est présent

Peut être remplacé par requête via QoraOptions.refetchOnMount.

// Global : ne pas recharger si des données existent
refetchOnMount: false,

// Remplacement par requête : toujours recharger cette requête spécifique
options: QoraOptions(refetchOnMount: true),

reconnectStrategy

final ReconnectStrategy reconnectStrategy

Défaut : const ReconnectStrategy() (5 concurrents, jitter de 100 ms)

Contrôle comment QoraClient rejoue les requêtes mises en pause quand la connectivité est rétablie. Sans regroupement, toutes les requêtes mises en pause se déclencheraient simultanément : le problème du "thundering herd". ReconnectStrategy introduit des limites de concurrence et un jitter aléatoire entre les lots :

reconnectStrategy: const ReconnectStrategy(
  maxConcurrent: 5,                      // Rejouer 5 requêtes à la fois
  jitter: Duration(milliseconds: 200),   // Attente aléatoire entre les lots
),

Constructeurs nommés pour les scénarios courants :

// Défaut : équilibré pour la plupart des apps
const ReconnectStrategy()

// Toutes les requêtes rejouées à la fois (utile dans les tests)
ReconnectStrategy.instant()

// Conservateur : 2 requêtes à la fois, jitter de 500 ms
ReconnectStrategy.conservative()

Configuration recommandée

import 'package:flutter/foundation.dart';
import 'package:qora/qora.dart';

final qoraClient = QoraClient(
  config: QoraClientConfig(
    defaultOptions: const QoraOptions(
      staleTime: Duration(minutes: 5),
      gcTime: Duration(minutes: 10),
      retryCount: 3,
      retryDelay: Duration(seconds: 1),
      networkMode: NetworkMode.online,
    ),
    debugMode: kDebugMode,
    maxCacheSize: 200,
    refetchOnMount: true,
    onBackgroundFetchError: (error, stackTrace, key) =>
        crashReporter.record(error, stackTrace),
    reconnectStrategy: const ReconnectStrategy(
      maxConcurrent: 5,
      jitter: Duration(milliseconds: 100),
    ),
  ),
);

Pour les apps Flutter, passer ce client à QoraScope à la racine de l'arbre de widgets pour que tous les widgets puissent y accéder via context.qora.

Voir le guide réseau adaptatif pour le walkthrough complet de configuration hors ligne.