RedisQueue class

Redis-backed message queue with at-least-once delivery — the default IMessageQueue implementation, and what IMQ.create() returns for a single-server configuration.

Signature:

export declare class RedisQueue extends EventEmitter<EventMap> implements IMessageQueue

Extends: EventEmitter<EventMap>

Implements: IMessageQueue

Remarks

Connection model: the reader is per instance and exists only in IMQMode.BOTH or IMQMode.WORKER mode, while the writer and watcher connections are shared per host:port across every queue in the process and reference-counted. Exactly one queue per key prefix is elected as the watcher through a <prefix>:watch:lock key, and that owner also releases delayed messages, recovers abandoned safe-delivery hand-offs and — when IMQOptions.cleanup is on — prunes orphaned keys.

Lifecycle: RedisQueue.start() is required before consuming or publishing, while RedisQueue.send() starts the queue lazily. RedisQueue.stop() only stops consuming; use RedisQueue.destroy() to release the watcher lock, the timers and the connections.

Reconnection is handled by the queue itself — ioredis's own retry strategy is disabled in favour of a capped exponential backoff from 1 s to 30 s per channel.

Events (typed by EventMap): message, with the payload, the message id and the sending queue's name; and error, with the error and the name of the internal routine that caught it (OnMessage, OnProcessDelayed, OnSafeDelivery, OnWatch, OnConfig, OnScriptLoad, OnReadUnsafe or OnReadSafe). Background errors are emitted only when at least one error listener is attached — otherwise they are logged and swallowed, so attach one if you need to observe them.

Constructors

Constructor	Modifiers	Description
(constructor)(name, options, mode)		Creates a queue handle. No connection is opened here — call RedisQueue.start(), or RedisQueue.send(), which starts the queue implicitly.

Properties

Property	Modifiers	Type	Description
available	`readonly`	boolean	Returns false only when this queue is known to be unable to accept writes right now — i.e., it has a writer connection currently in a non-ready (reconnecting/closed) state. A queue that has not yet connected is considered available, since sending connects it lazily. Used for health-aware routing in the clustered queue.
name		string	The queue name. The underlying redis list key is `<prefix>:<name>`, the same name is the default pub/sub channel used by RedisQueue.publish(), and it is the `from` value carried by messages this queue sends.
options		IMQOptions	The effective options for this queue: DEFAULT_IMQ_OPTIONS merged with the values passed to the constructor.
redisKey	`readonly`	string	The `host:port` address of the redis server this queue talks to.

Methods

Method	Modifiers	Description
clear()		Deletes this queue's message list and its delayed-message set from redis.
destroy(clearData)		Gracefully destroys this queue handle. Does not remove queue data from redis unless clearData is explicitly set to true, so that destroying one handle (e.g., on scale-down) never wipes messages still pending for other producers/consumers.
isPublisher()		Returns true if publisher mode is enabled on this queue, false otherwise.
isWorker()		Returns true if worker mode is enabled on this queue, false otherwise.
publish(data, toName)		Publishes a message to this queue subscription channel for currently subscribed clients. If toName specified will publish to PubSub with a different name. This can be used to implement broadcasting some messages to other subscribers on other PubSub channels.
queueLength()		Returns the number of messages currently waiting in this queue's main list.
send(toQueue, message, delay, errorHandler)		Sends a given message to a given queue (by name).
start()		Initializes and starts current queue routines: opens the writer (and, in IMQMode.BOTH or IMQMode.WORKER mode, the reader), joins watcher election and starts the periodic watcher check.
stop()		Stops consuming messages by tearing down this instance's reader connection.
subscribe(channel, handler)		Creates a subscription channel over redis and sets up channel data read handler. The effective Redis channel is `<prefix>:<channel>`.
unsubscribe()		Closes the subscription connection and forgets the channel name together with every handler registered through RedisQueue.subscribe().

Read this page as plain markdown — no HTML, no navigation. For pasting into an LLM, or for an agent to fetch.