<?php

declare(strict_types=1);

namespace App\Framework\Performance\Contracts;

use App\Framework\Performance\PerformanceCategory;
use App\Framework\Performance\PerformanceConfig;
use App\Framework\Performance\PerformanceMetric;

interface PerformanceServiceInterface
{
    /**
     * Measure a callable's execution time and memory usage
     */
    public function measure(string $key, callable $callback, PerformanceCategory $category = PerformanceCategory::CUSTOM, array $context = []): mixed;

    /**
     * Start timing an operation
     */
    public function startTiming(string $key, PerformanceCategory $category = PerformanceCategory::CUSTOM, array $context = []): void;

    /**
     * End timing an operation
     */
    public function endTiming(string $key): void;

    /**
     * Record a metric value
     */
    public function recordMetric(string $key, float $value, PerformanceCategory $category = PerformanceCategory::CUSTOM, array $context = []): void;

    /**
     * Increment a counter
     */
    public function increment(string $key, int $amount = 1, PerformanceCategory $category = PerformanceCategory::CUSTOM, array $context = []): void;

    /**
     * Get all metrics for a category
     *
     * @return array<string, PerformanceMetric>
     */
    public function getMetrics(?PerformanceCategory $category = null): array;

    /**
     * Get a specific metric
     */
    public function getMetric(string $key): ?PerformanceMetric;

    /**
     * Generate a performance report
     *
     * @param string $format Supported formats: 'array', 'json', 'html', 'text'
     * @return string|array
     */
    public function generateReport(string $format = 'array'): string|array;

    /**
     * Get current request statistics
     *
     * @return array{
     *     time_ms: float,
     *     memory_bytes: int,
     *     peak_memory_bytes: int,
     *     metrics_count: int
     * }
     */
    public function getRequestStats(): array;

    /**
     * Get performance summary
     *
     * @return array
     */
    public function getSummary(): array;

    /**
     * Get slowest operations
     *
     * @param int $limit Maximum number of operations to return
     * @return array
     */
    public function getSlowestOperations(int $limit = 10): array;

    /**
     * Export metrics to array for external processing
     *
     * @return array
     */
    public function exportMetrics(): array;

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

    /**
     * Check if performance tracking is enabled
     */
    public function isEnabled(): bool;

    /**
     * Enable or disable performance tracking
     */
    public function setEnabled(bool $enabled): void;

    /**
     * Get configuration
     */
    public function getConfig(): PerformanceConfig;

    // Convenience methods for common operations

    /**
     * Measure database query timing
     */
    public function measureDatabaseQuery(string $queryType, callable $callback, array $context = []): mixed;

    /**
     * Measure cache operation timing
     */
    public function measureCacheOperation(string $operation, callable $callback, array $context = []): mixed;

    /**
     * Measure view rendering timing
     */
    public function measureViewRender(string $view, callable $callback, array $context = []): mixed;
}
