ts-server-lib 0.0.48

package/db/TSRedis.d.ts

@@ -0,0 +1,530 @@
+/**
+ * TSRedis – Single file for Redis: connection (standalone/Sentinel), events (pub/sub), operations.
+ */
+import { EventEmitter } from 'events';
+import { type RedisClientType, type RedisClusterType, type RedisSentinelType } from 'redis';
+export type TSRedisClient = RedisClientType | RedisClusterType | RedisSentinelType;
+export type TSRedisPattern = {
+    match?: string;
+    text?: string;
+} | string;
+export type TSRedisScan = {
+    pattern?: TSRedisPattern;
+    COUNT?: number;
+    /** Hard ceiling on keys materialised. Defaults to `COUNT * 500`. */
+    maxKeys?: number;
+    /**
+     * What to do when the ceiling is reached.
+     *
+     * `'throw'` (DEFAULT) — a scan that could not see the whole match set is an error, because the caller asked
+     * for "the keys matching this pattern" and a prefix of that set is a WRONG ANSWER THAT LOOKS RIGHT. Measured
+     * 2026-08-10: `loadLists('*')` returned 100,000 of 477,377 keys with no signal, and the only symptom was two
+     * assertions failing on a key that was present in Redis the whole time.
+     *
+     * `'truncate'` — return the first `maxKeys`. Legitimate for sampling or a bounded probe, but the caller has
+     * to say so, which is the entire point: silence is no longer a possible outcome.
+     */
+    onLimit?: 'throw' | 'truncate';
+};
+export type TSRedisCallback = (data: unknown, k?: string) => unknown;
+export interface RedisSentinelConfig {
+    hosts: Array<{
+        host: string;
+        port: number;
+    }>;
+    name: string;
+    /** Auth password for the sentinel nodes themselves (rare — only when sentinels have requirepass). */
+    password?: string;
+    /**
+     * Remap master/replica addresses announced by sentinel to client-reachable addresses.
+     * Useful when sentinel runs in Docker/k8s on a different network than the client
+     * (e.g. sentinel announces 172.x.x.x:6379 but client must connect via 127.0.0.1:6381).
+     */
+    nodeAddressMap?: RedisClusterConfig['nodeAddressMap'];
+}
+export interface RedisReplicaConfig {
+    enabled: boolean;
+    urls?: string[];
+    strategy?: 'round-robin' | 'random' | 'first-available';
+}
+/**
+ * Redis Cluster connection config. When set on `RedisConfig`, `TSRedis.connect()` creates
+ * a `createCluster()` client instead of `createClient()` and stores it as the active client.
+ *
+ * Multi-key constraints: commands that touch >1 key (`mGet`, `mSet`, `multi().chain`, custom
+ * Lua) require all keys to hash to the same slot. Use {tag} hash tags
+ * (e.g. `wallet:{tenantId:userId}:bal`) so co-located keys land on the same node.
+ *
+ * Caveat for queue consumers: TSRQW is built for the standalone client API. In cluster
+ * deployments, pass a standalone client to TSRQW (or a dedicated connection to one node)
+ * — see TSRedis.md §"Tuning and deployment".
+ */
+export interface RedisClusterConfig {
+    /** Seed nodes — node-redis discovers the rest via CLUSTER SLOTS after connect. */
+    nodes: Array<{
+        host: string;
+        port: number;
+    }>;
+    /** When true, route read-only commands (GET, MGET, …) to replicas. Default false (read from masters). */
+    useReplicas?: boolean;
+    /** Max MOVED/ASK hops per command (node-redis default 16). Raised to 32 for resharding tolerance. */
+    maxCommandRedirections?: number;
+    /** Cluster-wide password (most clusters share one). */
+    password?: string;
+    /**
+     * Optional remap of cluster-announced addresses. Cluster nodes typically announce docker
+     * hostnames (e.g. `ms-redis-3`) which aren't resolvable from a host-machine validator;
+     * supply this map to rewrite each discovered address to a client-reachable one
+     * (e.g. `127.0.0.1:7003`). Form: object map keyed by `host:port`, OR a function returning
+     * `{ host, port }` per discovered address string.
+     */
+    nodeAddressMap?: Record<string, {
+        host: string;
+        port: number;
+    }> | ((address: string) => {
+        host: string;
+        port: number;
+    } | undefined);
+}
+export interface RedisConfig {
+    url: string;
+    connectTimeout?: number;
+    socketTimeout?: number;
+    autoReconnect?: boolean;
+    maxReconnectRetries?: number;
+    reconnectDelay?: number;
+    clientName?: string;
+    pingInterval?: number;
+    commandsQueueMaxLength?: number;
+    disableOfflineQueue?: boolean;
+    sentinel?: RedisSentinelConfig;
+    /**
+     * Redis Cluster mode. Mutually exclusive with `sentinel` and `readReplicas` (the cluster
+     * client handles replica routing internally via `useReplicas`).
+     * When set, `TSRedis.connect()` creates a cluster client; `TSRedis.getCluster()` returns it.
+     * `TSRedis.getClient()` returns null in cluster mode (singleton client variable stays null);
+     * callers needing the cluster client should use `TSRedis.getCluster()` or `TSRedis.getActiveClient()`.
+     */
+    cluster?: RedisClusterConfig;
+    readReplicas?: RedisReplicaConfig;
+}
+export interface ScanOptions {
+    pattern?: string;
+    count?: number;
+    maxKeys?: number;
+    batchSize?: number;
+}
+export interface RedisConnectionStats {
+    connected: boolean;
+    mode: 'standalone' | 'sentinel' | 'cluster';
+    hasReadReplica: boolean;
+    master: {
+        connected: boolean;
+    };
+    replica: {
+        connected: boolean;
+        count: number;
+    };
+}
+/**
+ * Flat topology descriptor — the single input shape for TSRedis.connectFromTopology().
+ *
+ * All values are explicit. The library never reads process.env inside this path —
+ * password, nodes, and mode come entirely from the caller's config snapshot.
+ *
+ * Usage pattern:
+ *   const descriptor = buildRedisDescriptor(myConfig);
+ *   await TSRedis.connectFromTopology(descriptor);
+ *   const config = TSRedis.buildConfigFromTopology(descriptor); // if another API needs RedisConfig
+ */
+export interface RedisTopologyDescriptor {
+    mode: 'single' | 'sentinel' | 'cluster';
+    /** Redis URL (redis://[:password@]host:port). Used directly for single mode; provides the
+     *  seed URL for cluster; ignored for sentinel (connection is driven by sentinel nodes). */
+    url?: string;
+    /** Auth password for the Redis master / standalone server. No env-var fallback. */
+    password?: string;
+    /**
+     * Sentinel: auth password for the sentinel nodes themselves.
+     * Only needed when sentinels are configured with 'requirepass'.
+     * Most setups only password-protect the master — in that case leave this unset.
+     */
+    sentinelPassword?: string;
+    /** Sentinel: quorum-monitor node addresses. Required when mode === 'sentinel'. */
+    sentinelNodes?: Array<{
+        host: string;
+        port: number;
+    }>;
+    /** Sentinel master set name (default 'mymaster'). */
+    sentinelMaster?: string;
+    /**
+     * Sentinel: remap master/replica addresses announced by sentinel to client-reachable addresses.
+     * Useful when sentinel runs in Docker/k8s on a different network than the client.
+     * Also readable from env via REDIS_SENTINEL_MASTER_HOST + REDIS_SENTINEL_MASTER_PORT
+     * (sets a static remap for all announced addresses).
+     */
+    sentinelNodeAddressMap?: RedisClusterConfig['nodeAddressMap'];
+    /** Cluster: seed nodes — node-redis discovers the rest via CLUSTER SLOTS. Required when mode === 'cluster'. */
+    clusterNodes?: Array<{
+        host: string;
+        port: number;
+    }>;
+    /**
+     * Cluster: optional address rewriter for MOVED redirect handling.
+     * Used by test runners behind Docker/k8s port-forwards where cluster-announced
+     * hostnames are not directly reachable from the host.
+     */
+    clusterNodeAddressMap?: RedisClusterConfig['nodeAddressMap'];
+    maxReconnectRetries?: number;
+    reconnectDelay?: number;
+    connectTimeout?: number;
+    /** Per-command socket timeout (ms) — maps to node-redis socketTimeout on all topologies. */
+    commandTimeoutMs?: number;
+}
+export declare function errMsg(e: unknown): string;
+/** True when a node-redis client handle is open/ready (false after max-reconnect exhaustion). */
+export declare function isClientOpen(c: TSRedisClient | null | undefined): boolean;
+/**
+ * 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.
+ */
+export declare function isStaleConnectionError(err: unknown): boolean;
+declare function connectRedisImpl(urlOrConfig: string | RedisConfig): Promise<RedisClientType>;
+declare function getRedisImpl(): RedisClientType | null;
+/**
+/** Returns the active cluster client when `connectRedisImpl` was called with `config.cluster`, else null. */
+declare function getRedisClusterImpl(): RedisClusterType | null;
+/**
+ * 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.
+ */
+declare function getActiveClientImpl(): TSRedisClient | null;
+/** True when TSRedis holds an active singleton client that is open (not post-max-reconnect closed). */
+export declare function isActiveClientConnected(): boolean;
+declare function getRedisForReadImpl(): RedisClientType | null;
+declare function hasReadReplicaImpl(): boolean;
+declare function checkRedisHealthImpl(): Promise<{
+    healthy: boolean;
+    latencyMs: number;
+}>;
+declare function publishImpl(channel: string, message: string): Promise<boolean>;
+declare function subscribeImpl(channel: string, handler: (message: string) => void): Promise<() => Promise<void>>;
+declare function scanKeysIteratorImpl(options?: ScanOptions): AsyncGenerator<string, void, unknown>;
+declare function batchGetValuesImpl(keys: string[]): Promise<Record<string, string | null>>;
+/** One live entry resolved through {@link keyIndexEnumerateImpl}. */
+export interface KeyIndexEntry {
+    member: string;
+    /** Redis key the member resolves to (via `keyOf`). */
+    key: string;
+    /** Raw value (`GET key`) — only populated when `withValues` (default true). */
+    value: string | null;
+    /** TTL of the value key in seconds — only populated when `withValues` (default true). */
+    ttlSeconds: number;
+}
+/** Register a member in an index set (idempotent). Refreshes the index's safety TTL. */
+declare function keyIndexAddImpl(indexKey: string, member: string, opts?: {
+    indexTtlSeconds?: number;
+}): Promise<void>;
+/** Remove a member from an index set (lazy pruning in enumerate covers a missed remove). */
+declare function keyIndexRemoveImpl(indexKey: string, member: string): Promise<void>;
+/** All members of an index set. */
+declare function keyIndexMembersImpl(indexKey: string): Promise<string[]>;
+/** Member count (SCARD). */
+declare function keyIndexCountImpl(indexKey: string): Promise<number>;
+/**
+ * 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.
+ */
+declare function keyIndexEnumerateImpl(indexKey: string, keyOf: (member: string) => string, opts?: {
+    limit?: number;
+    withValues?: boolean;
+}): Promise<{
+    entries: KeyIndexEntry[];
+    prunedCount: number;
+}>;
+/** True when `client` is a Redis Cluster client (has a `masters` array). */
+declare function isClusterImpl(client: TSRedisClient): client is RedisClusterType;
+/** True when Redis returns a transient cluster error that should be retried (TRYAGAIN, CLUSTERDOWN, LOADING). */
+export declare function isTransientClusterError(err: unknown): boolean;
+/**
+ * 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.
+ */
+export declare function executeWithClusterRetry<T>(fn: () => Promise<T>, opts?: {
+    maxRetries?: number;
+    delayMs?: number;
+}): Promise<T>;
+/** True when a Redis command failed due to client timeout or stale connection. */
+export declare function isCommandTimeoutError(err: unknown): boolean;
+/**
+ * Retry wrapper for feed-hot paths: command timeout / stale connection + cluster TRYAGAIN
+ * (via nested executeWithClusterRetry).
+ */
+export declare function executeWithCommandRetry<T>(fn: () => Promise<T>, opts?: {
+    maxRetries?: number;
+    delayMs?: number;
+    jitterMs?: number;
+}): Promise<T>;
+export interface EvalTaggedScriptOptions {
+    keys: string[];
+    argv?: string[];
+    source: string;
+    /** Validates all KEYS share one `{tag}` — catches CROSSSLOT mistakes before runtime. */
+    validateSameTag?: boolean;
+}
+/**
+ * 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.
+ */
+export declare function evalTaggedScript(client: TSRedisClient, opts: EvalTaggedScriptOptions): Promise<unknown>;
+/**
+ * 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.
+ */
+export declare const 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.
+ */
+export declare const BATCH_COMMAND_CHUNK = 500;
+/**
+ * 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.
+ */
+declare function mGetImpl(client: TSRedisClient, keys: string[]): Promise<(string | null)[]>;
+/**
+ * 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).
+ */
+declare function mSetImpl(client: TSRedisClient, entries: Array<{
+    key: string;
+    value: string;
+    ttl?: number;
+}>): Promise<void>;
+/**
+ * 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.
+ */
+declare function mDelImpl(client: TSRedisClient, keys: string[]): Promise<number>;
+/**
+ * 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.
+ */
+declare function flushAllImpl(client: TSRedisClient): Promise<void>;
+declare function closeRedisImpl(): Promise<void>;
+declare function getRedisConnectionStatsImpl(): RedisConnectionStats;
+/**
+ * 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).
+ */
+declare function buildConfigFromDescriptor(d: RedisTopologyDescriptor): RedisConfig;
+/**
+ * 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.
+ */
+declare function connectFromTopologyImpl(descriptor: RedisTopologyDescriptor): Promise<void>;
+/**
+ * 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.
+ */
+declare function buildTopologyDescriptorFromEnvImpl(): RedisTopologyDescriptor;
+export declare class TSRedis extends EventEmitter {
+    redis: TSRedisClient;
+    constructor(instance: TSRedisClient);
+    /**
+     * 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: typeof 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: typeof buildTopologyDescriptorFromEnvImpl;
+    /**
+     * Translate a RedisTopologyDescriptor into a RedisConfig.
+     * Use when another API (e.g. configureRedisStrategy) still takes RedisConfig directly.
+     */
+    static buildConfigFromTopology: typeof 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: typeof connectRedisImpl;
+    /** Standalone / sentinel client singleton. Returns null in cluster mode — use {@link getCluster}. */
+    static getClient: typeof getRedisImpl;
+    /** Active cluster client. Returns null when not in cluster mode. */
+    static getCluster: typeof getRedisClusterImpl;
+    /** Topology-agnostic accessor — returns the active client (standalone / sentinel / cluster). */
+    static getActiveClient: typeof getActiveClientImpl;
+    static getClientForRead: typeof getRedisForReadImpl;
+    static hasReadReplica: typeof hasReadReplicaImpl;
+    static close: typeof closeRedisImpl;
+    static checkHealth: typeof checkRedisHealthImpl;
+    static getConnectionStats: typeof getRedisConnectionStatsImpl;
+    static publish: typeof publishImpl;
+    static subscribe: typeof 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: typeof scanKeysIteratorImpl;
+    static batchGetValues: typeof 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: typeof keyIndexAddImpl;
+    static keyIndexRemove: typeof keyIndexRemoveImpl;
+    static keyIndexMembers: typeof keyIndexMembersImpl;
+    static keyIndexCount: typeof keyIndexCountImpl;
+    static keyIndexEnumerate: typeof keyIndexEnumerateImpl;
+    /**
+     * True when `client` is a Redis Cluster client.
+     * Prefer the topology-aware helpers (mGet, mSet, mDel, flushAll) over manual branching.
+     */
+    static isCluster: typeof 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: typeof 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: typeof mSetImpl;
+    /**
+     * Topology-aware multi-key DELETE: per-key loop in cluster (avoids CROSSSLOT),
+     * batch DEL in standalone/sentinel (single round-trip).
+     */
+    static mDel: typeof mDelImpl;
+    static executeWithCommandRetry: typeof executeWithCommandRetry;
+    static evalTaggedScript: typeof evalTaggedScript;
+    static isCommandTimeoutError: typeof isCommandTimeoutError;
+    /**
+     * Topology-aware FLUSHDB: flushes every master in cluster mode, single flushDb()
+     * otherwise.  Test/dev tooling only — never call on production data.
+     */
+    static flushAll: typeof flushAllImpl;
+    cachedRequest(options: Record<string, unknown>, defaultValue?: unknown, debug?: unknown): Promise<any>;
+    pathToStore(keys: string[] | undefined, object: unknown): unknown;
+    cached: (path: string, options?: {
+        value?: string;
+        expire?: number;
+    }) => Promise<string | undefined>;
+    load: (entity: string) => Promise<unknown[]>;
+    get: (key: string, cb?: (r: string | null) => unknown) => Promise<unknown>;
+    set: (key: string, data: unknown) => Promise<boolean>;
+    hget: (key: string, field: string) => Promise<any>;
+    getM: (entity: string, keys: string[]) => Promise<(string | null)[]>;
+    hgetall: (key: string, cb?: (r: Record<string, string>) => unknown) => Promise<unknown>;
+    hset: (key: string, field: string, data: unknown) => Promise<boolean>;
+    hdel: (key: string, fields: string[] | string) => Promise<boolean>;
+    del: (keys: string[] | string) => Promise<boolean>;
+    readonly loadLists: (pattern?: TSRedisPattern) => Promise<Record<string, Record<string, string>>>;
+    readonly hscanr: (entity: string, { pattern, COUNT }: TSRedisScan, cb?: TSRedisCallback) => Promise<Record<string, unknown>>;
+    readonly zscanr: (entity: string, { pattern, COUNT }: TSRedisScan, cb?: TSRedisCallback) => Promise<unknown[]>;
+    /**
+     * 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).
+     */
+    readonly scanr: ({ pattern, COUNT, maxKeys, onLimit }: TSRedisScan, cb?: TSRedisCallback) => Promise<string[]>;
+    private static readonly _regexCache;
+    private check;
+    private match;
+}
+export {};