# exframe-mq

> Messaging framework module

Latest version **5.3.5** (published 2026-10-29) · ISC license · 0 weekly downloads

## Install

```sh
npm install exframe-mq
pnpm add exframe-mq
yarn add exframe-mq
bun add exframe-mq
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 5.3.5 |
| Published | 2026-10-29 |
| First published | 2016-11-10 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=14.0.0 |
| Dependencies | 4 |
| Unpacked size | 188.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Exzeo |
| Maintainers | exzeodevops |

## Links

- npm: https://www.npmjs.com/package/exframe-mq
- Repository: https://bitbucket.org/exzeo-usa/exframe
- Homepage: https://bitbucket.org/exzeo-usa/exframe#readme
- Issues: https://bitbucket.org/exzeo-usa/exframe/issues
- npm.io page: https://npm.io/package/exframe-mq

## Dependencies (4)

- [amqplib](https://npm.io/package/amqplib.md) 0.x
- [@types/amqplib](https://npm.io/package/@types/amqplib.md) 0.x
- [exframe-errors](https://npm.io/package/exframe-errors.md) ^1.0.0
- [exframe-utilities](https://npm.io/package/exframe-utilities.md) ^1.0.0

## Recent versions

- 5.3.5 (latest) — 2026-10-29
- 5.3.4 — 2026-08-13
- 5.3.3 — 2026-07-17
- 5.3.2 — 2026-06-12
- 5.3.1 — 2026-05-26
- 5.3.0 — 2026-05-18
- 5.2.0 — 2025-06-13
- 5.1.4 — 2025-04-10
- 5.1.3 — 2025-02-24
- 5.1.2 — 2023-11-21
- 5.1.1 — 2023-10-10
- 5.1.0 — 2023-09-07
- 5.0.8 — 2023-08-15
- 5.0.7 — 2023-04-12
- 5.0.6 — 2023-02-17
- … 65 more at https://npm.io/package/exframe-mq/versions

## README

exframe Messaging Framework Module
====================================

A simplified abstraction for RabbitMQ.

### Features and Assumptions
* Persistant and shared connections
* Assumes JSON payload
* Default connection settings

### Available Topologies
* Publish/Subscribe

### Usage
```javascript
const mq = require("exframe-mq");
const rabbitmq = mq.create({
  logger,

  url: 'amqp://localhost',
  heartbeat: 30,
  baseTimeout: 500,
  maxAttempts: 5,
  responseTimeout: 60 * 1000
});
```

#### Configuration Settings

- `logger` - See [winston logger](https://www.npmjs.com/package/winston) for interface of the logger. A default implementation will write to the stdout
- `url` - _default: 'amqp://localhost'_ The url for the rabbitmq server
- `heartbeat` - _default: 30_ Time in seconds for a heartbeat between the client code and the rabbitmq server. Basically, keeps the connection alive with inactivity particularly if the connection will be closed by external mechanisms like Amazon's ELB.
- `baseTimeout` - _default: 500_ Time in milliseconds for waiting between connection failures
- `maxAttempts` - _default: 190_ Max number of attempts to try connecting to the rabbitmq server.
- `responseTimeout` - _default: 60000_ Time in milliseconds for re-establishing a connection with the rabbitmq server after inactivity.

#### Environment Variable Configuration Settings

- `MQ_MAX_ATTEMPTS` - _default: 190_ Max number of attempts to try and connect to the rabbitmq server.
- `MQ_EXIT_ON_FAILURE` - _default: false_ Whether or not the application should fail on FIRST attempt at message queue connection.

### Methods

#### getConnection
Gets the connection used to communicate to the rabbitmq server with.

```javascript
const connection = await mq.getConnection();
```

#### client
Creates a client to the configured rabbitmq server. For subscribing to and publishing messages.

```javascript
const client = mq.client(options);
```
Arguments:
- `options` - _optional_ _object_
  - `eventing` - _optional_ _object_ The configuration rpc publishing events to the eventing microservice.
    - `exchangeName` - _string_ The exchange to publish events to the eventing microservice
    - `routingKey` - _string_ The routing key to route events to the eventing microservice

Returns:
- `Client`

### Client

#### subscribe
Subscribes to a given exchange and routing key pattern. Will ensure the existence of the exchange and the queue matching on the routing key pattern with the given options.

The subscribe method will take a series of middleware for error handling and message processing. Middleware are expected to return promises that resolve with or without values.

```javascript
client.subscribe(exchangeName, routingKey, async (context, message) => {
  // do something with the message
});
```
for recieving some extra params in callback use default params 
default param can be null or empty object or we can set any value
```javascript
client.subscribe(exchangeName, routingKey, async (context, message, extraParams = {}) => {
  // do something with the message
});
```

Arguments:
- `exchangeName` - _string_ The exchange to publish the message to
- `routingKey` - _string_ The routing key for the exchange, governs which subscription to send the message to
- `message` - _object_ The message passed from the server. If a context field was part of the message, the contents of the object will have been merged into the context object and the field will be removed from the message.
- `...middleware` - One or more message or error handling functions. See [middleware functions](#middleware-functions)
- `options` - _optional_, _object_
  - `exchangeType` - _string, default: 'topic'_ The type of exchange the message will be published to see [rabbitmq documentation](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges). Valid values: 'topic', 'fanout', 'direct'
  - `exchangeOptions` - _object_ options for the creation of the exchange see [amqplib documentation](http://www.squaremobius.net/amqp.node/channel_api.html#channel_assertExchange)
    - Default Options
      - `durable` - _boolean, default: true_
  - `publishOptions` - _object_ options for the publishing of the message see [amqplib documentation](http://www.squaremobius.net/amqp.node/channel_api.html#channel_publish)
    - Default Options
      - `mandatory` - _boolean, default: true_
  - `exclusiveQueue` - _boolean, default: false_ If true, the created queue will be exclusive to that connection / channel. This is generally used for short lived temporary queues that need to handle an ephemeral set of messages. Closing the subscription will close this queue.

#### publish
Publishes a message to a given exchange and routing key. If the exchange does not exist, will create the exchange with the given options.

```javascript
await client.publish(context, exchangeName, routingKey, message, options)
```

Arguments:
- `context` - See [context object](#context-object)
  - expects `log`
- `exchangeName` - _string_ The exchange to publish the message to
- `routingKey` - _string_ The routing key for the exchange, governs which subscription to send the message to
- `message` - _object_ The message passed from the server. If a context field was part of the message, the contents of the object will have been merged into the context object and the field will be removed from the message.
- `options` - _optional_, _object_
  - `exchangeType` - _string, default: 'topic'_ The type of exchange the message will be published to see [rabbitmq documentation](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges). Valid values: 'topic', 'fanout', 'direct'
  - `exchangeOptions` - _object_ options for the creation of the exchange see [amqplib documentation](http://www.squaremobius.net/amqp.node/channel_api.html#channel_assertExchange)
    - Default Options
      - `durable` - _boolean, default: true_
  - `publishOptions` - _object_ options for the publishing of the message see [amqplib documentation](http://www.squaremobius.net/amqp.node/channel_api.html#channel_publish)
    - Default Options
      - `mandatory` - _boolean, default: true_

#### rpc
RPCs to a given exchange and routing key. If the exchange does not exist, will create the exchange with the given options. Will resolve or reject with the response from the subscribed client. If the subscribing service takes too long, rpc will reject with a timeout error.

```javascript
const response = await client.rpc(context, exchangeName, routingKey, message, options)
```

Arguments:
- `context` - See [context object](#context-object)
  - expects `log`
- `exchangeName` - _string_ The exchange to publish the message to
- `routingKey` - _string_ The routing key for the exchange, governs which subscription to send the message to
- `message` - _object_ The message passed from the server. If a context field was part of the message, the contents of the object will have been merged into the context object and the field will be removed from the message.
- `options` - _optional_, _object_
  - `exchangeType` - _string, default: 'topic'_ The type of exchange the message will be published to see [rabbitmq documentation](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges). Valid values: 'topic', 'fanout', 'direct'
  - `exchangeOptions` - _object_ options for the creation of the exchange see [amqplib documentation](http://www.squaremobius.net/amqp.node/channel_api.html#channel_assertExchange)
    - Default Options
      - `durable` - _boolean, default: true_
  - `publishOptions` - _object_ options for the publishing of the message see [amqplib documentation](http://www.squaremobius.net/amqp.node/channel_api.html#channel_publish)
    - Default Options
      - `mandatory` - _boolean, default: true_
  - `timeout` - _integer, default: 60000_ Time to wait for a response from the server.

Returns:
- `Promise<Response>` - _object_ The response from server

#### event
RPC an event to the eventing microservice, which adds the event to an event log and then publishes the event for consumption.

```javascript
const response = await client.event(context, documentId, routingKey, message, options)
```
Arguments:
- `context` - See [context object](#context-object)
  - expects `log`
- `documentId` - _string_ The document id associated with the event
- `routingKey` - _string_ The routing key subscribers for the event to be routed to
- `message` - _object_ The event data to pass to the consumer of the event.
- `options` - _optional_, _object_
  - `exchangeType` - _string, default: 'topic'_ The type of exchange the message will be published to see [rabbitmq documentation](https://www.rabbitmq.com/tutorials/amqp-concepts.html#exchanges). Valid values: 'topic', 'fanout', 'direct'
  - `exchangeOptions` - _object_ options for the creation of the exchange see [amqplib documentation](http://www.squaremobius.net/amqp.node/channel_api.html#channel_assertExchange)
    - Default Options
      - `durable` - _boolean, default: true_
  - `publishOptions` - _object_ options for the publishing of the message see [amqplib documentation](http://www.squaremobius.net/amqp.node/channel_api.html#channel_publish)
    - Default Options
      - `mandatory` - _boolean, default: true_
  - `timeout` - _integer, default: 60000_ Time to wait for a response from the server.

Returns:
- `Promise<Response>` - _object_ The response from server

#### use
Sets up global middleware for subscriptions. Middleware are expected to return promises that resolve with or without values.

```javascript
client.use(async (context, message) => {
  context.user = await authorizeUser(message.token);
});
client.use(async (error, context, message) => {
  context.log.error('error occurred', { errorData: error });
});
```
Arguments:
- `...middleware` - One or more message or error handling functions. See [middleware functions](#middleware-functions)

### Context Objects
Context objects are used to pass information from middleware to middleware. Just add additional fields to the context object as necessary. The context object is pre-populated upon the handling of a message or passed in by the calling code.

#### Subscription Generated Fields
- `requestId` - _string_ This is the request id associated with message. If a request id is not passed with the message context a request id will be generated, e.g., A1B2C3E4
- `log` - _object_ A logger that will take the interface of the [winston logger](https://www.npmjs.com/package/winston). If a logger was not passed a default logger will be used that outputs to the stdout.

### Middleware Functions
There are two types of middleware used by subscriptions: an error handling function that takes 3 arguments and a message processing function that takes 2.

To finish processing and the current middleware function is not the last in the chain of middleware. Set a done flag to the context object `context.done = true` and resolve the returning promise.

If the function resolves with an object, the object is returned to the calling client code if available.

#### Message Handling
- `context` - See [context object](#context-object)
- `message` - _object_ The message passed to the subscribing middleware
- *Returns* `Promise<Any>`

### Error Handling
- `error` - The error that has occurred either on the subscription or during message processing
- `context` - See [context object](#context-object)
- `message` - _object_ The message passed to the subscribing middleware (If available, may be null/undefined)
- *Returns* `Promise<Any>`

---
_Source: https://npm.io/package/exframe-mq · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._