ioredis-toolkit 0.0.10 → 0.5.0

package/dist/cluster-slot.d.ts

@@ -1,4 +0,0 @@
-/** Extracts the Redis Cluster hash tag from a key. */
-export declare function hashTag(key: string): string;
-/** Returns the Redis Cluster hash slot for a key (0..16383). */
-export declare function calculateRedisClusterSlot(key: string): number;

package/dist/cluster-slot.js

@@ -1,31 +0,0 @@
-/** Redis Cluster uses CRC16-CCITT/XMODEM over the hash-tagged key bytes. */
-const CRC16_TABLE = (() => {
-    const table = new Uint16Array(256);
-    for (let i = 0; i < 256; i++) {
-        let crc = i << 8;
-        for (let bit = 0; bit < 8; bit++) {
-            crc = (crc & 0x8000) !== 0
-                ? ((crc << 1) ^ 0x1021) & 0xffff
-                : (crc << 1) & 0xffff;
-        }
-        table[i] = crc;
-    }
-    return table;
-})();
-/** Extracts the Redis Cluster hash tag from a key. */
-export function hashTag(key) {
-    const start = key.indexOf("{");
-    if (start < 0)
-        return key;
-    const end = key.indexOf("}", start + 1);
-    return end > start + 1 ? key.slice(start + 1, end) : key;
-}
-/** Returns the Redis Cluster hash slot for a key (0..16383). */
-export function calculateRedisClusterSlot(key) {
-    const bytes = Buffer.from(hashTag(key), "utf8");
-    let crc = 0;
-    for (const byte of bytes) {
-        crc = ((crc << 8) ^ CRC16_TABLE[((crc >>> 8) ^ byte) & 0xff]) & 0xffff;
-    }
-    return crc % 16384;
-}

package/dist/cluster.d.ts

@@ -1,79 +0,0 @@
-import type { RedisClientWrapper } from './client.js';
-/** A single queued pipeline command. */
-export interface PipelineCommand {
-    /** ioredis command name, e.g. `'get'`, `'del'`. */
-    command: string;
-    /** Arguments for the command (key first for routed commands). */
-    args: unknown[];
-    /** Slot for the key this command targets (computed by the caller). */
-    slot: number;
-}
-/** Result of one pipelined command: `[error, value]` like ioredis. */
-export type PipelineCommandResult = [Error | null, unknown];
-/** Options for {@link executeBySlot}. */
-export interface ExecuteBySlotOptions {
-    /**
-     * Maximum number of slot pipelines to run concurrently.
-     * Default: 8.
-     */
-    concurrency?: number;
-    /**
-     * When a whole slot pipeline fails at the network level (rejected promise,
-     * e.g. connection loss), how many times it may be retried before the error
-     * is reported per command. Command-level errors are never retried.
-     * Default: 1. Pass `false` to disable retries.
-     *
-     * Only safe for idempotent command batches; the caller decides.
-     */
-    retry?: number | false;
-}
-/**
- * Executes a batch of commands grouped by Redis hash slot.
- *
- * For every distinct slot the commands are collected into one pipeline and
- * executed on the node owning that slot. Pipelines run with bounded
- * concurrency (default 8 slots at a time) so a fan-out over many slots cannot
- * exhaust sockets or event-loop resources.
- *
- * Result ordering is preserved: the returned array mirrors the input array.
- * Command-level failures do NOT reject the whole call; each entry is reported
- * as `[error, null]` so callers can implement partial-failure handling.
- * Network-level pipeline failures are retried once per slot pipeline before
- * being reported per command.
- *
- * @param client - The Redis client wrapper.
- * @param commands - Commands to run, each with a resolved slot.
- * @param options - Concurrency and retry tuning.
- * @returns One result per input command, in input order.
- */
-export declare function executeBySlot(client: RedisClientWrapper, commands: PipelineCommand[], options?: ExecuteBySlotOptions): Promise<PipelineCommandResult[]>;
-/**
- * Inspects ioredis pipeline results and throws a structured error if any
- * command failed. Returns the values (without errors) on success.
- *
- * Pipeline `exec()` resolves with `[error, value][]` per command; a resolved
- * promise does NOT mean every command succeeded. Use this helper to enforce
- * command-level error handling.
- *
- * @param results - The `exec()` result array.
- * @param describe - Optional per-index description used in the error message
- *   (must not contain sensitive data).
- * @throws {Error} Listing the failed command indexes.
- */
-export declare function assertPipelineOk(results: PipelineCommandResult[] | null, describe?: (index: number) => string): unknown[];
-/**
- * Runs an async map over a list with bounded concurrency.
- *
- * Do NOT use `Promise.all(list.map(fn))` for cross-slot fan-out; use this to
- * keep the number of in-flight Redis operations bounded.
- *
- * @param items - Input list.
- * @param limit - Maximum concurrent workers.
- * @param fn - Async mapper.
- * @returns Results in input order.
- */
-export declare function mapWithConcurrency<T, R>(items: readonly T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
-/**
- * Chunks an array into bounded batches. Yields nothing for an empty array.
- */
-export declare function chunk<T>(items: readonly T[], size: number): Generator<T[]>;

package/dist/cluster.js

@@ -1,156 +0,0 @@
-/**
- * Executes a batch of commands grouped by Redis hash slot.
- *
- * For every distinct slot the commands are collected into one pipeline and
- * executed on the node owning that slot. Pipelines run with bounded
- * concurrency (default 8 slots at a time) so a fan-out over many slots cannot
- * exhaust sockets or event-loop resources.
- *
- * Result ordering is preserved: the returned array mirrors the input array.
- * Command-level failures do NOT reject the whole call; each entry is reported
- * as `[error, null]` so callers can implement partial-failure handling.
- * Network-level pipeline failures are retried once per slot pipeline before
- * being reported per command.
- *
- * @param client - The Redis client wrapper.
- * @param commands - Commands to run, each with a resolved slot.
- * @param options - Concurrency and retry tuning.
- * @returns One result per input command, in input order.
- */
-export async function executeBySlot(client, commands, options = {}) {
-    if (commands.length === 0)
-        return [];
-    const concurrency = Math.max(1, options.concurrency ?? 8);
-    const results = new Array(commands.length);
-    const missing = new Array(commands.length).fill(false);
-    // Group by slot, remembering the original indexes so ordering is preserved.
-    const groups = new Map();
-    for (let i = 0; i < commands.length; i++) {
-        const command = commands[i];
-        const group = groups.get(command.slot);
-        if (group) {
-            group.push({ index: i, command });
-        }
-        else {
-            groups.set(command.slot, [{ index: i, command }]);
-        }
-    }
-    const entries = Array.from(groups.entries());
-    // Bounded concurrency: run at most `concurrency` slot pipelines at once.
-    let cursor = 0;
-    const workers = Array.from({ length: Math.min(concurrency, entries.length) }, async () => {
-        while (cursor < entries.length) {
-            const [slot, group] = entries[cursor++];
-            await runSlotPipeline(client, slot, group, results, missing, options);
-        }
-    });
-    await Promise.all(workers);
-    for (let i = 0; i < missing.length; i++) {
-        if (missing[i]) {
-            results[i] = [new Error('Command did not produce a pipeline result'), null];
-        }
-    }
-    return results;
-}
-async function runSlotPipeline(client, slot, group, results, missing, options) {
-    const retries = options.retry === false ? 0 : Math.max(0, options.retry ?? 1);
-    let lastError = null;
-    for (let attempt = 0; attempt <= retries; attempt++) {
-        try {
-            const pipeline = client.pipeline();
-            for (const { command } of group) {
-                // `args` are formatted for the ioredis pipeline method signature.
-                const fn = pipeline[command.command];
-                fn.call(pipeline, ...command.args);
-            }
-            const raw = await pipeline.exec();
-            const resultsArray = Array.isArray(raw) ? raw : [];
-            for (let i = 0; i < group.length; i++) {
-                const item = group[i];
-                const result = resultsArray[i];
-                if (Array.isArray(result) && result.length === 2) {
-                    results[item.index] = result;
-                }
-                else {
-                    missing[item.index] = true;
-                }
-            }
-            return;
-        }
-        catch (error) {
-            lastError = error instanceof Error ? error : new Error(String(error));
-            // Network-level failure: retry the whole slot pipeline.
-        }
-    }
-    // All retries exhausted: report the network error on every command.
-    for (const item of group) {
-        results[item.index] = [lastError, null];
-    }
-}
-/**
- * Inspects ioredis pipeline results and throws a structured error if any
- * command failed. Returns the values (without errors) on success.
- *
- * Pipeline `exec()` resolves with `[error, value][]` per command; a resolved
- * promise does NOT mean every command succeeded. Use this helper to enforce
- * command-level error handling.
- *
- * @param results - The `exec()` result array.
- * @param describe - Optional per-index description used in the error message
- *   (must not contain sensitive data).
- * @throws {Error} Listing the failed command indexes.
- */
-export function assertPipelineOk(results, describe) {
-    if (!results) {
-        throw new Error('Pipeline returned no results (connection likely lost).');
-    }
-    const failures = [];
-    for (let i = 0; i < results.length; i++) {
-        const result = results[i];
-        const error = Array.isArray(result) ? result[0] : undefined;
-        if (error) {
-            const label = describe ? `"${describe(i)}"` : `index ${i}`;
-            failures.push(`${label}: ${error.message}`);
-        }
-    }
-    if (failures.length > 0) {
-        throw new Error(`Pipeline failed for ${failures.length} command(s): ${failures.join('; ')}`);
-    }
-    return results.map((r) => (Array.isArray(r) ? r[1] : undefined));
-}
-/**
- * Runs an async map over a list with bounded concurrency.
- *
- * Do NOT use `Promise.all(list.map(fn))` for cross-slot fan-out; use this to
- * keep the number of in-flight Redis operations bounded.
- *
- * @param items - Input list.
- * @param limit - Maximum concurrent workers.
- * @param fn - Async mapper.
- * @returns Results in input order.
- */
-export async function mapWithConcurrency(items, limit, fn) {
-    if (items.length === 0)
-        return [];
-    const concurrency = Math.max(1, limit);
-    const results = new Array(items.length);
-    let cursor = 0;
-    const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
-        while (cursor < items.length) {
-            const index = cursor++;
-            results[index] = await fn(items[index], index);
-        }
-    });
-    await Promise.all(workers);
-    return results;
-}
-/**
- * Chunks an array into bounded batches. Yields nothing for an empty array.
- */
-export function chunk(items, size) {
-    return (function* () {
-        for (let i = 0; i < items.length; i += size) {
-            yield items.slice(i, i + size);
-        }
-    })();
-}

package/dist/errors.d.ts

@@ -1,30 +0,0 @@
-export declare class RedisError extends Error {
-    code: string;
-    details?: Record<string, any>;
-    constructor(message: string, code?: string, details?: Record<string, any>);
-}
-export declare class ConnectionError extends RedisError {
-    constructor(message: string, details?: Record<string, any>);
-}
-export declare class TimeoutError extends RedisError {
-    constructor(message: string, details?: Record<string, any>);
-}
-/** Session referenced by a token no longer exists or has expired. */
-export declare class SessionExpiredError extends RedisError {
-    constructor(message: string, details?: Record<string, any>);
-}
-export declare class LockError extends RedisError {
-    constructor(message: string, details?: Record<string, any>);
-}
-export declare class SerializationError extends RedisError {
-    constructor(message: string, details?: Record<string, any>);
-}
-export declare class CompressionError extends RedisError {
-    constructor(message: string, details?: Record<string, any>);
-}
-export declare class ConfigurationError extends RedisError {
-    constructor(message: string, details?: Record<string, any>);
-}
-export declare class ClusterError extends RedisError {
-    constructor(message: string, details?: Record<string, any>);
-}

package/dist/errors.js

@@ -1,63 +0,0 @@
-export class RedisError extends Error {
-    code;
-    details;
-    constructor(message, code = 'UNKNOWN_ERROR', details) {
-        super(message);
-        this.name = 'RedisError';
-        this.code = code;
-        this.details = details;
-        // Maintains proper stack trace for where our error was thrown (only available on V8)
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, RedisError);
-        }
-    }
-}
-export class ConnectionError extends RedisError {
-    constructor(message, details) {
-        super(message, 'CONNECTION_ERROR', details);
-        this.name = 'ConnectionError';
-    }
-}
-export class TimeoutError extends RedisError {
-    constructor(message, details) {
-        super(message, 'TIMEOUT_ERROR', details);
-        this.name = 'TimeoutError';
-    }
-}
-/** Session referenced by a token no longer exists or has expired. */
-export class SessionExpiredError extends RedisError {
-    constructor(message, details) {
-        super(message, 'AUTH_SESSION_EXPIRED', details);
-        this.name = 'SessionExpiredError';
-    }
-}
-export class LockError extends RedisError {
-    constructor(message, details) {
-        super(message, 'LOCK_ERROR', details);
-        this.name = 'LockError';
-    }
-}
-export class SerializationError extends RedisError {
-    constructor(message, details) {
-        super(message, 'SERIALIZATION_ERROR', details);
-        this.name = 'SerializationError';
-    }
-}
-export class CompressionError extends RedisError {
-    constructor(message, details) {
-        super(message, 'COMPRESSION_ERROR', details);
-        this.name = 'CompressionError';
-    }
-}
-export class ConfigurationError extends RedisError {
-    constructor(message, details) {
-        super(message, 'CONFIGURATION_ERROR', details);
-        this.name = 'ConfigurationError';
-    }
-}
-export class ClusterError extends RedisError {
-    constructor(message, details) {
-        super(message, 'CLUSTER_ERROR', details);
-        this.name = 'ClusterError';
-    }
-}

package/dist/health.d.ts

@@ -1,180 +0,0 @@
-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;
-    };
-}
-export declare class HealthChecker {
-    private client;
-    private logger;
-    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.
-     *
-     * @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(): 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>;
-}