ioredis-toolkit 0.0.9 → 0.5.0

package/dist/client.d.ts

@@ -1,284 +0,0 @@
-import { Cluster, Redis as RedisClient } from "ioredis";
-import { RateLimitOptionsInput, type ClusterInfo, type ClusterSlotRange, type ConnectionStatus, type RedisConfigInput, type RedisMode, DistributedLockInputOptions, CacheInputConfig } from "./types.js";
-import { type LoggerLike } from "./logger.js";
-import { Cache } from "./cache.js";
-import { PubSub } from "./pubsub.js";
-import { DistributedLock } from "./lock.js";
-import { RateLimiter } from "./ratelimiter.js";
-import { SessionManager, WithSessionManagerOptions } from "./session/session-manager.js";
-import { RedisRevocationStore } from "./session/revocation-store.js";
-export interface RedisClientOptions {
-    config: RedisConfigInput;
-    logger?: LoggerLike;
-}
-/**
- * Cluster-only administrative/capability surface.
- */
-export interface ClusterCapabilities {
-    getClusterNodes(): RedisClient[];
-    getClusterSlots(): Promise<ClusterSlotRange[]>;
-    getClusterInfo(): ClusterInfo;
-    calculateSlot(key: string): number;
-    getSlotRanges(): Promise<Map<number, string[]>>;
-    getNodeForKey(key: string): Promise<RedisClient | null>;
-    isKeyServed(key: string): Promise<boolean>;
-    executeOnNode<T>(key: string, command: string, ...args: unknown[]): Promise<T>;
-    mgetClusterAware(keys: string[]): Promise<(string | null)[]>;
-    clearNamespaceClusterAware(prefix: string, options?: {
-        batchSize?: number;
-        scanCount?: number;
-    }): Promise<number>;
-}
-type ClusterMethodName = keyof ClusterCapabilities | "isCluster";
-/**
- * Public client surface specialized by Redis topology.
- */
-export type RedisClientForMode<M extends RedisMode> = M extends "cluster" ? Omit<RedisClientWrapper, "select" | ClusterMethodName> & ClusterCapabilities & {
-    isCluster(): true;
-} : Omit<RedisClientWrapper, "isCluster" | "getClusterNodes" | "getClusterSlots" | "getClusterInfo" | "calculateSlot" | "getSlotRanges" | "getNodeForKey" | "isKeyServed" | "executeOnNode" | "mgetClusterAware" | "clearNamespaceClusterAware"> & {
-    isCluster(): false;
-};
-type RedisUnderlyingClient = RedisClient | Cluster;
-type RedisCommandArgument = string | number | Buffer;
-type ScanOptions = {
-    count?: number;
-    batchSize?: number;
-};
-type DeletePatternOptions = {
-    batchSize?: number;
-    scanCount?: number;
-};
-/**
- * Production-grade Redis client wrapper supporting:
- *
- * - standalone Redis
- * - Redis Sentinel
- * - Redis Cluster
- * - connection lifecycle handling
- * - slow-command tracking
- * - cluster-aware multi-key operations
- * - cache
- * - pub/sub
- * - distributed locks
- * - rate limiting
- * - sessions
- */
-export declare class RedisClientWrapper {
-    private readonly client;
-    private _cache?;
-    private _pubsub?;
-    private _lock?;
-    private _rateLimiter?;
-    private _session?;
-    private _revocationStore?;
-    private readonly config;
-    private readonly logger;
-    private isReady;
-    constructor(config: RedisConfigInput, logger?: LoggerLike);
-    /**
-     * Creates a new Redis client wrapper supporting standalone, sentinel, and cluster topologies.
-     *
-     * The client automatically adapts to the configured Redis topology and lazily creates
-     * and shares sub-components: `cache`, `pubsub`, `lock`, `rateLimiter`, and `session`.
-     *
-       * @param config - Redis configuration (validated with Zod `RedisConfigSchema`).
-       *   Must include `mode` (standalone/sentinel/cluster), and topology-specific fields.
-       * @param logger - Optional pino-compatible logger; defaults to `console`.
-       *
-       * @example
-       * ```ts
-       * const client = new RedisClientWrapper({
-       *   mode: 'standalone',
-       *   host: 'localhost',
-       *   port: 6379,
-       * });
-       * ```
-       */
-    /**
-     * Returns the Redis topology mode of this client.
-     *
-     * @returns `'standalone'`, `'sentinel'`, or `'cluster'`
-     */
-    get mode(): RedisMode;
-    /**
-     * Returns the shared Cache instance (lazily created on first access).
-     *
-     * The Cache provides JSON serialization, optional gzip compression, namespace
-     * support, TTLs, hash helpers, and pattern-based cleanup. All multi-key
-     * operations are slot-aware and cluster-safe.
-     *
-     * @example
-     * ```ts
-     * const cache = client.cache;
-     * await cache.set('user:1', { name: 'alice' });
-     * const user = await cache.get('user:1');
-     * ```
-     */
-    get cache(): Cache;
-    withCache(value: CacheInputConfig): RedisClientWrapper;
-    /**
-     * Returns the shared Pub/Sub instance (lazily created on first access).
-     *
-     * Publishing works immediately; subscribing requires calling {@link connectSubscriber}
-     * first. Messages are JSON-serialized on publish and auto-parsed on delivery.
-     *
-     * @example
-     * ```ts
-     * const pubsub = client.pubsub;
-     * await pubsub.connectSubscriber({ mode: 'standalone', host: 'localhost', port: 6379 });
-     * await pubsub.subscribe('orders:created', (message) => {
-     *   console.log(message); // { id: 1 }
-     * });
-     * await pubsub.publish('orders:created', { id: 1 });
-     * ```
-     */
-    get pubsub(): PubSub;
-    /**
-     * Returns the shared DistributedLock instance (lazily created on first access).
-     *
-     * Provides atomic distributed mutual-exclusion locks backed by Redis. Works in
-     * standalone, sentinel, and cluster modes. Acquisition uses atomic `SET ... PX NX`;
-     * release and extension use Lua scripts so only the lock owner can release or extend.
-     *
-     * @example
-     * ```ts
-     * const lock = client.lock;
-     * const acquired = await lock.acquire('order:42');
-     * if (acquired) {
-     *   try {
-     *     // critical section
-     *   } finally {
-     *     await lock.release('order:42');
-     *   }
-     * }
-     * ```
-     */
-    get lock(): DistributedLock;
-    withLock(value: DistributedLockInputOptions): RedisClientWrapper;
-    /**
-     * Returns the shared RateLimiter instance (lazily created on first access).
-     *
-     * Generic rate limiting for any resource — routes, API endpoints, users, IPs,
-     * API keys, database writes, email sends, webhooks. Supports fixed and sliding
-     * window algorithms. Fails open when Redis is unavailable.
-     *
-     * @example
-     * ```ts
-     * const limiter = client.rateLimiter;
-     * const result = await limiter.consume('/api/login', 'ip-10.0.0.1');
-     * if (!result.allowed) {
-     *   // HTTP 429, set Retry-After: result.retryAfter
-     * }
-     * ```
-     */
-    get rateLimiter(): RateLimiter;
-    withRateLimiter(value: RateLimitOptionsInput): RedisClientWrapper;
-    get revocationStore(): RedisRevocationStore;
-    /**
-     * Returns the shared SessionManager instance (lazily created on first access).
-     *
-     * The production session stack: validation with fail-closed semantics, rotation
-     * with retry-safe idempotency, throttled touches, idle/absolute expiry, per-user
-     * eviction ceilings, security versioning, optional AES-256-GCM encryption at rest,
-     * fail-closed circuit breaker, metrics and health. Cluster-safe by construction.
-     *
-     * @example
-     * ```ts
-     * const manager = client.session;
-     * const { token, session } = await manager.service.create({ userId: 'user-42' });
-     * const result = await manager.service.validate(token, { userId: 'user-42' });
-     * ```
-     */
-    get session(): SessionManager;
-    withSession(value: WithSessionManagerOptions): RedisClientWrapper;
-    private createClient;
-    private createClusterClient;
-    private createSentinelClient;
-    private createStandaloneClient;
-    private buildCommonRedisOptions;
-    private setupEventHandlers;
-    getRawClient<T extends RedisUnderlyingClient = RedisUnderlyingClient>(): T;
-    get raw(): RedisUnderlyingClient;
-    ping(): Promise<boolean>;
-    close(): Promise<void>;
-    private isClusterClient;
-    private exec;
-    get(key: string): Promise<string | null>;
-    set(key: string, value: string | Buffer, ttl?: number): Promise<"OK" | null>;
-    setexnx(key: string, value: string | Buffer, ttl?: number): Promise<"OK" | null>;
-    defineCommand(...args: Parameters<RedisClient["defineCommand"]>): ReturnType<RedisClient["defineCommand"]>;
-    eval(script: string, numKeys: number, ...args: RedisCommandArgument[]): Promise<unknown>;
-    evalsha(sha: string, script: string, numKeys: number, ...args: RedisCommandArgument[]): Promise<unknown>;
-    scriptLoad(script: string): Promise<string>;
-    setnx(key: string, value: string | Buffer, ttl?: number): Promise<number>;
-    del(...keys: string[]): Promise<number>;
-    getdel(key: string): Promise<string | null>;
-    exists(key: string): Promise<number>;
-    expire(key: string, ttl: number): Promise<number>;
-    ttl(key: string): Promise<number>;
-    incr(key: string): Promise<number>;
-    decr(key: string): Promise<number>;
-    incrby(key: string, amount: number): Promise<number>;
-    decrby(key: string, amount: number): Promise<number>;
-    time(): Promise<number>;
-    mget(...keys: string[]): Promise<(string | null)[]>;
-    mset(...pairs: Array<[
-        string,
-        string | Buffer
-    ]>): Promise<"OK">;
-    hget(key: string, field: string): Promise<string | null>;
-    hset(key: string, field: string, value: string | Buffer): Promise<number>;
-    hgetall(key: string): Promise<Record<string, string>>;
-    hdel(key: string, ...fields: string[]): Promise<number>;
-    sadd(key: string, ...members: string[]): Promise<number>;
-    srem(key: string, ...members: string[]): Promise<number>;
-    smembers(key: string): Promise<string[]>;
-    sismember(key: string, member: string): Promise<number>;
-    zadd(key: string, score: number, member: string): Promise<number>;
-    zrange(key: string, start: number, stop: number): Promise<string[]>;
-    zcard(key: string): Promise<number>;
-    zrem(key: string, ...members: string[]): Promise<number>;
-    pipeline(): ReturnType<RedisClient["pipeline"]>;
-    scanIterator(pattern: string, count?: number): AsyncIterable<string>;
-    scanCluster(pattern: string, options?: ScanOptions): AsyncIterable<string[]>;
-    isCluster(): boolean;
-    getClusterNodes(): RedisClient[];
-    getClusterSlots(): Promise<ClusterSlotRange[]>;
-    calculateSlot(key: string): number;
-    getNodeForKey(key: string): Promise<RedisClient | null>;
-    getSlotRanges(): Promise<Map<number, string[]>>;
-    isKeyServed(key: string): Promise<boolean>;
-    executeOnNode<T>(key: string, command: string, ...args: unknown[]): Promise<T>;
-    private executeCommandOnClient;
-    mgetClusterAware(keys: string[]): Promise<(string | null)[]>;
-    deletePattern(pattern: string, options?: DeletePatternOptions): Promise<number>;
-    clearNamespace(prefix: string, options?: DeletePatternOptions): Promise<number>;
-    clearNamespaceClusterAware(prefix: string, options?: DeletePatternOptions): Promise<number>;
-    getClusterInfo(): ClusterInfo;
-    info(section?: string): Promise<string>;
-    select(database: number): Promise<"OK">;
-    getConnectionStatus(): ConnectionStatus;
-    private runWithConcurrency;
-}
-/**
- * Cluster-specific factory overload.
- */
-export declare function createRedisClient(config: Extract<RedisConfigInput, {
-    mode: "cluster";
-}>, logger?: LoggerLike): RedisClientForMode<"cluster">;
-/**
- * Sentinel-specific factory overload.
- */
-export declare function createRedisClient(config: Extract<RedisConfigInput, {
-    mode: "sentinel";
-}>, logger?: LoggerLike): RedisClientForMode<"sentinel">;
-/**
- * Standalone factory overload.
- *
- * Standalone is also the default topology, therefore the input type permits
- * the discriminator to be omitted.
- */
-export declare function createRedisClient(config: Exclude<RedisConfigInput, {
-    mode: "cluster" | "sentinel";
-}>, logger?: LoggerLike): RedisClientForMode<"standalone">;
-export {};