ioredis-toolkit 0.0.5 → 0.0.7

package/dist/client.d.ts

@@ -75,15 +75,120 @@ export declare class RedisClientWrapper {
     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;

package/dist/client.js

@@ -81,15 +81,53 @@ export class RedisClientWrapper {
         this.client = this.createClient();
         this.setupEventHandlers();
     }
+    /**
+     * 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,
+       * });
+       * ```
+       */
     // ========================================================================
     // Configuration
     // ========================================================================
+    /**
+     * Returns the Redis topology mode of this client.
+     *
+     * @returns `'standalone'`, `'sentinel'`, or `'cluster'`
+     */
     get mode() {
         return this.config.mode;
     }
     // ========================================================================
     // Cache
     // ========================================================================
+    /**
+     * 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() {
         if (!this._cache) {
             this._cache = new Cache(this, this.config.cacheOptions ?? {}, this.logger);
@@ -114,6 +152,22 @@ export class RedisClientWrapper {
     // ========================================================================
     // Pub/Sub
     // ========================================================================
+    /**
+     * 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() {
         if (!this._pubsub) {
             this._pubsub = new PubSub(this, this.logger);
@@ -123,6 +177,26 @@ export class RedisClientWrapper {
     // ========================================================================
     // Distributed Lock
     // ========================================================================
+    /**
+     * 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() {
         if (!this._lock) {
             this._lock = new DistributedLock(this, this.logger, this.config.lockOptions);
@@ -147,6 +221,22 @@ export class RedisClientWrapper {
     // ========================================================================
     // Rate Limiter
     // ========================================================================
+    /**
+     * 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() {
         if (!this._rateLimiter) {
             this._rateLimiter = new RateLimiter(this, this.config.rateLimit);
@@ -181,6 +271,21 @@ export class RedisClientWrapper {
     // ========================================================================
     // Session
     // ========================================================================
+    /**
+     * 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() {
         if (!this._session) {
             const options = this.config.sessionOptions ?? {};

package/dist/health.d.ts

@@ -1,13 +1,21 @@
 import { RedisClientWrapper } from './client.js';
 import { LoggerLike } from './logger.js';
 export interface HealthStatus {
+    /** Whether the system is healthy. */
     healthy: boolean;
+    /** Current status label. */
     status: 'healthy' | 'degraded' | 'unhealthy';
+    /** Latency of the last ping check in milliseconds. */
     latency: number;
+    /** Timestamp of when the status was recorded. */
     timestamp: Date;
+    /** Additional details about the health check. */
     details: {
+        /** Whether a PING command succeeded. */
         ping: boolean;
+        /** Number of connected clients (when available). */
         connections?: number;
+        /** Memory usage information (when available). */
         memory?: string;
     };
 }
@@ -17,9 +25,82 @@ export declare class HealthChecker {
     private timer;
     private callbacks;
     private lastStatus;
+    /**
+     * Creates a health checker instance.
+     *
+     * @param client - The underlying {@link RedisClientWrapper}.
+     * @param logger - Optional pino-compatible logger; defaults to `console`.
+     *
+     * @example
+     * ```ts
+     * const health = new HealthChecker(client);
+     * ```
+     */
     constructor(client: RedisClientWrapper, logger?: LoggerLike);
+    /**
+     * Starts periodic health checks.
+     *
+     * **Behavior:**
+     * - If a timer is already running, it is cleared and replaced with the new interval.
+     * - Health checks run at the specified `interval` in milliseconds.
+     * - Each check runs asynchronously; errors are logged but do not stop the interval.
+     * - The first check runs immediately when `start()` is called (depending on setInterval timing).
+     *
+     * **Parameters:**
+     * - `interval` - Check interval in milliseconds. Default: `10000` (10 seconds).
+     *
+     * @example
+     * ```ts
+     * // Check every 5 seconds
+     * health.start(5000);
+     *
+     * // Check every 30 seconds (default)
+     * health.start();
+     * ```
+     *
+     * @returns `void`
+     */
     start(interval?: number): void;
+    /**
+     * Stops the health checker.
+     *
+     * **Behavior:**
+     * - Clears the internal timer, stopping further health checks.
+     * - Logs a warning if no timer was active.
+     *
+     * @example
+     * ```ts
+     * health.stop();
+     * ```
+     *
+     * @returns `void`
+     */
     stop(): void;
+    /**
+     * Runs a single health check.
+     *
+     * **Behavior:**
+     * - Performs a PING command to verify Redis connectivity.
+     * - Attempts to fetch Redis INFO for additional details (connections, memory).
+     *   In cluster mode, INFO may not be available and is silently ignored.
+     * - Measures latency of the PING command.
+     * - Updates the internal `lastStatus` and notifies all registered callbacks.
+     *
+     * **Returns:**
+     * - A {@link HealthStatus} object with the current health state.
+     *
+     * **Example:**
+     * ```ts
+     * const status = await health.check();
+     * console.log(status.healthy, status.latency);
+     * // healthy === true, latency === 1.2 (ms)
+     * ```
+     *
+     * **Parameters:**
+     * - None
+     *
+     * @returns Current health status.
+     */
     check(): Promise<HealthStatus>;
     /**
      * Returns the most recent health check result.
@@ -32,8 +113,68 @@ export declare class HealthChecker {
      * console.log(status?.healthy, status?.latency);
      * ```
      */
+    /**
+     * Returns the most recent health check result.
+     *
+     * **Returns:**
+     * - The last {@link HealthStatus}, or `null` before the first check.
+     *
+     * **Example:**
+     * ```ts
+     * const status = health.getStatus();
+     * console.log(status?.healthy, status?.latency);
+     * ```
+     *
+     * **Parameters:**
+     * - None
+     *
+     * @returns The last result, or `null`.
+     */
     getStatus(): HealthStatus | null;
+    /**
+     * Registers a callback for health status changes.
+     *
+     * **Behavior:**
+     * - The callback is invoked whenever a health check runs and the status changes.
+     * - Callbacks are invoked synchronously within the `check()` method.
+     * - Multiple callbacks can be registered; they are invoked in registration order.
+     *
+     * **Parameters:**
+     * - `callback` - A function receiving a {@link HealthStatus} object.
+     *
+     * @example
+     * ```ts
+     * health.onChange((status) => {
+     *   console.log(`Health status: ${status.status}, latency: ${status.latency}ms`);
+     * });
+     * ```
+     *
+     * @returns `void`
+     */
     onChange(callback: (status: HealthStatus) => void): void;
     private notifyCallbacks;
+    /**
+     * Waits until the Redis connection is healthy.
+     *
+     * **Behavior:**
+     * - Polls {@link check} at 1-second intervals.
+     * - Returns `true` as soon as `status.healthy` is `true`.
+     * - Returns `false` if the timeout is reached without becoming healthy.
+     *
+     * **Parameters:**
+     * - `timeout` - Maximum time to wait in milliseconds. Default: `30000` (30 seconds).
+     *
+     * **Returns:**
+     * - `true` if the connection became healthy within the timeout.
+     * - `false` if the timeout was reached without the connection becoming healthy.
+     *
+     * **Example:**
+     * ```ts
+     * const healthy = await health.waitForHealthy(10000);
+     * // healthy === true if Redis became healthy within 10 seconds
+     * ```
+     *
+     * @returns `true` if became healthy within timeout.
+     */
     waitForHealthy(timeout?: number): Promise<boolean>;
 }

package/dist/health.js

@@ -5,10 +5,44 @@ export class HealthChecker {
     timer = null;
     callbacks = [];
     lastStatus = null;
+    /**
+     * Creates a health checker instance.
+     *
+     * @param client - The underlying {@link RedisClientWrapper}.
+     * @param logger - Optional pino-compatible logger; defaults to `console`.
+     *
+     * @example
+     * ```ts
+     * const health = new HealthChecker(client);
+     * ```
+     */
     constructor(client, logger = defaultLogger) {
         this.client = client;
         this.logger = logger.child({ component: 'HealthChecker' });
     }
+    /**
+     * Starts periodic health checks.
+     *
+     * **Behavior:**
+     * - If a timer is already running, it is cleared and replaced with the new interval.
+     * - Health checks run at the specified `interval` in milliseconds.
+     * - Each check runs asynchronously; errors are logged but do not stop the interval.
+     * - The first check runs immediately when `start()` is called (depending on setInterval timing).
+     *
+     * **Parameters:**
+     * - `interval` - Check interval in milliseconds. Default: `10000` (10 seconds).
+     *
+     * @example
+     * ```ts
+     * // Check every 5 seconds
+     * health.start(5000);
+     *
+     * // Check every 30 seconds (default)
+     * health.start();
+     * ```
+     *
+     * @returns `void`
+     */
     start(interval = 10000) {
         if (this.timer) {
             clearInterval(this.timer);
@@ -20,6 +54,20 @@ export class HealthChecker {
         }, interval);
         this.logger.info(`Health checker started (interval: ${interval}ms)`);
     }
+    /**
+     * Stops the health checker.
+     *
+     * **Behavior:**
+     * - Clears the internal timer, stopping further health checks.
+     * - Logs a warning if no timer was active.
+     *
+     * @example
+     * ```ts
+     * health.stop();
+     * ```
+     *
+     * @returns `void`
+     */
     stop() {
         if (this.timer) {
             clearInterval(this.timer);
@@ -27,6 +75,31 @@ export class HealthChecker {
             this.logger.info('Health checker stopped');
         }
     }
+    /**
+     * Runs a single health check.
+     *
+     * **Behavior:**
+     * - Performs a PING command to verify Redis connectivity.
+     * - Attempts to fetch Redis INFO for additional details (connections, memory).
+     *   In cluster mode, INFO may not be available and is silently ignored.
+     * - Measures latency of the PING command.
+     * - Updates the internal `lastStatus` and notifies all registered callbacks.
+     *
+     * **Returns:**
+     * - A {@link HealthStatus} object with the current health state.
+     *
+     * **Example:**
+     * ```ts
+     * const status = await health.check();
+     * console.log(status.healthy, status.latency);
+     * // healthy === true, latency === 1.2 (ms)
+     * ```
+     *
+     * **Parameters:**
+     * - None
+     *
+     * @returns Current health status.
+     */
     async check() {
         const start = Date.now();
         const details = {
@@ -77,9 +150,46 @@ export class HealthChecker {
      * console.log(status?.healthy, status?.latency);
      * ```
      */
+    /**
+     * Returns the most recent health check result.
+     *
+     * **Returns:**
+     * - The last {@link HealthStatus}, or `null` before the first check.
+     *
+     * **Example:**
+     * ```ts
+     * const status = health.getStatus();
+     * console.log(status?.healthy, status?.latency);
+     * ```
+     *
+     * **Parameters:**
+     * - None
+     *
+     * @returns The last result, or `null`.
+     */
     getStatus() {
         return this.lastStatus;
     }
+    /**
+     * Registers a callback for health status changes.
+     *
+     * **Behavior:**
+     * - The callback is invoked whenever a health check runs and the status changes.
+     * - Callbacks are invoked synchronously within the `check()` method.
+     * - Multiple callbacks can be registered; they are invoked in registration order.
+     *
+     * **Parameters:**
+     * - `callback` - A function receiving a {@link HealthStatus} object.
+     *
+     * @example
+     * ```ts
+     * health.onChange((status) => {
+     *   console.log(`Health status: ${status.status}, latency: ${status.latency}ms`);
+     * });
+     * ```
+     *
+     * @returns `void`
+     */
     onChange(callback) {
         this.callbacks.push(callback);
     }
@@ -93,6 +203,29 @@ export class HealthChecker {
             }
         }
     }
+    /**
+     * Waits until the Redis connection is healthy.
+     *
+     * **Behavior:**
+     * - Polls {@link check} at 1-second intervals.
+     * - Returns `true` as soon as `status.healthy` is `true`.
+     * - Returns `false` if the timeout is reached without becoming healthy.
+     *
+     * **Parameters:**
+     * - `timeout` - Maximum time to wait in milliseconds. Default: `30000` (30 seconds).
+     *
+     * **Returns:**
+     * - `true` if the connection became healthy within the timeout.
+     * - `false` if the timeout was reached without the connection becoming healthy.
+     *
+     * **Example:**
+     * ```ts
+     * const healthy = await health.waitForHealthy(10000);
+     * // healthy === true if Redis became healthy within 10 seconds
+     * ```
+     *
+     * @returns `true` if became healthy within timeout.
+     */
     async waitForHealthy(timeout = 30000) {
         const start = Date.now();
         while (Date.now() - start < timeout) {