ts-server-lib 0.0.48

package/db/TSRedis.js

@@ -0,0 +1,1368 @@
+"use strict";
+/**
+ * TSRedis – Single file for Redis: connection (standalone/Sentinel), events (pub/sub), operations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TSRedis = exports.BATCH_COMMAND_CHUNK = exports.PER_KEY_BATCH_CONCURRENCY = void 0;
+exports.errMsg = errMsg;
+exports.isClientOpen = isClientOpen;
+exports.isStaleConnectionError = isStaleConnectionError;
+exports.isActiveClientConnected = isActiveClientConnected;
+exports.isTransientClusterError = isTransientClusterError;
+exports.executeWithClusterRetry = executeWithClusterRetry;
+exports.isCommandTimeoutError = isCommandTimeoutError;
+exports.executeWithCommandRetry = executeWithCommandRetry;
+exports.evalTaggedScript = evalTaggedScript;
+const events_1 = require("events");
+const node_crypto_1 = require("node:crypto");
+const redis_1 = require("redis");
+const TSRequest_1 = require("../utils/TSRequest");
+// ═══════════════════════════════════════════════════════════════════
+// Connection – module state
+// ═══════════════════════════════════════════════════════════════════
+const ERR_PREFIX = 'TSRedis:ERROR';
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** True when a node-redis client handle is open/ready (false after max-reconnect exhaustion). */
+function isClientOpen(c) {
+    if (!c)
+        return false;
+    const open = c.isOpen;
+    if (typeof open === 'boolean')
+        return open;
+    const ready = c.isReady;
+    if (typeof ready === 'boolean')
+        return ready;
+    return true;
+}
+/**
+ * True when an error indicates the caller is using a closed or half-open Redis / cluster client.
+ * Used by queue/cron recovery paths after max-reconnect exhaustion or cluster slot churn.
+ */
+function isStaleConnectionError(err) {
+    const msg = errMsg(err);
+    return /reading 'master'|reading 'replicas'|no Redis client connected|Connection is closed|Socket closed|ECONNRESET|CLUSTERDOWN|Max reconnect attempts reached|The client is closed/i.test(msg);
+}
+/**
+ * node-redis internal abort dispatch: when a queued command is aborted by its AbortSignal
+ * (connection torn down / reconnecting while the command was in flight), the rejection is a
+ * bare `new Error()` with no message and the generic name "Error" — neither the name/message
+ * checks in {@link isCommandTimeoutError} nor the message-substring checks in
+ * {@link isStaleConnectionError} can recognize it, even though it is the exact same
+ * "command aborted by disconnect/reconnect" class those checks exist to catch. The only
+ * identifying signal left is the stack frame from node-redis's own dispatch internals.
+ * Deliberately requires an EMPTY message — any error carrying real message text goes through
+ * the checks above instead, so this cannot mask a genuine application error that merely
+ * happens to call through a Redis client.
+ */
+const NODE_REDIS_ABORT_DISPATCH_STACK_RE = /@redis[\\/]client[\\/]lib[\\/]client[\\/]commands-queue/i;
+function isNodeRedisAbortDispatchError(err) {
+    if (!(err instanceof Error) || err.message || !err.stack)
+        return false;
+    return NODE_REDIS_ABORT_DISPATCH_STACK_RE.test(err.stack);
+}
+let client = null;
+let readClient = null;
+/**
+ * Active cluster client. Set ONLY after `clusterClient.connect()` fully resolves —
+ * callers that check this are guaranteed to get a ready, slot-mapped client.
+ */
+let clusterClient = null;
+/** Active sentinel client (redis v6 createSentinel). Set only after connect() fully resolves. */
+let sentinelClient = null;
+/** Dedup promise: concurrent calls to connectRedisImpl share one cluster-connect attempt. */
+let _clusterConnectPromise = null;
+const DEFAULT_CONFIG = {
+    connectTimeout: 5000,
+    socketTimeout: 0,
+    autoReconnect: true,
+    maxReconnectRetries: 10,
+    reconnectDelay: 1000,
+    disableOfflineQueue: false
+};
+function parseRedisUrl(url, envPassword) {
+    const urlMatch = url.match(/^redis:\/\/:([^@]+)@(.+)$/);
+    if (urlMatch) {
+        return { url: `redis://${urlMatch[2]}`, password: urlMatch[1] };
+    }
+    return { url, password: envPassword };
+}
+function buildReconnectStrategy(cfg) {
+    if (!cfg.autoReconnect)
+        return false;
+    return (retries) => {
+        if (retries > cfg.maxReconnectRetries) {
+            console.error(ERR_PREFIX, 'max reconnect attempts reached');
+            return new Error('Max reconnect attempts reached');
+        }
+        const jitter = Math.floor(Math.random() * 200);
+        return Math.min(Math.pow(2, retries) * 50, cfg.reconnectDelay || 2000) + jitter;
+    };
+}
+/** Drop singleton slots that hold a closed client so the next connect creates a fresh pool. */
+async function discardStaleClientsIfNeeded() {
+    const stale = (client != null && !isClientOpen(client)) ||
+        (readClient != null && !isClientOpen(readClient)) ||
+        (clusterClient != null && !isClientOpen(clusterClient)) ||
+        (sentinelClient != null && !isClientOpen(sentinelClient));
+    if (stale) {
+        await closeRedisImpl();
+    }
+}
+function buildStandaloneClientOptions(cfg, redisUrl, password) {
+    const clientOptions = {
+        url: redisUrl,
+        socket: {
+            connectTimeout: cfg.connectTimeout,
+            socketTimeout: cfg.socketTimeout || undefined,
+            keepAlive: true,
+            keepAliveInitialDelay: 5000,
+            noDelay: true,
+            reconnectStrategy: buildReconnectStrategy(cfg)
+        },
+        disableOfflineQueue: cfg.disableOfflineQueue
+    };
+    if (cfg.clientName)
+        clientOptions.name = cfg.clientName;
+    if (cfg.pingInterval)
+        clientOptions.pingInterval = cfg.pingInterval;
+    if (cfg.commandsQueueMaxLength)
+        clientOptions.commandsQueueMaxLength = cfg.commandsQueueMaxLength;
+    if (password)
+        clientOptions.password = password;
+    return clientOptions;
+}
+// ═══════════════════════════════════════════════════════════════════
+// Connection – connect logic (standalone, Sentinel, read replicas)
+// ═══════════════════════════════════════════════════════════════════
+async function connectRedisSentinel(sentinel, cfg) {
+    // Master password: embedded in cfg.url as redis://:pass@_ by buildConfigFromDescriptor.
+    const masterPassword = cfg.url.match(/^redis:\/\/:([^@]+)@/)?.[1];
+    const sc = (0, redis_1.createSentinel)({
+        name: sentinel.name,
+        sentinelRootNodes: sentinel.hosts,
+        nodeClientOptions: {
+            socket: { connectTimeout: cfg.connectTimeout, reconnectStrategy: buildReconnectStrategy(cfg) },
+            ...(masterPassword ? { password: masterPassword } : {})
+        },
+        // sentinel.password is the sentinel-node auth (rare — only when sentinels have requirepass).
+        ...(sentinel.password ? { sentinelClientOptions: { password: sentinel.password } } : {}),
+        // nodeAddressMap remaps master/replica addresses announced by sentinel to client-reachable
+        // addresses (e.g. Docker-internal 172.x → 127.0.0.1:hostPort for local testing).
+        ...(sentinel.nodeAddressMap !== undefined ? { nodeAddressMap: sentinel.nodeAddressMap } : {})
+    });
+    sc.on('error', (err) => console.error(ERR_PREFIX, 'sentinel', errMsg(err)));
+    await sc.connect();
+    sentinelClient = sc;
+}
+async function connectReadReplicas(replicaConfig, cfg) {
+    if (!replicaConfig.urls?.length)
+        return;
+    const { url, password } = parseRedisUrl(replicaConfig.urls[0]);
+    const options = {
+        url,
+        socket: {
+            connectTimeout: cfg.connectTimeout,
+            reconnectStrategy: buildReconnectStrategy(cfg)
+        },
+        readonly: true
+    };
+    if (password)
+        options.password = password;
+    readClient = (0, redis_1.createClient)(options);
+    readClient.on('error', (err) => console.error(ERR_PREFIX, 'read replica', errMsg(err)));
+    await readClient.connect();
+}
+// ═══════════════════════════════════════════════════════════════════
+// Connection – internal helpers (used by TSRedis static API)
+// ═══════════════════════════════════════════════════════════════════
+async function connectRedisCluster(clusterConfig, cfg) {
+    // Password resolution order: explicit clusterConfig.password → URL-embedded in cfg.url → env var.
+    let password = clusterConfig.password;
+    if (!password) {
+        const urlMatch = cfg.url.match(/^redis:\/\/:([^@]+)@/);
+        if (urlMatch)
+            password = urlMatch[1];
+        else if (process.env.REDIS_PASSWORD)
+            password = process.env.REDIS_PASSWORD;
+    }
+    // `nodeAddressMap` is passed through verbatim so callers (e.g. host-side validators) can
+    // rewrite cluster-discovered hostnames to client-reachable addresses without touching docker DNS.
+    // Build inline so node-redis's RedisClusterOptions generic stays satisfied (the type
+    // inference depends on the literal object shape — extracting to a typed variable widens it).
+    // Use a local variable: module-level `clusterClient` is set ONLY after connect() resolves
+    // so concurrent callers that check `clusterClient !== null` always get a ready client.
+    const cluster = (0, redis_1.createCluster)({
+        rootNodes: clusterConfig.nodes.map((n) => ({
+            socket: { host: n.host, port: n.port }
+        })),
+        // Default 16 — raise for resharding / Docker nodeAddressMap churn during dev.
+        maxCommandRedirections: clusterConfig.maxCommandRedirections ?? 32,
+        useReplicas: clusterConfig.useReplicas ?? false,
+        defaults: {
+            socket: {
+                connectTimeout: cfg.connectTimeout,
+                keepAlive: true,
+                keepAliveInitialDelay: 5000,
+                noDelay: true,
+                reconnectStrategy: buildReconnectStrategy(cfg)
+            },
+            ...(password ? { password } : {})
+        },
+        ...(clusterConfig.nodeAddressMap !== undefined
+            ? { nodeAddressMap: clusterConfig.nodeAddressMap }
+            : {})
+    });
+    cluster.on('error', (err) => console.error(ERR_PREFIX, 'cluster', errMsg(err)));
+    await cluster.connect();
+    clusterClient = cluster; // assign only after full connection + slot discovery
+    return clusterClient;
+}
+async function connectRedisImpl(urlOrConfig) {
+    await discardStaleClientsIfNeeded();
+    if (client && isClientOpen(client))
+        return client;
+    if (clusterClient && isClientOpen(clusterClient)) {
+        return clusterClient;
+    }
+    if (sentinelClient && isClientOpen(sentinelClient)) {
+        return sentinelClient;
+    }
+    const config = typeof urlOrConfig === 'string' ? { url: urlOrConfig } : urlOrConfig;
+    const cfg = { ...DEFAULT_CONFIG, ...config };
+    if (config.cluster) {
+        // Dedup: concurrent callers share one connect attempt; clusterClient is only set after
+        // connect() fully resolves so nobody gets a not-yet-ready client.
+        if (!_clusterConnectPromise) {
+            _clusterConnectPromise = connectRedisCluster(config.cluster, cfg)
+                .finally(() => { _clusterConnectPromise = null; });
+        }
+        await _clusterConnectPromise;
+        return clusterClient;
+    }
+    if (config.sentinel) {
+        await connectRedisSentinel(config.sentinel, cfg);
+        return sentinelClient;
+    }
+    const { url: redisUrl, password } = parseRedisUrl(cfg.url, process.env.REDIS_PASSWORD);
+    const clientOptions = buildStandaloneClientOptions(cfg, redisUrl, password);
+    client = (0, redis_1.createClient)(clientOptions);
+    client.on('error', (err) => console.error(ERR_PREFIX, errMsg(err)));
+    await client.connect();
+    if (config.readReplicas?.enabled && config.readReplicas.urls?.length) {
+        await connectReadReplicas(config.readReplicas, cfg);
+    }
+    return client;
+}
+function getRedisImpl() {
+    return client;
+}
+/**
+/** Returns the active cluster client when `connectRedisImpl` was called with `config.cluster`, else null. */
+function getRedisClusterImpl() {
+    return clusterClient;
+}
+/**
+ * Returns whichever client backs the active singleton: standalone, sentinel, or cluster.
+ * Use this when the code path is topology-agnostic (e.g. health checks, GET/SET on a single key).
+ * For multi-key ops you still need to know cluster mode to enforce hash-tag co-location.
+ */
+function getActiveClientImpl() {
+    return clusterClient ?? sentinelClient ?? client;
+}
+/** True when TSRedis holds an active singleton client that is open (not post-max-reconnect closed). */
+function isActiveClientConnected() {
+    const c = getActiveClientImpl();
+    return c != null && isClientOpen(c);
+}
+function requireActiveClient() {
+    const c = getActiveClientImpl();
+    if (!c)
+        throw new Error('Redis not connected');
+    return c;
+}
+function getRedisForReadImpl() {
+    return readClient ?? client;
+}
+function hasReadReplicaImpl() {
+    return readClient !== null;
+}
+async function checkRedisHealthImpl() {
+    const start = Date.now();
+    try {
+        // Both `RedisClientType.ping()` and `RedisClusterType.ping()` exist; cluster pings one node.
+        await requireActiveClient().ping();
+        return { healthy: true, latencyMs: Date.now() - start };
+    }
+    catch {
+        return { healthy: false, latencyMs: -1 };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// Events – pub/sub (internal)
+// ═══════════════════════════════════════════════════════════════════
+async function publishImpl(channel, message) {
+    try {
+        // Cluster pub/sub: classic PUBLISH broadcasts to every node (bandwidth amplification).
+        // For per-slot delivery use SPUBLISH/SSUBSCRIBE (Redis 7+, sharded pub/sub).
+        await requireActiveClient().publish(channel, message);
+        return true;
+    }
+    catch (error) {
+        console.error(ERR_PREFIX, 'publish failed', channel, errMsg(error));
+        return false;
+    }
+}
+async function subscribeImpl(channel, handler) {
+    requireActiveClient(); // throws if nothing connected
+    if (clusterClient) {
+        await clusterClient.subscribe(channel, handler);
+        return async () => { await clusterClient.unsubscribe(channel); };
+    }
+    if (sentinelClient) {
+        // Sentinel has built-in pub/sub routing — no duplicate() needed.
+        await sentinelClient.subscribe(channel, handler);
+        return async () => { await sentinelClient.unsubscribe(channel); };
+    }
+    // Standalone: v6 manages the pub/sub connection internally — subscribe() directly.
+    await client.subscribe(channel, handler);
+    return async () => { await client.unsubscribe(channel); };
+}
+// ═══════════════════════════════════════════════════════════════════
+// Scan utilities (internal)
+// ═══════════════════════════════════════════════════════════════════
+/** Drain a single node's scanIterator into the generator, respecting maxKeys cap. */
+async function* _yieldBatches(iterator, maxKeys, yielded) {
+    for await (const keysBatch of iterator) {
+        for (const key of keysBatch) {
+            if (maxKeys > 0 && yielded.count >= maxKeys)
+                return;
+            yield key;
+            yielded.count++;
+        }
+    }
+}
+async function* _scanCluster(pattern, batchSize, maxKeys, yielded) {
+    // Scan each master using its already-connected client directly.
+    // Reading master.client avoids nodeClient(master) which creates a new TCP connection
+    // when the node is disconnected, hanging indefinitely in k8s.
+    // isReady check: skip clients that are connecting/reconnecting.
+    for (const master of clusterClient.masters) {
+        const nodeClient = master.client;
+        if (!nodeClient || !nodeClient.isReady)
+            continue;
+        try {
+            yield* _yieldBatches(nodeClient.scanIterator({ MATCH: pattern, COUNT: batchSize }), maxKeys, yielded);
+        }
+        catch {
+            // Shard unreachable — skip; L1 cleared, TTL handles L2 expiry.
+        }
+        if (maxKeys > 0 && yielded.count >= maxKeys)
+            return;
+    }
+}
+async function* _scanSentinel(pattern, batchSize, maxKeys, yielded) {
+    // SCAN is in NON_STICKY_COMMANDS and routes to the master automatically.
+    let cursor = '0';
+    do {
+        const reply = await sentinelClient.scan(cursor, { MATCH: pattern, COUNT: batchSize });
+        cursor = String(reply.cursor);
+        for (const key of reply.keys) {
+            if (maxKeys > 0 && yielded.count >= maxKeys)
+                return;
+            yield key;
+            yielded.count++;
+        }
+    } while (cursor !== '0' && (maxKeys <= 0 || yielded.count < maxKeys));
+}
+async function* scanKeysIteratorImpl(options = {}) {
+    // batchSize is SCAN's COUNT hint: total round-trips ≈ totalKeys / COUNT regardless of how
+    // few keys MATCH. The old default (100) turned sparse-match scans over a large keyspace
+    // into tens of thousands of round-trips (observed 60-90 s for a ~2-key pattern on an
+    // instance holding millions of feed keys). 1000 keeps per-call server work small while
+    // cutting round-trips 10x. Callers scanning as part of any latency-sensitive path should
+    // not SCAN at all — maintain an index set (see ms repo: cache-invalidation-governance CIG-4).
+    const { pattern = '*', maxKeys = 10000, batchSize = 1000 } = options;
+    const yielded = { count: 0 };
+    if (clusterClient && !client) {
+        yield* _scanCluster(pattern, batchSize, maxKeys, yielded);
+        return;
+    }
+    if (sentinelClient && !client) {
+        yield* _scanSentinel(pattern, batchSize, maxKeys, yielded);
+        return;
+    }
+    // Standalone: scanIterator yields string[] batches (one array per SCAN cursor step).
+    if (!client)
+        return;
+    yield* _yieldBatches(client.scanIterator({ MATCH: pattern, COUNT: batchSize }), maxKeys, yielded);
+}
+async function batchGetValuesImpl(keys) {
+    if (keys.length === 0)
+        return {};
+    const redis = requireActiveClient();
+    // Bounded: one GET per key, so an unbounded fan-out would queue the caller's entire key list
+    // ahead of any latency-critical command sharing this client. See PER_KEY_BATCH_CONCURRENCY.
+    const values = await mapWithBoundedConcurrency(keys, (k) => executeWithClusterRetry(() => redis.get(k)));
+    const result = {};
+    for (let i = 0; i < keys.length; i++)
+        result[keys[i]] = values[i] ?? null;
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════════
+// Key-family index — the canonical SCAN replacement
+// ═══════════════════════════════════════════════════════════════════
+//
+// Enumerating a family of keys via SCAN+MATCH costs O(TOTAL keyspace / COUNT) round-trips
+// regardless of how few keys match — on an instance holding a large unrelated dataset a
+// handful-of-matches enumeration takes tens of seconds. Maintain a SET of members instead:
+// `keyIndexAdd` on create (refreshes the index's safety TTL), `keyIndexRemove` on
+// consume/delete, `keyIndexEnumerate` to list (SMEMBERS + per-member GET — per-key on
+// purpose: family members usually hash to different slots, so MGET would raise CROSSSLOT
+// in cluster mode). Members whose value key no longer exists (TTL-expired, deleted
+// out-of-band) are lazily SREM'd during enumeration — the index self-heals, so a missed
+// remove is never permanent. No SCAN backfill by design: pre-index keys age out via their
+// own TTL.
+/** Safety TTL on index sets — far beyond any member key's own TTL; refreshed on every add. */
+const KEY_INDEX_DEFAULT_TTL_S = 7 * 24 * 3600;
+/** Register a member in an index set (idempotent). Refreshes the index's safety TTL. */
+async function keyIndexAddImpl(indexKey, member, opts) {
+    const redis = requireActiveClient();
+    await executeWithClusterRetry(() => redis.sAdd(indexKey, member));
+    await executeWithClusterRetry(() => redis.expire(indexKey, opts?.indexTtlSeconds ?? KEY_INDEX_DEFAULT_TTL_S));
+}
+/** Remove a member from an index set (lazy pruning in enumerate covers a missed remove). */
+async function keyIndexRemoveImpl(indexKey, member) {
+    const redis = requireActiveClient();
+    await executeWithClusterRetry(() => redis.sRem(indexKey, member));
+}
+/** All members of an index set. */
+async function keyIndexMembersImpl(indexKey) {
+    const redis = requireActiveClient();
+    return executeWithClusterRetry(() => redis.sMembers(indexKey));
+}
+/** Member count (SCARD). */
+async function keyIndexCountImpl(indexKey) {
+    const redis = requireActiveClient();
+    return executeWithClusterRetry(() => redis.sCard(indexKey));
+}
+/**
+ * Enumerate an index: resolve each member to its value key via `keyOf`, GET it, and lazily
+ * `SREM` members whose key no longer exists. Returns only LIVE entries — O(members), never
+ * a keyspace SCAN. `withValues: false` skips GET/TTL (EXISTS-only liveness) for callers that
+ * only need the live member list.
+ */
+async function keyIndexEnumerateImpl(indexKey, keyOf, opts) {
+    const redis = requireActiveClient();
+    const entries = [];
+    let prunedCount = 0;
+    const limit = opts?.limit ?? 10000;
+    const withValues = opts?.withValues ?? true;
+    const members = await executeWithClusterRetry(() => redis.sMembers(indexKey));
+    for (const member of members) {
+        if (entries.length >= limit)
+            break;
+        const key = keyOf(member);
+        if (withValues) {
+            const value = await executeWithClusterRetry(() => redis.get(key));
+            if (value === null || value === undefined) {
+                await executeWithClusterRetry(() => redis.sRem(indexKey, member)).catch(() => undefined);
+                prunedCount++;
+                continue;
+            }
+            const ttlSeconds = await executeWithClusterRetry(() => redis.ttl(key));
+            entries.push({ member, key, value, ttlSeconds });
+        }
+        else {
+            const exists = await executeWithClusterRetry(() => redis.exists(key)).catch(() => 0);
+            if (exists !== 1) {
+                await executeWithClusterRetry(() => redis.sRem(indexKey, member)).catch(() => undefined);
+                prunedCount++;
+                continue;
+            }
+            entries.push({ member, key, value: null, ttlSeconds: -1 });
+        }
+    }
+    return { entries, prunedCount };
+}
+// ═══════════════════════════════════════════════════════════════════
+// Topology-aware multi-key helpers (internal)
+// ═══════════════════════════════════════════════════════════════════
+/** True when `client` is a Redis Cluster client (has a `masters` array). */
+function isClusterImpl(client) {
+    return 'masters' in client;
+}
+/**
+ * Cluster batch fast-path failures recoverable via per-key commands.
+ * CROSSSLOT: keys span slots in MGET/MULTI/EXEC.
+ * MOVED/ASK: pipeline cannot follow slot redirects — per-key ops let node-redis route each command.
+ * TRYAGAIN: slot migration in progress — batch fails; per-key with retry handles it.
+ */
+const CLUSTER_BATCH_FALLBACK_RE = /CROSSSLOT|cross.?slot|MOVED|ASK|TRYAGAIN/i;
+/** Transient cluster errors — Redis spec: retry the same command after a brief pause. */
+const CLUSTER_TRANSIENT_RETRY_RE = /TRYAGAIN|CLUSTERDOWN|LOADING/i;
+const CLUSTER_RETRY_DELAY_MS = 25;
+const CLUSTER_MAX_RETRIES = 2;
+function shouldFallbackClusterBatch(err) {
+    return CLUSTER_BATCH_FALLBACK_RE.test(errMsg(err));
+}
+/** True when Redis returns a transient cluster error that should be retried (TRYAGAIN, CLUSTERDOWN, LOADING). */
+function isTransientClusterError(err) {
+    return CLUSTER_TRANSIENT_RETRY_RE.test(errMsg(err));
+}
+function sleepMs(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Execute a Redis command with bounded retry on transient cluster errors (TRYAGAIN / CLUSTERDOWN / LOADING).
+ * MOVED/ASK are handled by node-redis per-command — no retry needed here.
+ */
+async function executeWithClusterRetry(fn, opts) {
+    const maxRetries = opts?.maxRetries ?? CLUSTER_MAX_RETRIES;
+    const delayMs = opts?.delayMs ?? CLUSTER_RETRY_DELAY_MS;
+    let lastErr;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (!isTransientClusterError(err) || attempt >= maxRetries)
+                throw err;
+            await sleepMs(delayMs * (attempt + 1));
+        }
+    }
+    throw lastErr;
+}
+/** errno / syscall codes — redis.io nodejs error-handling recommends retry on these. */
+const COMMAND_TIMEOUT_ERR_CODES = new Set(['ETIMEDOUT', 'EAI_AGAIN', 'ESOCKETTIMEDOUT']);
+/** node-redis v6 error class names — packages/client/lib/errors.ts */
+const COMMAND_TIMEOUT_ERR_NAMES = /^(AbortError|ConnectionTimeoutError|SocketTimeoutError|TimeoutError|SocketTimeoutDuringMaintenanceError|CommandTimeoutDuringMaintenanceError)$/;
+/**
+ * Message substrings for client-side command / socket timeouts and aborts.
+ * @see https://redis.io/docs/latest/develop/clients/nodejs/error-handling/
+ * @see https://github.com/redis/node-redis/blob/master/packages/client/lib/errors.ts
+ */
+const COMMAND_TIMEOUT_RETRY_RE = /AbortSignal|The command was aborted|Connection timeout|Socket timeout|Command timeout during maintenance|Socket timeout during maintenance|command timed out|timed out|ETIMEDOUT|ESOCKETTIMEDOUT|read ETIMEDOUT|write ETIMEDOUT/i;
+function errCode(err) {
+    if (err && typeof err === 'object' && 'code' in err) {
+        const code = err.code;
+        return typeof code === 'string' ? code : undefined;
+    }
+    return undefined;
+}
+/** True when a Redis command failed due to client timeout or stale connection. */
+function isCommandTimeoutError(err) {
+    const code = errCode(err);
+    if (code !== undefined && COMMAND_TIMEOUT_ERR_CODES.has(code))
+        return true;
+    if (err instanceof Error && COMMAND_TIMEOUT_ERR_NAMES.test(err.name))
+        return true;
+    if (isNodeRedisAbortDispatchError(err))
+        return true;
+    return COMMAND_TIMEOUT_RETRY_RE.test(errMsg(err)) || isStaleConnectionError(err);
+}
+/**
+ * Retry wrapper for feed-hot paths: command timeout / stale connection + cluster TRYAGAIN
+ * (via nested executeWithClusterRetry).
+ */
+async function executeWithCommandRetry(fn, opts) {
+    const maxRetries = opts?.maxRetries ?? 2;
+    const baseDelay = opts?.delayMs ?? CLUSTER_RETRY_DELAY_MS;
+    const jitterMs = opts?.jitterMs ?? 50;
+    let lastErr;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await executeWithClusterRetry(fn);
+        }
+        catch (err) {
+            lastErr = err;
+            const retryable = isCommandTimeoutError(err) || isTransientClusterError(err);
+            if (!retryable || attempt >= maxRetries)
+                throw err;
+            await sleepMs(baseDelay * (attempt + 1) + Math.floor(Math.random() * jitterMs));
+        }
+    }
+    throw lastErr;
+}
+function extractHashTag(key) {
+    const start = key.indexOf('{');
+    if (start < 0)
+        return null;
+    const end = key.indexOf('}', start + 1);
+    if (end < 0)
+        return null;
+    return key.slice(start + 1, end);
+}
+/**
+ * SHA1 per script source, computed once.
+ *
+ * Keyed by the source string itself, so callers keep passing `source` and need no registration step or
+ * lifecycle. Scripts are module-level constants, so this map is bounded by the number of distinct
+ * scripts in the process (single digits), not by call volume.
+ */
+const scriptShaCache = new Map();
+function scriptSha(source) {
+    let sha = scriptShaCache.get(source);
+    if (sha === undefined) {
+        sha = (0, node_crypto_1.createHash)('sha1').update(source).digest('hex');
+        scriptShaCache.set(source, sha);
+    }
+    return sha;
+}
+/**
+ * True for the error Redis returns when a script is not in that node's cache.
+ *
+ * Matched on the message rather than a type: node-redis surfaces this as a generic ErrorReply, and the
+ * prefix is part of the Redis wire protocol, so it is stable across client versions.
+ */
+function isNoScriptError(e) {
+    const message = e?.message;
+    return typeof message === 'string' && message.includes('NOSCRIPT');
+}
+/**
+ * EVAL a Lua script whose KEYS[] share a hash tag (cluster-safe multi-key atomicity).
+ *
+ * Sends **EVALSHA** (40-byte digest), falling back to EVAL exactly once per node on `NOSCRIPT`.
+ *
+ * Why this matters: this used to call `eval(source, …)` unconditionally, which transmits the ENTIRE Lua
+ * body and makes the server SHA1 it to find the cached script — on every single invocation. Measured on
+ * the 2026-07-31 sports-service replay, `eval` accounted for **385,732 calls and 588 s of server CPU**,
+ * the single largest Redis cost in the cluster, and every one of those calls re-shipped a ~1 KB script
+ * that Redis already had compiled. The digest is constant-size, so the wire and hashing cost stop scaling
+ * with body length — which also means script sources may be commented normally again.
+ *
+ * The `NOSCRIPT` fallback is what makes this safe on cluster and across failover, and why there is no
+ * `SCRIPT LOAD` step: a node that has never seen the script (fresh node, restart, `SCRIPT FLUSH`, a
+ * MOVED/ASK redirect to a different master, a promoted replica) answers NOSCRIPT, and the EVAL both runs
+ * the script and caches it there. Self-healing per node, no coordination, no startup ordering.
+ */
+async function evalTaggedScript(client, opts) {
+    const { keys, argv = [], source, validateSameTag = true } = opts;
+    if (keys.length === 0)
+        throw new Error('evalTaggedScript: at least one key required');
+    if (validateSameTag && keys.length > 1) {
+        const tags = keys.map(extractHashTag);
+        const first = tags[0];
+        if (!first || tags.some((t) => t !== first)) {
+            throw new Error('evalTaggedScript: all KEYS must share the same hash tag');
+        }
+    }
+    const sha = scriptSha(source);
+    const c = client;
+    return executeWithCommandRetry(async () => {
+        try {
+            // `return await`, not `return`: the rejection must surface inside this try to reach the catch.
+            return await c.evalSha(sha, { keys, arguments: argv });
+        }
+        catch (e) {
+            if (!isNoScriptError(e))
+                throw e;
+            return c.eval(source, { keys, arguments: argv });
+        }
+    });
+}
+/**
+ * Max commands in flight on the per-key cluster fallback paths.
+ *
+ * These paths issue one command PER KEY, so an unbounded `Promise.all` puts the caller's whole key
+ * list on the connection at once. Redis serves each of them quickly — a slowlog stays clean — but
+ * any latency-critical command issued by another caller on the same client queues behind every
+ * pending reply. Observed in a sports feed replay (2026-07-28): a 400-key `mSet` from a background
+ * schedule sweep pushed a live odds-book `hmGet` to 1435 ms of wait while the event loop was idle
+ * (worst stall 15 ms), GC was negligible (28 ms) and the slowlog's worst entry was 15 ms.
+ *
+ * A cap converts that from "whole batch, then the read" into "at most this many, then the read".
+ * Chosen small because it is a queue-depth budget shared with latency-sensitive traffic, not a
+ * throughput knob — node-redis still auto-pipelines each chunk per target node.
+ */
+exports.PER_KEY_BATCH_CONCURRENCY = 25;
+/**
+ * Max keys per batched command on the standalone/sentinel fast paths (`MGET`, `MULTI/EXEC`).
+ *
+ * Separate budget from {@link PER_KEY_BATCH_CONCURRENCY} because the failure mode differs: there the
+ * risk is queue depth (many small commands), here it is a single command whose payload and
+ * server-side service time scale with the key count. Redis executes one command at a time, so an
+ * unbounded `MGET k1 … k10000` blocks every other client on that node for its full duration.
+ *
+ * 500 matches the chunk convention used by callers for the same reason.
+ */
+exports.BATCH_COMMAND_CHUNK = 500;
+/** Split into fixed-size slices; returns the input as a single slice when already small enough. */
+function chunked(items, size) {
+    if (items.length <= size)
+        return [items];
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+/** Run `task` over `items` with at most {@link PER_KEY_BATCH_CONCURRENCY} in flight, preserving order. */
+async function mapWithBoundedConcurrency(items, task) {
+    if (items.length <= exports.PER_KEY_BATCH_CONCURRENCY)
+        return Promise.all(items.map(task));
+    const out = new Array(items.length);
+    for (let i = 0; i < items.length; i += exports.PER_KEY_BATCH_CONCURRENCY) {
+        const slice = items.slice(i, i + exports.PER_KEY_BATCH_CONCURRENCY);
+        const settled = await Promise.all(slice.map(task));
+        for (let j = 0; j < settled.length; j++)
+            out[i + j] = settled[j];
+    }
+    return out;
+}
+async function perKeyMGetImpl(client, keys) {
+    return mapWithBoundedConcurrency(keys, (k) => executeWithClusterRetry(() => client.get(k)));
+}
+async function perKeyMSetImpl(client, entries) {
+    await mapWithBoundedConcurrency(entries, ({ key, value, ttl }) => executeWithClusterRetry(() => ttl ? client.setEx(key, ttl, value) : client.set(key, value)));
+}
+/**
+ * Topology-aware MGET — standalone/sentinel fast path, cluster per-key path.
+ *
+ * Cluster: always per-key GET via `Promise.all` — Redis requires same slot for MGET; node-redis
+ * auto-pipelines per target node and follows MOVED/ASK per command.
+ * Standalone/sentinel: single `mGet` round-trip; falls back to per-key on unexpected batch errors.
+ */
+async function mGetImpl(client, keys) {
+    if (keys.length === 0)
+        return [];
+    if (isClusterImpl(client))
+        return perKeyMGetImpl(client, keys);
+    try {
+        // Chunked: one unbounded MGET would block the node for its whole service time.
+        const out = [];
+        for (const slice of chunked(keys, exports.BATCH_COMMAND_CHUNK)) {
+            out.push(...(await client.mGet(slice)));
+        }
+        return out;
+    }
+    catch (err) {
+        if (!shouldFallbackClusterBatch(err))
+            throw err;
+        return perKeyMGetImpl(client, keys);
+    }
+}
+/**
+ * Topology-aware multi-key SET — standalone/sentinel pipeline, cluster per-key path.
+ *
+ * Cluster: per-key SETEX/SET via `Promise.all` — avoids CROSSSLOT/MOVED from MULTI/EXEC pipelines.
+ * Standalone/sentinel: `multi().exec()` fast path; falls back to per-key on batch errors.
+ *
+ * entries.value must already be serialised to a string (JSON.stringify beforehand).
+ */
+async function mSetImpl(client, entries) {
+    if (entries.length === 0)
+        return;
+    if (isClusterImpl(client)) {
+        await perKeyMSetImpl(client, entries);
+        return;
+    }
+    try {
+        // Chunked: MULTI/EXEC runs as one unit, so an unbounded pipeline blocks the node for the whole
+        // batch. Chunking splits atomicity, which is safe for the independent per-key writes this API
+        // takes (no caller relies on all-or-nothing across unrelated keys) — see BATCH_COMMAND_CHUNK.
+        for (const slice of chunked(entries, exports.BATCH_COMMAND_CHUNK)) {
+            const pipeline = client.multi();
+            for (const { key, value, ttl } of slice) {
+                if (ttl)
+                    pipeline.setEx(key, ttl, value);
+                else
+                    pipeline.set(key, value);
+            }
+            await pipeline.exec();
+        }
+    }
+    catch (err) {
+        if (!shouldFallbackClusterBatch(err))
+            throw err;
+        await perKeyMSetImpl(client, entries);
+    }
+}
+/**
+ * Topology-aware multi-key DELETE — the single canonical implementation.
+ *
+ * Standalone / sentinel: single `DEL k1 k2 …` round-trip.
+ * Cluster: per-key DEL loop — avoids CROSSSLOT when keys span different hash slots.
+ *
+ * All callers should use this instead of `client.del(array)` directly.
+ */
+async function mDelImpl(client, keys) {
+    if (keys.length === 0)
+        return 0;
+    if (isClusterImpl(client)) {
+        let n = 0;
+        for (const k of keys) {
+            n += await executeWithClusterRetry(() => client.del(k));
+        }
+        return n;
+    }
+    // Chunked for the same reason as MGET: `DEL k1 … kN` is one command whose service time scales with
+    // N, and Redis serves it to the exclusion of every other client. The cluster branch above is
+    // already bounded (strictly serial, one key in flight).
+    const c = client;
+    let removed = 0;
+    for (const slice of chunked(keys, exports.BATCH_COMMAND_CHUNK)) {
+        removed += await c.del(slice);
+    }
+    return removed;
+}
+/**
+ * Topology-aware FLUSHDB — flushes every data store.
+ *
+ * Standalone / sentinel: single `flushDb()` call.
+ * Cluster: `flushDb()` on the cluster client only flushes the node owning the command's
+ * hash slot — i.e. one master. This calls `flushDb()` on every master client directly.
+ *
+ * Use only in tests and dev tooling — never on production data.
+ */
+async function flushAllImpl(client) {
+    if (isClusterImpl(client)) {
+        await Promise.all(client.masters
+            .filter((m) => m.client != null)
+            .map((m) => m.client.flushDb()));
+    }
+    else {
+        await client.flushDb();
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// Lifecycle (internal)
+// ═══════════════════════════════════════════════════════════════════
+async function closeRedisImpl() {
+    if (readClient) {
+        try {
+            await readClient.quit();
+        }
+        catch (e) {
+            console.error(ERR_PREFIX, 'close read replica', errMsg(e));
+        }
+        readClient = null;
+    }
+    if (clusterClient) {
+        try {
+            await clusterClient.quit();
+        }
+        catch (e) {
+            console.error(ERR_PREFIX, 'close cluster', errMsg(e));
+        }
+        clusterClient = null;
+    }
+    if (sentinelClient) {
+        try {
+            await sentinelClient.close();
+        }
+        catch (e) {
+            console.error(ERR_PREFIX, 'close sentinel', errMsg(e));
+        }
+        sentinelClient = null;
+    }
+    if (client) {
+        try {
+            await client.quit();
+        }
+        catch (e) {
+            console.error(ERR_PREFIX, 'close standalone', errMsg(e));
+        }
+        client = null;
+    }
+}
+function getRedisConnectionStatsImpl() {
+    if (clusterClient) {
+        // Cluster mode: replica routing is handled internally by node-redis when `useReplicas`
+        // is true; we surface `hasReadReplica = true` to keep observability uniform with the
+        // standalone+readClient story. Per-node connection counts would require introspecting
+        // the cluster's slot map and are intentionally left out of this lightweight snapshot.
+        return {
+            connected: true,
+            mode: 'cluster',
+            hasReadReplica: true,
+            master: { connected: true },
+            replica: { connected: true, count: 1 }
+        };
+    }
+    if (sentinelClient) {
+        return { connected: true, mode: 'sentinel', hasReadReplica: false, master: { connected: true }, replica: { connected: false, count: 0 } };
+    }
+    return {
+        connected: client !== null,
+        mode: 'standalone',
+        hasReadReplica: readClient !== null,
+        master: { connected: client !== null },
+        replica: { connected: readClient !== null, count: readClient ? 1 : 0 }
+    };
+}
+// ═══════════════════════════════════════════════════════════════════
+// Topology descriptor → RedisConfig translation
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Translate a RedisTopologyDescriptor into the internal RedisConfig shape.
+ * Exported as TSRedis.buildConfigFromTopology for callers that need a RedisConfig
+ * alongside connectFromTopology (e.g. passing defaultConfig to configureRedisStrategy).
+ */
+function buildConfigFromDescriptor(d) {
+    const base = {
+        url: d.url ?? '',
+        maxReconnectRetries: d.maxReconnectRetries ?? DEFAULT_CONFIG.maxReconnectRetries,
+        reconnectDelay: d.reconnectDelay ?? DEFAULT_CONFIG.reconnectDelay,
+        connectTimeout: d.connectTimeout ?? DEFAULT_CONFIG.connectTimeout,
+        socketTimeout: d.commandTimeoutMs ?? DEFAULT_CONFIG.socketTimeout
+    };
+    switch (d.mode) {
+        case 'sentinel': {
+            // Master auth: embed in URL so connectRedisSentinel's urlMatch extracts it into
+            // sentinelOptions.password (the master connection password), independently of
+            // sentinel node auth. sentinel.password is strictly for sentinel-node requirepass
+            // (rare — most setups only password-protect the master, not the sentinel processes).
+            const urlWithPass = d.password ? `redis://:${d.password}@_` : (d.url ?? '');
+            return {
+                ...base,
+                url: urlWithPass,
+                sentinel: {
+                    hosts: d.sentinelNodes ?? [],
+                    name: d.sentinelMaster ?? 'mymaster',
+                    ...(d.sentinelPassword ? { password: d.sentinelPassword } : {}),
+                    ...(d.sentinelNodeAddressMap !== undefined ? { nodeAddressMap: d.sentinelNodeAddressMap } : {})
+                }
+            };
+        }
+        case 'cluster':
+            return {
+                ...base,
+                cluster: {
+                    nodes: d.clusterNodes ?? [],
+                    ...(d.password ? { password: d.password } : {}),
+                    ...(d.clusterNodeAddressMap !== undefined ? { nodeAddressMap: d.clusterNodeAddressMap } : {})
+                }
+            };
+        default: // 'single'
+            return base;
+    }
+}
+/**
+ * Connect using a flat topology descriptor — the preferred entry point for all callers.
+ *
+ * Handles all three topologies (single / sentinel / cluster) from one call.
+ * No environment-variable reads; every value comes explicitly from the descriptor.
+ * Idempotent: if a client for this topology is already connected, this is a no-op.
+ * Stale closed clients (max-reconnect exhausted) are discarded and reconnected.
+ */
+async function connectFromTopologyImpl(descriptor) {
+    await discardStaleClientsIfNeeded();
+    const active = getActiveClientImpl();
+    if (active && isClientOpen(active))
+        return;
+    await connectRedisImpl(buildConfigFromDescriptor(descriptor));
+}
+/**
+ * Build a RedisTopologyDescriptor from standard Redis environment variables.
+ *
+ * Detection priority:
+ *   1. REDIS_SENTINEL_NODES (comma-separated host:port) → sentinel
+ *   2. REDIS_CLUSTER_NODES (comma-separated host:port) → cluster
+ *   3. REDIS_URL → single
+ *   4. Default → cluster on 127.0.0.1:7000-7005 (local dev default)
+ *
+ * Env vars consumed:
+ *   REDIS_SENTINEL_NODES       e.g. "127.0.0.1:26380,127.0.0.1:26381,127.0.0.1:26382"
+ *   REDIS_SENTINEL_MASTER      sentinel master name (default: "mymaster")
+ *   REDIS_CLUSTER_NODES        e.g. "127.0.0.1:7000,...,127.0.0.1:7005"
+ *   REDIS_CLUSTER_HOST_REWRITE host to rewrite cluster-announced addresses to (default: "127.0.0.1")
+ *   REDIS_URL                  e.g. "redis://localhost:6379"
+ *   REDIS_PASSWORD             auth password (applied to all modes)
+ *
+ * For cluster mode the nodeAddressMap handles three redirect scenarios automatically:
+ *   - Port-matched rewrites (Docker host-port-forward)
+ *   - k8s FQDN MOVED redirects (redis-cluster-N.* → localhost:startPort+N)
+ *   - Dynamic Docker pod-IP MOVED redirect mapping
+ * When all cluster nodes are non-loopback hosts (direct k8s pod routing), no rewrite is applied.
+ */
+function buildTopologyDescriptorFromEnvImpl() {
+    const password = process.env.REDIS_PASSWORD;
+    const sentinelRaw = process.env.REDIS_SENTINEL_NODES;
+    const clusterRaw = process.env.REDIS_CLUSTER_NODES;
+    const redisUrl = process.env.REDIS_URL;
+    if (sentinelRaw) {
+        const nodes = sentinelRaw.split(',').map(s => {
+            const [host, port] = s.trim().split(':');
+            return { host: host, port: Number(port) };
+        });
+        // REDIS_SENTINEL_MASTER_HOST + REDIS_SENTINEL_MASTER_PORT: remap Docker/k8s-internal
+        // master/replica addresses to a client-reachable address.
+        // Example: sentinel announces 172.21.0.2:6379 → remap to 127.0.0.1:6381.
+        // Loopback addresses (sentinel nodes themselves) are never remapped.
+        const addrHost = process.env.REDIS_SENTINEL_MASTER_HOST;
+        const addrPort = process.env.REDIS_SENTINEL_MASTER_PORT;
+        const sentinelNodeAddressMap = addrHost && addrPort
+            ? (address) => {
+                // Only remap standard Redis master/replica port (6379).
+                // Sentinel root nodes (28380+) and sentinel peer ports (26379) must not be remapped —
+                // nodeAddressMap is applied to ALL node connections, not just master connections.
+                const colonIdx = address.lastIndexOf(':');
+                const reportedPort = colonIdx >= 0 ? Number(address.slice(colonIdx + 1)) : 6379;
+                if (reportedPort !== 6379)
+                    return undefined;
+                return { host: addrHost, port: Number(addrPort) };
+            }
+            : undefined;
+        return {
+            mode: 'sentinel',
+            password,
+            sentinelNodes: nodes,
+            sentinelMaster: process.env.REDIS_SENTINEL_MASTER ?? 'mymaster',
+            ...(sentinelNodeAddressMap ? { sentinelNodeAddressMap } : {})
+        };
+    }
+    if (clusterRaw || !redisUrl) {
+        const raw = clusterRaw
+            ?? '127.0.0.1:7000,127.0.0.1:7001,127.0.0.1:7002,127.0.0.1:7003,127.0.0.1:7004,127.0.0.1:7005';
+        const nodes = raw.split(',').map(s => {
+            const [host, port] = s.trim().split(':');
+            return { host: host, port: Number(port) };
+        });
+        const hostRewrite = process.env.REDIS_CLUSTER_HOST_REWRITE ?? '127.0.0.1';
+        const knownPorts = new Set(nodes.map(n => n.port));
+        const startPort = Math.min(...nodes.map(n => n.port));
+        // Direct k8s: real pod hostnames, cluster is routable without any rewrite.
+        const isDirectK8s = nodes.every(n => n.host !== '127.0.0.1' && n.host !== 'localhost');
+        const k8sDynamicMap = new Map();
+        let k8sNextPort = startPort;
+        const clusterNodeAddressMap = isDirectK8s
+            ? undefined
+            : (address) => {
+                const m = address.match(/:(\d+)$/);
+                if (!m)
+                    return undefined;
+                const port = Number(m[1]);
+                if (knownPorts.has(port))
+                    return { host: hostRewrite, port };
+                // k8s FQDN MOVED redirect: redis-cluster-N.* → localhost:startPort+N
+                const fqdn = address.match(/redis-cluster-(\d+)\./);
+                if (fqdn)
+                    return { host: '127.0.0.1', port: startPort + Number(fqdn[1]) };
+                // Docker pod-IP MOVED redirect: dynamic sequential assignment
+                if (!k8sDynamicMap.has(address) && k8sNextPort < startPort + nodes.length) {
+                    k8sDynamicMap.set(address, k8sNextPort++);
+                }
+                const mapped = k8sDynamicMap.get(address);
+                return mapped !== undefined ? { host: '127.0.0.1', port: mapped } : undefined;
+            };
+        return {
+            mode: 'cluster',
+            password,
+            url: `redis://${nodes[0].host}:${nodes[0].port}`,
+            clusterNodes: nodes,
+            clusterNodeAddressMap
+        };
+    }
+    return { mode: 'single', url: redisUrl, password };
+}
+// ═══════════════════════════════════════════════════════════════════
+// TSRedis – static API (connect, pub/sub, scan) + instance ops
+// ═══════════════════════════════════════════════════════════════════
+class TSRedis extends events_1.EventEmitter {
+    redis;
+    constructor(instance) {
+        super();
+        this.redis = instance;
+    }
+    /**
+     * Connect from a flat topology descriptor — the preferred entry point.
+     * Handles single / sentinel / cluster from one call; no env-var reads inside.
+     * Idempotent: already-connected clients are reused.
+     * Stale closed clients (max-reconnect exhausted) are discarded and reconnected.
+     */
+    static connectFromTopology = connectFromTopologyImpl;
+    /**
+     * Build a RedisTopologyDescriptor from standard Redis env vars.
+     * Use with connectFromTopology for zero-config topology-aware connections:
+     *   await TSRedis.connectFromTopology(TSRedis.buildTopologyDescriptorFromEnv())
+     */
+    static buildTopologyDescriptorFromEnv = buildTopologyDescriptorFromEnvImpl;
+    /**
+     * Translate a RedisTopologyDescriptor into a RedisConfig.
+     * Use when another API (e.g. configureRedisStrategy) still takes RedisConfig directly.
+     */
+    static buildConfigFromTopology = buildConfigFromDescriptor;
+    /** Connect (standalone, Sentinel, Cluster, or with read replicas). Cluster is selected
+     * when the supplied `RedisConfig.cluster` is set; otherwise sentinel / standalone per
+     * the existing precedence rules. */
+    static connect = connectRedisImpl;
+    /** Standalone / sentinel client singleton. Returns null in cluster mode — use {@link getCluster}. */
+    static getClient = getRedisImpl;
+    /** Active cluster client. Returns null when not in cluster mode. */
+    static getCluster = getRedisClusterImpl;
+    /** Topology-agnostic accessor — returns the active client (standalone / sentinel / cluster). */
+    static getActiveClient = getActiveClientImpl;
+    static getClientForRead = getRedisForReadImpl;
+    static hasReadReplica = hasReadReplicaImpl;
+    static close = closeRedisImpl;
+    static checkHealth = checkRedisHealthImpl;
+    static getConnectionStats = getRedisConnectionStatsImpl;
+    static publish = publishImpl;
+    static subscribe = subscribeImpl;
+    /**
+     * STREAMING key scan — the primitive to reach for whenever the match-set size is not already known.
+     *
+     * Preferred over {@link TSRedis.scanr} for one structural reason: an iterator cannot misreport completeness.
+     * The caller drains it or does not, and either way there is no single value that claims to be "all the keys".
+     * `scanr` materialises, so it needs a ceiling and a policy for hitting it — see `TSRedisScan.onLimit`.
+     *
+     * `maxKeys` still bounds it (default 10,000) and reaching that bound ends iteration SILENTLY, so if
+     * completeness matters here too, pass a `maxKeys` you are prepared to treat as an error and check the count
+     * yourself. Best of all: do not scan on a hot path at all — keep an index set (ms repo: CIG-4).
+     */
+    static scanKeysIterator = scanKeysIteratorImpl;
+    static batchGetValues = batchGetValuesImpl;
+    /**
+     * Key-family index — the canonical SCAN replacement for enumerating a family of keys.
+     * O(members) SMEMBERS + per-member GET (CROSSSLOT-safe), lazy pruning of dead members.
+     * Prefer these over scanKeysIterator for ANY latency-sensitive or repeated enumeration.
+     */
+    static keyIndexAdd = keyIndexAddImpl;
+    static keyIndexRemove = keyIndexRemoveImpl;
+    static keyIndexMembers = keyIndexMembersImpl;
+    static keyIndexCount = keyIndexCountImpl;
+    static keyIndexEnumerate = keyIndexEnumerateImpl;
+    /**
+     * True when `client` is a Redis Cluster client.
+     * Prefer the topology-aware helpers (mGet, mSet, mDel, flushAll) over manual branching.
+     */
+    static isCluster = isClusterImpl;
+    /**
+     * Topology-aware MGET: tries a single mGet round-trip; on cluster CROSSSLOT/MOVED/ASK falls back
+     * to per-key GETs via Promise.all.  Safe for keys that span different hash slots.
+     */
+    static mGet = mGetImpl;
+    /**
+     * Topology-aware multi-key SET: tries a multi().exec() pipeline; on cluster CROSSSLOT/MOVED/ASK
+     * falls back to per-key SETEX/SET via Promise.all.
+     * entries.value must be pre-serialised (string).
+     */
+    static mSet = mSetImpl;
+    /**
+     * Topology-aware multi-key DELETE: per-key loop in cluster (avoids CROSSSLOT),
+     * batch DEL in standalone/sentinel (single round-trip).
+     */
+    static mDel = mDelImpl;
+    static executeWithCommandRetry = executeWithCommandRetry;
+    static evalTaggedScript = evalTaggedScript;
+    static isCommandTimeoutError = isCommandTimeoutError;
+    /**
+     * Topology-aware FLUSHDB: flushes every master in cluster mode, single flushDb()
+     * otherwise.  Test/dev tooling only — never call on production data.
+     */
+    static flushAll = flushAllImpl;
+    async cachedRequest(options, defaultValue = {}, debug) {
+        if (!options.getData) {
+            options.getData = (response) => response;
+        }
+        const { url, key, ...requestOptions } = options;
+        const result = await this.redis.get(key);
+        if (result) {
+            return JSON.parse(result);
+        }
+        else {
+            const response = await TSRequest_1.TSRequest.json(url, { ...requestOptions, method: (options.method || 'post') }, debug);
+            const data = options.getData(response);
+            if (data) {
+                let value = this.pathToStore(options.pathValue || [], data);
+                value = options.format && typeof options.format === 'function'
+                    ? options.format(value)
+                    : value;
+                if (value) {
+                    await this.redis.setEx(key, options.expire || 300, JSON.stringify(value));
+                    return value;
+                }
+                else {
+                    return defaultValue;
+                }
+            }
+            else {
+                console.error(response);
+                return defaultValue;
+            }
+        }
+    }
+    pathToStore(keys = [], object) {
+        let current = object;
+        let value = object;
+        for (const i in keys) {
+            if (Object.prototype.hasOwnProperty.call(keys, i) && current && typeof current === 'object' && current[keys[i]]) {
+                value = current[keys[i]];
+                current = value;
+            }
+            else {
+                value = undefined;
+                break;
+            }
+        }
+        return value;
+    }
+    cached = async (path, options) => {
+        const result = await this.redis.get(path);
+        if (result)
+            return result;
+        if (options?.value) {
+            await this.redis.setEx(path, options.expire || 3600, options.value);
+            return options.value;
+        }
+    };
+    load = async (entity) => {
+        const result = await this.redis.hGetAll(entity);
+        const mappedResult = [];
+        Object.keys(result || {}).map((k) => mappedResult.push(JSON.parse(result[k])));
+        return mappedResult;
+    };
+    get = async (key, cb) => {
+        const result = await this.redis.get(key);
+        return cb ? cb(result) : result;
+    };
+    set = async (key, data) => (await this.redis.set(key, String(data))) === 'OK';
+    hget = async (key, field) => {
+        const result = await this.redis.hGet(key, field);
+        return result ? JSON.parse(result) : null;
+    };
+    getM = async (entity, keys) => this.redis.hmGet(entity, keys);
+    hgetall = async (key, cb) => {
+        const result = await this.redis.hGetAll(key);
+        return cb ? cb(result) : result;
+    };
+    hset = async (key, field, data) => {
+        if (typeof data !== 'undefined' && data !== null && String(data).length > 0) {
+            return (await this.redis.hSet(key, field, JSON.stringify(data))) >= 0;
+        }
+        return false;
+    };
+    hdel = async (key, fields) => (await this.redis.hDel(key, fields)) > 0;
+    del = async (keys) => {
+        const ks = Array.isArray(keys) ? keys : [keys];
+        if (ks.length === 0)
+            return false;
+        // Per-key DEL: cluster mode rejects multi-key DEL across slots (CROSSSLOT).
+        const counts = await Promise.all(ks.map(k => this.redis.del(k)));
+        return counts.some(c => c > 0);
+    };
+    loadLists = async (pattern = '*') => {
+        const list = await this.scanr({ pattern });
+        const result = {};
+        if (list.length === 0)
+            return result;
+        // Per-key TYPE: cluster multi() across different slots causes CROSSSLOT.
+        // NOT bounded by PER_KEY_BATCH_CONCURRENCY on purpose: `list` is a whole scan result, so chunking
+        // it turns one wide fan-out into thousands of sequential round-trip batches (measured: 55k keys
+        // → ~2.2k chunks, slow enough to time out). This is a scan-everything tooling API, not a path
+        // shared with latency-critical traffic — callers needing queue-depth safety should use mGet/mSet.
+        const types = await Promise.all(list.map(k => this.redis.type(k).catch(() => 'none')));
+        const hashKeys = [];
+        const hashScopes = [];
+        for (let i = 0; i < list.length; i++) {
+            if (String(types[i]) === 'hash') {
+                hashKeys.push(list[i]);
+                hashScopes.push(list[i].split(':').pop());
+            }
+        }
+        if (hashKeys.length === 0)
+            return result;
+        // Per-key hGetAll: cluster multi() across slots causes CROSSSLOT. Unbounded for the same reason
+        // as the TYPE fan-out above.
+        const hashResults = await Promise.all(hashKeys.map(k => this.redis.hGetAll(k).catch(() => ({}))));
+        for (let j = 0; j < hashScopes.length; j++) {
+            const val = hashResults[j];
+            result[hashScopes[j]] = (val != null && typeof val === 'object') ? val : {};
+        }
+        return result;
+    };
+    hscanr = async (entity, { pattern, COUNT = 200 }, cb) => {
+        const MATCH = this.match(pattern ?? '*');
+        const results = {};
+        let cursor = '0';
+        do {
+            const scanned = await this.redis.hScan(entity, cursor, { COUNT, MATCH });
+            cursor = scanned.cursor;
+            for (let i = 0; i < scanned.entries.length; i++) {
+                const entry = scanned.entries[i];
+                if (this.check(entry.value, pattern ?? '*')) {
+                    if (cb)
+                        cb(JSON.parse(entry.value), entry.field);
+                    else
+                        results[entry.field] = JSON.parse(entry.value);
+                }
+            }
+        } while (cursor !== '0');
+        return results;
+    };
+    zscanr = async (entity, { pattern, COUNT = 200 }, cb = (value, score) => ({ value, score })) => {
+        const MATCH = this.match(pattern ?? '*');
+        const results = [];
+        let cursor = '0';
+        do {
+            const scanned = await this.redis.zScan(entity, cursor, { COUNT, MATCH });
+            cursor = scanned.cursor;
+            for (let i = 0; i < scanned.members.length; i++) {
+                const member = scanned.members[i];
+                if (this.check(member.value, pattern ?? '*')) {
+                    const data = cb(member.value, String(member.score));
+                    if (typeof data !== 'undefined')
+                        results.push(data);
+                }
+            }
+        } while (cursor !== '0');
+        return results;
+    };
+    /**
+     * Materialise every key matching `pattern`, across all shards.
+     *
+     * ⚠ This BUILDS A LIST. For anything whose size you do not already know, prefer
+     * {@link TSRedis.scanKeysIterator} — an iterator cannot misreport completeness, because the caller either
+     * drains it or does not. This wrapper exists for bounded, known-small patterns.
+     *
+     * Exceeding `maxKeys` THROWS by default; pass `onLimit: 'truncate'` to opt into a prefix. See
+     * {@link TSRedisScan.onLimit} for why the default is loud.
+     *
+     * And note what this costs even when it succeeds: `SCAN` walks the entire keyspace regardless of how few keys
+     * match, so a sparse pattern over a large instance is expensive. On any latency-sensitive path, do not scan —
+     * address exact keys or maintain an index set (ms repo: cache-invalidation-governance CIG-4).
+     */
+    scanr = async ({ pattern, COUNT = 200, maxKeys, onLimit = 'throw' }, cb) => {
+        const limit = maxKeys ?? COUNT * 500;
+        const results = [];
+        let seen = 0;
+        // Over-fetch by ONE. Stopping exactly at `limit` is indistinguishable from a match set of exactly `limit`,
+        // so the extra key is what turns "we hit the ceiling" into an observable fact rather than an inference.
+        for await (const key of scanKeysIteratorImpl({
+            pattern: this.match(pattern ?? '*'),
+            maxKeys: limit + 1
+        })) {
+            if (!this.check(key, pattern ?? '*'))
+                continue;
+            seen++;
+            if (seen > limit) {
+                if (onLimit === 'throw') {
+                    throw new Error(`TSRedis.scanr: pattern '${this.match(pattern ?? '*')}' matched more than the ${limit}-key ceiling. ` +
+                        'Narrow the pattern, raise maxKeys, use scanKeysIterator to stream, or pass onLimit:"truncate" to ' +
+                        'accept a prefix deliberately.');
+                }
+                break;
+            }
+            if (cb)
+                cb([key]);
+            else
+                results.push(key);
+        }
+        return results;
+    };
+    static _regexCache = new Map();
+    check = (value, pattern) => {
+        if (typeof pattern !== 'object' || !pattern.text)
+            return true;
+        let re = TSRedis._regexCache.get(pattern.text);
+        if (!re) {
+            re = new RegExp(pattern.text, 'i');
+            TSRedis._regexCache.set(pattern.text, re);
+        }
+        return value.search(re) > -1;
+    };
+    match = (pattern) => (typeof pattern === 'string' ? pattern : (pattern.match ?? '*'));
+}
+exports.TSRedis = TSRedis;