using TrajetKmTracker.Api.Models.Entities;

namespace TrajetKmTracker.Api.Repositories;

/// <summary>
/// Accès aux données du Cache_Adresses (table <c>AdresseCache</c>).
/// Toutes les correspondances d'adresse s'effectuent sur le texte normalisé
/// (voir <see cref="AdresseCacheService"/>).
/// </summary>
public interface IAdresseCacheRepository
{
    /// <summary>
    /// Retourne les entrées dont l'adresse normalisée contient le fragment normalisé fourni,
    /// triées de la plus récemment utilisée à la plus ancienne, limitées à <paramref name="limite"/>.
    /// </summary>
    Task<IReadOnlyList<AdresseCache>> RechercherAsync(
        string fragmentNormalise,
        int limite,
        CancellationToken cancellationToken = default);

    /// <summary>Retourne l'entrée correspondant exactement à l'adresse normalisée, ou <c>null</c>.</summary>
    Task<AdresseCache?> ObtenirParAdresseNormaliseeAsync(
        string adresseNormalisee,
        CancellationToken cancellationToken = default);

    /// <summary>Ajoute une nouvelle entrée au cache.</summary>
    Task AjouterAsync(AdresseCache entree, CancellationToken cancellationToken = default);

    /// <summary>Compte le nombre total d'entrées du cache.</summary>
    Task<int> CompterAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Retourne les entrées les plus anciennes (par <c>DerniereUtilisation</c> croissante),
    /// limitées à <paramref name="nombre"/>. Utilisé pour l'éviction LRU.
    /// </summary>
    Task<IReadOnlyList<AdresseCache>> ObtenirPlusAnciennesAsync(
        int nombre,
        CancellationToken cancellationToken = default);

    /// <summary>Supprime les entrées fournies du cache.</summary>
    void Supprimer(IEnumerable<AdresseCache> entrees);

    /// <summary>Persiste les modifications en attente.</summary>
    Task<int> SauvegarderAsync(CancellationToken cancellationToken = default);
}