namespace EnvelopeGenerator.Application.Common.Interfaces.SQLExecutor;

/// <summary>
/// Defines methods for executing raw SQL queries or custom SQL query classes and returning query executors for further operations.
/// Provides abstraction for raw SQL execution as well as 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>: ISQLExecutor
{
    /// <summary>
    /// Executes a raw SQL query and returns an <see cref="IQuery{TEntity}"/> for further querying operations on the result.
    /// </summary>
    /// <param name="sql">The raw SQL query to execute.</param>
    /// <param name="cancellation">Optional cancellation token for the operation.</param>
    /// <param name="parameters">Optional parameters for the SQL query.</param>
    /// <returns>An <see cref="IQuery{TEntity}"/> instance for further query operations on the result.</returns>
    IQuery<TEntity> Execute(string sql, CancellationToken cancellation = default, params object[] parameters);

    /// <summary>
    /// Executes a custom SQL query defined by a class that implements <see cref="ISQL{TEntity}"/> and returns an <see cref="IQuery{TEntity}"/> for further querying operations on the result.
    /// </summary>
    /// <typeparam name="TSQL">The type of the custom SQL query class implementing <see cref="ISQL{TEntity}"/>.</typeparam>
    /// <param name="cancellation">Optional cancellation token for the operation.</param>
    /// <param name="parameters">Optional parameters for the SQL query.</param>
    /// <returns>An <see cref="IQuery{TEntity}"/> instance for further query operations on the result.</returns>
    IQuery<TEntity> Execute<TSQL>(CancellationToken cancellation = default, params object[] parameters) where TSQL : ISQL<TEntity>;
}