<?php

declare(strict_types=1);

namespace App\Framework\Database\Cache;

use App\Framework\Core\ValueObjects\Duration;

/**
 * Second-Level Cache for entity data caching
 */
interface SecondLevelCacheInterface
{
    /**
     * Cache an entity by its class and ID
     */
    public function putEntity(string $entityClass, mixed $entityId, object $entity, ?Duration $ttl = null): bool;

    /**
     * Get an entity from cache by class and ID
     */
    public function getEntity(string $entityClass, mixed $entityId): ?object;

    /**
     * Check if entity exists in cache
     */
    public function hasEntity(string $entityClass, mixed $entityId): bool;

    /**
     * Remove entity from cache
     */
    public function evictEntity(string $entityClass, mixed $entityId): bool;

    /**
     * Cache query results
     */
    public function putQueryResult(QueryCacheKey $key, array $result, ?Duration $ttl = null): bool;

    /**
     * Get query results from cache
     */
    public function getQueryResult(QueryCacheKey $key): ?array;

    /**
     * Check if query result exists in cache
     */
    public function hasQueryResult(QueryCacheKey $key): bool;

    /**
     * Remove query result from cache
     */
    public function evictQueryResult(QueryCacheKey $key): bool;

    /**
     * Cache collection results
     */
    public function putCollection(string $entityClass, array $entities, string $cacheKey, ?Duration $ttl = null): bool;

    /**
     * Get collection from cache
     */
    public function getCollection(string $entityClass, string $cacheKey): ?array;

    /**
     * Check if collection exists in cache
     */
    public function hasCollection(string $entityClass, string $cacheKey): bool;

    /**
     * Remove collection from cache
     */
    public function evictCollection(string $entityClass, string $cacheKey): bool;

    /**
     * Invalidate all cache entries for a specific entity class
     */
    public function evictEntityClass(string $entityClass): int;

    /**
     * Clear all second-level cache
     */
    public function clear(): bool;

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

    /**
     * Get cache regions statistics
     */
    public function getRegionStats(): array;
}
