namespace EnvelopeGenerator.Application.Contracts.SQLExecutor;

/// <summary>
/// Defines methods for executing raw SQL queries and mapping the results to <typeparamref name="TEntity"/> objects.
/// </summary>
/// <typeparam name="TEntity">The entity type to which the SQL query results will be mapped.</typeparam>
public interface ISQLExecutor<TEntity>
{
    /// <summary>
    /// Executes a raw SQL query and returns the first result or <c>null</c> if no result is found.
    /// </summary>
    /// <param name="sql">The raw SQL query to execute.</param>
    /// <param name="cancellation">Optional cancellation token.</param>
    /// <param name="parameters">Optional parameters for the SQL query.</param>
    /// <returns>The first <typeparamref name="TEntity"/> result, or <c>null</c> if none found.</returns>
    Task<TEntity?> ExecuteFirstAsync(string sql, CancellationToken cancellation = default, params object[] parameters);

    /// <summary>
    /// Executes a raw SQL query and expects a single result, or <c>null</c> if no result is found.
    /// </summary>
    /// <param name="sql">The raw SQL query to execute.</param>
    /// <param name="cancellation">Optional cancellation token.</param>
    /// <param name="parameters">Optional parameters for the SQL query.</param>
    /// <returns>The single <typeparamref name="TEntity"/> result, or <c>null</c> if none found.</returns>
    Task<TEntity?> ExecuteSingleAsync(string sql, CancellationToken cancellation = default, params object[] parameters);

    /// <summary>
    /// Executes a raw SQL query and returns all results as a collection of <typeparamref name="TEntity"/>.
    /// </summary>
    /// <param name="sql">The raw SQL query to execute.</param>
    /// <param name="cancellation">Optional cancellation token.</param>
    /// <param name="parameters">Optional parameters for the SQL query.</param>
    /// <returns>An <see cref="IEnumerable{TEntity}"/> containing all matching results.</returns>
    Task<IEnumerable<TEntity>> ExecuteAllAsync(string sql, CancellationToken cancellation = default, params object[] parameters);

    Task<TEntity?> ExecuteFirstAsync<TSQL>(CancellationToken cancellation = default, params object[] parameters) where TSQL : ISQL<TEntity>;

    Task<TEntity?> ExecuteSingleAsync<TSQL>(CancellationToken cancellation = default, params object[] parameters) where TSQL : ISQL<TEntity>;

    Task<IEnumerable<TEntity>> ExecuteAllAsync<TSQL>(CancellationToken cancellation = default, params object[] parameters) where TSQL : ISQL<TEntity>;
}