# @imqueue/core 3.3.2 · API reference

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

Redis-backed message queue engine for the `@imqueue` framework — the transport shared by `@imqueue/rpc` and the job packages.

Start from `IMQ.create()`, which picks a queue adapter from the options and returns an unstarted `IMessageQueue`. The two concrete adapters are `RedisQueue` (a single Redis server) and `ClusteredRedisQueue` (several servers, with sends distributed between them), and either can also be constructed directly.

## Remarks

Every queue follows the same lifecycle: construct, `start()`, then either consume `message` events or `send()`, and finally `destroy()` to release the connections. `start()` is required before `publish()` or `subscribe()`; `send()` starts the queue implicitly. `stop()` only stops consuming — it keeps the writer, the watcher lock and the maintenance timers alive, so `destroy()` is what actually releases resources.

Delivery is at-least-once, so message handlers must be idempotent. Within a single process, writer and watcher connections are shared per `host:port` and reference-counted, and exactly one queue per key prefix is elected as the watcher that releases delayed messages and performs maintenance.

## Example


```typescript
import IMQ, { IMQMode, type IMessageQueue } from '@imqueue/core';

const queue: IMessageQueue = IMQ.create('my-queue', {
    host: 'localhost',
    port: 6379,
});

queue.on('message', (message, id, from) => {
    console.log(`got ${id} from ${from}`, message);
});

await queue.start();
await queue.send('my-queue', { hello: 'world' });
```

## Classes


| Class | Description |
| --- | --- |
| [ClusteredRedisQueue](https://imqueue.org/api/core/latest/core.clusteredredisqueue/) | 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. |
| [IMQ](https://imqueue.org/api/core/latest/core.imq/) | Message queue factory. This is also the default export of `@imqueue/core`. |
| [RedisQueue](https://imqueue.org/api/core/latest/core.redisqueue/) | Redis-backed message queue with at-least-once delivery — the default [IMessageQueue](https://imqueue.org/api/core/latest/core.imessagequeue/) implementation, and what [IMQ.create()](https://imqueue.org/api/core/latest/core.imq.create/) returns for a single-server configuration. |
| [UDPClusterManager](https://imqueue.org/api/core/latest/core.udpclustermanager/) | Cluster manager that discovers redis cluster members from UDP broadcast announcements. Supply instances through [IMQOptions.clusterManagers](https://imqueue.org/api/core/latest/core.imqoptions.clustermanagers/). |


## Abstract Classes


| Abstract Class | Description |
| --- | --- |
| [ClusterManager](https://imqueue.org/api/core/latest/core.clustermanager/) | Abstract base for cluster-membership discovery. A manager tracks the clusters it feeds and pushes server add/remove events into each of them, so several clustered queues can share one discovery mechanism. Supply instances through [IMQOptions.clusterManagers](https://imqueue.org/api/core/latest/core.imqoptions.clustermanagers/). [UDPClusterManager](https://imqueue.org/api/core/latest/core.udpclustermanager/) is the implementation shipped with the framework. |


## Enumerations


| Enumeration | Description |
| --- | --- |
| [IMQMode](https://imqueue.org/api/core/latest/core.imqmode/) | Operating mode of a queue instance, selecting which halves of the queue are active. Passed as the third constructor argument and defaults to [IMQMode.BOTH](https://imqueue.org/api/core/latest/core.imqmode/). All modes still open a writer connection and take part in watcher election; the mode only controls whether a reader is created and whether sending is allowed. |
| [LogLevel](https://imqueue.org/api/core/latest/core.loglevel/) | Logger method to which profiling output is dispatched. Each value is the literal name of the corresponding [ILogger](https://imqueue.org/api/core/latest/core.ilogger/) method, so the level is used as a property lookup on the logger. |


## Functions


| Function | Description |
| --- | --- |
| [logDebugInfo(input)](https://imqueue.org/api/core/latest/core.logdebuginfo/) | Emits the profiling output for a single call: the elapsed time computed from `input.start`, and/or the call arguments serialized as indented JSON. |
| [profile(options)](https://imqueue.org/api/core/latest/core.profile/) | Wraps a class method so that its execution time and/or its call arguments are logged through the `logger` property of the decorated instance. |
| [verifyLogLevel(level)](https://imqueue.org/api/core/latest/core.verifyloglevel/) | Normalizes an arbitrary value into a [LogLevel](https://imqueue.org/api/core/latest/core.loglevel/). |


## Interfaces


| Interface | Description |
| --- | --- |
| [ClusterServer](https://imqueue.org/api/core/latest/core.clusterserver/) | A server registered in a [ClusteredRedisQueue](https://imqueue.org/api/core/latest/core.clusteredredisqueue/): its address, plus the [RedisQueue](https://imqueue.org/api/core/latest/core.redisqueue/) instance serving that host. Returned by [ClusteredRedisQueue.addServer()](https://imqueue.org/api/core/latest/core.clusteredredisqueue.addserver/) so callers can address or inspect one specific host of the cluster. |
| [DebugInfoOptions](https://imqueue.org/api/core/latest/core.debuginfooptions/) | Fully-resolved description of a single profiled call, as passed to [logDebugInfo()](https://imqueue.org/api/core/latest/core.logdebuginfo/). Normally constructed by the [profile()](https://imqueue.org/api/core/latest/core.profile/) decorator; supply it directly only to emit profiling output by hand. Every field except `logger` is required. |
| [EventMap](https://imqueue.org/api/core/latest/core.eventmap/) | Typed event map for a queue's `EventEmitter` base, giving compile-time signatures for the only two events a queue emits. |
| [ICluster](https://imqueue.org/api/core/latest/core.icluster/) | Membership callbacks a clustered queue hands to a [ClusterManager](https://imqueue.org/api/core/latest/core.clustermanager/) so the manager can add and remove servers as it discovers them. Implement this to feed a clustered queue from your own discovery mechanism; [ClusteredRedisQueue](https://imqueue.org/api/core/latest/core.clusteredredisqueue/) supplies an implementation of its own. |
| [ILogger](https://imqueue.org/api/core/latest/core.ilogger/) | Minimal logging contract the framework writes diagnostics through. The global `console` satisfies it, and it is the default. Pass an implementation as [IMQOptions.logger](https://imqueue.org/api/core/latest/core.imqoptions.logger/) to redirect queue output, or a no-op implementation to silence it. The method names match the members of [LogLevel](https://imqueue.org/api/core/latest/core.loglevel/), so a level can be used as a property lookup on a logger. |
| [IMessage](https://imqueue.org/api/core/latest/core.imessage/) | Internal envelope of a queued message as it is stored in Redis: a generated id, the caller's payload, and the name of the queue that sent it. |
| [IMessageQueue](https://imqueue.org/api/core/latest/core.imessagequeue/) | Contract every messaging queue implementation fulfils. Implement it to add a transport of your own, or program against it to stay adapter-agnostic. A queue is an `EventEmitter` typed by [EventMap](https://imqueue.org/api/core/latest/core.eventmap/), so it emits exactly two events: `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. The `error` event fires only when a listener is attached — attach one if background failures must be observed. |
| [IMessageQueueAuthConnection](https://imqueue.org/api/core/latest/core.imessagequeueauthconnection/) | Optional credentials for a queue host, forwarded to the Redis client as `username` and `password`. Supply both for a Redis ACL user, or just `password` for a `requirepass`-only server. Omit both to connect unauthenticated, which is the default. |
| [IMessageQueueConnection](https://imqueue.org/api/core/latest/core.imessagequeueconnection/) | A single queue-host endpoint: where to connect and, optionally, how to authenticate. |
| [IMQOptions](https://imqueue.org/api/core/latest/core.imqoptions/) | Options accepted by every queue implementation. Anything omitted falls back to [DEFAULT\_IMQ\_OPTIONS](https://imqueue.org/api/core/latest/core.default_imq_options/) — `localhost:6379`, prefix `imq`, cleanup off, safe delivery off, gzip off, a 5000 ms watcher check and safe-delivery TTL, and signal handling on. |
| [InitializedCluster](https://imqueue.org/api/core/latest/core.initializedcluster/) | A cluster that has been registered with a [ClusterManager](https://imqueue.org/api/core/latest/core.clustermanager/), carrying the generated id that identifies it for [ClusterManager.remove()](https://imqueue.org/api/core/latest/core.clustermanager.remove/). |
| [IRedisClient](https://imqueue.org/api/core/latest/core.iredisclient/) | The ioredis `Redis` client type augmented with the two internal bookkeeping flags imq stamps onto the connections it creates. Not intended for use as an option or parameter type by consumers. |
| [IServerInput](https://imqueue.org/api/core/latest/core.iserverinput/) | Address of a cluster server, as supplied to the cluster membership operations [ICluster.add](https://imqueue.org/api/core/latest/core.icluster.add/), [ICluster.remove](https://imqueue.org/api/core/latest/core.icluster.remove/) and [ICluster.find](https://imqueue.org/api/core/latest/core.icluster.find/). |
| [JsonArray](https://imqueue.org/api/core/latest/core.jsonarray/) | Represents JSON-serializable array |
| [JsonObject](https://imqueue.org/api/core/latest/core.jsonobject/) | Represents JSON serializable object |
| [ProfileDecoratorOptions](https://imqueue.org/api/core/latest/core.profiledecoratoroptions/) | Options accepted by the [profile()](https://imqueue.org/api/core/latest/core.profile/) decorator. Every field is optional; omitted fields fall back to the [IMQ\_LOG\_TIME](https://imqueue.org/api/core/latest/core.imq_log_time/), [IMQ\_LOG\_ARGS](https://imqueue.org/api/core/latest/core.imq_log_args/) and [IMQ\_LOG\_LEVEL](https://imqueue.org/api/core/latest/core.imq_log_level/) environment defaults. |
| [UDPClusterManagerOptions](https://imqueue.org/api/core/latest/core.udpclustermanageroptions/) | Configuration for [UDPClusterManager](https://imqueue.org/api/core/latest/core.udpclustermanager/). Pass any subset to the constructor; unspecified values come from [DEFAULT\_UDP\_CLUSTER\_MANAGER\_OPTIONS](https://imqueue.org/api/core/latest/core.default_udp_cluster_manager_options/). |


## Variables


| Variable | Description |
| --- | --- |
| [DEFAULT\_IMQ\_OPTIONS](https://imqueue.org/api/core/latest/core.default_imq_options/) | Default option values applied to every queue instance: `localhost:6379`, prefix `imq`, `console` as the logger, cleanup off with filter `'*'`, safe delivery off with a 5000 ms lease TTL, gzip off, a 5000 ms watcher check interval, and process signal handling on. |
| [DEFAULT\_UDP\_CLUSTER\_MANAGER\_OPTIONS](https://imqueue.org/api/core/latest/core.default_udp_cluster_manager_options/) | Default options applied to every [UDPClusterManager](https://imqueue.org/api/core/latest/core.udpclustermanager/) unless overridden: broadcast address `255.255.255.255` on port `63000`, a 5000 ms alive-timeout correction, liveness checking enabled, process signal handling enabled, and `console` as the logger. |
| [IMQ\_CONNECTION\_QUIT\_TIMEOUT](https://imqueue.org/api/core/latest/core.imq_connection_quit_timeout/) | Grace period (ms) for a graceful QUIT to complete before a channel is forcibly disconnected. A reader blocked on an infinite BRPOP/BLMOVE can never let QUIT through, so without this the socket would leak and keep the process alive. |
| [IMQ\_LOG\_ARGS](https://imqueue.org/api/core/latest/core.imq_log_args/) | Whether call-argument profiling is on by default, from the `IMQ_LOG_ARGS` environment variable. |
| [IMQ\_LOG\_LEVEL](https://imqueue.org/api/core/latest/core.imq_log_level/) | Default logger method for profiling output, from the `IMQ_LOG_LEVEL` environment variable. Accepts `log`, `info`, `warn` or `error`; any other or missing value resolves to `info` without warning. |
| [IMQ\_LOG\_TIME\_FORMAT](https://imqueue.org/api/core/latest/core.imq_log_time_format/) | Unit used when rendering profiled execution time, from the `IMQ_LOG_TIME_FORMAT` environment variable. Accepts `microseconds`, `milliseconds` or `seconds`, and defaults to `microseconds`. |
| [IMQ\_LOG\_TIME](https://imqueue.org/api/core/latest/core.imq_log_time/) | Whether execution-time profiling is on by default, from the `IMQ_LOG_TIME` environment variable. |
| [IMQ\_SHUTDOWN\_TIMEOUT](https://imqueue.org/api/core/latest/core.imq_shutdown_timeout/) | Time in milliseconds allowed for releasing watcher locks when a shutdown signal is received, before the process is force-exited. Defaults to 1000; override with the `IMQ_SHUTDOWN_TIMEOUT` environment variable. |


## Type Aliases


| Type Alias | Description |
| --- | --- |
| [AllowedTimeFormat](https://imqueue.org/api/core/latest/core.allowedtimeformat/) | Units in which profiled execution time can be rendered. |
| [AnyJson](https://imqueue.org/api/core/latest/core.anyjson/) | Any JSON value. |
| [IMessageQueueConstructor](https://imqueue.org/api/core/latest/core.imessagequeueconstructor/) | Constructor contract every queue adapter must satisfy: it takes the queue name, optional partial options and an optional [IMQMode](https://imqueue.org/api/core/latest/core.imqmode/), and yields an [IMessageQueue](https://imqueue.org/api/core/latest/core.imessagequeue/). [IMQ.create()](https://imqueue.org/api/core/latest/core.imq.create/) resolves an adapter of this shape from the registered vendor adapters and instantiates it. |
| [UDPWorkerOptions](https://imqueue.org/api/core/latest/core.udpworkeroptions/) | The options actually handed to the UDP worker thread: everything except the logger, which is not structured-cloneable, and the signal-handling flag, which the main thread owns. |