using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;

namespace Svrnty.CQRS.Sagas.Abstractions.Persistence;

/// <summary>
/// Abstraction for saga state persistence.
/// </summary>
public interface ISagaStateStore
{
    /// <summary>
    /// Creates a new saga state entry.
    /// </summary>
    /// <param name="state">The saga state to create.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The created saga state.</returns>
    Task<SagaState> CreateAsync(SagaState state, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a saga state by its ID.
    /// </summary>
    /// <param name="sagaId">The saga instance ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The saga state, or null if not found.</returns>
    Task<SagaState?> GetByIdAsync(Guid sagaId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets a saga state by its correlation ID.
    /// </summary>
    /// <param name="correlationId">The correlation ID.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The saga state, or null if not found.</returns>
    Task<SagaState?> GetByCorrelationIdAsync(Guid correlationId, CancellationToken cancellationToken = default);

    /// <summary>
    /// Updates an existing saga state.
    /// </summary>
    /// <param name="state">The saga state to update.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The updated saga state.</returns>
    Task<SagaState> UpdateAsync(SagaState state, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all pending (in progress) sagas.
    /// </summary>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of pending saga states.</returns>
    Task<IReadOnlyList<SagaState>> GetPendingSagasAsync(CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets all sagas with a specific status.
    /// </summary>
    /// <param name="status">The status to filter by.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>List of saga states with the specified status.</returns>
    Task<IReadOnlyList<SagaState>> GetSagasByStatusAsync(SagaStatus status, CancellationToken cancellationToken = default);
}