using adas_core.Domain.Models.Filter;
using adas_core.Domain.Models.MongoModels;
using MongoDB.Bson;
using MongoDB.Driver;

namespace adas_core.Application.Repositories.Interfaces;

public interface ILightBeaconRepository : IMongoRepository<LightBeacon>
{
    /// <summary>
    /// Retrieves the list of <see cref="LightBeacon"/> objects associated with the specified configuration relay identifiers.
    /// </summary>
    /// <param name="configurationRelayList">The collection of configuration relay <see cref="ObjectId"/> values used to look up the corresponding light beacons.</param>
    /// <returns>A <see cref="List{LightBeacon}"/> containing the light beacons matching the provided configuration relay identifiers; returns an empty list if no matches are found.</returns>
    List<LightBeacon> GetLightBeaconInList(List<ObjectId> configurationRelayList);
    /// <summary>
    /// Retrieves a light beacon by its associated relay identifier.
    /// </summary>
    /// <param name="relayId">The unique identifier of the relay used to look up the corresponding light beacon.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the matching <see cref="LightBeacon"/>, or <c>null</c> if no beacon is found for the specified relay.</returns>
    Task<LightBeacon?> GetById(ObjectId relayId);
    /// <summary>
    /// Asynchronously retrieves a <see cref="LightBeacon"/> by its name.
    /// </summary>
    /// <param name="name">The name of the light beacon to look up.</param>
    /// <returns>A task that returns the matching <see cref="LightBeacon"/>, or <c>null</c> if no beacon with the specified name is found.</returns>
    Task<LightBeacon?> GetByName(string name);
    /// <summary>
    /// Asynchronously inserts a new LightBeacon and returns the persisted entity, or null if the insertion did not produce a result.
    /// </summary>
    /// <param name="beacon">The LightBeacon entity to insert.</param>
    /// <returns>A task containing the inserted LightBeacon, or null when no entity was returned by the underlying operation.</returns>
    Task<LightBeacon?> InsertOneAsyncAndReturn(LightBeacon beacon);
    /// <summary>
    /// Retrieves a paginated, queryable collection of light beacons (relays) based on the supplied pagination filter.
    /// </summary>
    /// <param name="filter">The pagination filter that controls paging parameters applied to the relay list.</param>
    /// <returns>An <see cref="IFindFluent{LightBeacon, LightBeacon}"/> exposing the paginated relay result set for further querying or enumeration.</returns>
    IFindFluent<LightBeacon, LightBeacon> GetPaginatedRelays(PaginationFilter filter);
    /// <summary>
    /// Asynchronously retrieves a list of <see cref="LightBeacon"/> objects whose name matches the specified search text.
    /// </summary>
    /// <param name="textToSearch">The text used to search for matching <see cref="LightBeacon"/> entries by name.</param>
    /// <returns>A task that represents the asynchronous operation, containing a list of <see cref="LightBeacon"/> objects that match the search criteria.</returns>
    Task<List<LightBeacon>> GetSearchByName(string textToSearch);
}