ioredis-toolkit 0.0.1

package/dist/client.js

@@ -0,0 +1,958 @@
+import { Cluster, Redis as RedisClient, } from "ioredis";
+import { ConfigurationError, RedisError } from "./errors.js";
+import { RedisConfigSchema, } from "./types.js";
+import { defaultLogger } from "./logger.js";
+import { executeBySlot } from "./cluster.js";
+import { calculateRedisClusterSlot } from "./cluster-slot.js";
+import { Cache } from "./cache.js";
+import { PubSub } from "./pubsub.js";
+import { DistributedLock } from "./lock.js";
+import { RateLimiter } from "./ratelimiter.js";
+import { createSessionManager, } from "./session/session-manager.js";
+import { prettifyError } from "zod";
+// ============================================================================
+// Type Guards
+// ============================================================================
+function isClusterConfig(config) {
+    return config.mode === "cluster";
+}
+function isSentinelConfig(config) {
+    return config.mode === "sentinel";
+}
+function isStandaloneConfig(config) {
+    return config.mode === "standalone";
+}
+// ============================================================================
+// Redis Client
+// ============================================================================
+/**
+ * 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 class RedisClientWrapper {
+    client;
+    _cache;
+    _pubsub;
+    _lock;
+    _rateLimiter;
+    _session;
+    config;
+    logger;
+    isReady = false;
+    // ========================================================================
+    // Constructor
+    // ========================================================================
+    constructor(config, logger = defaultLogger) {
+        const parsed = RedisConfigSchema.safeParse(config);
+        if (!parsed.success) {
+            throw new ConfigurationError(`Invalid Redis config: ${parsed.error.message}`, {
+                config,
+                message: prettifyError(parsed.error),
+            });
+        }
+        /**
+         * IMPORTANT:
+         *
+         * `parsed.data` is already `RedisConfig`.
+         *
+         * Do NOT cast it back to `RedisConfigInput`.
+         * Do NOT normalize it manually.
+         *
+         * The Zod schema is the normalization boundary.
+         */
+        this.config = parsed.data;
+        this.logger = logger.child({
+            component: "RedisClient",
+        });
+        this.client = this.createClient();
+        this.setupEventHandlers();
+    }
+    // ========================================================================
+    // Configuration
+    // ========================================================================
+    get mode() {
+        return this.config.mode;
+    }
+    // ========================================================================
+    // Cache
+    // ========================================================================
+    get cache() {
+        if (!this._cache) {
+            this._cache = new Cache(this, this.config, this.logger);
+        }
+        return this._cache;
+    }
+    set cache(value) {
+        this._cache = value;
+    }
+    // ========================================================================
+    // Pub/Sub
+    // ========================================================================
+    get pubsub() {
+        if (!this._pubsub) {
+            this._pubsub = new PubSub(this, this.logger);
+        }
+        return this._pubsub;
+    }
+    set pubsub(value) {
+        this._pubsub = value;
+    }
+    // ========================================================================
+    // Distributed Lock
+    // ========================================================================
+    get lock() {
+        if (!this._lock) {
+            this._lock = new DistributedLock(this, this.logger);
+        }
+        return this._lock;
+    }
+    set lock(value) {
+        this._lock = value;
+    }
+    // ========================================================================
+    // Rate Limiter
+    // ========================================================================
+    get rateLimiter() {
+        if (!this._rateLimiter) {
+            this._rateLimiter = new RateLimiter(this);
+        }
+        return this._rateLimiter;
+    }
+    set rateLimiter(value) {
+        this._rateLimiter = value;
+    }
+    // ========================================================================
+    // Session
+    // ========================================================================
+    get session() {
+        if (!this._session) {
+            const sessionOptions = this.config.sessionOptions;
+            if (sessionOptions) {
+                const { client: customClient, ...options } = sessionOptions;
+                this._session = createSessionManager({
+                    client: customClient ?? this,
+                    ...options,
+                });
+            }
+            else {
+                this._session = createSessionManager({
+                    client: this,
+                });
+            }
+        }
+        return this._session;
+    }
+    set session(value) {
+        this._session = value;
+    }
+    // ========================================================================
+    // Client Creation
+    // ========================================================================
+    createClient() {
+        const common = this.buildCommonRedisOptions();
+        const retryStrategy = (times) => {
+            if (times > this.config.maxRetries) {
+                return null;
+            }
+            return Math.min(times * this.config.retryDelay, 5_000);
+        };
+        switch (this.config.mode) {
+            case "cluster":
+                return this.createClusterClient(this.config, common, retryStrategy);
+            case "sentinel":
+                return this.createSentinelClient(this.config, common, retryStrategy);
+            case "standalone":
+                return this.createStandaloneClient(this.config, common, retryStrategy);
+        }
+    }
+    createClusterClient(config, common, retryStrategy) {
+        return new Cluster(config.clusterNodes.map(({ host, port }) => ({
+            host,
+            port,
+        })), {
+            clusterRetryStrategy: retryStrategy,
+            enableOfflineQueue: true,
+            scaleReads: "master",
+            redisOptions: {
+                ...common,
+                connectTimeout: config.connectionTimeout,
+                maxRetriesPerRequest: config.maxRetries,
+            },
+        });
+    }
+    createSentinelClient(config, common, retryStrategy) {
+        return new RedisClient({
+            ...common,
+            connectTimeout: config.connectionTimeout,
+            maxRetriesPerRequest: config.maxRetries,
+            retryStrategy,
+            // sentinel: true,
+            sentinels: config.sentinelNodes.map(({ host, port }) => ({
+                host,
+                port,
+            })),
+            name: config.sentinelMasterName,
+        });
+    }
+    createStandaloneClient(config, common, retryStrategy) {
+        const connectionOptions = {
+            ...common,
+            connectTimeout: config.connectionTimeout,
+            maxRetriesPerRequest: config.maxRetries,
+            retryStrategy,
+        };
+        if (config.url !== undefined) {
+            return new RedisClient(config.url, connectionOptions);
+        }
+        return new RedisClient({
+            ...connectionOptions,
+            host: config.host,
+            port: config.port,
+            db: config.database,
+        });
+    }
+    buildCommonRedisOptions() {
+        const options = {
+            enableReadyCheck: true,
+            enableOfflineQueue: true,
+            lazyConnect: false,
+        };
+        if (this.config.username !== undefined) {
+            options.username = this.config.username;
+        }
+        if (this.config.password !== undefined) {
+            options.password = this.config.password;
+        }
+        if (this.config.tls) {
+            options.tls =
+                this.config.tlsOptions ?? {
+                    rejectUnauthorized: true,
+                };
+        }
+        return options;
+    }
+    // ========================================================================
+    // Events
+    // ========================================================================
+    setupEventHandlers() {
+        this.client.on("connect", () => {
+            this.logger.info("Redis connected");
+        });
+        this.client.on("ready", () => {
+            this.isReady = true;
+            this.logger.info("Redis ready");
+        });
+        this.client.on("error", (error) => {
+            this.isReady = false;
+            this.logger.error("Redis error:", {
+                error,
+            });
+        });
+        this.client.on("close", () => {
+            this.isReady = false;
+            this.logger.warn("Redis connection closed");
+        });
+        this.client.on("reconnecting", () => {
+            this.isReady = false;
+            this.logger.info("Redis reconnecting...");
+        });
+    }
+    // ========================================================================
+    // Raw Client
+    // ========================================================================
+    getRawClient() {
+        return this.client;
+    }
+    get raw() {
+        return this.client;
+    }
+    // ========================================================================
+    // Connection
+    // ========================================================================
+    async ping() {
+        try {
+            const result = await this.exec("PING", [], () => this.client.ping());
+            return result === "PONG";
+        }
+        catch {
+            return false;
+        }
+    }
+    async close() {
+        try {
+            await this.client.quit();
+        }
+        finally {
+            this.isReady = false;
+        }
+    }
+    // ========================================================================
+    // Internal Helpers
+    // ========================================================================
+    isClusterClient(client) {
+        return client instanceof Cluster;
+    }
+    async exec(command, args, operation) {
+        const startedAt = Date.now();
+        try {
+            const result = await operation();
+            const duration = Date.now() - startedAt;
+            if (duration >
+                this.config.slowCommandThreshold) {
+                this.logger.warn(`Slow command: ${command} took ${duration}ms`, {
+                    command,
+                    args: args.slice(0, 5),
+                    duration,
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            this.logger.error(`Command failed: ${command}`, {
+                command,
+                error,
+            });
+            throw error;
+        }
+    }
+    // ========================================================================
+    // Basic Commands
+    // ========================================================================
+    async get(key) {
+        return this.exec("GET", [key], () => this.client.get(key));
+    }
+    async set(key, value, ttl) {
+        if (ttl !== undefined) {
+            return this.exec("SET", [key, value, "EX", ttl], () => this.client.set(key, value, "EX", ttl));
+        }
+        return this.exec("SET", [key, value], () => this.client.set(key, value));
+    }
+    async setexnx(key, value, ttl) {
+        if (ttl !== undefined) {
+            return this.exec("SET", [key, value, "EX", ttl, "NX"], () => this.client.set(key, value, "EX", ttl, "NX"));
+        }
+        return this.exec("SET", [key, value, "NX"], () => this.client.set(key, value, "NX"));
+    }
+    defineCommand(...args) {
+        return this.client.defineCommand(...args);
+    }
+    async eval(script, numKeys, ...args) {
+        return this.exec("EVAL", [script, numKeys, ...args], () => this.client.eval(script, numKeys, ...args));
+    }
+    async evalsha(sha, script, numKeys, ...args) {
+        try {
+            return await this.exec("EVALSHA", [sha, numKeys, ...args], () => this.client.evalsha(sha, numKeys, ...args));
+        }
+        catch (error) {
+            const code = error instanceof Error &&
+                "code" in error &&
+                typeof error.code === "string"
+                ? error.code
+                : undefined;
+            const message = error instanceof Error
+                ? error.message
+                : String(error);
+            if (code === "NOSCRIPT" ||
+                message.includes("NOSCRIPT")) {
+                return this.eval(script, numKeys, ...args);
+            }
+            throw error;
+        }
+    }
+    async scriptLoad(script) {
+        return this.exec("SCRIPT LOAD", [script], () => this.client.script("LOAD", script));
+    }
+    async setnx(key, value, ttl) {
+        const result = ttl !== undefined
+            ? await this.exec("SET", [key, value, "EX", ttl, "NX"], () => this.client.set(key, value, "EX", ttl, "NX"))
+            : await this.exec("SET", [key, value, "NX"], () => this.client.set(key, value, "NX"));
+        return result === "OK" ? 1 : 0;
+    }
+    async del(...keys) {
+        if (keys.length === 0) {
+            return 0;
+        }
+        return this.exec("DEL", keys, () => this.client.del(...keys));
+    }
+    async getdel(key) {
+        return this.exec("GETDEL", [key], () => this.client.getdel(key));
+    }
+    async exists(key) {
+        return this.exec("EXISTS", [key], () => this.client.exists(key));
+    }
+    async expire(key, ttl) {
+        return this.exec("EXPIRE", [key, ttl], () => this.client.expire(key, ttl));
+    }
+    async ttl(key) {
+        return this.exec("TTL", [key], () => this.client.ttl(key));
+    }
+    async incr(key) {
+        return this.exec("INCR", [key], () => this.client.incr(key));
+    }
+    async decr(key) {
+        return this.exec("DECR", [key], () => this.client.decr(key));
+    }
+    async incrby(key, amount) {
+        if (!Number.isSafeInteger(amount) ||
+            amount <= 0) {
+            throw new RedisError("INCRBY amount must be a positive safe integer", "INVALID_AMOUNT");
+        }
+        return this.exec("INCRBY", [key, amount], () => this.client.incrby(key, amount));
+    }
+    async decrby(key, amount) {
+        if (!Number.isSafeInteger(amount) ||
+            amount <= 0) {
+            throw new RedisError("DECRBY amount must be a positive safe integer", "INVALID_AMOUNT");
+        }
+        return this.exec("DECRBY", [key, amount], () => this.client.decrby(key, amount));
+    }
+    async time() {
+        const result = await this.exec("TIME", [], () => this.client.time());
+        if (Array.isArray(result) &&
+            result.length > 0) {
+            const seconds = Number(result[0]);
+            if (Number.isSafeInteger(seconds)) {
+                return seconds;
+            }
+        }
+        throw new RedisError("Unexpected TIME response from Redis", "TIME_ERROR");
+    }
+    // ========================================================================
+    // Multi-Key Commands
+    // ========================================================================
+    async mget(...keys) {
+        if (keys.length === 0) {
+            return [];
+        }
+        if (this.isClusterClient(this.client)) {
+            return this.mgetClusterAware(keys);
+        }
+        return this.exec("MGET", keys, () => this.client.mget(...keys));
+    }
+    async mset(...pairs) {
+        if (pairs.length === 0) {
+            return "OK";
+        }
+        if (this.isClusterClient(this.client)) {
+            const groups = new Map();
+            for (const [key, value,] of pairs) {
+                const slot = this.calculateSlot(key);
+                const group = groups.get(slot) ?? [];
+                group.push(key, value);
+                groups.set(slot, group);
+            }
+            const tasks = [...groups.values()];
+            await this.runWithConcurrency(tasks, this.config.maxFanOutConcurrency, async (flat) => {
+                await this.exec("MSET", flat, () => this.client.mset(flat));
+            });
+            return "OK";
+        }
+        const flat = pairs.flat();
+        return this.exec("MSET", flat, () => this.client.mset(flat));
+    }
+    // ========================================================================
+    // Hash Commands
+    // ========================================================================
+    async hget(key, field) {
+        return this.exec("HGET", [key, field], () => this.client.hget(key, field));
+    }
+    async hset(key, field, value) {
+        return this.exec("HSET", [key, field, value], () => this.client.hset(key, field, value));
+    }
+    async hgetall(key) {
+        return this.exec("HGETALL", [key], () => this.client.hgetall(key));
+    }
+    async hdel(key, ...fields) {
+        if (fields.length === 0) {
+            return 0;
+        }
+        return this.exec("HDEL", [key, ...fields], () => this.client.hdel(key, ...fields));
+    }
+    // ========================================================================
+    // Set Commands
+    // ========================================================================
+    async sadd(key, ...members) {
+        if (members.length === 0) {
+            return 0;
+        }
+        return this.exec("SADD", [key, ...members], () => this.client.sadd(key, ...members));
+    }
+    async srem(key, ...members) {
+        if (members.length === 0) {
+            return 0;
+        }
+        return this.exec("SREM", [key, ...members], () => this.client.srem(key, ...members));
+    }
+    async smembers(key) {
+        return this.exec("SMEMBERS", [key], () => this.client.smembers(key));
+    }
+    async sismember(key, member) {
+        return this.exec("SISMEMBER", [key, member], () => this.client.sismember(key, member));
+    }
+    // ========================================================================
+    // Sorted Set Commands
+    // ========================================================================
+    async zadd(key, score, member) {
+        return this.exec("ZADD", [key, score, member], () => this.client.zadd(key, score, member));
+    }
+    async zrange(key, start, stop) {
+        return this.exec("ZRANGE", [key, start, stop], () => this.client.zrange(key, start, stop));
+    }
+    async zcard(key) {
+        return this.exec("ZCARD", [key], () => this.client.zcard(key));
+    }
+    async zrem(key, ...members) {
+        if (members.length === 0) {
+            return 0;
+        }
+        return this.exec("ZREM", [key, ...members], () => this.client.zrem(key, ...members));
+    }
+    // ========================================================================
+    // Pipeline
+    // ========================================================================
+    pipeline() {
+        return this.client.pipeline();
+    }
+    // ========================================================================
+    // Scanning
+    // ========================================================================
+    async *scanIterator(pattern, count = 100) {
+        for await (const batch of this.scanCluster(pattern, {
+            count,
+            batchSize: 1,
+        })) {
+            for (const key of batch) {
+                yield key;
+            }
+        }
+    }
+    async *scanCluster(pattern, options = {}) {
+        const count = options.count ?? 100;
+        const batchSize = Math.max(1, options.batchSize ?? 100);
+        const scanNode = async function* (node) {
+            let cursor = "0";
+            let buffer = [];
+            do {
+                const [nextCursor, keys,] = await node.scan(cursor, "MATCH", pattern, "COUNT", count);
+                cursor = nextCursor;
+                buffer.push(...keys);
+                while (buffer.length >=
+                    batchSize) {
+                    yield buffer.splice(0, batchSize);
+                }
+            } while (cursor !== "0");
+            if (buffer.length > 0) {
+                yield buffer;
+            }
+        };
+        const nodes = this.isClusterClient(this.client)
+            ? this.getClusterNodes()
+            : [this.client];
+        for (const node of nodes) {
+            yield* scanNode(node);
+        }
+    }
+    // ========================================================================
+    // Cluster
+    // ========================================================================
+    isCluster() {
+        return this.isClusterClient(this.client);
+    }
+    getClusterNodes() {
+        if (!this.isClusterClient(this.client)) {
+            return [];
+        }
+        return this.client.nodes("master");
+    }
+    async getClusterSlots() {
+        if (!this.isClusterClient(this.client)) {
+            return [];
+        }
+        const raw = (await this.exec("CLUSTER SLOTS", [], () => this.client.cluster("SLOTS")));
+        if (!Array.isArray(raw)) {
+            return [];
+        }
+        return raw.flatMap((entry) => {
+            if (!Array.isArray(entry) ||
+                entry.length < 3) {
+                return [];
+            }
+            const [start, end, master, ...replicas] = entry;
+            if (!Number.isInteger(start) ||
+                !Number.isInteger(end) ||
+                !Array.isArray(master)) {
+                return [];
+            }
+            const parseNode = (node) => {
+                if (!Array.isArray(node) ||
+                    node.length < 2) {
+                    return null;
+                }
+                const host = typeof node[0] === "string"
+                    ? node[0]
+                    : String(node[0]);
+                const port = typeof node[1] === "number"
+                    ? node[1]
+                    : Number(node[1]);
+                if (host.length === 0 ||
+                    !Number.isInteger(port) ||
+                    port < 1 ||
+                    port > 65_535) {
+                    return null;
+                }
+                const nodeId = node[2] === undefined
+                    ? undefined
+                    : String(node[2]);
+                return nodeId === undefined
+                    ? {
+                        host,
+                        port,
+                    }
+                    : {
+                        host,
+                        port,
+                        nodeId,
+                    };
+            };
+            const parsedMaster = parseNode(master);
+            if (!parsedMaster) {
+                return [];
+            }
+            const parsedReplicas = replicas
+                .map(parseNode)
+                .filter((node) => node !== null);
+            return [
+                {
+                    start,
+                    end,
+                    master: parsedMaster,
+                    replicas: parsedReplicas,
+                },
+            ];
+        });
+    }
+    calculateSlot(key) {
+        return calculateRedisClusterSlot(key);
+    }
+    async getNodeForKey(key) {
+        if (!this.isClusterClient(this.client)) {
+            return null;
+        }
+        const nodes = this.client.nodes("master");
+        if (nodes.length === 0) {
+            return null;
+        }
+        try {
+            const slot = this.calculateSlot(key);
+            const raw = await this.client.cluster("SLOTS");
+            if (!Array.isArray(raw)) {
+                return null;
+            }
+            for (const entry of raw) {
+                if (!Array.isArray(entry) ||
+                    entry.length < 3) {
+                    continue;
+                }
+                const [startSlot, endSlot, master,] = entry;
+                if (typeof startSlot !==
+                    "number" ||
+                    typeof endSlot !==
+                        "number" ||
+                    !Array.isArray(master)) {
+                    continue;
+                }
+                if (slot < startSlot ||
+                    slot > endSlot) {
+                    continue;
+                }
+                const host = String(master[2] ?? "");
+                const port = Number(master[1]);
+                if (host.length === 0 ||
+                    !Number.isInteger(port)) {
+                    continue;
+                }
+                const node = nodes.find((candidate) => candidate.options
+                    .host === host &&
+                    candidate.options
+                        .port === port);
+                if (node) {
+                    return node;
+                }
+            }
+        }
+        catch (error) {
+            this.logger.debug("Unable to resolve cluster node for key", {
+                error,
+            });
+        }
+        return null;
+    }
+    async getSlotRanges() {
+        const result = new Map();
+        const ranges = await this.getClusterSlots();
+        for (const range of ranges) {
+            const nodeId = `${range.master.host}:${range.master.port}`;
+            for (let slot = range.start; slot <= range.end; slot++) {
+                result.set(slot, [
+                    nodeId,
+                ]);
+            }
+        }
+        return result;
+    }
+    async isKeyServed(key) {
+        if (!this.isClusterClient(this.client)) {
+            return true;
+        }
+        try {
+            const node = await this.getNodeForKey(key);
+            return node !== null;
+        }
+        catch {
+            return false;
+        }
+    }
+    async executeOnNode(key, command, ...args) {
+        if (this.isClusterClient(this.client)) {
+            const node = await this.getNodeForKey(key);
+            if (node) {
+                return this.executeCommandOnClient(node, command, args);
+            }
+        }
+        return this.executeCommandOnClient(this.client, command, args);
+    }
+    executeCommandOnClient(client, command, args) {
+        const method = Reflect.get(client, command);
+        if (typeof method !==
+            "function") {
+            throw new RedisError(`Unsupported Redis command: ${command}`, "UNSUPPORTED_COMMAND");
+        }
+        return Reflect.apply(method, client, args);
+    }
+    // ========================================================================
+    // Cluster-Aware MGET
+    // ========================================================================
+    async mgetClusterAware(keys) {
+        if (keys.length === 0) {
+            return [];
+        }
+        if (!this.isClusterClient(this.client)) {
+            return this.mget(...keys);
+        }
+        const groups = new Map();
+        for (const key of keys) {
+            const slot = this.calculateSlot(key);
+            const group = groups.get(slot) ?? [];
+            group.push(key);
+            groups.set(slot, group);
+        }
+        const values = new Map();
+        await this.runWithConcurrency([...groups.values()], this.config
+            .maxFanOutConcurrency, async (slotKeys) => {
+            const result = await this.exec("MGET", slotKeys, () => this.client.mget(...slotKeys));
+            slotKeys.forEach((key, index) => {
+                values.set(key, result[index] ??
+                    null);
+            });
+        });
+        return keys.map((key) => values.get(key) ??
+            null);
+    }
+    // ========================================================================
+    // Namespace Operations
+    // ========================================================================
+    async deletePattern(pattern, options = {}) {
+        const batchSize = Math.max(1, options.batchSize ??
+            100);
+        const scanCount = Math.max(1, options.scanCount ??
+            100);
+        let deleted = 0;
+        for await (const batch of this.scanCluster(pattern, {
+            count: scanCount,
+            batchSize,
+        })) {
+            if (batch.length === 0) {
+                continue;
+            }
+            const commands = batch.map((key) => ({
+                command: "del",
+                args: [key],
+                slot: this.calculateSlot(key),
+            }));
+            const results = await executeBySlot(this, commands, {
+                concurrency: this.config
+                    .maxFanOutConcurrency,
+                retry: 1,
+            });
+            for (const result of results) {
+                if (!result[0] &&
+                    typeof result[1] ===
+                        "number") {
+                    deleted += result[1];
+                }
+            }
+        }
+        return deleted;
+    }
+    async clearNamespace(prefix, options = {}) {
+        return this.deletePattern(`${prefix}*`, options);
+    }
+    async clearNamespaceClusterAware(prefix, options = {}) {
+        return this.clearNamespace(prefix, options);
+    }
+    // ========================================================================
+    // Cluster Information
+    // ========================================================================
+    getClusterInfo() {
+        if (this.isClusterClient(this.client)) {
+            try {
+                const nodes = this.client.nodes("master");
+                return {
+                    mode: "cluster",
+                    status: this.isReady
+                        ? "ready"
+                        : "connecting",
+                    nodeCount: nodes.length,
+                    nodes: nodes.map((node) => ({
+                        host: String(node.options
+                            .host ??
+                            ""),
+                        port: Number(node.options
+                            .port),
+                        role: "master",
+                    })),
+                };
+            }
+            catch (error) {
+                return {
+                    mode: "cluster",
+                    status: "error",
+                    error: error instanceof Error
+                        ? error.message
+                        : String(error),
+                };
+            }
+        }
+        if (isStandaloneConfig(this.config)) {
+            return {
+                mode: "standalone",
+                host: this.config.host,
+                port: this.config.port,
+                status: this.isReady
+                    ? "ready"
+                    : "connecting",
+            };
+        }
+        return {
+            mode: this.config.mode,
+            status: this.isReady
+                ? "ready"
+                : "connecting",
+        };
+    }
+    // ========================================================================
+    // INFO
+    // ========================================================================
+    async info(section) {
+        if (section !== undefined) {
+            return this.exec("INFO", [section], () => this.client.info(section));
+        }
+        return this.exec("INFO", [], () => this.client.info());
+    }
+    // ========================================================================
+    // SELECT
+    // ========================================================================
+    async select(database) {
+        if (this.isClusterClient(this.client)) {
+            throw new RedisError("SELECT is not supported in Redis Cluster mode", "CLUSTER_MODE");
+        }
+        if (!Number.isInteger(database) ||
+            database < 0 ||
+            database > 15) {
+            throw new RedisError("Database must be an integer between 0 and 15", "INVALID_DATABASE");
+        }
+        return this.client.select(database);
+    }
+    // ========================================================================
+    // Connection Status
+    // ========================================================================
+    getConnectionStatus() {
+        const state = this.isReady
+            ? "connected"
+            : this.client.status ===
+                "connecting"
+                ? "connecting"
+                : this.client.status ===
+                    "end"
+                    ? "closed"
+                    : this.client.status ===
+                        "ready"
+                        ? "connected"
+                        : "disconnected";
+        return {
+            state,
+            connected: this.isReady,
+            ready: this.isReady,
+            reconnectAttempts: 0,
+            uptime: 0,
+        };
+    }
+    // ========================================================================
+    // Concurrency Helper
+    // ========================================================================
+    async runWithConcurrency(items, concurrency, worker) {
+        if (items.length === 0) {
+            return;
+        }
+        const limit = Math.max(1, Math.min(concurrency, items.length));
+        let cursor = 0;
+        const workers = Array.from({
+            length: limit,
+        }, async () => {
+            while (true) {
+                const index = cursor++;
+                if (index >=
+                    items.length) {
+                    return;
+                }
+                await worker(items[index]);
+            }
+        });
+        await Promise.all(workers);
+    }
+}
+/**
+ * Generic runtime factory.
+ */
+export function createRedisClient(config, logger) {
+    const client = new RedisClientWrapper(config, logger);
+    /**
+     * The runtime configuration has already been validated by
+     * RedisConfigSchema inside RedisClientWrapper.
+     *
+     * The specialized public API is therefore safe to expose according to
+     * the validated discriminator.
+     *
+     * The cast is isolated to this factory boundary instead of being spread
+     * throughout the implementation.
+     */
+    switch (client.mode) {
+        case "cluster":
+            return client;
+        case "sentinel":
+            return client;
+        case "standalone":
+            return client;
+    }
+}