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

An instance manager with observability for Node.js applications

/**
 * @file src/redis/BeaconRedis.ts
 * @description Implementation of IBeaconRedis that wraps a native `redis` client.
 * It centralizes command execution to add instrumentation (logging, metrics, etc.).
 */
import { IBeaconRedis, IBeaconRedisTransaction } from './IBeaconRedis';
import { RedisInstanceConfig, RedisInstanceReconfigurableConfig } from '../config';
import { ILogger } from '../logger/ILogger';
import { RedisCommandExecutor } from './RedisCommandExecutor';
import { RedisConnectionManager } from './RedisConnectionManager';
import { RedisZMember } from './redis.types';
import { RedisValue, RedisListElement, RedisSetMember, RedisHashValue, RedisCommandOptions } from '../types';
/**
 * The primary implementation of the `IBeaconRedis` interface.
 * This class wraps a native `redis` client and uses a central logger
 * to provide instrumentation for all commands. It delegates connection
 * management and command execution to specialized classes.
 * @implements {IBeaconRedis}
 */
export declare class BeaconRedis implements IBeaconRedis {
    private config;
    /** @private The logger instance for this specific Redis client. */
    private readonly logger;
    /** @private Manages the connection state and lifecycle of the native client. */
    private readonly connectionManager;
    /** @private Executes the actual commands against the native client. */
    private readonly commandExecutor;
    /**
     * Constructs a new BeaconRedis instance.
     * @param {RedisInstanceConfig} config - The configuration specific to this Redis instance.
     * @param {RedisConnectionManager} connectionManager - The manager for the client's connection lifecycle.
     * @param {RedisCommandExecutor} commandExecutor - The executor for sending commands to Redis.
     * @param {ILogger} logger - The pre-configured logger instance for this client.
     */
    constructor(config: RedisInstanceConfig, connectionManager: RedisConnectionManager, commandExecutor: RedisCommandExecutor, logger: ILogger);
    /**
     * @inheritdoc
     */
    getInstanceName(): string;
    /**
     * @inheritdoc
     */
    connect(): Promise<void>;
    /**
     * @inheritdoc
     */
    quit(): Promise<void>;
    /**
     * @inheritdoc
     */
    updateConfig(newConfig: Partial<RedisInstanceReconfigurableConfig>): void;
    /**
     * @inheritdoc
     * @throws {Error} This method is not yet implemented.
     */
    multi(): IBeaconRedisTransaction;
    /**
     * A centralized method for executing and instrumenting any Redis command.
     * It ensures the client is ready, executes the command, logs the outcome
     * (success or failure) with timing information, and handles errors.
     * @private
     * @template T The expected return type of the command.
     * @param {string} commandName - The name of the Redis command (e.g., 'GET', 'HSET').
     * @param {() => Promise<T>} commandFn - A function that, when called, executes the native Redis command.
     * @param {...RedisValue[]} params - The parameters passed to the original command, used for logging.
     * @returns {Promise<T>} A promise that resolves with the result of the command.
     * @throws The error from the native command is re-thrown after being logged.
     */
    private _executeCommand;
    /**
     * @inheritdoc
     */
    get(key: string): Promise<string | null>;
    /**
     * @inheritdoc
     */
    set(key: string, value: string, ttlSeconds?: number): Promise<string | null>;
    /**
     * @inheritdoc
     */
    del(keys: string | string[]): Promise<number>;
    /**
     * @inheritdoc
     */
    exists(keys: string | string[]): Promise<number>;
    /**
     * @inheritdoc
     */
    expire(key: string, seconds: number): Promise<boolean>;
    /**
     * @inheritdoc
     */
    ttl(key: string): Promise<number>;
    /**
     * @inheritdoc
     */
    incr(key: string): Promise<number>;
    /**
     * @inheritdoc
     */
    decr(key: string): Promise<number>;
    /**
     * @inheritdoc
     */
    incrBy(key: string, increment: number): Promise<number>;
    /**
     * @inheritdoc
     */
    decrBy(key: string, decrement: number): Promise<number>;
    /**
     * @inheritdoc
     */
    hGet(key: string, field: string): Promise<string | null>;
    /**
     * @inheritdoc
     */
    hSet(key: string, fieldsAndValues: Record<string, RedisHashValue>): Promise<number>;
    hSet(key: string, field: string, value: RedisHashValue): Promise<number>;
    /**
     * @inheritdoc
     */
    hGetAll(key: string): Promise<Record<string, string>>;
    /**
     * @inheritdoc
     */
    hDel(key: string, fields: string | string[]): Promise<number>;
    /**
     * @inheritdoc
     */
    hExists(key: string, field: string): Promise<boolean>;
    /**
     * @inheritdoc
     */
    hIncrBy(key: string, field: string, increment: number): Promise<number>;
    /**
     * @inheritdoc
     */
    lPush(key: string, element: RedisListElement): Promise<number>;
    lPush(key: string, elements: RedisListElement[]): Promise<number>;
    /**
     * @inheritdoc
     */
    rPush(key: string, element: RedisListElement): Promise<number>;
    rPush(key: string, elements: RedisListElement[]): Promise<number>;
    /**
     * @inheritdoc
     */
    lPop(key: string): Promise<string | null>;
    /**
     * @inheritdoc
     */
    rPop(key: string): Promise<string | null>;
    /**
     * @inheritdoc
     */
    lRange(key: string, start: number, stop: number): Promise<string[]>;
    /**
     * @inheritdoc
     */
    lLen(key: string): Promise<number>;
    /**
     * @inheritdoc
     */
    lTrim(key: string, start: number, stop: number): Promise<string>;
    /**
     * @inheritdoc
     */
    sAdd(key: string, member: RedisSetMember): Promise<number>;
    sAdd(key: string, members: RedisSetMember[]): Promise<number>;
    /**
     * @inheritdoc
     */
    sMembers(key: string): Promise<string[]>;
    /**
     * @inheritdoc
     */
    sIsMember(key: string, member: RedisSetMember): Promise<boolean>;
    /**
     * @inheritdoc
     */
    sRem(key: string, member: any): Promise<number>;
    sRem(key: string, members: any[]): Promise<number>;
    /**
     * @inheritdoc
     */
    sCard(key: string): Promise<number>;
    /**
     * @inheritdoc
     */
    zAdd(key: string, score: number, member: any): Promise<number>;
    zAdd(key: string, members: {
        score: number;
        value: any;
    }[]): Promise<number>;
    /**
     * @inheritdoc
     */
    zRange(key: string, min: string | number, max: string | number, options?: RedisCommandOptions): Promise<string[]>;
    /**
     * @inheritdoc
     */
    zRangeWithScores(key: string, min: string | number, max: string | number, options?: RedisCommandOptions): Promise<RedisZMember[]>;
    /**
     * @inheritdoc
     */
    zRem(key: string, members: RedisValue | RedisValue[]): Promise<number>;
    /**
     * @inheritdoc
     */
    zCard(key: string): Promise<number>;
    /**
     * @inheritdoc
     */
    zScore(key: string, member: RedisValue): Promise<number | null>;
    /**
     * Subscribes the client to a channel to listen for messages.
     * Note: This is a long-lived command. The initial subscription action is logged,
     * but individual messages received by the listener are not logged by this wrapper.
     * The listener itself should handle any required logging for received messages.
     * @param {string} channel - The channel to subscribe to.
     * @param {(message: string, channel: string) => void} listener - The function to call when a message is received.
     * @returns {Promise<void>} A promise that resolves when the subscription is successful.
     */
    subscribe(channel: string, listener: (message: string, channel: string) => void): Promise<void>;
    /**
     * Unsubscribes the client from a channel, or all channels if none is specified.
     * @param {string} [channel] - The optional channel to unsubscribe from.
     * @returns {Promise<void>} A promise that resolves when the unsubscription is successful.
     */
    unsubscribe(channel?: string): Promise<void>;
    /**
     * @inheritdoc
     */
    ping(message?: string): Promise<string>;
    /**
     * @inheritdoc
     */
    info(section?: string): Promise<string>;
    /**
     * Executes a Lua script on the server.
     * @param {string} script - The Lua script to execute.
     * @param {string[]} keys - An array of key names used by the script, accessible via the `KEYS` table in Lua.
     * @param {string[]} args - An array of argument values for the script, accessible via the `ARGV` table in Lua.
     * @returns {Promise<any>} A promise that resolves with the result of the script execution.
     */
    eval(script: string, keys: string[], args: string[]): Promise<RedisValue>;
}