# IMessageQueue interface · @imqueue/core

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

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.

**Signature:**

```typescript
export interface IMessageQueue extends EventEmitter<EventMap> 
```
**Extends:** EventEmitter<[EventMap](https://imqueue.org/api/core/latest/core.eventmap/)>

## Example

Implementing an adapter:

```typescript
import {
    type IMessageQueue,
    type EventMap,
    type JsonObject,
    EventEmitter,
} from '@imqueue/core';
import { randomUUID } from 'node:crypto';

class SomeMQAdapter extends EventEmitter<EventMap>
    implements IMessageQueue
{
    public async start(): Promise<SomeMQAdapter> {
        // ... implementation goes here
        return this;
    }
    public async stop(): Promise<SomeMQAdapter> {
        // ... implementation goes here
        return this;
    }
    public async send(
        toQueue: string,
        message: JsonObject,
        delay?: number,
    ): Promise<string> {
        const messageId = randomUUID();
        // ... implementation goes here
        return messageId;
    }
    public async subscribe(
        channel: string,
        handler: (data: JsonObject) => void,
    ): Promise<void> {
        // ... implementation goes here
    }
    public async unsubscribe(): Promise<void> {
        // ... implementation goes here
    }
    public async publish(
        data: JsonObject,
        toName?: string,
    ): Promise<void> {
        // ... implementation goes here
    }
    public async queueLength(): Promise<number> {
        // ... implementation goes here
        return 0;
    }
    public async clear(): Promise<SomeMQAdapter> {
        // ... implementation goes here
        return this;
    }
    public async destroy(): Promise<void> {
        // ... implementation goes here
    }
}
```

## Methods


| Method | Description |
| --- | --- |
| [clear()](https://imqueue.org/api/core/latest/core.imessagequeue.clear/) | Deletes this queue's pending messages — both the main list and the delayed set for `<prefix>:<name>`. |
| [destroy()](https://imqueue.org/api/core/latest/core.imessagequeue.destroy/) | Releases this queue handle: removes all event listeners, stops the maintenance timers, releases the watcher lock if held, disconnects the reader, and drops this instance's reference to the shared writer. |
| [publish(data, toName)](https://imqueue.org/api/core/latest/core.imessagequeue.publish/) | Publishes data to the current queue channel If toName is specified, publishes to a pubsub with a different name. This can be used to broadcast messages to other subscribers on different pubsub channels. Different names must be in the same namespace (same imq prefix). |
| [queueLength()](https://imqueue.org/api/core/latest/core.imessagequeue.queuelength/) | Returns the number of messages currently waiting in this queue's main list. |
| [send(toQueue, message, delay, errorHandler)](https://imqueue.org/api/core/latest/core.imessagequeue.send/) | Sends a message to the specified queue with the given data. |
| [start()](https://imqueue.org/api/core/latest/core.imessagequeue.start/) | Starts the queue: opens its connections, joins watcher election and begins consuming, so `message` events start arriving. |
| [stop()](https://imqueue.org/api/core/latest/core.imessagequeue.stop/) | Stops consuming, so no further `message` events fire. |
| [subscribe(channel, handler)](https://imqueue.org/api/core/latest/core.imessagequeue.subscribe/) | Subscribes to the pub/sub channel with the given name and registers a handler for the data it delivers. The effective channel is `<prefix>:<channel>`. |
| [unsubscribe()](https://imqueue.org/api/core/latest/core.imessagequeue.unsubscribe/) | Closes the subscription channel and drops every handler registered through [IMessageQueue.subscribe()](https://imqueue.org/api/core/latest/core.imessagequeue.subscribe/), resetting the instance so a later subscription may use a different channel name. |