IMessageQueue interface

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, 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:

export interface IMessageQueue extends EventEmitter<EventMap>

Extends: EventEmitter<EventMap>

Example

Implementing an adapter:

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()	Deletes this queue's pending messages — both the main list and the delayed set for `<prefix>:<name>`.
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)	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()	Returns the number of messages currently waiting in this queue's main list.
send(toQueue, message, delay, errorHandler)	Sends a message to the specified queue with the given data.
start()	Starts the queue: opens its connections, joins watcher election and begins consuming, so `message` events start arriving.
stop()	Stops consuming, so no further `message` events fire.
subscribe(channel, handler)	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()	Closes the subscription channel and drops every handler registered through IMessageQueue.subscribe(), resetting the instance so a later subscription may use a different channel name.

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