namespace StellaOps.Messaging.Abstractions;

/// <summary>
/// Transport-agnostic distributed cache interface.
/// </summary>
/// <typeparam name="TKey">The key type.</typeparam>
/// <typeparam name="TValue">The value type.</typeparam>
public interface IDistributedCache<TKey, TValue>
{
    /// <summary>
    /// Gets the provider name for diagnostics (e.g., "valkey", "postgres").
    /// </summary>
    string ProviderName { get; }

    /// <summary>
    /// Gets a value from the cache.
    /// </summary>
    /// <param name="key">The cache key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The cache result.</returns>
    ValueTask<CacheResult<TValue>> GetAsync(TKey key, CancellationToken cancellationToken = default);

    /// <summary>
    /// Sets a value in the cache.
    /// </summary>
    /// <param name="key">The cache key.</param>
    /// <param name="value">The value to cache.</param>
    /// <param name="options">Optional cache entry options.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    ValueTask SetAsync(TKey key, TValue value, CacheEntryOptions? options = null, CancellationToken cancellationToken = default);

    /// <summary>
    /// Removes a value from the cache.
    /// </summary>
    /// <param name="key">The cache key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if the key existed and was removed.</returns>
    ValueTask<bool> InvalidateAsync(TKey key, CancellationToken cancellationToken = default);

    /// <summary>
    /// Removes values matching a pattern from the cache.
    /// </summary>
    /// <param name="pattern">The key pattern (supports wildcards).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The number of keys invalidated.</returns>
    ValueTask<long> InvalidateByPatternAsync(string pattern, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets or sets a value in the cache, using a factory function if the value is not present.
    /// </summary>
    /// <param name="key">The cache key.</param>
    /// <param name="factory">Factory function to create the value if not cached.</param>
    /// <param name="options">Optional cache entry options.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The cached or newly created value.</returns>
    ValueTask<TValue> GetOrSetAsync(
        TKey key,
        Func<CancellationToken, ValueTask<TValue>> factory,
        CacheEntryOptions? options = null,
        CancellationToken cancellationToken = default);
}

/// <summary>
/// Simple string-keyed distributed cache interface.
/// </summary>
/// <typeparam name="TValue">The value type.</typeparam>
public interface IDistributedCache<TValue> : IDistributedCache<string, TValue>
{
}