# ClusteredRedisQueue class · @imqueue/core

Source: https://imqueue.org/api/core/latest/core.clusteredredisqueue/
Published: 2026-08-04
Author: @imqueue maintainers (https://github.com/imqueue)
Package: @imqueue/core 3.3.2 — generated reference, not hand-written

Scales a single logical queue horizontally across several redis instances. This is what [IMQ.create()](https://imqueue.org/api/core/latest/core.imq.create/) returns when [IMQOptions.cluster](https://imqueue.org/api/core/latest/core.imqoptions.cluster/) or [IMQOptions.clusterManagers](https://imqueue.org/api/core/latest/core.imqoptions.clustermanagers/) is supplied.

**Signature:**

```typescript
export declare class ClusteredRedisQueue implements IMessageQueue, EventEmitter<EventMap> 
```
**Implements:** [IMessageQueue](https://imqueue.org/api/core/latest/core.imessagequeue/), EventEmitter<[EventMap](https://imqueue.org/api/core/latest/core.eventmap/)>

## Remarks

Distribution is asymmetric, and this is the most important thing to know about the class: [ClusteredRedisQueue.send()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.send/) routes each message to exactly one server, chosen by health-aware round-robin that skips instances whose writer connection is not ready. Every other operation — `start`, `stop`, `clear`, `destroy`, `publish`, `subscribe`, `unsubscribe` and `queueLength` — fans out to every server.

Every fan-out uses `Promise.all`, so one failing host fails the whole call with no partial-failure reporting and no rollback.

The class only `implements` the `EventEmitter` interface rather than extending it, so `instanceof EventEmitter` is false and every emitter method is a delegating shim — see the individual methods for their fan-out semantics, and note in particular that [ClusteredRedisQueue.once()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.once/) is per-server.

## Constructors


| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(name, options, \_mode)](https://imqueue.org/api/core/latest/core.clusteredredisqueue._constructor_/) |  | Creates a clustered queue. |


## Properties


| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [logger](https://imqueue.org/api/core/latest/core.clusteredredisqueue.logger/) |  | [ILogger](https://imqueue.org/api/core/latest/core.ilogger/) | Logger used for this cluster's own messages, defaulting to [IMQOptions.logger](https://imqueue.org/api/core/latest/core.imqoptions.logger/) or `console`. |
| [name](https://imqueue.org/api/core/latest/core.clusteredredisqueue.name/) |  | string | Name of this queue, used as the queue name for every per-host queue in the cluster. |


## Methods


| Method | Modifiers | Description |
| --- | --- | --- |
| [addListener(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.addlistener/) |  | Registers a listener on every server's queue and on the internal template. Alias of [ClusteredRedisQueue.on()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.on/). |
| [addServer(server)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.addserver/) | `protected` | Adds a single server to the cluster and returns its registration record. |
| [clear()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.clear/) |  | Deletes this queue's data on every redis host in the cluster, concurrently. |
| [destroy()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.destroy/) |  | Destroys every server's queue — closing their connections and removing their event listeners — then unregisters this cluster from all configured cluster managers. |
| [emit(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.emit/) |  | Emits an event on every server's queue and on the internal template, so each listener registered through this class runs once per server. |
| [eventNames()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.eventnames/) |  | Returns the event names reported by a single representative emitter. |
| [getMaxListeners()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.getmaxlisteners/) |  | Returns the maximum listener count of the internal template emitter. |
| [listenerCount(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.listenercount/) |  | Returns the listener count reported by a single representative emitter. |
| [listeners(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.listeners/) |  | Returns the listeners of every server's queue plus the internal template, concatenated. |
| [off(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.off/) |  | Removes a listener from every server's queue and from the internal template. |
| [on(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.on/) |  | Registers a listener on every server's queue and on the internal template used to seed servers that join later. |
| [once(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.once/) |  | Registers a one-shot listener on every server's queue and on the internal template. |
| [prependListener(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.prependlistener/) |  | Registers a listener at the front of the queue on every server's queue and on the internal template. |
| [prependOnceListener(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.prependoncelistener/) |  | Registers a one-shot listener at the front of the queue on every server's queue and on the internal template. |
| [publish(data, toName)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.publish/) |  | Publishes the payload on every redis host in the cluster. |
| [queueLength()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.queuelength/) |  | Returns the total number of messages waiting, summed across every redis host in the cluster. |
| [rawListeners(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.rawlisteners/) |  | Returns the raw listeners of every server's queue plus the internal template, concatenated. |
| [removeAllListeners(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.removealllisteners/) |  | Removes every listener from every server's queue and from the internal template, so servers that join later also start clean. |
| [removeListener(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.removelistener/) |  | Removes a listener from every server's queue and from the internal template. Alias of [ClusteredRedisQueue.off()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.off/). |
| [removeServer(server)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.removeserver/) | `protected` | Removes a server from the cluster, matching by `id` or by host and port. |
| [send(toQueue, message, delay, errorHandler)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.send/) |  | Sends a message to one server of the cluster, selected by health-aware round-robin. |
| [setMaxListeners(args)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.setmaxlisteners/) |  | Sets the maximum listener count on every server's queue and on the internal template. |
| [start()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.start/) |  | Starts every server's queue concurrently. |
| [stop()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.stop/) |  | Stops message handling on every server concurrently. |
| [subscribe(channel, handler)](https://imqueue.org/api/core/latest/core.clusteredredisqueue.subscribe/) |  | Subscribes the given handler on every redis host in the cluster, and remembers the subscription so servers that join later are subscribed automatically. |
| [unsubscribe()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.unsubscribe/) |  | Unsubscribes from the channel on every redis host and forgets the remembered subscription, so servers joining later are no longer subscribed automatically. |