namespace StellaOps.Provcache;

/// <summary>
/// Result of a cache service lookup.
/// </summary>
public sealed record ProvcacheServiceResult
{
    /// <summary>
    /// The cache result status.
    /// </summary>
    public required ProvcacheResultStatus Status { get; init; }

    /// <summary>
    /// The cache entry if found.
    /// </summary>
    public ProvcacheEntry? Entry { get; init; }

    /// <summary>
    /// Whether the result came from cache (true) or needs computation (false).
    /// </summary>
    public bool WasCached => Status == ProvcacheResultStatus.CacheHit;

    /// <summary>
    /// Source of the cache hit for diagnostics.
    /// </summary>
    public string? Source { get; init; }

    /// <summary>
    /// Time taken for the lookup in milliseconds.
    /// </summary>
    public double ElapsedMs { get; init; }

    /// <summary>
    /// Creates a cache hit result.
    /// </summary>
    public static ProvcacheServiceResult Hit(ProvcacheEntry entry, string source, double elapsedMs) => new()
    {
        Status = ProvcacheResultStatus.CacheHit,
        Entry = entry,
        Source = source,
        ElapsedMs = elapsedMs
    };

    /// <summary>
    /// Creates a cache miss result.
    /// </summary>
    public static ProvcacheServiceResult Miss(double elapsedMs) => new()
    {
        Status = ProvcacheResultStatus.CacheMiss,
        Entry = null,
        Source = null,
        ElapsedMs = elapsedMs
    };

    /// <summary>
    /// Creates a bypassed result (cache was skipped).
    /// </summary>
    public static ProvcacheServiceResult Bypassed() => new()
    {
        Status = ProvcacheResultStatus.Bypassed,
        Entry = null,
        Source = null,
        ElapsedMs = 0
    };

    /// <summary>
    /// Creates an expired result.
    /// </summary>
    public static ProvcacheServiceResult Expired(ProvcacheEntry entry, double elapsedMs) => new()
    {
        Status = ProvcacheResultStatus.Expired,
        Entry = entry,
        Source = "expired",
        ElapsedMs = elapsedMs
    };
}