using System.Linq.Expressions;

namespace DigitalData.Core.Application.Interfaces.Repository;

/// <summary>
/// Provides methods for executing common queries on a given entity type.
/// This interface abstracts away the direct usage of ORM libraries (such as Entity Framework) for querying data
/// and provides asynchronous and synchronous operations for querying a collection or single entity.
/// </summary>
/// <typeparam name="TEntity">The type of the entity being queried.</typeparam>
public interface IReadQuery<TEntity>
{
    /// <summary>
    /// Adds a filter to the query using the specified predicate expression.
    /// This method allows chaining multiple filter conditions to refine the query results.
    /// </summary>
    /// <param name="expression">An expression that defines the filter condition for the entity.</param>
    /// <returns>The current <see cref="IReadQuery{TEntity}"/> instance with the applied filter.</returns>
    public IReadQuery<TEntity> Where(Expression<Func<TEntity, bool>> expression);

    /// <summary>
    /// Asynchronously retrieves the first entity or a default value if no entity is found.
    /// </summary>
    /// <param name="cancellation">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the entity or a default value.</returns>
    public Task<TEntity?> FirstOrDefaultAsync(CancellationToken cancellation = default);

    /// <summary>
    /// Asynchronously retrieves a single entity or a default value if no entity is found.
    /// </summary>
    /// <param name="cancellation">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the entity or a default value.</returns>
    public Task<TEntity?> SingleOrDefaultAsync(CancellationToken cancellation = default);

    /// <summary>
    /// Asynchronously retrieves a list of entities.
    /// </summary>
    /// <param name="cancellation">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the list of entities.</returns>
    public Task<IEnumerable<TEntity>> ToListAsync(CancellationToken cancellation = default);

    /// <summary>
    /// Asynchronously retrieves the first entity. Throws an exception if no entity is found.
    /// </summary>
    /// <param name="cancellation">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the first entity.</returns>
    public Task<TEntity> FirstAsync(CancellationToken cancellation = default);

    /// <summary>
    /// Asynchronously retrieves a single entity. Throws an exception if no entity is found.
    /// </summary>
    /// <param name="cancellation">A <see cref="CancellationToken"/> to observe while waiting for the task to complete.</param>
    /// <returns>A task that represents the asynchronous operation. The task result contains the single entity.</returns>
    public Task<TEntity> SingleAsync(CancellationToken cancellation = default);

    /// <summary>
    /// Synchronously retrieves the first entity or a default value if no entity is found.
    /// </summary>
    /// <returns>The first entity or a default value.</returns>
    public TEntity? FirstOrDefault();

    /// <summary>
    /// Synchronously retrieves a single entity or a default value if no entity is found.
    /// </summary>
    /// <returns>The single entity or a default value.</returns>
    public TEntity? SingleOrDefault();

    /// <summary>
    /// Synchronously retrieves a list of entities.
    /// </summary>
    /// <returns>The list of entities.</returns>
    public IEnumerable<TEntity> ToList();

    /// <summary>
    /// Synchronously retrieves the first entity. Throws an exception if no entity is found.
    /// </summary>
    /// <returns>The first entity.</returns>
    public TEntity First();

    /// <summary>
    /// Synchronously retrieves a single entity. Throws an exception if no entity is found.
    /// </summary>
    /// <returns>The single entity.</returns>
    public TEntity Single();
}