ioredis 5.9.0 → 5.9.1

package/README.md

@@ -802,16 +802,22 @@ Set maxRetriesPerRequest to `null` to disable this behavior, and every command w
 
 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):
+This feature is **opt-in**. It is **disabled by default** and is only enabled
+when `blockingTimeout` is set to a positive number of milliseconds. If
+`blockingTimeout` is omitted, `0`, or negative (for example `-1`), ioredis
+does not arm any client-side timeouts for blocking commands and their
+behavior matches Redis exactly.
 
 ```javascript
 const redis = new Redis({
-  blockingTimeout: 30000, // Resolve with null after 30 seconds when timeout=0/BLOCK 0
+  blockingTimeout: 30000, // Enable blocking timeout protection
 });
 ```
 
+When enabled:
+- For commands with a finite timeout (e.g., `blpop("key", 5)`), ioredis sets a client-side deadline based on the command's timeout plus a small grace period (`blockingTimeoutGrace`, default 100ms). 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 block forever (e.g., `timeout = 0` or `BLOCK 0`), the `blockingTimeout` value is used as a safety net.
+
 ### 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:

package/built/Redis.js

@@ -325,7 +325,7 @@ class Redis extends Commander_1.default {
      * @ignore
      */
     sendCommand(command, stream) {
-        var _a, _b, _c;
+        var _a, _b;
         if (this.status === "wait") {
             this.connect().catch(lodash_1.noop);
         }
@@ -379,11 +379,11 @@ 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
+            // For blocking commands in the offline queue, arm a client-side timeout
+            // only when blockingTimeout is configured. Without this option, queued
+            // blocking commands may wait indefinitely on a dead connection.
             if (Command_1.default.checkFlag("BLOCKING_COMMANDS", command.name)) {
-                const offlineTimeout = (_b = this.getConfiguredBlockingTimeout()) !== null && _b !== void 0 ? _b : blockingTimeout;
+                const offlineTimeout = this.getConfiguredBlockingTimeout();
                 if (offlineTimeout !== undefined) {
                     command.setBlockingTimeout(offlineTimeout);
                 }
@@ -392,7 +392,7 @@ class Redis extends Commander_1.default {
         else {
             // @ts-expect-error
             if (debug.enabled) {
-                debug("write command[%s]: %d -> %s(%o)", this._getDescription(), (_c = this.condition) === null || _c === void 0 ? void 0 : _c.select, command.name, command.args);
+                debug("write command[%s]: %d -> %s(%o)", this._getDescription(), (_b = this.condition) === null || _b === void 0 ? void 0 : _b.select, command.name, command.args);
             }
             if (stream) {
                 if ("isPipeline" in stream && stream.isPipeline) {
@@ -435,6 +435,11 @@ class Redis extends Commander_1.default {
         if (!Command_1.default.checkFlag("BLOCKING_COMMANDS", command.name)) {
             return undefined;
         }
+        // Feature is opt-in: only enabled when blockingTimeout is set to a positive number
+        const configuredTimeout = this.getConfiguredBlockingTimeout();
+        if (configuredTimeout === undefined) {
+            return undefined;
+        }
         const timeout = command.extractBlockingTimeout();
         if (typeof timeout === "number") {
             if (timeout > 0) {
@@ -442,11 +447,11 @@ class Redis extends Commander_1.default {
                 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();
+            return configuredTimeout;
         }
         if (timeout === null) {
             // No BLOCK option found (e.g., XREAD without BLOCK), use blockingTimeout as safety net
-            return this.getConfiguredBlockingTimeout();
+            return configuredTimeout;
         }
         return undefined;
     }

package/built/redis/RedisOptions.d.ts

@@ -12,13 +12,15 @@ export interface CommonRedisOptions extends CommanderOptions {
      */
     commandTimeout?: number;
     /**
-     * Timeout (ms) for blocking commands with timeout=0 / BLOCK 0.
-     * When exceeded, the command resolves with null.
+     * Enables client-side timeout protection for blocking commands when set
+     * to a positive number. If `blockingTimeout` is undefined, `0`, or
+     * negative (e.g. `-1`), the protection is disabled and no client-side
+     * timers are installed for blocking commands.
      */
     blockingTimeout?: number;
     /**
-     * Grace period (ms) added to blocking command timeouts to account for network latency.
-     * @default 100
+     * Grace period (ms) added to blocking command timeouts. Only used when
+     * `blockingTimeout` is a positive number. Defaults to 100ms.
      */
     blockingTimeoutGrace?: number;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ioredis",
-  "version": "5.9.0",
+  "version": "5.9.1",
   "description": "A robust, performance-focused and full-featured Redis client for Node.js.",
   "main": "./built/index.js",
   "types": "./built/index.d.ts",