ioredis-toolkit 0.0.1

package/dist/client.d.ts

@@ -0,0 +1,177 @@
+import { Cluster, Redis as RedisClient } from "ioredis";
+import { type ClusterInfo, type ClusterSlotRange, type ConnectionStatus, type RedisConfigInput, type RedisMode } from "./types.js";
+import { type LoggerLike } from "./logger.js";
+import { Cache } from "./cache.js";
+import { PubSub } from "./pubsub.js";
+import { DistributedLock } from "./lock.js";
+import { RateLimiter } from "./ratelimiter.js";
+import { SessionManager } from "./session/session-manager.js";
+export interface RedisClientOptions {
+    config: RedisConfigInput;
+    logger?: LoggerLike;
+}
+/**
+ * Cluster-only administrative/capability surface.
+ */
+export interface ClusterCapabilities {
+    getClusterNodes(): RedisClient[];
+    getClusterSlots(): Promise<ClusterSlotRange[]>;
+    getClusterInfo(): ClusterInfo;
+    calculateSlot(key: string): number;
+    getSlotRanges(): Promise<Map<number, string[]>>;
+    getNodeForKey(key: string): Promise<RedisClient | null>;
+    isKeyServed(key: string): Promise<boolean>;
+    executeOnNode<T>(key: string, command: string, ...args: unknown[]): Promise<T>;
+    mgetClusterAware(keys: string[]): Promise<(string | null)[]>;
+    clearNamespaceClusterAware(prefix: string, options?: {
+        batchSize?: number;
+        scanCount?: number;
+    }): Promise<number>;
+}
+type ClusterMethodName = keyof ClusterCapabilities | "isCluster";
+/**
+ * Public client surface specialized by Redis topology.
+ */
+export type RedisClientForMode<M extends RedisMode> = M extends "cluster" ? Omit<RedisClientWrapper, "select" | ClusterMethodName> & ClusterCapabilities & {
+    isCluster(): true;
+} : Omit<RedisClientWrapper, "isCluster" | "getClusterNodes" | "getClusterSlots" | "getClusterInfo" | "calculateSlot" | "getSlotRanges" | "getNodeForKey" | "isKeyServed" | "executeOnNode" | "mgetClusterAware" | "clearNamespaceClusterAware"> & {
+    isCluster(): false;
+};
+type RedisUnderlyingClient = RedisClient | Cluster;
+type RedisCommandArgument = string | number | Buffer;
+type ScanOptions = {
+    count?: number;
+    batchSize?: number;
+};
+type DeletePatternOptions = {
+    batchSize?: number;
+    scanCount?: number;
+};
+/**
+ * Production-grade Redis client wrapper supporting:
+ *
+ * - standalone Redis
+ * - Redis Sentinel
+ * - Redis Cluster
+ * - connection lifecycle handling
+ * - slow-command tracking
+ * - cluster-aware multi-key operations
+ * - cache
+ * - pub/sub
+ * - distributed locks
+ * - rate limiting
+ * - sessions
+ */
+export declare class RedisClientWrapper {
+    private readonly client;
+    private _cache?;
+    private _pubsub?;
+    private _lock?;
+    private _rateLimiter?;
+    private _session?;
+    private readonly config;
+    private readonly logger;
+    private isReady;
+    constructor(config: RedisConfigInput, logger?: LoggerLike);
+    get mode(): RedisMode;
+    get cache(): Cache;
+    set cache(value: Cache);
+    get pubsub(): PubSub;
+    set pubsub(value: PubSub);
+    get lock(): DistributedLock;
+    set lock(value: DistributedLock);
+    get rateLimiter(): RateLimiter;
+    set rateLimiter(value: RateLimiter);
+    get session(): SessionManager;
+    set session(value: SessionManager);
+    private createClient;
+    private createClusterClient;
+    private createSentinelClient;
+    private createStandaloneClient;
+    private buildCommonRedisOptions;
+    private setupEventHandlers;
+    getRawClient<T extends RedisUnderlyingClient = RedisUnderlyingClient>(): T;
+    get raw(): RedisUnderlyingClient;
+    ping(): Promise<boolean>;
+    close(): Promise<void>;
+    private isClusterClient;
+    private exec;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string | Buffer, ttl?: number): Promise<"OK" | null>;
+    setexnx(key: string, value: string | Buffer, ttl?: number): Promise<"OK" | null>;
+    defineCommand(...args: Parameters<RedisClient["defineCommand"]>): ReturnType<RedisClient["defineCommand"]>;
+    eval(script: string, numKeys: number, ...args: RedisCommandArgument[]): Promise<unknown>;
+    evalsha(sha: string, script: string, numKeys: number, ...args: RedisCommandArgument[]): Promise<unknown>;
+    scriptLoad(script: string): Promise<string>;
+    setnx(key: string, value: string | Buffer, ttl?: number): Promise<number>;
+    del(...keys: string[]): Promise<number>;
+    getdel(key: string): Promise<string | null>;
+    exists(key: string): Promise<number>;
+    expire(key: string, ttl: number): Promise<number>;
+    ttl(key: string): Promise<number>;
+    incr(key: string): Promise<number>;
+    decr(key: string): Promise<number>;
+    incrby(key: string, amount: number): Promise<number>;
+    decrby(key: string, amount: number): Promise<number>;
+    time(): Promise<number>;
+    mget(...keys: string[]): Promise<(string | null)[]>;
+    mset(...pairs: Array<[
+        string,
+        string | Buffer
+    ]>): Promise<"OK">;
+    hget(key: string, field: string): Promise<string | null>;
+    hset(key: string, field: string, value: string | Buffer): Promise<number>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    hdel(key: string, ...fields: string[]): Promise<number>;
+    sadd(key: string, ...members: string[]): Promise<number>;
+    srem(key: string, ...members: string[]): Promise<number>;
+    smembers(key: string): Promise<string[]>;
+    sismember(key: string, member: string): Promise<number>;
+    zadd(key: string, score: number, member: string): Promise<number>;
+    zrange(key: string, start: number, stop: number): Promise<string[]>;
+    zcard(key: string): Promise<number>;
+    zrem(key: string, ...members: string[]): Promise<number>;
+    pipeline(): ReturnType<RedisClient["pipeline"]>;
+    scanIterator(pattern: string, count?: number): AsyncIterable<string>;
+    scanCluster(pattern: string, options?: ScanOptions): AsyncIterable<string[]>;
+    isCluster(): boolean;
+    getClusterNodes(): RedisClient[];
+    getClusterSlots(): Promise<ClusterSlotRange[]>;
+    calculateSlot(key: string): number;
+    getNodeForKey(key: string): Promise<RedisClient | null>;
+    getSlotRanges(): Promise<Map<number, string[]>>;
+    isKeyServed(key: string): Promise<boolean>;
+    executeOnNode<T>(key: string, command: string, ...args: unknown[]): Promise<T>;
+    private executeCommandOnClient;
+    mgetClusterAware(keys: string[]): Promise<(string | null)[]>;
+    deletePattern(pattern: string, options?: DeletePatternOptions): Promise<number>;
+    clearNamespace(prefix: string, options?: DeletePatternOptions): Promise<number>;
+    clearNamespaceClusterAware(prefix: string, options?: DeletePatternOptions): Promise<number>;
+    getClusterInfo(): ClusterInfo;
+    info(section?: string): Promise<string>;
+    select(database: number): Promise<"OK">;
+    getConnectionStatus(): ConnectionStatus;
+    private runWithConcurrency;
+}
+/**
+ * Cluster-specific factory overload.
+ */
+export declare function createRedisClient(config: Extract<RedisConfigInput, {
+    mode: "cluster";
+}>, logger?: LoggerLike): RedisClientForMode<"cluster">;
+/**
+ * Sentinel-specific factory overload.
+ */
+export declare function createRedisClient(config: Extract<RedisConfigInput, {
+    mode: "sentinel";
+}>, logger?: LoggerLike): RedisClientForMode<"sentinel">;
+/**
+ * Standalone factory overload.
+ *
+ * Standalone is also the default topology, therefore the input type permits
+ * the discriminator to be omitted.
+ */
+export declare function createRedisClient(config: Exclude<RedisConfigInput, {
+    mode: "cluster" | "sentinel";
+}>, logger?: LoggerLike): RedisClientForMode<"standalone">;
+export {};