ioredis 5.8.2 → 5.9.0

package/README.md

@@ -21,7 +21,7 @@ ioredis is a stable project and maintenance is done on a best-effort basis for r
 ioredis is a robust, full-featured Redis client that is
 used in the world's biggest online commerce company [Alibaba](http://www.alibaba.com/) and many other awesome companies.
 
-0. Full-featured. It supports [Cluster](http://redis.io/topics/cluster-tutorial), [Sentinel](https://redis.io/docs/reference/sentinel-clients), [Streams](https://redis.io/topics/streams-intro), [Pipelining](http://redis.io/topics/pipelining), and of course [Lua scripting](http://redis.io/commands/eval), [Redis Functions](https://redis.io/topics/functions-intro), [Pub/Sub](http://redis.io/topics/pubsub) (with the support of binary messages).
+0. Full-featured. It supports [Cluster](http://redis.io/topics/cluster-tutorial), [Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/), [Streams](https://redis.io/topics/streams-intro), [Pipelining](http://redis.io/topics/pipelining), and of course [Lua scripting](http://redis.io/commands/eval), [Redis Functions](https://redis.io/topics/functions-intro), [Pub/Sub](http://redis.io/topics/pubsub) (with the support of binary messages).
 1. High performance 🚀.
 2. Delightful API 😄. It works with Node callbacks and Native promises.
 3. Transformation of command arguments and replies.
@@ -798,6 +798,20 @@ const redis = new Redis({
 
 Set maxRetriesPerRequest to `null` to disable this behavior, and every command will wait forever until the connection is alive again (which is the default behavior before ioredis v4).
 
+### Blocking Command Timeout
+
+ioredis can apply a client-side timeout to blocking commands (such as `blpop`, `brpop`, `bzpopmin`, `bzmpop`, `blmpop`, `xread`, `xreadgroup`, etc.). This protects against scenarios where the TCP connection becomes a zombie (e.g., due to a silent network failure like a Docker network disconnect) and Redis never replies.
+
+For commands with a finite timeout (e.g., `blpop("key", 5)`), ioredis automatically sets a client-side deadline based on the command's timeout plus a small grace period. If no reply arrives before the deadline, the command resolves with `null`—the same value Redis returns when a blocking command times out normally.
+
+For commands that intentionally block forever (e.g., `timeout = 0` or `BLOCK 0`), you can provide a safety net via the optional `blockingTimeout` option (milliseconds):
+
+```javascript
+const redis = new Redis({
+  blockingTimeout: 30000, // Resolve with null after 30 seconds when timeout=0/BLOCK 0
+});
+```
+
 ### Reconnect on Error
 
 Besides auto-reconnect when the connection is closed, ioredis supports reconnecting on certain Redis errors using the `reconnectOnError` option. Here's an example that will reconnect when receiving `READONLY` error:
@@ -1213,7 +1227,7 @@ cluster.on("smessage", (channel, message) => {
     console.log(message);
 });
 
-        
+
 //Subscribe to the channels on the same slot
 cluster.ssubscribe("channel{my}:1", "channel{my}:2").then( ( count: number ) => {
     console.log(count);

package/built/Command.d.ts

@@ -32,6 +32,28 @@ export interface CommandNameFlags {
     WILL_DISCONNECT: ["quit"];
     HANDSHAKE_COMMANDS: ["auth", "select", "client", "readonly", "info"];
     IGNORE_RECONNECT_ON_ERROR: ["client"];
+    BLOCKING_COMMANDS: [
+        "blpop",
+        "brpop",
+        "brpoplpush",
+        "blmove",
+        "bzpopmin",
+        "bzpopmax",
+        "bzmpop",
+        "blmpop",
+        "xread",
+        "xreadgroup"
+    ];
+    LAST_ARG_TIMEOUT_COMMANDS: [
+        "blpop",
+        "brpop",
+        "brpoplpush",
+        "blmove",
+        "bzpopmin",
+        "bzpopmax"
+    ];
+    FIRST_ARG_TIMEOUT_COMMANDS: ["bzmpop", "blmpop"];
+    BLOCK_OPTION_COMMANDS: ["xread", "xreadgroup"];
 }
 /**
  * Command instance
@@ -82,6 +104,8 @@ export default class Command implements Respondable {
     private callback;
     private transformed;
     private _commandTimeoutTimer?;
+    private _blockingTimeoutTimer?;
+    private _blockingDeadline?;
     private slot?;
     private keys?;
     /**
@@ -110,6 +134,24 @@ export default class Command implements Respondable {
      * and generating an error.
      */
     setTimeout(ms: number): void;
+    /**
+     * Set a timeout for blocking commands.
+     * When the timeout expires, the command resolves with null (matching Redis behavior).
+     * This handles the case of undetectable network failures (e.g., docker network disconnect)
+     * where the TCP connection becomes a zombie and no close event fires.
+     */
+    setBlockingTimeout(ms: number): void;
+    /**
+     * Extract the blocking timeout from the command arguments.
+     *
+     * @returns The timeout in seconds, null for indefinite blocking (timeout of 0),
+     *          or undefined if this is not a blocking command
+     */
+    extractBlockingTimeout(): number | null | undefined;
+    /**
+     * Clear the command and blocking timers
+     */
+    private _clearTimers;
     private initPromise;
     /**
      * Iterate through the command arguments that are considered keys.

package/built/Command.js

@@ -4,6 +4,7 @@ const commands_1 = require("@ioredis/commands");
 const calculateSlot = require("cluster-key-slot");
 const standard_as_callback_1 = require("standard-as-callback");
 const utils_1 = require("./utils");
+const argumentParsers_1 = require("./utils/argumentParsers");
 /**
  * Command instance
  *
@@ -72,6 +73,7 @@ class Command {
      * Check whether the command has the flag
      */
     static checkFlag(flagName, commandName) {
+        commandName = commandName.toLowerCase();
         return !!this.getFlagMap()[flagName][commandName];
     }
     static setArgumentTransformer(name, func) {
@@ -194,6 +196,81 @@ class Command {
             }, ms);
         }
     }
+    /**
+     * Set a timeout for blocking commands.
+     * When the timeout expires, the command resolves with null (matching Redis behavior).
+     * This handles the case of undetectable network failures (e.g., docker network disconnect)
+     * where the TCP connection becomes a zombie and no close event fires.
+     */
+    setBlockingTimeout(ms) {
+        if (ms <= 0) {
+            return;
+        }
+        // Clear existing timer if any (can happen when command moves from offline to command queue)
+        if (this._blockingTimeoutTimer) {
+            clearTimeout(this._blockingTimeoutTimer);
+            this._blockingTimeoutTimer = undefined;
+        }
+        const now = Date.now();
+        // First call: establish absolute deadline
+        if (this._blockingDeadline === undefined) {
+            this._blockingDeadline = now + ms;
+        }
+        // Check if we've already exceeded the deadline
+        const remaining = this._blockingDeadline - now;
+        if (remaining <= 0) {
+            // Resolve with null to indicate timeout (same as Redis behavior)
+            this.resolve(null);
+            return;
+        }
+        this._blockingTimeoutTimer = setTimeout(() => {
+            if (this.isResolved) {
+                this._blockingTimeoutTimer = undefined;
+                return;
+            }
+            this._blockingTimeoutTimer = undefined;
+            // Timeout expired - resolve with null (same as Redis behavior when blocking command times out)
+            this.resolve(null);
+        }, remaining);
+    }
+    /**
+     * Extract the blocking timeout from the command arguments.
+     *
+     * @returns The timeout in seconds, null for indefinite blocking (timeout of 0),
+     *          or undefined if this is not a blocking command
+     */
+    extractBlockingTimeout() {
+        const args = this.args;
+        if (!args || args.length === 0) {
+            return undefined;
+        }
+        const name = this.name.toLowerCase();
+        if (Command.checkFlag("LAST_ARG_TIMEOUT_COMMANDS", name)) {
+            return (0, argumentParsers_1.parseSecondsArgument)(args[args.length - 1]);
+        }
+        if (Command.checkFlag("FIRST_ARG_TIMEOUT_COMMANDS", name)) {
+            return (0, argumentParsers_1.parseSecondsArgument)(args[0]);
+        }
+        if (Command.checkFlag("BLOCK_OPTION_COMMANDS", name)) {
+            return (0, argumentParsers_1.parseBlockOption)(args);
+        }
+        return undefined;
+    }
+    /**
+     * Clear the command and blocking timers
+     */
+    _clearTimers() {
+        const existingTimer = this._commandTimeoutTimer;
+        if (existingTimer) {
+            clearTimeout(existingTimer);
+            delete this._commandTimeoutTimer;
+        }
+        const blockingTimer = this._blockingTimeoutTimer;
+        if (blockingTimer) {
+            clearTimeout(blockingTimer);
+            delete this._blockingTimeoutTimer;
+        }
+    }
     initPromise() {
         const promise = new Promise((resolve, reject) => {
             if (!this.transformed) {
@@ -205,14 +282,15 @@ class Command {
                 this.stringifyArguments();
             }
             this.resolve = this._convertValue(resolve);
-            if (this.errorStack) {
-                this.reject = (err) => {
+            this.reject = (err) => {
+                this._clearTimers();
+                if (this.errorStack) {
                     reject((0, utils_1.optimizeErrorStack)(err, this.errorStack.stack, __dirname));
-                };
-            }
-            else {
-                this.reject = reject;
-            }
+                }
+                else {
+                    reject(err);
+                }
+            };
         });
         this.promise = (0, standard_as_callback_1.default)(promise, this.callback);
     }
@@ -222,9 +300,11 @@ class Command {
     _iterateKeys(transform = (key) => key) {
         if (typeof this.keys === "undefined") {
             this.keys = [];
-            if ((0, commands_1.exists)(this.name)) {
+            if ((0, commands_1.exists)(this.name, { caseInsensitive: true })) {
                 // @ts-expect-error
-                const keyIndexes = (0, commands_1.getKeyIndexes)(this.name, this.args);
+                const keyIndexes = (0, commands_1.getKeyIndexes)(this.name, this.args, {
+                    nameCaseInsensitive: true,
+                });
                 for (const index of keyIndexes) {
                     this.args[index] = transform(this.args[index]);
                     this.keys.push(this.args[index]);
@@ -239,11 +319,7 @@ class Command {
     _convertValue(resolve) {
         return (value) => {
             try {
-                const existingTimer = this._commandTimeoutTimer;
-                if (existingTimer) {
-                    clearTimeout(existingTimer);
-                    delete this._commandTimeoutTimer;
-                }
+                this._clearTimers();
                 resolve(this.transformReply(value));
                 this.isResolved = true;
             }
@@ -272,6 +348,28 @@ Command.FLAGS = {
     WILL_DISCONNECT: ["quit"],
     HANDSHAKE_COMMANDS: ["auth", "select", "client", "readonly", "info"],
     IGNORE_RECONNECT_ON_ERROR: ["client"],
+    BLOCKING_COMMANDS: [
+        "blpop",
+        "brpop",
+        "brpoplpush",
+        "blmove",
+        "bzpopmin",
+        "bzpopmax",
+        "bzmpop",
+        "blmpop",
+        "xread",
+        "xreadgroup",
+    ],
+    LAST_ARG_TIMEOUT_COMMANDS: [
+        "blpop",
+        "brpop",
+        "brpoplpush",
+        "blmove",
+        "bzpopmin",
+        "bzpopmax",
+    ],
+    FIRST_ARG_TIMEOUT_COMMANDS: ["bzmpop", "blmpop"],
+    BLOCK_OPTION_COMMANDS: ["xread", "xreadgroup"],
 };
 Command._transformer = {
     argument: {},

package/built/Pipeline.js

@@ -101,7 +101,8 @@ class Pipeline extends Commander_1.default {
                     }
                 }
                 else if (!command.inTransaction) {
-                    const isReadOnly = (0, commands_1.exists)(command.name) && (0, commands_1.hasFlag)(command.name, "readonly");
+                    const isReadOnly = (0, commands_1.exists)(command.name, { caseInsensitive: true }) &&
+                        (0, commands_1.hasFlag)(command.name, "readonly", { nameCaseInsensitive: true });
                     if (!isReadOnly) {
                         retriable = false;
                         break;

package/built/Redis.d.ts

@@ -161,6 +161,8 @@ declare class Redis extends Commander implements DataHandledable {
      * @ignore
      */
     sendCommand(command: Command, stream?: WriteableStream): unknown;
+    private getBlockingTimeoutInMs;
+    private getConfiguredBlockingTimeout;
     private setSocketTimeout;
     scanStream(options?: ScanStreamOptions): ScanStream;
     scanBufferStream(options?: ScanStreamOptions): ScanStream;

package/built/Redis.js

@@ -325,7 +325,7 @@ class Redis extends Commander_1.default {
      * @ignore
      */
     sendCommand(command, stream) {
-        var _a, _b;
+        var _a, _b, _c;
         if (this.status === "wait") {
             this.connect().catch(lodash_1.noop);
         }
@@ -341,11 +341,12 @@ class Redis extends Commander_1.default {
         if (typeof this.options.commandTimeout === "number") {
             command.setTimeout(this.options.commandTimeout);
         }
+        const blockingTimeout = this.getBlockingTimeoutInMs(command);
         let writable = this.status === "ready" ||
             (!stream &&
                 this.status === "connect" &&
-                (0, commands_1.exists)(command.name) &&
-                ((0, commands_1.hasFlag)(command.name, "loading") ||
+                (0, commands_1.exists)(command.name, { caseInsensitive: true }) &&
+                ((0, commands_1.hasFlag)(command.name, "loading", { nameCaseInsensitive: true }) ||
                     Command_1.default.checkFlag("HANDSHAKE_COMMANDS", command.name)));
         if (!this.stream) {
             writable = false;
@@ -378,11 +379,20 @@ class Redis extends Commander_1.default {
                 stream: stream,
                 select: this.condition.select,
             });
+            // For blocking commands, set a timeout while queued to ensure they don't wait forever
+            // if connection never becomes ready (e.g., docker network disconnect scenario)
+            // Use blockingTimeout if configured, otherwise fall back to the command's own timeout
+            if (Command_1.default.checkFlag("BLOCKING_COMMANDS", command.name)) {
+                const offlineTimeout = (_b = this.getConfiguredBlockingTimeout()) !== null && _b !== void 0 ? _b : blockingTimeout;
+                if (offlineTimeout !== undefined) {
+                    command.setBlockingTimeout(offlineTimeout);
+                }
+            }
         }
         else {
             // @ts-expect-error
             if (debug.enabled) {
-                debug("write command[%s]: %d -> %s(%o)", this._getDescription(), (_b = this.condition) === null || _b === void 0 ? void 0 : _b.select, command.name, command.args);
+                debug("write command[%s]: %d -> %s(%o)", this._getDescription(), (_c = this.condition) === null || _c === void 0 ? void 0 : _c.select, command.name, command.args);
             }
             if (stream) {
                 if ("isPipeline" in stream && stream.isPipeline) {
@@ -400,6 +410,9 @@ class Redis extends Commander_1.default {
                 stream: stream,
                 select: this.condition.select,
             });
+            if (blockingTimeout !== undefined) {
+                command.setBlockingTimeout(blockingTimeout);
+            }
             if (Command_1.default.checkFlag("WILL_DISCONNECT", command.name)) {
                 this.manuallyClosing = true;
             }
@@ -417,6 +430,33 @@ class Redis extends Commander_1.default {
         }
         return command.promise;
     }
+    getBlockingTimeoutInMs(command) {
+        var _a;
+        if (!Command_1.default.checkFlag("BLOCKING_COMMANDS", command.name)) {
+            return undefined;
+        }
+        const timeout = command.extractBlockingTimeout();
+        if (typeof timeout === "number") {
+            if (timeout > 0) {
+                // Finite timeout from command args - add grace period
+                return timeout + ((_a = this.options.blockingTimeoutGrace) !== null && _a !== void 0 ? _a : RedisOptions_1.DEFAULT_REDIS_OPTIONS.blockingTimeoutGrace);
+            }
+            // Command has timeout=0 (block forever), use blockingTimeout option as safety net
+            return this.getConfiguredBlockingTimeout();
+        }
+        if (timeout === null) {
+            // No BLOCK option found (e.g., XREAD without BLOCK), use blockingTimeout as safety net
+            return this.getConfiguredBlockingTimeout();
+        }
+        return undefined;
+    }
+    getConfiguredBlockingTimeout() {
+        if (typeof this.options.blockingTimeout === "number" &&
+            this.options.blockingTimeout > 0) {
+            return this.options.blockingTimeout;
+        }
+        return undefined;
+    }
     setSocketTimeout() {
         this.socketTimeoutTimer = setTimeout(() => {
             this.stream.destroy(new Error(`Socket timeout. Expecting data, but didn't receive any in ${this.options.socketTimeout}ms.`));

package/built/cluster/ClusterSubscriberGroup.d.ts

@@ -1,37 +1,39 @@
 /// <reference types="node" />
-import ClusterSubscriber from "./ClusterSubscriber";
-import Cluster from "./index";
+import * as EventEmitter from "events";
+import ShardedSubscriber from "./ShardedSubscriber";
 /**
- * Redis differs between "normal" and sharded PubSub. If using the "normal" PubSub feature, exactly one
- * ClusterSubscriber exists per cluster instance. This works because the Redis cluster bus forwards m
- * messages between shards. However, this has scalability limitations, which is the reason why the sharded
- * PubSub feature was added to Redis. With sharded PubSub, each shard is responsible for its own messages.
- * Given that, we need at least one ClusterSubscriber per master endpoint/node.
+ * Redis distinguishes between "normal" and sharded PubSub. When using the normal PubSub feature,
+ * exactly one subscriber exists per cluster instance because the Redis cluster bus forwards
+ * messages between shards. Sharded PubSub removes this limitation by making each shard
+ * responsible for its own messages.
  *
- * This class leverages the previously exising ClusterSubscriber by adding support for multiple such subscribers
- * in alignment to the master nodes of the cluster. The ClusterSubscriber class was extended in a non-breaking way
- * to support this feature.
+ * This class coordinates one ShardedSubscriber per master node in the cluster, providing
+ * sharded PubSub support while keeping the public API backward compatible.
  */
 export default class ClusterSubscriberGroup {
-    private cluster;
+    private readonly subscriberGroupEmitter;
     private shardedSubscribers;
     private clusterSlots;
     private subscriberToSlotsIndex;
     private channels;
+    private failedAttemptsByNode;
+    private isResetting;
+    private pendingReset;
+    private static readonly MAX_RETRY_ATTEMPTS;
+    private static readonly MAX_BACKOFF_MS;
+    private static readonly BASE_BACKOFF_MS;
     /**
      * Register callbacks
      *
      * @param cluster
      */
-    constructor(cluster: Cluster, refreshSlotsCacheCallback: () => void);
+    constructor(subscriberGroupEmitter: EventEmitter);
     /**
      * Get the responsible subscriber.
      *
-     * Returns null if no subscriber was found
-     *
      * @param slot
      */
-    getResponsibleSubscriber(slot: number): ClusterSubscriber;
+    getResponsibleSubscriber(slot: number): ShardedSubscriber | undefined;
     /**
      * Adds a channel for which this subscriber group is responsible
      *
@@ -50,24 +52,17 @@ export default class ClusterSubscriberGroup {
     /**
      * Start all not yet started subscribers
      */
-    start(): void;
-    /**
-     * Add a subscriber to the group of subscribers
-     *
-     * @param redis
-     */
-    private _addSubscriber;
+    start(): Promise<any[]>;
     /**
-     * Removes a subscriber from the group
-     * @param redis
+     * Resets the subscriber group by disconnecting all subscribers that are no longer needed and connecting new ones.
      */
-    private _removeSubscriber;
+    reset(clusterSlots: string[][], clusterNodes: any[]): Promise<void>;
     /**
      * Refreshes the subscriber-related slot ranges
      *
      * Returns false if no refresh was needed
      *
-     * @param cluster
+     * @param targetSlots
      */
     private _refreshSlots;
     /**
@@ -83,4 +78,28 @@ export default class ClusterSubscriberGroup {
      * @private
      */
     private _slotsAreEqual;
+    /**
+     * Checks if any subscribers are in an unhealthy state.
+     *
+     * A subscriber is considered unhealthy if:
+     * - It exists but is not started (failed/disconnected)
+     * - It's missing entirely for a node that should have one
+     *
+     * @returns true if any subscribers need to be recreated
+     */
+    private hasUnhealthySubscribers;
+    /**
+     * Handles failed subscriber connections by emitting an event to refresh the slots cache
+     * after a backoff period.
+     *
+     * @param error
+     * @param nodeKey
+     */
+    private handleSubscriberConnectFailed;
+    /**
+     * Handles successful subscriber connections by resetting the failed attempts counter.
+     *
+     * @param nodeKey
+     */
+    private handleSubscriberConnectSucceeded;
 }

package/built/cluster/ClusterSubscriberGroup.js

@@ -1,21 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const utils_1 = require("../utils");
-const ClusterSubscriber_1 = require("./ClusterSubscriber");
-const ConnectionPool_1 = require("./ConnectionPool");
 const util_1 = require("./util");
 const calculateSlot = require("cluster-key-slot");
+const ShardedSubscriber_1 = require("./ShardedSubscriber");
 const debug = (0, utils_1.Debug)("cluster:subscriberGroup");
 /**
- * Redis differs between "normal" and sharded PubSub. If using the "normal" PubSub feature, exactly one
- * ClusterSubscriber exists per cluster instance. This works because the Redis cluster bus forwards m
- * messages between shards. However, this has scalability limitations, which is the reason why the sharded
- * PubSub feature was added to Redis. With sharded PubSub, each shard is responsible for its own messages.
- * Given that, we need at least one ClusterSubscriber per master endpoint/node.
+ * Redis distinguishes between "normal" and sharded PubSub. When using the normal PubSub feature,
+ * exactly one subscriber exists per cluster instance because the Redis cluster bus forwards
+ * messages between shards. Sharded PubSub removes this limitation by making each shard
+ * responsible for its own messages.
  *
- * This class leverages the previously exising ClusterSubscriber by adding support for multiple such subscribers
- * in alignment to the master nodes of the cluster. The ClusterSubscriber class was extended in a non-breaking way
- * to support this feature.
+ * This class coordinates one ShardedSubscriber per master node in the cluster, providing
+ * sharded PubSub support while keeping the public API backward compatible.
  */
 class ClusterSubscriberGroup {
     /**
@@ -23,31 +20,50 @@ class ClusterSubscriberGroup {
      *
      * @param cluster
      */
-    constructor(cluster, refreshSlotsCacheCallback) {
-        this.cluster = cluster;
+    constructor(subscriberGroupEmitter) {
+        this.subscriberGroupEmitter = subscriberGroupEmitter;
         this.shardedSubscribers = new Map();
         this.clusterSlots = [];
-        //Simple [min, max] slot ranges aren't enough because you can migrate single slots
+        // Simple [min, max] slot ranges aren't enough because you can migrate single slots
         this.subscriberToSlotsIndex = new Map();
         this.channels = new Map();
-        cluster.on("+node", (redis) => {
-            this._addSubscriber(redis);
-        });
-        cluster.on("-node", (redis) => {
-            this._removeSubscriber(redis);
-        });
-        cluster.on("refresh", () => {
-            this._refreshSlots(cluster);
-        });
-        cluster.on("forceRefresh", () => {
-            refreshSlotsCacheCallback();
-        });
+        this.failedAttemptsByNode = new Map();
+        // Only latest pending reset kept; throttled by refreshSlotsCache's isRefreshing + backoff delay
+        this.isResetting = false;
+        this.pendingReset = null;
+        /**
+         * Handles failed subscriber connections by emitting an event to refresh the slots cache
+         * after a backoff period.
+         *
+         * @param error
+         * @param nodeKey
+         */
+        this.handleSubscriberConnectFailed = (error, nodeKey) => {
+            const currentAttempts = this.failedAttemptsByNode.get(nodeKey) || 0;
+            const failedAttempts = currentAttempts + 1;
+            this.failedAttemptsByNode.set(nodeKey, failedAttempts);
+            const attempts = Math.min(failedAttempts, ClusterSubscriberGroup.MAX_RETRY_ATTEMPTS);
+            const backoff = Math.min(ClusterSubscriberGroup.BASE_BACKOFF_MS * 2 ** attempts, ClusterSubscriberGroup.MAX_BACKOFF_MS);
+            const jitter = Math.floor((Math.random() - 0.5) * (backoff * 0.5));
+            const delay = Math.max(0, backoff + jitter);
+            debug("Failed to connect subscriber for %s. Refreshing slots in %dms", nodeKey, delay);
+            this.subscriberGroupEmitter.emit("subscriberConnectFailed", {
+                delay,
+                error,
+            });
+        };
+        /**
+         * Handles successful subscriber connections by resetting the failed attempts counter.
+         *
+         * @param nodeKey
+         */
+        this.handleSubscriberConnectSucceeded = (nodeKey) => {
+            this.failedAttemptsByNode.delete(nodeKey);
+        };
     }
     /**
      * Get the responsible subscriber.
      *
-     * Returns null if no subscriber was found
-     *
      * @param slot
      */
     getResponsibleSubscriber(slot) {
@@ -61,11 +77,12 @@ class ClusterSubscriberGroup {
      */
     addChannels(channels) {
         const slot = calculateSlot(channels[0]);
-        //Check if the all channels belong to the same slot and otherwise reject the operation
-        channels.forEach((c) => {
-            if (calculateSlot(c) != slot)
+        // Check if the all channels belong to the same slot and otherwise reject the operation
+        for (const c of channels) {
+            if (calculateSlot(c) !== slot) {
                 return -1;
-        });
+            }
+        }
         const currChannels = this.channels.get(slot);
         if (!currChannels) {
             this.channels.set(slot, channels);
@@ -73,7 +90,7 @@ class ClusterSubscriberGroup {
         else {
             this.channels.set(slot, currChannels.concat(channels));
         }
-        return [...this.channels.values()].flatMap(v => v).length;
+        return Array.from(this.channels.values()).reduce((sum, array) => sum + array.length, 0);
     }
     /**
      * Removes channels for which the subscriber group is responsible by optionally unsubscribing
@@ -81,17 +98,18 @@ class ClusterSubscriberGroup {
      */
     removeChannels(channels) {
         const slot = calculateSlot(channels[0]);
-        //Check if the all channels belong to the same slot and otherwise reject the operation
-        channels.forEach((c) => {
-            if (calculateSlot(c) != slot)
+        // Check if the all channels belong to the same slot and otherwise reject the operation
+        for (const c of channels) {
+            if (calculateSlot(c) !== slot) {
                 return -1;
-        });
+            }
+        }
         const slotChannels = this.channels.get(slot);
         if (slotChannels) {
-            const updatedChannels = slotChannels.filter(c => !channels.includes(c));
+            const updatedChannels = slotChannels.filter((c) => !channels.includes(c));
             this.channels.set(slot, updatedChannels);
         }
-        return [...this.channels.values()].flatMap(v => v).length;
+        return Array.from(this.channels.values()).reduce((sum, array) => sum + array.length, 0);
     }
     /**
      * Disconnect all subscribers
@@ -105,79 +123,123 @@ class ClusterSubscriberGroup {
      * Start all not yet started subscribers
      */
     start() {
+        const startPromises = [];
         for (const s of this.shardedSubscribers.values()) {
             if (!s.isStarted()) {
-                s.start();
+                startPromises.push(s
+                    .start()
+                    .then(() => {
+                    this.handleSubscriberConnectSucceeded(s.getNodeKey());
+                })
+                    .catch((err) => {
+                    this.handleSubscriberConnectFailed(err, s.getNodeKey());
+                }));
             }
         }
+        return Promise.all(startPromises);
     }
     /**
-     * Add a subscriber to the group of subscribers
-     *
-     * @param redis
+     * Resets the subscriber group by disconnecting all subscribers that are no longer needed and connecting new ones.
      */
-    _addSubscriber(redis) {
-        const pool = new ConnectionPool_1.default(redis.options);
-        if (pool.addMasterNode(redis)) {
-            const sub = new ClusterSubscriber_1.default(pool, this.cluster, true);
-            const nodeKey = (0, util_1.getNodeKey)(redis.options);
-            this.shardedSubscribers.set(nodeKey, sub);
-            sub.start();
-            // We need to attempt to resubscribe them in case the new node serves their slot
-            this._resubscribe();
-            this.cluster.emit("+subscriber");
-            return sub;
+    async reset(clusterSlots, clusterNodes) {
+        if (this.isResetting) {
+            this.pendingReset = { slots: clusterSlots, nodes: clusterNodes };
+            return;
         }
-        return null;
-    }
-    /**
-     * Removes a subscriber from the group
-     * @param redis
-     */
-    _removeSubscriber(redis) {
-        const nodeKey = (0, util_1.getNodeKey)(redis.options);
-        const sub = this.shardedSubscribers.get(nodeKey);
-        if (sub) {
-            sub.stop();
-            this.shardedSubscribers.delete(nodeKey);
-            // Even though the subscriber to this node is going down, we might have another subscriber
-            // handling the same slots, so we need to attempt to subscribe the orphaned channels
+        this.isResetting = true;
+        try {
+            const hasTopologyChanged = this._refreshSlots(clusterSlots);
+            const hasFailedSubscribers = this.hasUnhealthySubscribers();
+            if (!hasTopologyChanged && !hasFailedSubscribers) {
+                debug("No topology change detected or failed subscribers. Skipping reset.");
+                return;
+            }
+            // For each of the sharded subscribers
+            for (const [nodeKey, shardedSubscriber] of this.shardedSubscribers) {
+                if (
+                // If the subscriber is still responsible for a slot range and is running then keep it
+                this.subscriberToSlotsIndex.has(nodeKey) &&
+                    shardedSubscriber.isStarted()) {
+                    debug("Skipping deleting subscriber for %s", nodeKey);
+                    continue;
+                }
+                debug("Removing subscriber for %s", nodeKey);
+                // Otherwise stop the subscriber and remove it
+                shardedSubscriber.stop();
+                this.shardedSubscribers.delete(nodeKey);
+                this.subscriberGroupEmitter.emit("-subscriber");
+            }
+            const startPromises = [];
+            // For each node in slots cache
+            for (const [nodeKey, _] of this.subscriberToSlotsIndex) {
+                // If we already have a subscriber for this node then keep it
+                if (this.shardedSubscribers.has(nodeKey)) {
+                    debug("Skipping creating new subscriber for %s", nodeKey);
+                    continue;
+                }
+                debug("Creating new subscriber for %s", nodeKey);
+                // Otherwise create a new subscriber
+                const redis = clusterNodes.find((node) => {
+                    return (0, util_1.getNodeKey)(node.options) === nodeKey;
+                });
+                if (!redis) {
+                    debug("Failed to find node for key %s", nodeKey);
+                    continue;
+                }
+                const sub = new ShardedSubscriber_1.default(this.subscriberGroupEmitter, redis.options);
+                this.shardedSubscribers.set(nodeKey, sub);
+                startPromises.push(sub
+                    .start()
+                    .then(() => {
+                    this.handleSubscriberConnectSucceeded(nodeKey);
+                })
+                    .catch((error) => {
+                    this.handleSubscriberConnectFailed(error, nodeKey);
+                }));
+                this.subscriberGroupEmitter.emit("+subscriber");
+            }
+            // It's vital to await the start promises before resubscribing
+            // Otherwise we might try to resubscribe to a subscriber that is not yet connected
+            // This can cause a race condition
+            await Promise.all(startPromises);
             this._resubscribe();
-            this.cluster.emit("-subscriber");
+            this.subscriberGroupEmitter.emit("subscribersReady");
+        }
+        finally {
+            this.isResetting = false;
+            if (this.pendingReset) {
+                const { slots, nodes } = this.pendingReset;
+                this.pendingReset = null;
+                await this.reset(slots, nodes);
+            }
         }
-        return this.shardedSubscribers;
     }
     /**
      * Refreshes the subscriber-related slot ranges
      *
      * Returns false if no refresh was needed
      *
-     * @param cluster
+     * @param targetSlots
      */
-    _refreshSlots(cluster) {
+    _refreshSlots(targetSlots) {
         //If there was an actual change, then reassign the slot ranges
-        if (this._slotsAreEqual(cluster.slots)) {
+        if (this._slotsAreEqual(targetSlots)) {
             debug("Nothing to refresh because the new cluster map is equal to the previous one.");
+            return false;
         }
-        else {
-            debug("Refreshing the slots of the subscriber group.");
-            //Rebuild the slots index
-            this.subscriberToSlotsIndex = new Map();
-            for (let slot = 0; slot < cluster.slots.length; slot++) {
-                const node = cluster.slots[slot][0];
-                if (!this.subscriberToSlotsIndex.has(node)) {
-                    this.subscriberToSlotsIndex.set(node, []);
-                }
-                this.subscriberToSlotsIndex.get(node).push(Number(slot));
+        debug("Refreshing the slots of the subscriber group.");
+        //Rebuild the slots index
+        this.subscriberToSlotsIndex = new Map();
+        for (let slot = 0; slot < targetSlots.length; slot++) {
+            const node = targetSlots[slot][0];
+            if (!this.subscriberToSlotsIndex.has(node)) {
+                this.subscriberToSlotsIndex.set(node, []);
             }
-            //Update the subscribers from the index
-            this._resubscribe();
-            //Update the cached slots map
-            this.clusterSlots = JSON.parse(JSON.stringify(cluster.slots));
-            this.cluster.emit("subscribersReady");
-            return true;
+            this.subscriberToSlotsIndex.get(node).push(Number(slot));
         }
-        return false;
+        //Update the cached slots map
+        this.clusterSlots = JSON.parse(JSON.stringify(targetSlots));
+        return true;
     }
     /**
      * Resubscribes to the previous channels
@@ -189,20 +251,27 @@ class ClusterSubscriberGroup {
             this.shardedSubscribers.forEach((s, nodeKey) => {
                 const subscriberSlots = this.subscriberToSlotsIndex.get(nodeKey);
                 if (subscriberSlots) {
-                    //More for debugging purposes
-                    s.associateSlotRange(subscriberSlots);
                     //Resubscribe on the underlying connection
                     subscriberSlots.forEach((ss) => {
                         //Might return null if being disconnected
                         const redis = s.getInstance();
                         const channels = this.channels.get(ss);
                         if (channels && channels.length > 0) {
-                            //Try to subscribe now
-                            if (redis) {
-                                redis.ssubscribe(channels);
-                                //If the instance isn't ready yet, then register the re-subscription for later
-                                redis.on("ready", () => {
-                                    redis.ssubscribe(channels);
+                            if (redis.status === "end") {
+                                return;
+                            }
+                            if (redis.status === "ready") {
+                                redis.ssubscribe(...channels).catch((err) => {
+                                    // TODO: Should we emit an error event here?
+                                    debug("Failed to ssubscribe on node %s: %s", nodeKey, err);
+                                });
+                            }
+                            else {
+                                redis.once("ready", () => {
+                                    redis.ssubscribe(...channels).catch((err) => {
+                                        // TODO: Should we emit an error event here?
+                                        debug("Failed to ssubscribe on node %s: %s", nodeKey, err);
+                                    });
                                 });
                             }
                         }
@@ -218,10 +287,30 @@ class ClusterSubscriberGroup {
      * @private
      */
     _slotsAreEqual(other) {
-        if (this.clusterSlots === undefined)
+        if (this.clusterSlots === undefined) {
             return false;
-        else
+        }
+        else {
             return JSON.stringify(this.clusterSlots) === JSON.stringify(other);
+        }
+    }
+    /**
+     * Checks if any subscribers are in an unhealthy state.
+     *
+     * A subscriber is considered unhealthy if:
+     * - It exists but is not started (failed/disconnected)
+     * - It's missing entirely for a node that should have one
+     *
+     * @returns true if any subscribers need to be recreated
+     */
+    hasUnhealthySubscribers() {
+        const hasFailedSubscribers = Array.from(this.shardedSubscribers.values()).some((sub) => !sub.isStarted());
+        const hasMissingSubscribers = Array.from(this.subscriberToSlotsIndex.keys()).some((nodeKey) => !this.shardedSubscribers.has(nodeKey));
+        return hasFailedSubscribers || hasMissingSubscribers;
     }
 }
 exports.default = ClusterSubscriberGroup;
+// Retry strategy
+ClusterSubscriberGroup.MAX_RETRY_ATTEMPTS = 10;
+ClusterSubscriberGroup.MAX_BACKOFF_MS = 2000;
+ClusterSubscriberGroup.BASE_BACKOFF_MS = 100;

package/built/cluster/ShardedSubscriber.d.ts

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+import EventEmitter = require("events");
+import { RedisOptions } from "./util";
+import Redis from "../Redis";
+export default class ShardedSubscriber {
+    private readonly emitter;
+    private readonly nodeKey;
+    private started;
+    private instance;
+    private readonly messageListeners;
+    constructor(emitter: EventEmitter, options: RedisOptions);
+    private onEnd;
+    private onError;
+    private onMoved;
+    start(): Promise<void>;
+    stop(): void;
+    isStarted(): boolean;
+    getInstance(): Redis | null;
+    getNodeKey(): string;
+}

package/built/cluster/ShardedSubscriber.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const util_1 = require("./util");
+const utils_1 = require("../utils");
+const Redis_1 = require("../Redis");
+const debug = (0, utils_1.Debug)("cluster:subscriberGroup:shardedSubscriber");
+class ShardedSubscriber {
+    constructor(emitter, options) {
+        this.emitter = emitter;
+        this.started = false;
+        this.instance = null;
+        // Store listener references for cleanup
+        this.messageListeners = new Map();
+        this.onEnd = () => {
+            this.started = false;
+            this.emitter.emit("-node", this.instance, this.nodeKey);
+        };
+        this.onError = (error) => {
+            this.emitter.emit("nodeError", error, this.nodeKey);
+        };
+        this.onMoved = () => {
+            this.emitter.emit("moved");
+        };
+        this.instance = new Redis_1.default({
+            port: options.port,
+            host: options.host,
+            username: options.username,
+            password: options.password,
+            enableReadyCheck: false,
+            offlineQueue: true,
+            connectionName: (0, util_1.getConnectionName)("ssubscriber", options.connectionName),
+            lazyConnect: true,
+            tls: options.tls,
+            /**
+             * Disable auto reconnection for subscribers.
+             * The ClusterSubscriberGroup will handle the reconnection.
+             */
+            retryStrategy: null,
+        });
+        this.nodeKey = (0, util_1.getNodeKey)(options);
+        // Register listeners
+        this.instance.once("end", this.onEnd);
+        this.instance.on("error", this.onError);
+        this.instance.on("moved", this.onMoved);
+        for (const event of ["smessage", "smessageBuffer"]) {
+            const listener = (...args) => {
+                this.emitter.emit(event, ...args);
+            };
+            this.messageListeners.set(event, listener);
+            this.instance.on(event, listener);
+        }
+    }
+    async start() {
+        if (this.started) {
+            debug("already started %s", this.nodeKey);
+            return;
+        }
+        try {
+            await this.instance.connect();
+            debug("started %s", this.nodeKey);
+            this.started = true;
+        }
+        catch (err) {
+            debug("failed to start %s: %s", this.nodeKey, err);
+            this.started = false;
+            throw err; // Re-throw so caller knows it failed
+        }
+    }
+    stop() {
+        this.started = false;
+        if (this.instance) {
+            this.instance.disconnect();
+            this.instance.removeAllListeners();
+            this.messageListeners.clear();
+            this.instance = null;
+        }
+        debug("stopped %s", this.nodeKey);
+    }
+    isStarted() {
+        return this.started;
+    }
+    getInstance() {
+        return this.instance;
+    }
+    getNodeKey() {
+        return this.nodeKey;
+    }
+}
+exports.default = ShardedSubscriber;

package/built/cluster/index.d.ts

@@ -49,6 +49,7 @@ declare class Cluster extends Commander {
     private _autoPipelines;
     private _runningAutoPipelines;
     private _readyDelayedCallbacks;
+    private subscriberGroupEmitter;
     /**
      * Every time Cluster#connect() is called, this value will be
      * auto-incrementing. The purpose of this value is used for
@@ -153,6 +154,7 @@ declare class Cluster extends Commander {
      */
     private resolveStartupNodeHostnames;
     private createScanStream;
+    private createShardedSubscriberGroup;
 }
 interface Cluster extends EventEmitter {
 }

package/built/cluster/index.js

@@ -62,8 +62,9 @@ class Cluster extends Commander_1.default {
         events_1.EventEmitter.call(this);
         this.startupNodes = startupNodes;
         this.options = (0, utils_1.defaults)({}, options, ClusterOptions_1.DEFAULT_CLUSTER_OPTIONS, this.options);
-        if (this.options.shardedSubscribers == true)
-            this.shardedSubscribers = new ClusterSubscriberGroup_1.default(this, this.refreshSlotsCache.bind(this));
+        if (this.options.shardedSubscribers) {
+            this.createShardedSubscriberGroup();
+        }
         if (this.options.redisOptions &&
             this.options.redisOptions.keyPrefix &&
             !this.options.keyPrefix) {
@@ -130,6 +131,14 @@ class Cluster extends Commander_1.default {
                     return;
                 }
                 this.connectionPool.reset(nodes);
+                if (this.options.shardedSubscribers) {
+                    this.shardedSubscribers
+                        .reset(this.slots, this.connectionPool.getNodes("all"))
+                        .catch((err) => {
+                        // TODO should we emit an error event here?
+                        debug("Error while starting subscribers: %s", err);
+                    });
+                }
                 const readyHandler = () => {
                     this.setStatus("ready");
                     this.retryAttempts = 0;
@@ -177,7 +186,10 @@ class Cluster extends Commander_1.default {
                 });
                 this.subscriber.start();
                 if (this.options.shardedSubscribers) {
-                    this.shardedSubscribers.start();
+                    this.shardedSubscribers.start().catch((err) => {
+                        // TODO should we emit an error event here?
+                        debug("Error while starting subscribers: %s", err);
+                    });
                 }
             })
                 .catch((err) => {
@@ -422,19 +434,25 @@ class Cluster extends Commander_1.default {
                 }
                 else if (Command_1.default.checkFlag("ENTER_SUBSCRIBER_MODE", command.name) ||
                     Command_1.default.checkFlag("EXIT_SUBSCRIBER_MODE", command.name)) {
-                    if (_this.options.shardedSubscribers == true &&
+                    if (_this.options.shardedSubscribers &&
                         (command.name == "ssubscribe" || command.name == "sunsubscribe")) {
                         const sub = _this.shardedSubscribers.getResponsibleSubscriber(targetSlot);
+                        if (!sub) {
+                            command.reject(new redis_errors_1.AbortError(`No sharded subscriber for slot: ${targetSlot}`));
+                            return;
+                        }
                         let status = -1;
-                        if (command.name == "ssubscribe")
+                        if (command.name == "ssubscribe") {
                             status = _this.shardedSubscribers.addChannels(command.getKeys());
-                        if (command.name == "sunsubscribe")
+                        }
+                        if (command.name == "sunsubscribe") {
                             status = _this.shardedSubscribers.removeChannels(command.getKeys());
+                        }
                         if (status !== -1) {
                             redis = sub.getInstance();
                         }
                         else {
-                            command.reject(new redis_errors_1.AbortError("Can't add or remove the given channels. Are they in the same slot?"));
+                            command.reject(new redis_errors_1.AbortError("Possible CROSSSLOT error: All channels must hash to the same slot"));
                         }
                     }
                     else {
@@ -614,6 +632,7 @@ class Cluster extends Commander_1.default {
      * Called when closed to check whether a reconnection should be made
      */
     handleCloseEvent(reason) {
+        var _a;
         if (reason) {
             debug("closed because %s", reason);
         }
@@ -633,6 +652,9 @@ class Cluster extends Commander_1.default {
             }, retryDelay);
         }
         else {
+            if (this.options.shardedSubscribers) {
+                (_a = this.subscriberGroupEmitter) === null || _a === void 0 ? void 0 : _a.removeAllListeners();
+            }
             this.setStatus("end");
             this.flushQueue(new Error("None of startup nodes is available"));
         }
@@ -744,6 +766,14 @@ class Cluster extends Commander_1.default {
                 this._groupsBySlot[i] = this._groupsIds[target];
             }
             this.connectionPool.reset(nodes);
+            if (this.options.shardedSubscribers) {
+                this.shardedSubscribers
+                    .reset(this.slots, this.connectionPool.getNodes("all"))
+                    .catch((err) => {
+                    // TODO should we emit an error event here?
+                    debug("Error while starting subscribers: %s", err);
+                });
+            }
             callback();
         }, this.options.slotsRefreshTimeout));
     }
@@ -857,6 +887,40 @@ class Cluster extends Commander_1.default {
             ...options,
         });
     }
+    createShardedSubscriberGroup() {
+        this.subscriberGroupEmitter = new events_1.EventEmitter();
+        this.shardedSubscribers = new ClusterSubscriberGroup_1.default(this.subscriberGroupEmitter);
+        this.subscriberGroupEmitter.on("-node", (redis, nodeKey) => {
+            this.emit("-node", redis, nodeKey);
+            this.refreshSlotsCache();
+        });
+        this.subscriberGroupEmitter.on("subscriberConnectFailed", ({ delay, error }) => {
+            this.emit("error", error);
+            setTimeout(() => {
+                this.refreshSlotsCache();
+            }, delay);
+        });
+        this.subscriberGroupEmitter.on("moved", () => {
+            this.refreshSlotsCache();
+        });
+        this.subscriberGroupEmitter.on("-subscriber", () => {
+            this.emit("-subscriber");
+        });
+        this.subscriberGroupEmitter.on("+subscriber", () => {
+            this.emit("+subscriber");
+        });
+        this.subscriberGroupEmitter.on("nodeError", (error, nodeKey) => {
+            this.emit("nodeError", error, nodeKey);
+        });
+        this.subscriberGroupEmitter.on("subscribersReady", () => {
+            this.emit("subscribersReady");
+        });
+        for (const event of ["smessage", "smessageBuffer"]) {
+            this.subscriberGroupEmitter.on(event, (arg1, arg2, arg3) => {
+                this.emit(event, arg1, arg2, arg3);
+            });
+        }
+    }
 }
 (0, applyMixin_1.default)(Cluster, events_1.EventEmitter);
 (0, transaction_1.addTransactionSupport)(Cluster.prototype);

package/built/redis/RedisOptions.d.ts

@@ -11,6 +11,16 @@ export interface CommonRedisOptions extends CommanderOptions {
      * a "Command timed out" error will be thrown.
      */
     commandTimeout?: number;
+    /**
+     * Timeout (ms) for blocking commands with timeout=0 / BLOCK 0.
+     * When exceeded, the command resolves with null.
+     */
+    blockingTimeout?: number;
+    /**
+     * Grace period (ms) added to blocking command timeouts to account for network latency.
+     * @default 100
+     */
+    blockingTimeoutGrace?: number;
     /**
      * If the socket does not receive data within a set number of milliseconds:
      * 1. the socket is considered "dead" and will be destroyed

package/built/redis/RedisOptions.js

@@ -54,4 +54,5 @@ exports.DEFAULT_REDIS_OPTIONS = {
     enableAutoPipelining: false,
     autoPipeliningIgnoredCommands: [],
     sentinelMaxConnections: 10,
+    blockingTimeoutGrace: 100,
 };

package/built/utils/argumentParsers.d.ts

@@ -0,0 +1,14 @@
+import { CommandParameter } from "../types";
+/**
+ * Parses a command parameter as seconds and converts to milliseconds.
+ * @param arg - The command parameter representing seconds
+ * @returns The value in milliseconds, 0 if value is <= 0, or undefined if parsing fails
+ */
+export declare const parseSecondsArgument: (arg: CommandParameter | undefined) => number | undefined;
+/**
+ * Parses the BLOCK option from Redis command arguments (e.g., XREAD, XREADGROUP).
+ * @param args - Array of command parameters to search for the BLOCK option
+ * @returns The block duration in milliseconds, 0 if duration is <= 0,
+ *          null if BLOCK option is not found, or undefined if BLOCK is found but duration is invalid
+ */
+export declare const parseBlockOption: (args: CommandParameter[]) => number | null | undefined;

package/built/utils/argumentParsers.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBlockOption = exports.parseSecondsArgument = void 0;
+/**
+ * Parses a command parameter to a number.
+ * @param arg - The command parameter to parse (number, string, or Buffer)
+ * @returns The parsed number, or undefined if parsing fails or arg is undefined
+ */
+const parseNumberArgument = (arg) => {
+    if (typeof arg === "number") {
+        return arg;
+    }
+    if (Buffer.isBuffer(arg)) {
+        return parseNumberArgument(arg.toString());
+    }
+    if (typeof arg === "string") {
+        const value = Number(arg);
+        return Number.isFinite(value) ? value : undefined;
+    }
+    return undefined;
+};
+/**
+ * Parses a command parameter to a string.
+ * @param arg - The command parameter to parse (string or Buffer)
+ * @returns The parsed string, or undefined if arg is not a string/Buffer or is undefined
+ */
+const parseStringArgument = (arg) => {
+    if (typeof arg === "string") {
+        return arg;
+    }
+    if (Buffer.isBuffer(arg)) {
+        return arg.toString();
+    }
+    return undefined;
+};
+/**
+ * Parses a command parameter as seconds and converts to milliseconds.
+ * @param arg - The command parameter representing seconds
+ * @returns The value in milliseconds, 0 if value is <= 0, or undefined if parsing fails
+ */
+const parseSecondsArgument = (arg) => {
+    const value = parseNumberArgument(arg);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value <= 0) {
+        return 0;
+    }
+    return value * 1000;
+};
+exports.parseSecondsArgument = parseSecondsArgument;
+/**
+ * Parses the BLOCK option from Redis command arguments (e.g., XREAD, XREADGROUP).
+ * @param args - Array of command parameters to search for the BLOCK option
+ * @returns The block duration in milliseconds, 0 if duration is <= 0,
+ *          null if BLOCK option is not found, or undefined if BLOCK is found but duration is invalid
+ */
+const parseBlockOption = (args) => {
+    for (let i = 0; i < args.length; i++) {
+        const token = parseStringArgument(args[i]);
+        if (token && token.toLowerCase() === "block") {
+            const duration = parseNumberArgument(args[i + 1]);
+            if (duration === undefined) {
+                return undefined;
+            }
+            if (duration <= 0) {
+                return 0;
+            }
+            return duration;
+        }
+    }
+    return null;
+};
+exports.parseBlockOption = parseBlockOption;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ioredis",
-  "version": "5.8.2",
+  "version": "5.9.0",
   "description": "A robust, performance-focused and full-featured Redis client for Node.js.",
   "main": "./built/index.js",
   "types": "./built/index.d.ts",
@@ -43,7 +43,7 @@
     "url": "https://opencollective.com/ioredis"
   },
   "dependencies": {
-    "@ioredis/commands": "1.4.0",
+    "@ioredis/commands": "1.5.0",
     "cluster-key-slot": "^1.1.0",
     "debug": "^4.3.4",
     "denque": "^2.1.0",