using adas_core.Domain.Enums;
using adas_core.Domain.Models.MongoModels;
using MongoDB.Bson;

namespace adas_core.Application.Repositories.Interfaces;

public interface IHistoricalConfigChangesRepository : IMongoRepository<HistoricalConfigChanges>
{
    /// <summary>
    /// Asynchronously retrieves a historical configuration changes record by its unique identifier.
    /// Returns null if no matching record is found.
    /// </summary>
    /// <param name="id">The unique identifier of the historical configuration changes record to look up.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the matching <see cref="HistoricalConfigChanges"/> record, or null if no record with the specified identifier exists.</returns>
    Task<HistoricalConfigChanges?> FindById(ObjectId id);

    /// <summary>
    /// Updates an existing historical config change record asynchronously.
    /// </summary>
    /// <param name="historicalConfigChange">The historical config change entity containing the values to persist.</param>
    /// <returns>A task that represents the asynchronous update operation. The result is the updated historical config change, or <c>null</c> if the record was not found.</returns>
    Task<HistoricalConfigChanges?> Update(HistoricalConfigChanges historicalConfigChange);

    /// <summary>
    /// Deletes the historical configuration change record identified by the specified identifier, returning the removed entry when found.
    /// If no record matches the given identifier, the task resolves to <c>null</c>.
    /// </summary>
    /// <param name="id">The unique identifier of the historical configuration change to delete.</param>
    /// <returns>A task that represents the asynchronous delete operation, containing the deleted <see cref="HistoricalConfigChanges"/> record, or <c>null</c> if no matching record exists.</returns>
    Task<HistoricalConfigChanges?> Delete(ObjectId id);

    /// <summary>
    /// Asynchronously retrieves a list of all object identifiers.
    /// </summary>
    /// <returns>A task that represents the asynchronous operation. The task result contains a list of ObjectId values.</returns>
    Task<List<ObjectId>> FindAllIds();

    /// <summary>
    /// Asynchronously retrieves all historical configuration changes.
    /// </summary>
    /// <returns>A task that represents the asynchronous operation. The task result contains a collection of <see cref="HistoricalConfigChanges"/> records.</returns>
    Task<ICollection<HistoricalConfigChanges>> FindAll();
    /// <summary>
    /// Asynchronously inserts a new <see cref="HistoricalConfigChanges"/> record into the data store.
    /// </summary>
    /// <param name="patientObservation">The historical config change entity to insert.</param>
    /// <returns>A task that represents the asynchronous insert operation, containing the inserted <see cref="HistoricalConfigChanges"/> entity, or <c>null</c> if the insertion did not produce a result.</returns>
    new Task<HistoricalConfigChanges?> InsertOneAsync(HistoricalConfigChanges patientObservation);

    /// <summary>
    /// Retrieves the most recent historical configuration changes filtered by the specified configuration type, limited to a given number of entries.
    /// </summary>
    /// <param name="cfgType">The configuration type used to filter the historical changes.</param>
    /// <param name="num">The maximum number of recent changes to return. Defaults to 10.</param>
    /// <returns>A task that returns a collection of historical configuration changes matching the specified type, ordered from most recent.</returns>
    Task<ICollection<HistoricalConfigChanges>> FindLastHistoricalConfigChangesByType(
            DisplayConfigEnums.ConfigTypes cfgType, int num = 10);

    /// <summary>
    /// Retrieves the most recent historical configuration changes for the specified user, optionally filtered by configuration type.
    /// </summary>
    /// <param name="user">The identifier of the user whose historical configuration changes are being retrieved.</param>
    /// <param name="cfgType">Optional. The configuration type to filter the results by. If null, changes across all configuration types are returned.</param>
    /// <param name="num">The maximum number of historical changes to return. Defaults to 10.</param>
    /// <returns>A task representing the asynchronous operation, containing a collection of historical configuration changes for the user.</returns>
    Task<ICollection<HistoricalConfigChanges>> FindLastHistoricalConfigChangesByUser(string user,
            DisplayConfigEnums.ConfigTypes? cfgType = null, int num = 10);
}