<?php

declare(strict_types=1);

namespace App\Framework\Redis;

use Redis;

/**
 * Interface for Redis connections with different purposes
 */
interface RedisConnectionInterface
{
    /**
     * Get the underlying Redis client
     */
    public function getClient(): Redis;

    /**
     * Get the database number this connection uses
     */
    public function getDatabase(): int;

    /**
     * Get a descriptive name for this connection
     */
    public function getName(): string;

    /**
     * Check if the connection is alive
     */
    public function isConnected(): bool;

    /**
     * Reconnect if connection is lost
     */
    public function reconnect(): void;

    /**
     * Flush all keys in current database
     * WARNING: Destructive operation!
     */
    public function flush(): void;

    /**
     * Get value for given key
     * Returns false if key doesn't exist
     */
    public function get(string $key): string|false;

    /**
     * Set key-value pair with optional expiration in seconds
     */
    public function set(string $key, string $value, ?int $ttl = null): bool;

    /**
     * Delete one or more keys
     * Returns number of keys deleted
     */
    public function delete(string ...$keys): int;

    /**
     * Check if one or more keys exist
     * Returns number of existing keys
     */
    public function exists(string ...$keys): int;

    /**
     * Get TTL for key in seconds
     * Returns -1 if key has no expiration
     * Returns -2 if key doesn't exist
     */
    public function ttl(string $key): int;

    /**
     * Set expiration on existing key in seconds
     */
    public function expire(string $key, int $seconds): bool;

    /**
     * Increment numeric value by amount (default: 1)
     */
    public function incr(string $key, int $by = 1): int;

    /**
     * Decrement numeric value by amount (default: 1)
     */
    public function decr(string $key, int $by = 1): int;

    /**
     * Get multiple values at once
     * Returns array of values (false for missing keys)
     *
     * @param array<string> $keys
     * @return array<string|false>
     */
    public function mGet(array $keys): array;

    /**
     * Set multiple key-value pairs at once
     *
     * @param array<string, string> $keyValuePairs
     */
    public function mSet(array $keyValuePairs): bool;

    /**
     * Execute arbitrary Redis command
     * Provides direct access to any Redis command
     *
     * @param string $command Redis command name (e.g., 'KEYS', 'SCAN', 'HGETALL')
     * @param string|int ...$arguments Command arguments
     * @return mixed Command result
     */
    public function command(string $command, string|int ...$arguments): mixed;
}
