using System.Collections.Generic;
using Svrnty.CQRS.Events.Abstractions.Models;
using System.Threading;
using System.Threading.Tasks;

namespace Svrnty.CQRS.Events.Abstractions.Schema;

/// <summary>
/// Persistent storage for event schemas.
/// </summary>
/// <remarks>
/// <para>
/// The schema store persists schema information to a database, enabling:
/// - Schema versioning across application restarts
/// - Centralized schema management in distributed systems
/// - Schema auditing and history tracking
/// </para>
/// <para>
/// <strong>Implementations:</strong>
/// - PostgresSchemaStore (stores schemas in PostgreSQL)
/// - InMemorySchemaStore (for testing)
/// </para>
/// </remarks>
public interface ISchemaStore
{
    /// <summary>
    /// Stores a schema in the persistent store.
    /// </summary>
    /// <param name="schema">The schema information to store.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Task representing the async operation.</returns>
    /// <remarks>
    /// If a schema with the same EventType and Version already exists,
    /// this method should throw an exception (schemas are immutable once registered).
    /// </remarks>
    Task StoreSchemaAsync(
        SchemaInfo schema,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Retrieves a schema by event type and version.
    /// </summary>
    /// <param name="eventType">The event type name.</param>
    /// <param name="version">The version number.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Schema information if found; otherwise null.</returns>
    Task<SchemaInfo?> GetSchemaAsync(
        string eventType,
        int version,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all schemas for an event type, ordered by version ascending.
    /// </summary>
    /// <param name="eventType">The event type name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of schema information for all versions.</returns>
    Task<IReadOnlyList<SchemaInfo>> GetSchemaHistoryAsync(
        string eventType,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets the latest version number for an event type.
    /// </summary>
    /// <param name="eventType">The event type name.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The latest version number, or null if no versions exist.</returns>
    Task<int?> GetLatestVersionAsync(
        string eventType,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all registered event types.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of unique event type names.</returns>
    Task<IReadOnlyList<string>> GetAllEventTypesAsync(
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Checks if a schema exists for the given event type and version.
    /// </summary>
    /// <param name="eventType">The event type name.</param>
    /// <param name="version">The version number.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if the schema exists; otherwise false.</returns>
    Task<bool> SchemaExistsAsync(
        string eventType,
        int version,
        CancellationToken cancellationToken = default);
}