namespace StellaOps.Provcache;

/// <summary>
/// Cache store interface for Provcache with read-through semantics.
/// Abstracts the caching layer (Valkey, in-memory, etc.).
/// </summary>
public interface IProvcacheStore
{
    /// <summary>
    /// Gets the store provider name for diagnostics.
    /// </summary>
    string ProviderName { get; }

    /// <summary>
    /// Gets a cache entry by VeriKey.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Cache result indicating hit/miss with the entry if found.</returns>
    ValueTask<ProvcacheLookupResult> GetAsync(string veriKey, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets multiple cache entries by VeriKeys.
    /// </summary>
    /// <param name="veriKeys">The cache keys.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Dictionary of found entries and list of misses.</returns>
    ValueTask<ProvcacheBatchLookupResult> GetManyAsync(
        IEnumerable<string> veriKeys,
        CancellationToken cancellationToken = default);

    /// <summary>
    /// Sets a cache entry.
    /// </summary>
    /// <param name="entry">The cache entry to set.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    ValueTask SetAsync(ProvcacheEntry entry, CancellationToken cancellationToken = default);

    /// <summary>
    /// Sets multiple cache entries in a batch.
    /// </summary>
    /// <param name="entries">The cache entries to set.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    ValueTask SetManyAsync(IEnumerable<ProvcacheEntry> entries, CancellationToken cancellationToken = default);

    /// <summary>
    /// Invalidates a cache entry by VeriKey.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>True if the entry existed and was invalidated.</returns>
    ValueTask<bool> InvalidateAsync(string veriKey, CancellationToken cancellationToken = default);

    /// <summary>
    /// Invalidates entries matching a key pattern.
    /// </summary>
    /// <param name="pattern">The key pattern (supports wildcards).</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>Number of entries invalidated.</returns>
    ValueTask<long> InvalidateByPatternAsync(string pattern, CancellationToken cancellationToken = default);

    /// <summary>
    /// Gets or sets a cache entry using a factory function for cache misses.
    /// </summary>
    /// <param name="veriKey">The cache key.</param>
    /// <param name="factory">Factory function to create the entry on cache miss.</param>
    /// <param name="cancellationToken">Cancellation token.</param>
    /// <returns>The cached or newly created entry.</returns>
    ValueTask<ProvcacheEntry> GetOrSetAsync(
        string veriKey,
        Func<CancellationToken, ValueTask<ProvcacheEntry>> factory,
        CancellationToken cancellationToken = default);
}