import type Redis from 'ioredis';
import type { RedisKey } from 'ioredis';
import type { AcquiredResult, AcquireDesire, AcquireOptions } from './Acquire';
import type { AcquireHelper } from './AcquireHelper';
interface Parser {
    parse: (text: string) => any;
    stringify: (value: any) => string;
}
interface CacheOptions {
    redis: Redis;
    parser?: Parser;
    acquire?: AcquireHelper;
    acquireType?: AcquireType;
}
declare type Key = RedisKey | number;
declare type AcquireType = 'lua' | 'pipeline';
declare type Mapping<T> = {
    [id: string]: T;
};
declare type ValueSource<K extends Key, T> = Mapping<T> | T[] | Map<K, T>;
declare type ValueMap<T> = Mapping<T | undefined>;
declare type Awaitable<T> = T | Promise<T>;
declare const NOT_FOUND_VALUE: undefined;
declare type CacheReturn<T> = T | typeof NOT_FOUND_VALUE;
declare class Cache {
    redis: Redis;
    private readonly acquireHelper;
    protected prefix: string;
    protected parser: Parser;
    /**
     * @param options - Either an ioredis instance directly or a CacheOptions object
     *   with a `redis` property plus optional `parser`, `acquire`, and
     *   `acquireType`. Throws if the redis instance doesn't satisfy the ioredis
     *   interface check.
     */
    constructor(options: Redis | CacheOptions);
    private createAcquireHelper;
    /**
     * Binds all prototype methods of Cache to a target instance so they can be
     * destructured and called without losing the `this` context.
     *
     * @returns The same target instance after binding.
     */
    static bindAll(target: Cache): Cache;
    /**
     * Read-through cache for a single key. Checks the cache first; if the value
     * is missing, calls `fn` to produce it, stores the result, and returns it.
     *
     * @param key - Cache key to look up.
     * @param fn - Factory function invoked on cache miss.
     * @param ttl - Optional TTL in seconds. If omitted the value is stored
     *   without expiry.
     */
    cache<T>(key: Key, fn: () => Awaitable<T>, ttl?: number): Promise<T>;
    /**
     * Retrieves a single cached value by key. Returns `undefined` when the key
     * is not found (the `NOT_FOUND_VALUE` sentinel), making it safe to
     * distinguish a cache miss from a stored value.
     */
    getCache<T>(key: Key): Promise<CacheReturn<T>>;
    /**
     * Stores a single value in the cache. The value is serialized through the
     * configured parser (default: JSON).
     *
     * @param ttl - Optional TTL in seconds. Uses `SETEX` when provided, plain
     *   `SET` otherwise.
     */
    setCache(key: Key, value: any, ttl?: number): Promise<"OK">;
    /**
     * Read-through cache for multiple keys in a single batch. Executes a single
     * `MGET` for all keys, then calls `fn` for any missing keys and stores the
     * result via `MSET` (or pipelined `SETEX` when TTL is provided).
     *
     * @param keys - List of logical keys to fetch.
     * @param fn - Factory invoked with the subset of keys that were not cached.
     *   Must return values in the same order as the supplied keys.
     * @param prefix - Optional string (or number) prepended to every key before
     *   interacting with Redis. The prefix is stripped from cached results.
     * @param ttl - Optional TTL in seconds for newly stored values.
     */
    manyCache<K extends Key, T>(keys: K[], fn: (keys: K[]) => Awaitable<ValueSource<K, T>>, prefix?: Key, ttl?: number): Promise<T[]>;
    /**
     * Retrieves multiple cached values by their keys using `MGET`. Returns an
     * array aligned with the input keys where missing entries are `undefined`
     * (the `NOT_FOUND_VALUE` sentinel).
     */
    getManyCache<T = any>(keys: Key[]): Promise<CacheReturn<T>[]>;
    /**
     * Stores multiple key-value pairs atomically. Uses `MSET` when no TTL is
     * given; otherwise uses a pipeline of `MSET` + per-key `EXPIRE` commands.
     *
     * @param valueMap - A plain object mapping string keys to serialisable values.
     * @param ttl - Optional TTL in seconds applied to every key in the batch.
     */
    setManyCache(valueMap: {
        [id: string]: any;
    }, ttl?: number): Promise<[error: Error | null, result: unknown][] | "OK" | null>;
    /**
     * Deletes one or more keys from the cache.
     *
     * @returns The number of keys that were actually removed.
     */
    deleteCache(...keys: Key[]): Promise<number>;
    /**
     * Deletes all keys matching a glob pattern by iterating with `SCAN` in
     * batches. The `keyPrefix` configured on the ioredis instance is
     * automatically prepended to the pattern so callers don't need to include it.
     *
     * @param pattern - Redis glob pattern (e.g. `user:*`).
     * @param batch - Number of keys to scan and delete per pipeline (default 100).
     */
    deletePattern(pattern: string, batch?: number): Promise<void>;
    /**
     * Read-through cache for a single field inside a Redis hash. Checks the hash
     * first; on miss calls `fn`, stores the result, and returns it.
     *
     * @param key - The Redis hash key.
     * @param id - The field name within the hash.
     * @param fn - Factory function invoked on cache miss.
     */
    hashCache<T>(key: Key, id: Key, fn: () => Awaitable<T>): Promise<T>;
    /**
     * Retrieves a single field from a Redis hash. Returns `undefined` (the
     * `NOT_FOUND_VALUE` sentinel) when the field does not exist.
     */
    getHashCache<T>(key: Key, id: Key): Promise<CacheReturn<T>>;
    /**
     * Stores a single field in a Redis hash. The value is serialised through the
     * configured parser.
     */
    setHashCache(key: Key, id: Key, value: any): Promise<number>;
    /**
     * Read-through cache for multiple fields within a single Redis hash. Issues
     * a single `HMGET`, calls `fn` for any missing fields, persists them with
     * `HMSET`, and returns the merged result aligned with the input `ids`.
     *
     * @param key - The Redis hash key.
     * @param ids - Field names to fetch.
     * @param fn - Factory invoked with the subset of field names that are not
     *   cached. Must return values in the same order.
     */
    hashManyCache<K extends Key, T>(key: Key, ids: K[], fn: (ids: K[]) => Awaitable<ValueSource<K, T>>): Promise<T[]>;
    /**
     * Retrieves multiple fields from a Redis hash using `HMGET`. Returns an
     * array aligned with the input `ids` where missing fields are `undefined`
     * (the `NOT_FOUND_VALUE` sentinel).
     */
    getHashManyCache<T>(key: Key, ids: Key[]): Promise<CacheReturn<T>[]>;
    /**
     * Stores multiple fields in a Redis hash atomically using `HMSET`.
     *
     * @param key - The Redis hash key.
     * @param valueMap - A plain object mapping field names to serialisable values.
     */
    setHashManyCache(key: Key, valueMap: {
        [id: string]: any;
    }): Promise<never[] | "OK">;
    /**
     * Deletes one or more fields from a Redis hash.
     *
     * @returns The number of fields that were actually removed.
     */
    deleteHashCache(key: Key, ...ids: Key[]): Promise<number>;
    /**
     * Atomically increments (or decrements) a Redis key and invokes `fn` with
     * the updated value. On failure the increment is automatically rolled back.
     *
     * @param key - Redis key holding the counter.
     * @param amount - Amount to add (use a negative number to decrement).
     * @param fn - Callback receiving current, acquired, and lacking amounts.
     * @param options - When `float` is true uses `INCRBYFLOAT`; `limit` caps
     *   how much can be acquired.
     */
    acquire<T>(key: Key, amount: number, fn: (currentAmount: number, acquiredAmount: number, lackingAmount: number) => Awaitable<T>, options?: AcquireOptions | boolean): Promise<T>;
    /**
     * Atomically increments (or decrements) a field inside a Redis hash and
     * invokes `fn` with the updated value.
     *
     * @param key - The Redis hash key.
     * @param id - The field name within the hash.
     * @param amount - Amount to add.
     * @param fn - Callback receiving current, acquired, and lacking amounts.
     * @param options - When `float` is true uses `HINCRBYFLOAT`; `limit` caps
     *   how much can be acquired.
     */
    hashAcquire<T>(key: Key, id: Key, amount: number, fn: (currentAmount: number, acquiredAmount: number, lackingAmount: number) => Awaitable<T>, options?: AcquireOptions | boolean): Promise<T>;
    /**
     * Atomically modifies multiple counters through the configured acquire
     * helper. Each desired change is specified as an `AcquireDesire` item; `fn`
     * receives the final values.
     */
    acquireMany<K extends string | number, T>(items: AcquireDesire<K>[], fn: (acquireResult: AcquiredResult<K>[]) => Awaitable<T>, options?: AcquireOptions): Promise<T>;
    /**
     * Atomically modifies multiple fields inside a single Redis hash counter
     * through the configured acquire helper.
     *
     * @param hashKey - The Redis hash key containing the counters.
     * @param items - Desired changes for each field.
     * @param fn - Callback receiving the array of results.
     */
    hashAcquireMany<K extends string | number, T>(hashKey: string, items: AcquireDesire<K>[], fn: (acquireResult: AcquiredResult<K>[]) => Awaitable<T>, options?: AcquireOptions): Promise<T>;
    /**
     * Filters the input `keys` down to those whose corresponding entry in
     * `cachedValues` is `NOT_FOUND_VALUE`.
     */
    protected _getUncachedKeys<K extends Key, T>(keys: K[], cachedValues: CacheReturn<T>[]): K[];
    /**
     * Merges a set of cached values with a map of uncached values. Where a
     * cached entry is `NOT_FOUND_VALUE`, the corresponding value is looked up
     * from `uncachedValueMap` by key.
     */
    protected _mergeCacheValues<K extends Key, T>(cachedValues: CacheReturn<T>[], keys: K[], uncachedValueMap: ValueMap<T>): T[];
    /**
     * Returns a new map with every key prefixed by `prefix`. Used internally
     * by `manyCache` to apply the configured prefix before storing.
     */
    protected _prefixValueMap<T>(valueMap: ValueMap<T>, prefix: Key): ValueMap<T>;
    /**
     * Converts a value map into a flat array of `[key, stringifiedValue, key,
     * stringifiedValue, ...]` suitable for `MSET` / `HMSET`. Entries whose
     * value is `NOT_FOUND_VALUE` are skipped.
     */
    protected _buildSetParams: (valueMap: {
        [id: string]: any;
    }) => string[];
    /**
     * Normalises a `ValueSource` (array, `Map`, or plain object) into a uniform
     * `ValueMap` keyed by the string representation of each id. Array and `Map`
     * sources are aligned with `ids` by position.
     */
    protected _buildValueMap<K extends Key, T>(ids: K[], valueMap: ValueSource<K, T>): ValueMap<T>;
}
export default Cache;