ioredis-toolkit 0.0.9 → 0.5.0

package/dist/lock.js

@@ -1,397 +0,0 @@
-import { RedisError } from './errors.js';
-import { randomBytes } from 'node:crypto';
-import { defaultLogger } from './logger.js';
-/**
- * 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 class DistributedLock {
-    client;
-    logger;
-    defaultTTL;
-    defaultRetryCount;
-    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, logger = defaultLogger, options = {}) {
-        this.client = client;
-        this.logger = logger.child({ component: 'DistributedLock' });
-        this.defaultTTL = options.ttl || 30000;
-        this.defaultRetryCount = options.retryCount || 3;
-        this.defaultRetryDelay = options.retryDelay || 200;
-    }
-    getLockKey(key) {
-        return `lock:${key}`;
-    }
-    generateLockId() {
-        return randomBytes(16).toString('hex');
-    }
-    async executeWithRetry(fn, retryCount = this.defaultRetryCount, retryDelay = this.defaultRetryDelay) {
-        let lastError = null;
-        for (let i = 0; i < retryCount; i++) {
-            try {
-                return await fn();
-            }
-            catch (error) {
-                lastError = error;
-                if (i < retryCount - 1) {
-                    const delay = retryDelay * Math.pow(2, i) * (0.5 + Math.random() * 0.5);
-                    await new Promise(resolve => setTimeout(resolve, delay));
-                }
-            }
-        }
-        throw lastError || new Error('Retry failed');
-    }
-    /**
-     * 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
-     * ```
-     */
-    async acquire(key, ttl = this.defaultTTL) {
-        const lockKey = this.getLockKey(key);
-        const lockId = this.generateLockId();
-        return this.executeWithRetry(async () => {
-            // Using SET with PX and NX for atomic lock acquisition
-            const result = await this.client.raw.set(lockKey, lockId, 'PX', ttl, 'NX');
-            return result === 'OK';
-        });
-    }
-    /**
-     * 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');
-     * ```
-     */
-    async release(key) {
-        const lockKey = this.getLockKey(key);
-        try {
-            // Use Lua script for atomic check-and-delete
-            const script = `
-        if redis.call('get', KEYS[1]) == ARGV[1] then
-          return redis.call('del', KEYS[1])
-        else
-          return 0
-        end
-      `;
-            const lockId = await this.client.raw.get(lockKey);
-            if (!lockId) {
-                this.logger.warn('Lock not found for release', { key });
-                return false;
-            }
-            const result = await this.client.raw.eval(script, 1, lockKey, lockId);
-            return result === 1;
-        }
-        catch (error) {
-            this.logger.error('Failed to release lock', { key, error });
-            return false;
-        }
-    }
-    /**
-     * 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');
-     * ```
-     */
-    async releaseForce(key) {
-        const lockKey = this.getLockKey(key);
-        const result = await this.client.raw.del(lockKey);
-        return result === 1;
-    }
-    /**
-     * 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
-     * ```
-     */
-    async extend(key, ttl = this.defaultTTL) {
-        const lockKey = this.getLockKey(key);
-        const script = `
-      if redis.call('get', KEYS[1]) == ARGV[1] then
-        return redis.call('pexpire', KEYS[1], ARGV[2])
-      else
-        return 0
-      end
-    `;
-        try {
-            const lockId = await this.client.raw.get(lockKey);
-            if (!lockId) {
-                return false;
-            }
-            const result = await this.client.raw.eval(script, 1, lockKey, lockId, ttl);
-            return result === 1;
-        }
-        catch (error) {
-            this.logger.error('Failed to extend lock', { key, error });
-            return false;
-        }
-    }
-    /**
-     * 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();
-     * });
-     * ```
-     */
-    async withLock(key, fn, options = {}) {
-        const ttl = options.ttl || this.defaultTTL;
-        const retryCount = options.retryCount || this.defaultRetryCount;
-        const retryDelay = options.retryDelay || this.defaultRetryDelay;
-        // Try to acquire the lock with retries
-        const acquired = await this.acquire(key, ttl);
-        if (!acquired) {
-            throw new RedisError(`Failed to acquire lock for key: ${key} after ${retryCount} attempts`, 'LOCK_ACQUISITION_FAILED');
-        }
-        let extensionTimer = null;
-        let lockRenewed = true;
-        try {
-            // Start auto-extension timer at half TTL
-            const extendInterval = Math.floor(ttl / 2);
-            let isExtending = false;
-            const extendLock = async () => {
-                if (isExtending || !lockRenewed)
-                    return;
-                isExtending = true;
-                try {
-                    const extended = await this.extend(key, ttl);
-                    if (!extended) {
-                        lockRenewed = false;
-                        this.logger.warn('Lock extension failed', { key });
-                    }
-                }
-                catch (error) {
-                    this.logger.error('Lock extension error', { key, error });
-                    lockRenewed = false;
-                }
-                finally {
-                    isExtending = false;
-                }
-            };
-            // Schedule auto-extension
-            extensionTimer = setInterval(() => {
-                extendLock().catch((error) => {
-                    this.logger.error('Extension interval error', { key, error });
-                });
-            }, extendInterval);
-            // Execute the function
-            const result = await fn();
-            // Check if lock was maintained during execution
-            if (!lockRenewed) {
-                throw new RedisError(`Lock was lost during execution for key: ${key}`, 'LOCK_LOST');
-            }
-            return result;
-        }
-        catch (error) {
-            this.logger.error('Error in locked operation', { key, error });
-            throw error;
-        }
-        finally {
-            // Clean up extension timer
-            if (extensionTimer) {
-                clearInterval(extensionTimer);
-                extensionTimer = null;
-            }
-            // Release the lock
-            try {
-                await this.release(key);
-            }
-            catch (releaseError) {
-                this.logger.error('Failed to release lock', { key, releaseError });
-                try {
-                    await this.releaseForce(key);
-                }
-                catch (forceError) {
-                    this.logger.error('Failed to force release lock', { key, forceError });
-                }
-            }
-        }
-    }
-    /**
-     * 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');
-     * ```
-     */
-    async isLocked(key) {
-        const lockKey = this.getLockKey(key);
-        const exists = await this.client.raw.exists(lockKey);
-        return exists === 1;
-    }
-    /**
-     * 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...' }
-     * ```
-     */
-    async getLockInfo(key) {
-        const lockKey = this.getLockKey(key);
-        const exists = await this.client.raw.exists(lockKey);
-        if (!exists) {
-            return { locked: false };
-        }
-        const [lockId, ttl] = await Promise.all([
-            this.client.raw.get(lockKey),
-            this.client.raw.ttl(lockKey),
-        ]);
-        // Build the result object with proper undefined handling
-        const result = { locked: true };
-        if (lockId !== null && lockId !== undefined) {
-            result.lockId = lockId;
-        }
-        if (ttl !== null && ttl !== undefined && ttl > 0) {
-            result.ttl = ttl;
-        }
-        return result;
-    }
-    /**
-     * 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');
-     * ```
-     */
-    async getLockOwner(key) {
-        const lockKey = this.getLockKey(key);
-        return this.client.raw.get(lockKey);
-    }
-    /**
-     * 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');
-     * ```
-     */
-    async getLockTTL(key) {
-        const lockKey = this.getLockKey(key);
-        const ttl = await this.client.raw.ttl(lockKey);
-        return ttl > 0 ? ttl : 0;
-    }
-    // Clean up all locks (for testing or emergency)
-    /**
-     * 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();
-     * ```
-     */
-    async cleanupAll() {
-        let deleted = 0;
-        for await (const key of this.client.scanIterator('lock:*')) {
-            const result = await this.client.raw.del(key);
-            deleted += result;
-        }
-        return deleted;
-    }
-}

package/dist/logger.d.ts

@@ -1,12 +0,0 @@
-export type LogMeta = Record<string, unknown>;
-export interface LoggerLike {
-    trace(message: string, meta?: LogMeta): void;
-    debug(message: string, meta?: LogMeta): void;
-    info(message: string, meta?: LogMeta): void;
-    warn(message: string, meta?: LogMeta): void;
-    error(message: string, meta?: LogMeta): void;
-    fatal(message: string, meta?: LogMeta): void;
-    child(bindings: LogMeta): LoggerLike;
-}
-export declare const defaultLogger: LoggerLike;
-export declare function createConsoleLogger(bindings?: LogMeta): LoggerLike;

package/dist/logger.js

@@ -1,40 +0,0 @@
-function mergeMeta(bindings, meta) {
-    return {
-        ...bindings,
-        ...(meta ?? {}),
-    };
-}
-class ConsoleLogger {
-    bindings;
-    constructor(bindings = {}) {
-        this.bindings = bindings;
-    }
-    trace(message, meta) {
-        console.trace(message, mergeMeta(this.bindings, meta));
-    }
-    debug(message, meta) {
-        console.debug(message, mergeMeta(this.bindings, meta));
-    }
-    info(message, meta) {
-        console.info(message, mergeMeta(this.bindings, meta));
-    }
-    warn(message, meta) {
-        console.warn(message, mergeMeta(this.bindings, meta));
-    }
-    error(message, meta) {
-        console.error(message, mergeMeta(this.bindings, meta));
-    }
-    fatal(message, meta) {
-        console.error(message, mergeMeta(this.bindings, meta));
-    }
-    child(bindings) {
-        return new ConsoleLogger({
-            ...this.bindings,
-            ...bindings,
-        });
-    }
-}
-export const defaultLogger = new ConsoleLogger();
-export function createConsoleLogger(bindings) {
-    return new ConsoleLogger(bindings);
-}