ioredis-toolkit 0.0.9 → 0.5.0

package/dist/health.js

@@ -1,239 +0,0 @@
-import { defaultLogger } from './logger.js';
-export class HealthChecker {
-    client;
-    logger;
-    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);
-        }
-        this.timer = setInterval(() => {
-            this.check().catch((error) => {
-                this.logger.error('Health check failed:', error);
-            });
-        }, 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);
-            this.timer = null;
-            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 = {
-            ping: false,
-        };
-        try {
-            const ping = await this.client.ping();
-            details.ping = ping;
-            // Try to get some info
-            try {
-                const info = await this.client.raw.info();
-                const connections = info.match(/connected_clients:(\d+)/)?.[1];
-                const memory = info.match(/used_memory_human:([^\n]+)/)?.[1];
-                if (connections)
-                    details.connections = parseInt(connections, 10);
-                if (memory)
-                    details.memory = memory.trim();
-            }
-            catch {
-                // Info not available in cluster mode
-            }
-        }
-        catch (error) {
-            this.logger.error('Health check error:', error);
-            details.ping = false;
-        }
-        const latency = Date.now() - start;
-        const healthy = details.ping;
-        const status = {
-            healthy,
-            status: healthy ? 'healthy' : 'unhealthy',
-            latency,
-            timestamp: new Date(),
-            details,
-        };
-        this.lastStatus = status;
-        this.notifyCallbacks(status);
-        return status;
-    }
-    /**
-     * 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);
-     * ```
-     */
-    /**
-     * 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);
-    }
-    notifyCallbacks(status) {
-        for (const callback of this.callbacks) {
-            try {
-                callback(status);
-            }
-            catch (error) {
-                this.logger.error('Callback error:', error);
-            }
-        }
-    }
-    /**
-     * 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) {
-            const status = await this.check();
-            if (status.healthy)
-                return true;
-            await new Promise(resolve => setTimeout(resolve, 1000));
-        }
-        return false;
-    }
-}

package/dist/lock.d.ts

@@ -1,248 +0,0 @@
-import { RedisClientWrapper } from './client.js';
-import { LoggerLike } from './logger.js';
-/**
- * Information about a distributed lock.
- *
- * **Fields:**
- * - `locked`: Whether the lock is currently held.
- * - `ttl`: Remaining TTL in seconds (when held and TTL set).
- * - `lockId`: Unique owner id of the lock.
- *
- * **Example:**
- * ```ts
- * const info = await lock.getLockInfo('order:42');
- * // { locked: true, ttl: 29, lockId: 'a1b2c3...' }
- * ```
- */
-export type LockInfo = {
-    /** Whether the lock is currently held. */
-    locked: boolean;
-    /** Remaining TTL in seconds (when held and TTL set). */
-    ttl?: number;
-    /** Unique owner id of the lock. */
-    lockId?: string;
-};
-/**
- * Options for the distributed lock.
- *
- * **Fields:**
- * - `ttl`: Lock TTL in milliseconds. Default: `30000`.
- * - `retryCount`: Number of acquisition attempts. Default: `3`.
- * - `retryDelay`: Base delay between retries in ms (grows exponentially). Default: `200`.
- *
- * **Example:**
- * ```ts
- * const lock = new DistributedLock(client, { ttl: 10000, retryCount: 5 });
- * ```
- */
-export interface DistributedLockOptions {
-    /** Lock TTL in milliseconds. Default: `30000`. */
-    ttl?: number;
-    /** Number of acquisition attempts. Default: `3`. */
-    retryCount?: number;
-    /** Base delay between retries in ms (grows exponentially). Default: `200`. */
-    retryDelay?: number;
-}
-/**
- * Distributed mutual-exclusion lock 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. `withLock` auto-extends the lock at half TTL while the
- * critical section runs and always releases afterwards.
- *
- * @example
- * ```ts
- * const lock = new DistributedLock(client, { ttl: 30000, retryCount: 5 });
- * const acquired = await lock.acquire('order:42');
- * if (acquired) {
- *   try {
- *     // critical section
- *   } finally {
- *     await lock.release('order:42');
- *   }
- * }
- * ```
- */
-export declare class DistributedLock {
-    private client;
-    private logger;
-    private defaultTTL;
-    private defaultRetryCount;
-    private defaultRetryDelay;
-    /**
-     * Creates a distributed lock bound to a Redis client.
-     *
-     * @param client - The underlying {@link RedisClientWrapper}.
-     * @param logger - Optional pino-compatible logger; defaults to `console`.
-     * @param options - Defaults for `ttl` (ms), `retryCount` and `retryDelay`.
-     *
-     * @example
-     * ```ts
-     * const lock = new DistributedLock(client, { ttl: 10000, retryCount: 3 });
-     * ```
-     */
-    constructor(client: RedisClientWrapper, logger?: LoggerLike, options?: Partial<DistributedLockOptions>);
-    private getLockKey;
-    private generateLockId;
-    private executeWithRetry;
-    /**
-     * Attempts to acquire the lock for a key.
-     *
-     * Uses atomic `SET lock:<key> <id> PX <ttl> NX` with exponential backoff
-     * retries. Locks expire automatically after `ttl` ms, so a crashed holder
-     * never blocks others forever.
-     *
-     * @param key - The resource to lock, e.g. `'order:42'` (stored as `lock:order:42`).
-     * @param ttl - Lock TTL in milliseconds (default: `30000`).
-     *
-     * @returns `true` when the lock was acquired.
-     *
-     * @example
-     * ```ts
-     * const acquired = await lock.acquire('order:42', 10000);
-     * // acquired === true when lock was successfully acquired
-     * ```
-     */
-    acquire(key: string, ttl?: number): Promise<boolean>;
-    /**
-     * Releases the lock, but only if this process still owns it.
-     *
-     * Uses an atomic Lua check-and-delete so a lock whose TTL expired (and was
-     * re-acquired by someone else) is never removed by the old owner.
-     *
-     * @param key - The locked resource.
-     *
-     * @returns `true` if the lock was released, `false` if not owned or missing.
-     *
-     * @example
-     * ```ts
-     * await lock.release('order:42');
-     * ```
-     */
-    release(key: string): Promise<boolean>;
-    /**
-     * Force-releases a lock without checking ownership.
-     *
-     * Use with care: only for emergency cleanup or when the holder is known to
-     * be gone. This is what `withLock` falls back to when a normal release fails.
-     *
-     * @param key - The locked resource.
-     *
-     * @returns `true` if a lock existed and was deleted.
-     *
-     * @example
-     * ```ts
-     * await lock.releaseForce('order:42');
-     * ```
-     */
-    releaseForce(key: string): Promise<boolean>;
-    /**
-     * Extends the TTL of a lock this process still owns.
-     *
-     * Uses an atomic Lua script so a re-acquired lock is never extended by the
-     * old owner.
-     *
-     * @param key - The locked resource.
-     * @param ttl - New TTL in milliseconds (default: `30000`).
-     *
-     * @returns `true` if the lock was extended.
-     *
-     * @example
-     * ```ts
-     * const extended = await lock.extend('order:42', 30000);
-     * // extended === true when lock TTL was renewed
-     * ```
-     */
-    extend(key: string, ttl?: number): Promise<boolean>;
-    /**
-     * Runs a critical section while holding a lock.
-     *
-     * Acquires the lock (with retries), auto-extends it at half TTL while `fn`
-     * runs, detects a lost lock, and always releases afterwards (force-releasing
-     * if a normal release fails).
-     *
-     * @param key - The resource to lock.
-     * @param fn - The critical section to run exclusively.
-     * @param options - Per-call `ttl` (ms), `retryCount`, `retryDelay`.
-     *
-     * @returns The return value of `fn`.
-     *
-     * @throws {@link RedisError} with code `LOCK_ACQUISITION_FAILED` when the lock
-     *   cannot be acquired, or `LOCK_LOST` when the lock expired mid-execution.
-     *
-     * @example
-     * ```ts
-     * const result = await lock.withLock('inventory:sku-1', async () => {
-     *   return await updateStock();
-     * });
-     * ```
-     */
-    withLock<T>(key: string, fn: () => Promise<T>, options?: DistributedLockOptions): Promise<T>;
-    /**
-     * Checks whether a lock is currently held.
-     *
-     * @param key - The locked resource.
-     *
-     * @returns `true` if the lock exists (held by anyone).
-     *
-     * @example
-     * ```ts
-     * const busy = await lock.isLocked('order:42');
-     * ```
-     */
-    isLocked(key: string): Promise<boolean>;
-    /**
-     * Returns details about a lock.
-     *
-     * @param key - The locked resource.
-     *
-     * @returns `{ locked: false }` when not held, otherwise `{ locked: true, ttl, lockId }`.
-     *
-     * @example
-     * ```ts
-     * const info = await lock.getLockInfo('order:42');
-     * // { locked: true, ttl: 29, lockId: 'a1b2c3...' }
-     * ```
-     */
-    getLockInfo(key: string): Promise<LockInfo>;
-    /**
-     * Returns the owner id of a lock.
-     *
-     * @param key - The locked resource.
-     *
-     * @returns The lock id (random hex token), or `null` when not held.
-     *
-     * @example
-     * ```ts
-     * const owner = await lock.getLockOwner('order:42');
-     * ```
-     */
-    getLockOwner(key: string): Promise<string | null>;
-    /**
-     * Returns the remaining TTL of a lock in seconds.
-     *
-     * @param key - The locked resource.
-     *
-     * @returns Remaining seconds (`0` when not held or expired).
-     *
-     * @example
-     * ```ts
-     * const remaining = await lock.getLockTTL('order:42');
-     * ```
-     */
-    getLockTTL(key: string): Promise<number>;
-    /**
-     * Deletes every lock key (`lock:*`) from Redis.
-     *
-     * Intended for tests and emergency recovery only.
-     *
-     * @returns The number of deleted locks.
-     *
-     * @example
-     * ```ts
-     * const removed = await lock.cleanupAll();
-     * ```
-     */
-    cleanupAll(): Promise<number>;
-}