<?php

declare(strict_types=1);

namespace App\Framework\StateManagement;

use App\Framework\Core\ValueObjects\Duration;

/**
 * Generic interface for state management
 *
 * @template T
 */
interface StateManager
{
    /**
     * Get state for given key
     *
     * @param string $key
     * @return T|null
     */
    public function getState(string $key): mixed;

    /**
     * Set state for given key
     *
     * @param string $key
     * @param T $state
     * @param Duration|null $ttl
     * @return void
     */
    public function setState(string $key, mixed $state, ?Duration $ttl = null): void;

    /**
     * Check if state exists for given key
     */
    public function hasState(string $key): bool;

    /**
     * Remove state for given key
     */
    public function removeState(string $key): void;

    /**
     * Update state atomically using callback
     *
     * @param string $key
     * @param callable(T|null): T $updater
     * @param Duration|null $ttl
     * @return T
     */
    public function updateState(string $key, callable $updater, ?Duration $ttl = null): mixed;

    /**
     * Get all states (if supported by implementation)
     *
     * @return array<string, T>
     */
    public function getAllStates(): array;

    /**
     * Clear all states
     */
    public function clearAll(): void;

    /**
     * Get state statistics
     */
    public function getStatistics(): StateManagerStatistics;
}
