using System.Threading;
using System.Threading.Tasks;
using Svrnty.CQRS.Events.Abstractions.EventStore;

namespace Svrnty.CQRS.Events.Abstractions.Schema;

/// <summary>
/// Defines a contract for upcasting events from one version to another.
/// </summary>
/// <typeparam name="TFrom">The source event version type.</typeparam>
/// <typeparam name="TTo">The target event version type.</typeparam>
/// <remarks>
/// <para>
/// <strong>Upcasting Strategies:</strong>
/// </para>
/// <para>
/// 1. <strong>Convention-based (Recommended):</strong>
/// Define a static UpcastFrom method on the target type:
/// <code>
/// public static UserCreatedEventV2 UpcastFrom(UserCreatedEventV1 v1)
/// {
///     return new UserCreatedEventV2 { ... };
/// }
/// </code>
/// </para>
/// <para>
/// 2. <strong>Interface-based (Advanced):</strong>
/// Implement IEventUpcaster for complex transformations:
/// <code>
/// public class UserCreatedEventUpcaster : IEventUpcaster&lt;UserCreatedEventV1, UserCreatedEventV2&gt;
/// {
///     public async Task&lt;UserCreatedEventV2&gt; UpcastAsync(UserCreatedEventV1 from, CancellationToken ct)
///     {
///         // Complex logic here (database lookups, calculations, etc.)
///         return new UserCreatedEventV2 { ... };
///     }
/// }
/// </code>
/// </para>
/// </remarks>
public interface IEventUpcaster<in TFrom, TTo>
    where TFrom : ICorrelatedEvent
    where TTo : ICorrelatedEvent
{
    /// <summary>
    /// Upcasts an event from the source version to the target version.
    /// </summary>
    /// <param name="from">The source event version.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The upcast event at the target version.</returns>
    /// <remarks>
    /// <para>
    /// Implementations should:
    /// - Preserve EventId, CorrelationId, and OccurredAt from the source event
    /// - Map all compatible properties
    /// - Provide sensible defaults for new properties
    /// - Perform any necessary data transformations
    /// </para>
    /// </remarks>
    Task<TTo> UpcastAsync(TFrom from, CancellationToken cancellationToken = default);
}