/**
 * Result shape returned by {@link RedisLike.scan}.
 *
 * Compatible with both `ioredis` (which returns `[cursor, keys]`) and
 * `node-redis` (which returns `{ cursor, keys }`) — adapters normalise into
 * this shape.
 */
export interface RedisScanResult {
    /** Opaque cursor; `"0"` signals end of iteration. */
    cursor: string;
    /** Keys discovered in this batch (may be empty). */
    keys: string[];
}

/**
 * Options accepted by {@link RedisLike.set}.
 *
 * `EX` and `PX` are mutually exclusive; the cache only ever emits `EX`.
 */
export interface RedisSetOptions {
    /** Expire-time in seconds (Redis `EX`). */
    EX?: number;
    /** Expire-time in milliseconds (Redis `PX`). Unused by this package. */
    PX?: number;
}

/**
 * Options accepted by {@link RedisLike.scan}.
 *
 * `MATCH` is the glob pattern; `COUNT` is a hint to the server.
 */
export interface RedisScanOptions {
    MATCH?: string;
    COUNT?: number;
}

/**
 * Minimal Redis client surface consumed by {@link RedisCache}.
 *
 * Implementations need not be Redis-specific — any data store offering these
 * primitives with the documented semantics will satisfy the contract. The
 * canonical adapters are `ioredis` and `node-redis`; tests use an in-memory
 * `FakeRedis` stub.
 */
export interface RedisLike {
    /** `SET key value [EX seconds]`. Returns the server response (typically `"OK"`). */
    set(
        key: string,
        value: string,
        options?: RedisSetOptions
    ): Promise<unknown>;
    /** `GET key`. Returns `null` for misses. */
    get(key: string): Promise<string | null>;
    /** `DEL key1 [key2 ...]`. Returns the number of keys deleted. */
    del(...keys: string[]): Promise<number>;
    /** `EXISTS key1 [key2 ...]`. Returns the number of matching keys. */
    exists(...keys: string[]): Promise<number>;
    /** `TTL key`. Returns seconds, `-1` for "no expiry", `-2` for "missing". */
    ttl(key: string): Promise<number>;
    /** `EXPIRE key seconds`. Returns `1` on success, `0` when the key is missing. */
    expire(key: string, seconds: number): Promise<number>;
    /** `MGET key1 [key2 ...]`. Optional; if absent the cache falls back to per-key `get`. */
    mget?(...keys: string[]): Promise<Array<string | null>>;
    /** `SCAN cursor [MATCH pattern] [COUNT count]`. */
    scan(cursor: string, options?: RedisScanOptions): Promise<RedisScanResult>;
}