<?php

declare(strict_types=1);

namespace App\Framework\Cache\Metrics;

interface CacheMetricsInterface
{
    /**
     * Record a cache hit
     */
    public function recordHit(string $driver, string $key, int $size = 0, float $latency = 0.0): void;

    /**
     * Record a cache miss
     */
    public function recordMiss(string $driver, string $key, float $latency = 0.0): void;

    /**
     * Record a cache set operation
     */
    public function recordSet(string $driver, string $key, int $size, int $ttl, float $latency = 0.0): void;

    /**
     * Record a cache delete operation
     */
    public function recordDelete(string $driver, string $key, float $latency = 0.0): void;

    /**
     * Record a cache clear operation
     */
    public function recordClear(string $driver, float $latency = 0.0): void;

    /**
     * Get comprehensive cache statistics
     */
    public function getStats(): CacheStatsSnapshot;

    /**
     * Get statistics for a specific driver
     */
    public function getStatsForDriver(string $driver): array;

    /**
     * Reset all statistics
     */
    public function reset(): void;

    /**
     * Get real-time hit rate
     */
    public function getHitRate(): float;

    /**
     * Get most frequently accessed keys
     */
    public function getTopKeys(int $limit = 10): array;

    /**
     * Get largest cached items
     */
    public function getHeaviestKeys(int $limit = 10): array;
}
