Registry / communication / exframe-mq

exframe-mq

JSON →
library5.2.0jsnpmunverified

exframe-mq is a messaging framework module providing a simplified abstraction layer over RabbitMQ for Node.js applications, currently stable at version 5.2.0. It is part of the broader exframe ecosystem and is typically used in conjunction with other exframe-* packages like exframe-context, exframe-health, and exframe-logger. The library primarily focuses on a Publish/Subscribe topology, makes a key assumption of JSON payloads for all messages, and manages persistent and shared connections to the RabbitMQ server. While a specific release cadence isn't detailed, its close ties to other exframe modules suggest coordinated releases. Key differentiators include its opinionated, simplified API for common RabbitMQ patterns and deep integration with the exframe application framework.

npm install exframe-mq
INSTALL
IMPORT
SIG · EXFRAME-MQ
E
exframe-mq
communicationjavascriptv5.2.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

mq
import mq from 'exframe-mq';
import { create } from 'exframe-mq';
The 'exframe-mq' module exports a single object containing its main functions (create, getConnection, client) as properties. Use a default import in ESM or direct require in CJS.
create
import mq from 'exframe-mq'; const client = mq.create(...);
import { create } from 'exframe-mq';
The 'create' function is a method on the default-exported 'mq' object, not a named export. It initializes the RabbitMQ client.
client
import mq from 'exframe-mq'; const clientInstance = mq.client(options);
import { client } from 'exframe-mq';
The 'client' function is a method on the default-exported 'mq' object used to create an instance for subscribing and publishing messages.

This example demonstrates how to initialize the `exframe-mq` module, configure a connection to RabbitMQ, create a messaging client, and then subscribe to and publish messages using a topic exchange topology.

import mq from 'exframe-mq'; // Use 'const mq = require("exframe-mq");' for CommonJS // Mock a logger for demonstration purposes const logger = { info: (message, ...args) => console.log('INFO:', message, ...args), error: (message, ...args) => console.error('ERROR:', message, ...args), warn: (message, ...args) => console.warn('WARN:', message, ...args), debug: (message, ...args) => console.debug('DEBUG:', message, ...args), }; async function runMessagingExample() { const rabbitmqUrl = process.env.RABBITMQ_URL ?? 'amqp://localhost'; console.log(`Attempting to connect to RabbitMQ at ${rabbitmqUrl}...`); try { // Initialize the main exframe-mq client const mqClient = mq.create({ logger, url: rabbitmqUrl, heartbeat: 30, baseTimeout: 500, maxAttempts: 5, responseTimeout: 60 * 1000, }); // Get a messaging client instance for publish/subscribe operations const client = mqClient.client(); const EXCHANGE_NAME = 'my-app-exchange'; const ROUTING_KEY_PATTERN = 'my.topic.#'; // Subscribe to all messages under 'my.topic' const PUBLISH_ROUTING_KEY = 'my.topic.hello'; // Subscribe to messages on a topic exchange await client.subscribe(EXCHANGE_NAME, ROUTING_KEY_PATTERN, async (context, message, extraParams = {}) => { logger.info(`Received message: ${JSON.stringify(message)} with context ${JSON.stringify(context)} and extraParams ${JSON.stringify(extraParams)}`); // Simulate some asynchronous processing await new Promise(resolve => setTimeout(resolve, 100)); }, { exchangeType: 'topic' }); logger.info(`Successfully subscribed to '${EXCHANGE_NAME}' with routing key pattern '${ROUTING_KEY_PATTERN}'.`); // Publish a message after a short delay to allow subscription to establish setTimeout(() => { const messagePayload = { sender: 'quickstart-app', content: 'Hello from exframe-mq!' }; logger.info(`Publishing message '${JSON.stringify(messagePayload)}' to '${EXCHANGE_NAME}' with routing key '${PUBLISH_ROUTING_KEY}'.`); client.publish(EXCHANGE_NAME, PUBLISH_ROUTING_KEY, messagePayload); }, 2000); console.log('Application running. Awaiting messages. Press Ctrl+C to exit.'); } catch (error) { logger.error('Failed to initialize or connect to RabbitMQ:', error); process.exit(1); } } runMessagingExample();
Debug
Known issues
gotchaThe library assumes all message payloads are JSON. Non-JSON messages will likely cause parsing errors in subscribers when the module attempts to process them.
fix
Ensure all messages published through `exframe-mq` are valid JSON objects. If receiving messages from external, non-JSON sources, implement custom middleware to handle parsing or validation before `exframe-mq`'s default processing.
affects: >=5.0
gotcha`exframe-mq` has several peer dependencies (`exframe-context`, `exframe-health`, `exframe-logger`, `exframe-service`) that must be installed and configured alongside it for full functionality. Missing or incompatible versions can lead to runtime errors.
fix
Install all listed peer dependencies at compatible versions (e.g., `npm install exframe-context@1 exframe-health@1 exframe-logger@3 exframe-service@1`). Ensure they are properly initialized and passed where required (e.g., `logger` in `mq.create()`).
affects: >=1.0
gotchaThe default RabbitMQ URL (`amqp://localhost`) and connection retry settings (e.g., `maxAttempts`, `baseTimeout`) are suitable for local development but are generally insufficient for robust production environments, which require proper authentication and more resilient retry logic.
fix
Always explicitly configure the `url`, `maxAttempts`, `baseTimeout`, `heartbeat`, and `responseTimeout` in `mq.create()` for production deployments, ideally using environment variables.
affects: >=5.0
gotchaMessage processing middleware functions passed to `client.subscribe` are expected to return Promises that resolve. Failing to return a Promise or returning a synchronous value without wrapping it can lead to unexpected behavior in message acknowledgment or error handling.
fix
Ensure all message processing functions passed to `client.subscribe` are `async` functions or explicitly return `Promise.resolve()` or `Promise.reject()`.
affects: >=5.0
gotchaThe `logger` option passed to `mq.create` expects an object with an interface compatible with `winston` logger methods (e.g., `info`, `error`, `warn`, `debug`). While a default logger outputs to stdout, custom logging requires a compliant object.
fix
Provide a logger object that implements `info`, `error`, `warn`, and `debug` methods, or use an instance of `winston` (or a `winston`-compatible logger) directly.
affects: >=5.0
Errors
Common errors & fixes
Error: connect ECONNREFUSED 127.0.0.1:5672
The RabbitMQ server is not running or is inaccessible at the configured address and port.
fix
Ensure the RabbitMQ server is running and accessible from the application's host. Verify the `url` configuration in `mq.create()` is correct.
TypeError: mq.create is not a function
The `exframe-mq` module was imported incorrectly, likely using named import syntax (e.g., `import { create } from 'exframe-mq';`) instead of importing the default object.
fix
Adjust your import statement to `import mq from 'exframe-mq';` (ESM) or `const mq = require('exframe-mq');` (CommonJS), then access the `create` method as `mq.create()`.
Error: Missing peer dependency "exframe-logger@3.x"
A required peer dependency of `exframe-mq` is not installed or its version does not match the expected range specified in `package.json`.
fix
Install the missing peer dependency using `npm install <package-name>@<version-range>` (e.g., `npm install exframe-logger@3`) to satisfy the requirement. Repeat for any other missing `exframe-*` peer dependencies.
Upgrade
Version history
5.2.0latest on npm
Audit
Dependencies
exframe-contextrequiredRequired for integrating with the exframe application context, handling request lifecycle and shared data.
exframe-healthrequiredUsed for exposing health check endpoints related to the RabbitMQ connection status.
exframe-loggerrequiredProvides a consistent logging interface across exframe modules; mq.create expects a logger instance.
exframe-servicerequiredIntegrates the messaging client within the broader exframe service architecture.
Agent activity
24 hits · last 30 days
node
22
OpenAI (training)
1
Resources
exframe-mq — npm install exframe-mq · libregistry