ioredis 5.10.0 → 5.11.0

package/README.md

@@ -729,13 +729,16 @@ const stream = redis.zscanStream("myhash", {
   match: "age:??",
 });
 ```
+
 The `hscanStream` also accepts the `noValues` option to specify whether Redis should return only the keys in the hash table without their corresponding values.
+
 ```javascript
 const stream = redis.hscanStream("myhash", {
   match: "age:??",
   noValues: true,
 });
 ```
+
 You can learn more from the [Redis documentation](http://redis.io/commands/scan).
 
 **Useful Tips**
@@ -815,6 +818,7 @@ const redis = new Redis({
 ```
 
 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.
 
@@ -842,15 +846,15 @@ On ElastiCache instances with Auto-failover enabled, `reconnectOnError` does not
 
 The Redis instance will emit some events about the state of the connection to the Redis server.
 
-| Event        | Description                                                                                                                                                                                                                                     |
-| :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| connect      | emits when a connection is established to the Redis server.                                                                                                                                                                                     |
-| ready        | If `enableReadyCheck` is `true`, client will emit `ready` when the server reports that it is ready to receive commands (e.g. finish loading data from disk).<br>Otherwise, `ready` will be emitted immediately right after the `connect` event. |
-| error        | emits when an error occurs while connecting.<br>However, ioredis emits all `error` events silently (only emits when there's at least one listener) so that your application won't crash if you're not listening to the `error` event.<br>When `redis.connect()` is explicitly called the error will also be rejected from the returned promise, in addition to emitting it. If `redis.connect()` is not called explicitly and `lazyConnect` is true, ioredis will try to connect automatically on the first command and emit the `error` event silently.                                                      |
-| close        | emits when an established Redis server connection has closed.                                                                                                                                                                                   |
-| reconnecting | emits after `close` when a reconnection will be made. The argument of the event is the time (in ms) before reconnecting.                                                                                                                        |
-| end          | emits after `close` when no more reconnections will be made, or the connection is failed to establish.                                                                                                                                          |
-| wait         | emits when `lazyConnect` is set and will wait for the first command to be called before connecting.                                                                                                                                             |
+| Event        | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| connect      | emits when a connection is established to the Redis server.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| ready        | If `enableReadyCheck` is `true`, client will emit `ready` when the server reports that it is ready to receive commands (e.g. finish loading data from disk).<br>Otherwise, `ready` will be emitted immediately right after the `connect` event.                                                                                                                                                                                                                                                                                                          |
+| error        | emits when an error occurs while connecting.<br>However, ioredis emits all `error` events silently (only emits when there's at least one listener) so that your application won't crash if you're not listening to the `error` event.<br>When `redis.connect()` is explicitly called the error will also be rejected from the returned promise, in addition to emitting it. If `redis.connect()` is not called explicitly and `lazyConnect` is true, ioredis will try to connect automatically on the first command and emit the `error` event silently. |
+| close        | emits when an established Redis server connection has closed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| reconnecting | emits after `close` when a reconnection will be made. The argument of the event is the time (in ms) before reconnecting.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| end          | emits after `close` when no more reconnections will be made, or the connection is failed to establish.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| wait         | emits when `lazyConnect` is set and will wait for the first command to be called before connecting.                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 
 You can also check out the `Redis#status` property to get the current connection status.
 
@@ -860,6 +864,38 @@ Besides the above connection events, there are several other custom events:
 | :----- | :------------------------------------------------------------------ |
 | select | emits when the database changed. The argument is the new db number. |
 
+## Diagnostics Channel
+
+ioredis publishes telemetry through Node.js [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html), allowing APM tools and custom instrumentation to observe commands, connections, and batch operations without modifying application code.
+
+These channels use `TracingChannel#tracePromise()` and emit `start`, `end`, `asyncStart`, `asyncEnd`, and `error` sub-events. Requires Node.js >= 18.19.0; on older versions the channels are silently unavailable (zero overhead). Subscribe via `tracing:<name>:<event>`:
+
+```typescript
+import dc from "node:diagnostics_channel";
+
+dc.subscribe("tracing:ioredis:command:start", ({ command, args }) => {
+  console.log(`> ${command}`, args);
+});
+
+dc.subscribe("tracing:ioredis:command:asyncEnd", ({ command }) => {
+  console.log(`${command} settled`);
+});
+
+dc.subscribe("tracing:ioredis:command:error", ({ command, error }) => {
+  console.error(`${command} failed:`, error);
+});
+```
+
+| Channel name      | Payload                 | Description                                              |
+| :---------------- | :---------------------- | :------------------------------------------------------- |
+| `ioredis:command` | `CommandTraceContext`   | Individual command (standalone, pipeline, or within MULTI) |
+| `ioredis:batch`   | `BatchOperationContext` | MULTI transaction as a whole                             |
+| `ioredis:connect` | `ConnectTraceContext`   | Socket connection attempt                                |
+
+Command arguments are sanitized before emission using rules adapted from `@opentelemetry/redis-common`. Sensitive values (e.g. values in `SET`, `AUTH` passwords) are replaced with `?`, while read-only commands like `GET` and `DEL` retain all arguments. This is safe by default: unlisted or custom commands have all arguments redacted.
+
+Context types (`CommandTraceContext`, `BatchOperationContext`, `ConnectTraceContext`) are exported from `ioredis`.
+
 ## Offline Queue
 
 When a command can't be processed by Redis (being sent before the `ready` event), by default, it's added to the offline queue and will be
@@ -1159,6 +1195,7 @@ const cluster = new Redis.Cluster(
 ```
 
 Or you can specify this parameter through function:
+
 ```javascript
 const cluster = new Redis.Cluster(
   [
@@ -1169,7 +1206,7 @@ const cluster = new Redis.Cluster(
   ],
   {
     natMap: (key) => {
-      if(key.includes('30001')) {
+      if (key.includes("30001")) {
         return { host: "203.0.113.73", port: 30001 };
       }
 
@@ -1226,28 +1263,33 @@ For sharded Pub/Sub, use the `spublish` and `ssubscribe` commands instead of the
 The following basic example shows you how to use sharded Pub/Sub:
 
 ```javascript
-const cluster: Cluster = new Cluster([{host: host, port: port}], {shardedSubscribers: true});
+const cluster: Cluster = new Cluster([{ host: host, port: port }], {
+  shardedSubscribers: true,
+});
 
 //Register the callback
 cluster.on("smessage", (channel, message) => {
-    console.log(message);
+  console.log(message);
 });
 
-
 //Subscribe to the channels on the same slot
-cluster.ssubscribe("channel{my}:1", "channel{my}:2").then( ( count: number ) => {
+cluster
+  .ssubscribe("channel{my}:1", "channel{my}:2")
+  .then((count: number) => {
     console.log(count);
-}).catch( (err) => {
+  })
+  .catch((err) => {
     console.log(err);
-});
+  });
 
 //Publish a message
-cluster.spublish("channel{my}:1", "This is a test message to my first channel.").then((value: number) => {
+cluster
+  .spublish("channel{my}:1", "This is a test message to my first channel.")
+  .then((value: number) => {
     console.log("Published a message to channel{my}:1");
-});
+  });
 ```
 
-
 ### Events
 
 | Event        | Description                                                                                                                                                                                                |

package/built/Command.d.ts

@@ -94,6 +94,7 @@ export default class Command implements Respondable {
     args: CommandParameter[];
     inTransaction: boolean;
     pipelineIndex?: number;
+    isTraced: boolean;
     isResolved: boolean;
     reject: (err: Error) => void;
     resolve: (result: any) => void;

package/built/Command.js

@@ -37,6 +37,7 @@ class Command {
     constructor(name, args = [], options = {}, callback) {
         this.name = name;
         this.inTransaction = false;
+        this.isTraced = false;
         this.isResolved = false;
         this.transformed = false;
         this.replyEncoding = options.replyEncoding;

package/built/Pipeline.js

@@ -5,6 +5,7 @@ const commands_1 = require("@ioredis/commands");
 const standard_as_callback_1 = require("standard-as-callback");
 const util_1 = require("util");
 const Command_1 = require("./Command");
+const buffer_1 = require("buffer");
 const utils_1 = require("./utils");
 const Commander_1 = require("./utils/Commander");
 /*
@@ -315,6 +316,15 @@ Pipeline.prototype.exec = function (callback) {
                     buffers.push(writable);
                 }
                 else {
+                    if (data.length + writable.length >= buffer_1.constants.MAX_STRING_LENGTH) {
+                        if (!buffers) {
+                            buffers = [];
+                        }
+                        if (data) {
+                            buffers.push(Buffer.from(data, "utf8"));
+                            data = "";
+                        }
+                    }
                     data += writable;
                 }
                 if (!--writePending) {

package/built/Redis.d.ts

@@ -7,6 +7,7 @@ import { RedisOptions } from "./redis/RedisOptions";
 import ScanStream from "./ScanStream";
 import { Transaction } from "./transaction";
 import { Callback, CommandItem, NetStream, ScanStreamOptions, WriteableStream } from "./types";
+import { type BatchOperationContext } from "./tracing";
 import Commander from "./utils/Commander";
 import Deque = require("denque");
 declare type RedisStatus = "wait" | "reconnecting" | "connecting" | "connect" | "ready" | "close" | "end";
@@ -85,6 +86,7 @@ declare class Redis extends Commander implements DataHandledable {
      * if the connection fails, times out, or if Redis is already connecting/connected.
      */
     connect(callback?: Callback<void>): Promise<void>;
+    private _connect;
     /**
      * Disconnect from Redis.
      *
@@ -186,6 +188,15 @@ declare class Redis extends Commander implements DataHandledable {
      * @ignore
      */
     handleReconnection(err: Error, item: CommandItem): void;
+    /**
+     * @ignore
+     */
+    _getServerAddress(): {
+        address: string;
+        port: number | undefined;
+    };
+    private _buildCommandContext;
+    _buildBatchContext(batchSize: number): BatchOperationContext;
     /**
      * Get description of the connection. Used for debugging.
      */

package/built/Redis.js

@@ -12,6 +12,7 @@ const RedisOptions_1 = require("./redis/RedisOptions");
 const ScanStream_1 = require("./ScanStream");
 const transaction_1 = require("./transaction");
 const utils_1 = require("./utils");
+const tracing_1 = require("./tracing");
 const applyMixin_1 = require("./utils/applyMixin");
 const Commander_1 = require("./utils/Commander");
 const lodash_1 = require("./utils/lodash");
@@ -101,7 +102,18 @@ class Redis extends Commander_1.default {
      * if the connection fails, times out, or if Redis is already connecting/connected.
      */
     connect(callback) {
-        const promise = new Promise((resolve, reject) => {
+        const promise = (0, tracing_1.traceConnect)(() => this._connect(), () => {
+            const { address, port } = this._getServerAddress();
+            return {
+                serverAddress: address,
+                serverPort: port,
+                connectionEpoch: this.connectionEpoch,
+            };
+        });
+        return (0, standard_as_callback_1.default)(promise, callback);
+    }
+    _connect() {
+        return new Promise((resolve, reject) => {
             if (this.status === "connecting" ||
                 this.status === "connect" ||
                 this.status === "ready") {
@@ -211,7 +223,6 @@ class Redis extends Commander_1.default {
                 _this.once("close", connectionCloseHandler);
             });
         });
-        return (0, standard_as_callback_1.default)(promise, callback);
     }
     /**
      * Disconnect from Redis.
@@ -416,7 +427,8 @@ class Redis extends Commander_1.default {
             if (Command_1.default.checkFlag("WILL_DISCONNECT", command.name)) {
                 this.manuallyClosing = true;
             }
-            if (this.options.socketTimeout !== undefined && this.socketTimeoutTimer === undefined) {
+            if (this.options.socketTimeout !== undefined &&
+                this.socketTimeoutTimer === undefined) {
                 this.setSocketTimeout();
             }
         }
@@ -428,7 +440,15 @@ class Redis extends Commander_1.default {
                 debug("switch to db [%d]", this.condition.select);
             }
         }
-        return command.promise;
+        if (!writable || command.isTraced) {
+            return command.promise;
+        }
+        // Trace on the write path only, and only once per command. Commands may
+        // pass through sendCommand multiple times (offline queue flush,
+        // prevCommandQueue resend after reconnect). The isTraced flag ensures
+        // we don't emit duplicate trace events.
+        command.isTraced = true;
+        return (0, tracing_1.traceCommand)(() => command.promise, () => this._buildCommandContext(command));
     }
     getBlockingTimeoutInMs(command) {
         var _a;
@@ -444,7 +464,8 @@ class Redis extends Commander_1.default {
         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);
+                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 configuredTimeout;
@@ -575,6 +596,40 @@ class Redis extends Commander_1.default {
                 item.command.reject(err);
         }
     }
+    /**
+     * @ignore
+     */
+    _getServerAddress() {
+        if ("path" in this.options && this.options.path) {
+            return { address: this.options.path, port: undefined };
+        }
+        return {
+            address: ("host" in this.options && this.options.host) || "localhost",
+            port: ("port" in this.options && this.options.port) || 6379,
+        };
+    }
+    _buildCommandContext(command) {
+        var _a, _b, _c;
+        const { address, port } = this._getServerAddress();
+        return {
+            command: command.name,
+            args: (0, tracing_1.sanitizeArgs)(command.name, command.args),
+            database: (_c = (_b = (_a = this.condition) === null || _a === void 0 ? void 0 : _a.select) !== null && _b !== void 0 ? _b : this.options.db) !== null && _c !== void 0 ? _c : 0,
+            serverAddress: address,
+            serverPort: port,
+        };
+    }
+    _buildBatchContext(batchSize) {
+        var _a, _b, _c;
+        const { address, port } = this._getServerAddress();
+        return {
+            batchMode: "MULTI",
+            batchSize,
+            database: (_c = (_b = (_a = this.condition) === null || _a === void 0 ? void 0 : _a.select) !== null && _b !== void 0 ? _b : this.options.db) !== null && _c !== void 0 ? _c : 0,
+            serverAddress: address,
+            serverPort: port,
+        };
+    }
     /**
      * Get description of the connection. Used for debugging.
      */

package/built/autoPipelining.js

@@ -100,6 +100,18 @@ function getFirstValueInFlattenedArray(args) {
     return undefined;
 }
 exports.getFirstValueInFlattenedArray = getFirstValueInFlattenedArray;
+function getFirstKeyForCommand(commandName, args) {
+    if ((0, commands_1.exists)(commandName, { caseInsensitive: true })) {
+        const flattenedArgs = args.flat();
+        const keyIndexes = (0, commands_1.getKeyIndexes)(commandName, flattenedArgs, {
+            nameCaseInsensitive: true,
+        });
+        if (keyIndexes.length) {
+            return flattenedArgs[keyIndexes[0]];
+        }
+    }
+    return getFirstValueInFlattenedArray(args);
+}
 function executeWithAutoPipelining(client, functionName, commandName, args, callback) {
     // On cluster mode let's wait for slots to be available
     if (client.isCluster && !client.slots.length) {
@@ -116,11 +128,9 @@ function executeWithAutoPipelining(client, functionName, commandName, args, call
         }), callback);
     }
     // If we have slot information, we can improve routing by grouping slots served by the same subset of nodes
-    // Note that the first value in args may be a (possibly empty) array.
-    // ioredis will only flatten one level of the array, in the Command constructor.
     const prefix = client.options.keyPrefix || "";
     let slotKey = client.isCluster
-        ? client.slots[calculateSlot(`${prefix}${getFirstValueInFlattenedArray(args)}`)].join(",")
+        ? client.slots[calculateSlot(`${prefix}${getFirstKeyForCommand(commandName, args)}`)].join(",")
         : "main";
     // When scaleReads is enabled, separate read and write commands into different pipelines
     // so they can be routed to replicas and masters respectively

package/built/cluster/ClusterSubscriberGroup.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="node" />
 import * as EventEmitter from "events";
 import ShardedSubscriber from "./ShardedSubscriber";
+import { ClusterOptions } from "./ClusterOptions";
 /**
  * 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
@@ -12,6 +13,7 @@ import ShardedSubscriber from "./ShardedSubscriber";
  */
 export default class ClusterSubscriberGroup {
     private readonly subscriberGroupEmitter;
+    private readonly options;
     private shardedSubscribers;
     private clusterSlots;
     private subscriberToSlotsIndex;
@@ -27,7 +29,7 @@ export default class ClusterSubscriberGroup {
      *
      * @param cluster
      */
-    constructor(subscriberGroupEmitter: EventEmitter);
+    constructor(subscriberGroupEmitter: EventEmitter, options: ClusterOptions);
     /**
      * Get the responsible subscriber.
      *
@@ -102,4 +104,5 @@ export default class ClusterSubscriberGroup {
      * @param nodeKey
      */
     private handleSubscriberConnectSucceeded;
+    private shouldStartSubscriber;
 }

package/built/cluster/ClusterSubscriberGroup.js

@@ -20,8 +20,9 @@ class ClusterSubscriberGroup {
      *
      * @param cluster
      */
-    constructor(subscriberGroupEmitter) {
+    constructor(subscriberGroupEmitter, options) {
         this.subscriberGroupEmitter = subscriberGroupEmitter;
+        this.options = options;
         this.shardedSubscribers = new Map();
         this.clusterSlots = [];
         // Simple [min, max] slot ranges aren't enough because you can migrate single slots
@@ -68,7 +69,18 @@ class ClusterSubscriberGroup {
      */
     getResponsibleSubscriber(slot) {
         const nodeKey = this.clusterSlots[slot][0];
-        return this.shardedSubscribers.get(nodeKey);
+        const sub = this.shardedSubscribers.get(nodeKey);
+        if (sub && sub.subscriberStatus === "idle") {
+            sub
+                .start()
+                .then(() => {
+                this.handleSubscriberConnectSucceeded(sub.getNodeKey());
+            })
+                .catch((err) => {
+                this.handleSubscriberConnectFailed(err, sub.getNodeKey());
+            });
+        }
+        return sub;
     }
     /**
      * Adds a channel for which this subscriber group is responsible
@@ -130,7 +142,7 @@ class ClusterSubscriberGroup {
     start() {
         const startPromises = [];
         for (const s of this.shardedSubscribers.values()) {
-            if (!s.isStarted()) {
+            if (this.shouldStartSubscriber(s)) {
                 startPromises.push(s
                     .start()
                     .then(() => {
@@ -139,6 +151,7 @@ class ClusterSubscriberGroup {
                     .catch((err) => {
                     this.handleSubscriberConnectFailed(err, s.getNodeKey());
                 }));
+                this.subscriberGroupEmitter.emit("+subscriber");
             }
         }
         return Promise.all(startPromises);
@@ -162,9 +175,9 @@ class ClusterSubscriberGroup {
             // 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
+                // If the subscriber is still responsible for a slot range and is healthy then keep it
                 this.subscriberToSlotsIndex.has(nodeKey) &&
-                    shardedSubscriber.isStarted()) {
+                    shardedSubscriber.isHealthy()) {
                     debug("Skipping deleting subscriber for %s", nodeKey);
                     continue;
                 }
@@ -177,11 +190,31 @@ class ClusterSubscriberGroup {
             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)) {
+                const existingSubscriber = this.shardedSubscribers.get(nodeKey);
+                // If we already have a subscriber for this node, only ensure it is healthy
+                // when it now owns slots with active channel subscriptions.
+                if (existingSubscriber && existingSubscriber.isHealthy()) {
                     debug("Skipping creating new subscriber for %s", nodeKey);
+                    if (!existingSubscriber.isStarted() &&
+                        this.shouldStartSubscriber(existingSubscriber)) {
+                        startPromises.push(existingSubscriber
+                            .start()
+                            .then(() => {
+                            this.handleSubscriberConnectSucceeded(nodeKey);
+                        })
+                            .catch((error) => {
+                            this.handleSubscriberConnectFailed(error, nodeKey);
+                        }));
+                    }
                     continue;
                 }
+                // If we have an existing subscriber but it is not healthy, stop it
+                if (existingSubscriber && !existingSubscriber.isHealthy()) {
+                    debug("Replacing subscriber for %s", nodeKey);
+                    existingSubscriber.stop();
+                    this.shardedSubscribers.delete(nodeKey);
+                    this.subscriberGroupEmitter.emit("-subscriber");
+                }
                 debug("Creating new subscriber for %s", nodeKey);
                 // Otherwise create a new subscriber
                 const redis = clusterNodes.find((node) => {
@@ -191,16 +224,18 @@ class ClusterSubscriberGroup {
                     debug("Failed to find node for key %s", nodeKey);
                     continue;
                 }
-                const sub = new ShardedSubscriber_1.default(this.subscriberGroupEmitter, redis.options);
+                const sub = new ShardedSubscriber_1.default(this.subscriberGroupEmitter, redis.options, this.options.redisOptions);
                 this.shardedSubscribers.set(nodeKey, sub);
-                startPromises.push(sub
-                    .start()
-                    .then(() => {
-                    this.handleSubscriberConnectSucceeded(nodeKey);
-                })
-                    .catch((error) => {
-                    this.handleSubscriberConnectFailed(error, nodeKey);
-                }));
+                if (this.shouldStartSubscriber(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
@@ -228,7 +263,8 @@ class ClusterSubscriberGroup {
      */
     _refreshSlots(targetSlots) {
         //If there was an actual change, then reassign the slot ranges
-        if (this._slotsAreEqual(targetSlots)) {
+        // Also rebuild if subscriberToSlotsIndex is empty (e.g., after stop() was called)
+        if (this._slotsAreEqual(targetSlots) && this.subscriberToSlotsIndex.size > 0) {
             debug("Nothing to refresh because the new cluster map is equal to the previous one.");
             return false;
         }
@@ -262,7 +298,7 @@ class ClusterSubscriberGroup {
                         const redis = s.getInstance();
                         const channels = this.channels.get(ss);
                         if (channels && channels.length > 0) {
-                            if (redis.status === "end") {
+                            if (!redis || redis.status === "end") {
                                 return;
                             }
                             if (redis.status === "ready") {
@@ -309,10 +345,26 @@ class ClusterSubscriberGroup {
      * @returns true if any subscribers need to be recreated
      */
     hasUnhealthySubscribers() {
-        const hasFailedSubscribers = Array.from(this.shardedSubscribers.values()).some((sub) => !sub.isStarted());
+        const hasFailedSubscribers = Array.from(this.shardedSubscribers.values()).some((sub) => !sub.isHealthy());
         const hasMissingSubscribers = Array.from(this.subscriberToSlotsIndex.keys()).some((nodeKey) => !this.shardedSubscribers.has(nodeKey));
         return hasFailedSubscribers || hasMissingSubscribers;
     }
+    shouldStartSubscriber(sub) {
+        if (sub.isStarted()) {
+            return false;
+        }
+        if (!sub.isLazyConnect()) {
+            return true;
+        }
+        const subscriberSlots = this.subscriberToSlotsIndex.get(sub.getNodeKey());
+        if (!subscriberSlots) {
+            return false;
+        }
+        return subscriberSlots.some((slot) => {
+            const channels = this.channels.get(slot);
+            return Boolean(channels && channels.length > 0);
+        });
+    }
 }
 exports.default = ClusterSubscriberGroup;
 // Retry strategy

package/built/cluster/ShardedSubscriber.d.ts

@@ -2,19 +2,35 @@
 import EventEmitter = require("events");
 import { RedisOptions } from "./util";
 import Redis from "../Redis";
+import { ClusterOptions } from "./ClusterOptions";
+declare const SubscriberStatus: {
+    readonly IDLE: "idle";
+    readonly STARTING: "starting";
+    readonly CONNECTED: "connected";
+    readonly STOPPING: "stopping";
+    readonly ENDED: "ended";
+};
+declare type SubscriberStatus = typeof SubscriberStatus[keyof typeof SubscriberStatus];
 export default class ShardedSubscriber {
     private readonly emitter;
     private readonly nodeKey;
-    private started;
+    private status;
     private instance;
+    private connectPromise;
+    private lazyConnect;
     private readonly messageListeners;
-    constructor(emitter: EventEmitter, options: RedisOptions);
-    private onEnd;
-    private onError;
-    private onMoved;
+    constructor(emitter: EventEmitter, options: RedisOptions, redisOptions?: ClusterOptions["redisOptions"]);
     start(): Promise<void>;
     stop(): void;
     isStarted(): boolean;
+    get subscriberStatus(): SubscriberStatus;
+    isHealthy(): boolean;
     getInstance(): Redis | null;
     getNodeKey(): string;
+    isLazyConnect(): boolean;
+    private onEnd;
+    private onError;
+    private onMoved;
+    private updateStatus;
 }
+export {};