syntropylog/dist/types/redis/RedisConnectionManager.d.ts

An instance manager with observability for Node.js applications

import { ILogger } from '../logger';
import { NodeRedisClient } from './redis.types.js';
import { RedisInstanceConfig } from '../config';
/**
 * @class RedisConnectionManager
 * Handles the state and lifecycle of a single native `node-redis` client.
 * It abstracts away the complexities of connection states, retries, and events,
 * providing a stable and predictable promise-based interface for connecting and disconnecting.
 */
export declare class RedisConnectionManager {
    readonly instanceName: string;
    private readonly client;
    private readonly logger;
    private connectionPromise;
    private connectionResolve;
    private connectionReject;
    private isConnectedAndReadyState;
    private isQuitState;
    /**
     * Constructs a new RedisConnectionManager.
     * @param {RedisClientOptions | RedisClusterOptions} options - The configuration options for the native `redis` client.
     * @param {ILogger} logger - The logger instance for logging connection events.
     */
    constructor(config: RedisInstanceConfig, logger: ILogger);
    /**
     * Creates a native Redis client based on the instance configuration mode.
     * @param config The configuration for the specific Redis instance.
     * @returns A `NodeRedisClient` (either single-node or cluster).
     */
    private createNativeClient;
    /**
     * Sets up all the necessary event listeners on the native Redis client
     * to manage and report on the connection's lifecycle state.
     * @private
     */
    private setupListeners;
    /**
     * Initiates a connection to the Redis server.
     * This method is idempotent; it will not attempt to reconnect if already connected
     * or if a connection attempt is already in progress.
     * @returns {Promise<void>} A promise that resolves when the client is connected and ready, or rejects on a connection error.
     */
    connect(): Promise<void>;
    /**
     * Ensures the client is connected and ready before proceeding.
     * This is the primary method that should be awaited before executing a command.
     * @returns {Promise<void>} A promise that resolves when the client is ready, or rejects if it can't connect.
     */
    ensureReady(): Promise<void>;
    /**
     * Gracefully closes the connection to the Redis server by calling `quit()`.
     * It also sets an internal state to prevent any further operations or reconnections.
     * @returns {Promise<void>} A promise that resolves when the client has been successfully quit.
     */
    disconnect(): Promise<void>;
    /**
     * Retrieves the underlying native `node-redis` client instance.
     * @returns {NodeRedisClient} The native client instance.
     */
    getNativeClient(): NodeRedisClient;
    /**
     * Checks if the client is currently connected and ready to accept commands.
     * @returns {boolean} `true` if the client is ready, `false` otherwise.
     */
    isReady(): boolean;
    /**
     * Performs a health check by sending a PING command to the server.
     * @returns {Promise<boolean>} A promise that resolves to `true` if the server responds correctly, `false` otherwise.
     */
    isHealthy(): Promise<boolean>;
    /**
     * Checks if the disconnect (`quit`) process has been initiated for this client.
     * @returns {boolean} `true` if `disconnect` has been called, `false` otherwise.
     */
    isQuit(): boolean;
    /**
     * Executes the Redis PING command.
     * Provides a fallback for cluster mode, as PING is not a standard cluster command.
     */
    ping(message?: string): Promise<string>;
    /**
     * Executes the Redis INFO command.
     * Provides a fallback for cluster mode.
     */
    info(section?: string): Promise<string>;
    /**
     * Executes the Redis EXISTS command.
     * @param {string | string[]} keys - A single key or an array of keys to check.
     * @returns {Promise<number>} A promise that resolves with the number of existing keys.
     */
    exists(keys: string | string[]): Promise<number>;
    /**
     * Executes the Redis GET command.
     * @param {string} key - The key to retrieve.
     * @returns {Promise<string | null>} A promise that resolves with the value or null if not found.
     */
    get(key: string): Promise<string | null>;
    /**
     * Executes the Redis SET command.
     * @param {string} key - The key to set.
     * @param {string} value - The value to set.
     * @param {number} [ttl] - Optional TTL in seconds.
     * @returns {Promise<string>} A promise that resolves with 'OK' on success.
     */
    set(key: string, value: string, ttl?: number): Promise<string>;
    /**
     * Executes the Redis DEL command.
     * @param {string} key - The key to delete.
     * @returns {Promise<number>} A promise that resolves with the number of keys deleted.
     */
    del(key: string): Promise<number>;
}