ioredis-toolkit 0.0.1

package/dist/cluster-slot.d.ts

@@ -0,0 +1,4 @@
+/** 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

@@ -0,0 +1,31 @@
+/** 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

@@ -0,0 +1,79 @@
+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

@@ -0,0 +1,156 @@
+/**
+ * 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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,63 @@
+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

@@ -0,0 +1,39 @@
+import { RedisClientWrapper } from './client.js';
+import { LoggerLike } from './logger.js';
+export interface HealthStatus {
+    healthy: boolean;
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    latency: number;
+    timestamp: Date;
+    details: {
+        ping: boolean;
+        connections?: number;
+        memory?: string;
+    };
+}
+export declare class HealthChecker {
+    private client;
+    private logger;
+    private timer;
+    private callbacks;
+    private lastStatus;
+    constructor(client: RedisClientWrapper, logger?: LoggerLike);
+    start(interval?: number): void;
+    stop(): void;
+    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);
+     * ```
+     */
+    getStatus(): HealthStatus | null;
+    onChange(callback: (status: HealthStatus) => void): void;
+    private notifyCallbacks;
+    waitForHealthy(timeout?: number): Promise<boolean>;
+}

package/dist/health.js

@@ -0,0 +1,106 @@
+import { defaultLogger } from './logger.js';
+export class HealthChecker {
+    client;
+    logger;
+    timer = null;
+    callbacks = [];
+    lastStatus = null;
+    constructor(client, logger = defaultLogger) {
+        this.client = client;
+        this.logger = logger.child({ component: 'HealthChecker' });
+    }
+    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)`);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.logger.info('Health checker stopped');
+        }
+    }
+    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);
+     * ```
+     */
+    getStatus() {
+        return this.lastStatus;
+    }
+    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);
+            }
+        }
+    }
+    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/index.d.ts

@@ -0,0 +1,51 @@
+export { RedisClientWrapper as RedisClient, createRedisClient } from './client.js';
+export type { RedisClientForMode, ClusterCapabilities } from './client.js';
+export { Cache } from './cache.js';
+export { PubSub } from './pubsub.js';
+export { DistributedLock } from './lock.js';
+export { HealthChecker } from './health.js';
+export { RateLimiter } from './ratelimiter.js';
+export type { RateLimitAlgorithm, RateLimitOptions, RateLimitResult } from './ratelimiter.js';
+export { createSessionManager } from './session/session-manager.js';
+export { SessionManager } from './session/session-manager.js';
+export type { SessionManagerOptions } from './session/session-manager.js';
+export { SessionService } from './session/session-service.js';
+export type { SessionServiceDeps } from './session/session-service.js';
+export { SessionRepository } from './session/session-repository.js';
+export { SessionKeyStrategy, encodeUserId } from './session/session-keys.js';
+export { SessionTokenManager } from './session/session-token.js';
+export { SessionMetrics } from './session/session-metrics.js';
+export type { SessionMetricsAdapter } from './session/session-metrics.js';
+export { SessionCircuitBreaker } from './session/session-circuit-breaker.js';
+export type { CircuitBreakerState } from './session/session-circuit-breaker.js';
+export { SessionHealthChecker } from './session/session-health.js';
+export type { SessionHealthStatus } from './session/session-health.js';
+export { SessionCookieManager, type SerializeCookieOptions, type SerializedCookie, type SerializedCookieAttributes, } from './session/session-cookie.js';
+export { parseSessionConfig, redactSessionConfig, TTL, IDLE_TIMEOUT, TOUCH_INTERVAL, } from './session/session-config.js';
+export type { SessionConfig, SessionConfigInput, PartialSessionConfig, } from './session/session-config.js';
+export { SessionError, SessionNotFoundError, SessionExpiredError, SessionRevokedError, SessionInvalidError, SessionRotationError, SessionReplayError, SessionStorageError, SessionSerializationError, SessionConfigurationError, SessionConcurrencyError, RevocationError, RevocationBatchError, CircuitBreakerOpenError, redactIdentifier, } from './session/session-errors.js';
+export { serializeSession, serializeEncryptedSession, deserializeSession, validateSessionRecord, envelopeKind, encryptedHeaderOf, assertHeaderMatches, } from './session/session-serializer.js';
+export { StaticSessionKeyProvider, createRandomSessionKeyProvider, toKeyBuffer, } from './session/session-encryption.js';
+export type { SessionKeyProvider } from './session/session-encryption.js';
+export type { SessionRecord, SessionCreateInput, SessionUpdatePatch, CreatedSession, RotatedSession, SessionValidationResult, SessionInvalidReason, TouchOutcome, SessionEnvelope, EncryptedSessionEnvelope, PlainSessionEnvelope, ListOptions, RotateOptions, TouchOptions, UpdateOptions, ValidateOptions, BindingMismatch, } from './session/session-types.js';
+export { RedisError } from './errors.js';
+export type { RedisConfig, RedisConfigInput, RedisCommonConfigInput, RedisMode, RedisNode, StandaloneRedisConfig, SentinelRedisConfig, ClusterRedisConfig, RedisConfigForMode, CacheOptions, LockOptions, LockInfo, DistributedLockOptions, HealthStatus, PubSubStats, PubSubMessage, ClusterInfo, ClusterSlotRange, ConnectionStatus, Redis } from './types.js';
+export { RedisConfigSchema } from './types.js';
+export { calculateRedisClusterSlot, hashTag } from './cluster-slot.js';
+export type { RedisConfig as RedisConfiguration } from './types.js';
+import { RedisClientWrapper as RedisClient, createRedisClient } from './client.js';
+import { Cache } from './cache.js';
+import { PubSub } from './pubsub.js';
+import { DistributedLock } from './lock.js';
+import { HealthChecker } from './health.js';
+import { RateLimiter } from './ratelimiter.js';
+declare const _default: {
+    RedisClient: typeof RedisClient;
+    createRedisClient: typeof createRedisClient;
+    Cache: typeof Cache;
+    PubSub: typeof PubSub;
+    DistributedLock: typeof DistributedLock;
+    HealthChecker: typeof HealthChecker;
+    RateLimiter: typeof RateLimiter;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,44 @@
+// Core exports
+export { RedisClientWrapper as RedisClient, createRedisClient } from './client.js';
+export { Cache } from './cache.js';
+export { PubSub } from './pubsub.js';
+export { DistributedLock } from './lock.js';
+export { HealthChecker } from './health.js';
+export { RateLimiter } from './ratelimiter.js';
+// Session subsystem (new API; the legacy stores remain exported via ./session)
+export { createSessionManager } from './session/session-manager.js';
+export { SessionManager } from './session/session-manager.js';
+export { SessionService } from './session/session-service.js';
+export { SessionRepository } from './session/session-repository.js';
+export { SessionKeyStrategy, encodeUserId } from './session/session-keys.js';
+export { SessionTokenManager } from './session/session-token.js';
+export { SessionMetrics } from './session/session-metrics.js';
+export { SessionCircuitBreaker } from './session/session-circuit-breaker.js';
+export { SessionHealthChecker } from './session/session-health.js';
+export { SessionCookieManager, } from './session/session-cookie.js';
+export { parseSessionConfig, redactSessionConfig, TTL, IDLE_TIMEOUT, TOUCH_INTERVAL, } from './session/session-config.js';
+export { SessionError, SessionNotFoundError, SessionExpiredError, SessionRevokedError, SessionInvalidError, SessionRotationError, SessionReplayError, SessionStorageError, SessionSerializationError, SessionConfigurationError, SessionConcurrencyError, RevocationError, RevocationBatchError, CircuitBreakerOpenError, redactIdentifier, } from './session/session-errors.js';
+export { serializeSession, serializeEncryptedSession, deserializeSession, validateSessionRecord, envelopeKind, encryptedHeaderOf, assertHeaderMatches, } from './session/session-serializer.js';
+export { StaticSessionKeyProvider, createRandomSessionKeyProvider, toKeyBuffer, } from './session/session-encryption.js';
+// Re-export logger types for convenience
+// Error exports
+export { RedisError } from './errors.js';
+// Zod schema
+export { RedisConfigSchema } from './types.js';
+export { calculateRedisClusterSlot, hashTag } from './cluster-slot.js';
+// Default export
+import { RedisClientWrapper as RedisClient, createRedisClient } from './client.js';
+import { Cache } from './cache.js';
+import { PubSub } from './pubsub.js';
+import { DistributedLock } from './lock.js';
+import { HealthChecker } from './health.js';
+import { RateLimiter } from './ratelimiter.js';
+export default {
+    RedisClient,
+    createRedisClient,
+    Cache,
+    PubSub,
+    DistributedLock,
+    HealthChecker,
+    RateLimiter,
+};