ts-server-lib 0.0.17

package/db/TSRedis.d.ts

@@ -0,0 +1,174 @@
+/**
+ * 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;
+};
+export type TSRedisCallback = (data: unknown, k?: string) => unknown;
+export interface RedisSentinelConfig {
+    hosts: Array<{
+        host: string;
+        port: number;
+    }>;
+    name: string;
+    password?: string;
+}
+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;
+    /** 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;
+    };
+}
+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;
+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>>;
+declare function closeRedisImpl(): Promise<void>;
+declare function getRedisConnectionStatsImpl(): RedisConnectionStats;
+export declare class TSRedis extends EventEmitter {
+    redis: TSRedisClient;
+    constructor(instance: TSRedisClient);
+    /** 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;
+    static scanKeysIterator: typeof scanKeysIteratorImpl;
+    static batchGetValues: typeof batchGetValuesImpl;
+    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[]>;
+    readonly scanr: ({ pattern, COUNT }: TSRedisScan, cb?: TSRedisCallback) => Promise<string[]>;
+    private static readonly _regexCache;
+    private check;
+    private match;
+}
+export {};