namespace Bit.Seeder;

/// <summary>
/// Base interface for query operations in the seeding system. The base interface should not be used directly, rather use `IQuery&lt;TRequest, TResult&gt;`.
/// </summary>
/// <remarks>
/// Queries are read-only operations that retrieve data from the seeding context.
/// Unlike scenes, which create data, queries fetch existing data based on request parameters.
/// They follow a type-safe pattern using generics to ensure proper request/response handling
/// while maintaining a common non-generic interface for dynamic invocation.
/// </remarks>
public interface IQuery
{
    /// <summary>
    /// Gets the type of request this query expects.
    /// </summary>
    /// <returns>The request type that this query can process.</returns>
    Type GetRequestType();

    /// <summary>
    /// Executes the query based on the provided request object.
    /// </summary>
    /// <param name="request">The request object containing parameters for the query operation.</param>
    /// <returns>The query result data as an object.</returns>
    Task<object> Execute(object request);
}

/// <summary>
/// Generic query interface for read-only operations with specific request and result types.
/// </summary>
/// <typeparam name="TRequest">The type of request object this query accepts.</typeparam>
/// <typeparam name="TResult">The type of data this query returns.</typeparam>
/// <remarks>
/// Use this interface when you need to retrieve existing data from the seeding context based on
/// specific request parameters. Queries do not modify data - they only read
/// and return information. The explicit interface implementations allow dynamic invocation while
/// maintaining type safety in the implementation.
/// </remarks>
public interface IQuery<TRequest, TResult> : IQuery where TRequest : class where TResult : class
{
    /// <summary>
    /// Executes the query based on the provided strongly-typed request and returns typed result data.
    /// </summary>
    /// <param name="request">The request object containing parameters for the query operation.</param>
    /// <returns>The typed query result data.</returns>
    Task<TResult> Execute(TRequest request);

    /// <summary>
    /// Gets the request type for this query.
    /// </summary>
    /// <returns>The type of TRequest.</returns>
    Type IQuery.GetRequestType() => typeof(TRequest);

    /// <summary>
    /// Adapts the non-generic Execute to the strongly-typed version.
    /// </summary>
    /// <param name="request">The request object to cast and process.</param>
    /// <returns>The typed result cast to object.</returns>
    async Task<object> IQuery.Execute(object request) => await Execute((TRequest)request);
}