namespace Webzine.Repository.Contracts
{
    using Webzine.Entity;

    /// <summary>
    /// Interface qui définit les opérations de base pour la gestion des titres dans une source de données.
    /// </summary>
    public interface ITitreRepository
    {
        /// <summary>
        /// Ajoute un titre à la liste des titres.
        /// </summary>
        /// <param name="titre">L'objet titre à ajouter.</param>
        void Add(Titre titre);

        /// <summary>
        /// Remonte le nombre de titres.
        /// </summary>
        /// <returns>Le nombre total de titres présents dans la liste après l'incrémentation du nombre de lectures.</returns>
        int Count();

        /// <summary>
        /// Supprime un titre de la liste des titres.
        /// </summary>
        /// <param name="titre">L'objet titre à supprimer.</param>
        void Delete(Titre titre);

        /// <summary>
        /// Trouve un titre dans la liste des titres en fonction de son identifiant.
        /// </summary>
        /// <param name="idTitre">L'identifiant du titre à trouver.</param>
        /// <returns>Le titre correspondant à l'identifiant fourni, ou null si aucun titre n'est trouvé.</returns>
        Titre Find(int idTitre);

        /// <summary>
        /// Recherche les titres dans la liste des titres en fonction de l'offset et de la limite spécifiés, permettant ainsi une pagination des résultats.
        /// </summary>
        /// <param name="offset">Le nombre de titres à ignorer avant de commencer à retourner les résultats.</param>
        /// <param name="limit">Le nombre maximum de titres à retourner.</param>
        /// <returns>Une collection de titres correspondant au critère de pagination, triée par libellé.</returns>
        IEnumerable<Titre> FindTitres(int offset, int limit);

        /// <summary>
        /// Trouve tous les titres dans la liste des titres.
        /// </summary>
        /// <returns>Une collection de tous les titres présents dans la liste.</returns>
        IEnumerable<Titre> FindAll();

        /// <summary>
        /// Incrémente le nombre de lectures d'un titre donné. Si le titre est null, un message d'avertissement est enregistré dans les logs et aucune action n'est effectuée.
        /// </summary>
        /// <param name="titre">L'objet titre dont le nombre de lectures doit être incrémenté.</param>
        void IncrementNbLectures(Titre titre);

        /// <summary>
        /// Incrémente le nombre de likes d'un titre donné. Si le titre est null, un message d'avertissement est enregistré dans les logs et aucune action n'est effectuée.
        /// </summary>
        /// <param name="titre">L'objet titre dont le nombre de likes doit être incrémenté.</param>
        void IncrementNbLikes(Titre titre);

        /// <summary>
        /// Recherche les titres dont le libellé contient le mot spécifié, en ignorant la casse.
        /// </summary>
        /// <param name="mot">Le mot à rechercher dans les libellés des titres.</param>
        /// <returns>Une collection de titres correspondant au critère de recherche, triée par libellé.</returns>
        IEnumerable<Titre> Search(string mot);

        /// <summary>
        /// Recherche les titres associés à un style dont le libellé contient la chaîne spécifiée, en ignorant la casse.
        /// </summary>
        /// <param name="libelle">Le libellé du style à rechercher dans les titres.</param>
        /// <returns>Une collection de titres correspondant au critère de recherche, triée par libellé.</returns>
        IEnumerable<Titre> SearchByStyle(string libelle);

        /// <summary>
        /// Retourne une liste de titre filtré par nom et paginé.
        /// </summary>
        /// <param name="offset">Nombre de titres a passer.</param>
        /// <param name="limit">Nombre de titre récupéré.</param>
        /// <param name="libelle">Nom du style.</param>
        /// <returns>Une liste de titre.</returns>
        IEnumerable<Titre> SearchByStylePaginate(int offset, int limit, string libelle);

        /// <summary>
        /// Compter le nombre de titres au sein d'un style.
        /// </summary>
        /// <param name="libelle">Style de la musique.</param>
        /// <returns>Un entier.</returns>
        int CountByStyle(string libelle);

        /// <summary>
        /// Met à jour un titre dans la liste des titres en fonction de son identifiant. Si aucun titre correspondant à l'identifiant du titre fourni n'est trouvé, un message d'avertissement est enregistré dans les logs et aucune mise à jour n'est effectuée.
        /// </summary>
        /// <param name="titre">L'objet titre à mettre à jour.</param>
        void Update(Titre titre);

        /// <summary>
        /// Retourne le nombre total de likes.
        /// </summary>
        /// <returns>Integer.</returns>
        int CountLike();

        /// <summary>
        /// Retourne le nombre total de lecture.
        /// </summary>
        /// <returns>Integer.</returns>
        int CountLecture();

        /// <summary>
        /// Retourne le nom de l'artiste ayant le plus de titres chroniqués.
        /// </summary>
        /// <returns>Le nom de l'artiste le plus chroniqué, ou null si aucun titre n'existe.</returns>
        string? FindMostReviewedArtistName();

        /// <summary>
        /// Retourne le nom de l'artiste ayant le plus d'albums chroniqués.
        /// </summary>
        /// <returns>Le nom de l'artiste concerné, ou null si aucun titre n'existe.</returns>
        string? FindArtistNameWithMostReviewedAlbums();

        /// <summary>
        /// Retourne l'identifiant et le libellé du titre le plus joué.
        /// </summary>
        /// <returns>Un tuple contenant l'identifiant et le libellé du titre le plus joué, ou null si aucun titre n'existe.</returns>
        (int IdTitre, string Libelle)? FindMostPlayedTitle();

        /// <summary>
        /// Récupération des chroniques.
        /// </summary>
        /// <param name="offset">Nombre d'éléments.</param>
        /// <param name="limit">Limite d'éléments.</param>
        /// <returns>Liste des derniers titres chroniqués.</returns>
        IEnumerable<Titre> DerniereChronique(int offset, int limit);

        /// <summary>
        /// Récupération du top titre liké.
        /// </summary>
        /// <returns>Liste de titre les plus likés.</returns>
        IEnumerable<Titre> TopTitre(int offset, int limit);
    }
}