namespace Core.Blueprint.Redis
{
    /// <summary>
    /// Interface for managing Redis cache operations.
    /// </summary>
    public interface IRedisCacheProvider
    {
        /// <summary>
        /// Retrieves a cache item by its key.
        /// </summary>
        /// <typeparam name="T">The type of the cached item.</typeparam>
        /// <param name="key">The cache key.</param>
        /// <returns>The cached item, or default if not found.</returns>
        ValueTask<TEntity> GetAsync<TEntity>(string key);

        /// <summary>
        /// Sets a cache item with the specified key and value.
        /// </summary>
        /// <typeparam name="T">The type of the item to cache.</typeparam>
        /// <param name="key">The cache key.</param>
        /// <param name="value">The item to cache.</param>
        /// <param name="expiry">The optional expiration time for the cache item.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        ValueTask SetAsync<TEntity>(string key, TEntity value, TimeSpan? expiry = null);

        /// <summary>
        /// Removes a cache item by its key.
        /// </summary>
        /// <param name="key">The cache key.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        ValueTask RemoveAsync(string key);

        /// <summary>
        /// Checks if a cache item exists for the specified key.
        /// </summary>
        /// <param name="key">The cache key.</param>
        /// <returns>True if the cache item exists; otherwise, false.</returns>
        ValueTask<bool> ExistsAsync(string key);

        /// <summary>
        /// Refreshes the expiration time of a cache item if it exists.
        /// </summary>
        /// <param name="key">The cache key.</param>
        /// <param name="expiry">The new expiration time for the cache item.</param>
        /// <returns>A task representing the asynchronous operation.</returns>
        ValueTask RefreshAsync(string key, TimeSpan? expiry = null);
    }
}