Stockage de données

SmartCommon propose plusieurs solutions pour le stockage de données côté client :

• useGlobalStates : état global avec persistance automatique (localStorage/sessionStorage)
• useStates : état local réactif avec path notation
• useDb : base de données IndexedDB via Dexie
• useCachedQuery : cache de données avec stratégies (NetworkFirst, CacheFirst, SWR)

Pour la synchronisation offline complète, voir Synchronisation offline (useSyncClient).

Documentation IndexedDB Documentation Dexie Documentation Redux Toolkit

Le hook useGlobalStates fournit un état global avec persistance automatique. C'est la méthode recommandée pour les données utilisateur (session, préférences, etc.).

import { useGlobalStates } from '@cap-rel/smartcommon';

export const MyComponent = () => {
  const gst = useGlobalStates();

  // Lire une valeur
  const user = gst.get('user');

  // Écrire dans localStorage (persistant)
  const login = (userData) => {
    gst.local.set('user', userData);
  };

  // Écrire dans sessionStorage (session uniquement)
  const setTempData = (data) => {
    gst.session.set('tempData', data);
  };

  // Supprimer une valeur
  const logout = () => {
    gst.unset('user');
  };

  return (
    <div>
      {user ? `Bonjour ${user.name}` : 'Non connecté'}
    </div>
  );
};

Vous pouvez accéder aux données imbriquées avec la notation par points :

// Définir des données imbriquées
gst.local.set('user.preferences.theme', 'dark');
gst.local.set('user.preferences.language', 'fr');

// Lire des données imbriquées
const theme = gst.get('user.preferences.theme'); // 'dark'
const prefs = gst.get('user.preferences'); // { theme: 'dark', language: 'fr' }

Le hook useStates fournit un état local réactif avec la même API que useGlobalStates.

import { useStates } from '@cap-rel/smartcommon';

export const MyForm = () => {
  const st = useStates({
    initialStates: {
      name: '',
      email: '',
      errors: {}
    },
    debug: true // affiche les changements dans la console
  });

  const handleChange = (field, value) => {
    st.set(field, value);
  };

  const validate = () => {
    if (!st.get('name')) {
      st.set('errors.name', 'Le nom est requis');
    }
  };

  return (
    <form>
      <Input
        value={st.get('name')}
        onChange={(e) => handleChange('name', e.target.value)}
        error={st.get('errors.name')}
      />
    </form>
  );
};

const st = useStates({ initialStates: { items: [] } });

// Ajouter un élément (push)
st.set('items[]', { id: 1, name: 'Item 1' });

// Modifier un élément par index
st.set('items[0].name', 'Item modifié');

// Supprimer un élément par index
st.unset('items[0]');

Le hook useCachedQuery permet de mettre en cache les données API dans IndexedDB avec des stratégies configurables.

import { useCachedQuery } from '@cap-rel/smartcommon';

const ItemsList = () => {
  const db = useMemo(() => new Dexie('myApp'), []);

  const {
    data,          // données (depuis cache ou réseau)
    isLoading,     // chargement en cours
    isFromCache,   // true si les données viennent du cache
    isStale,       // true si les données sont périmées
    error,         // erreur éventuelle
    lastFetch,     // timestamp du dernier fetch
    refetch,       // forcer un nouveau fetch
    invalidate,    // invalider le cache
  } = useCachedQuery({
    db,
    store: 'cache',         // nom du store IndexedDB (schéma: 'key')
    key: 'items-list',      // clé de cache unique
    fetchFn: () => api.get('items'),  // fonction de récupération
    strategy: 'networkFirst',         // stratégie de cache
    ttl: 3600000,           // durée de vie du cache (1h par défaut)
    staleTime: 60000,       // durée avant que le cache soit "stale" (1min par défaut)
    enabled: true,          // activer/désactiver le fetch
  });

  if (isLoading) return <Spinner />;

  return (
    <List>
      {data?.map(item => (
        <ListItem key={item.id}>{item.label}</ListItem>
      ))}
    </List>
  );
};