A High-Performance Redis Simple Message Queue for Node.js
Note
You are viewing the documentation for the "next" branch. These docs describe unreleased changes published under the npm "next" dist-tag.
For the latest stable documentation, see:
- Master (stable) README: https://github.com/weyoss/redis-smq/tree/master
- Latest release notes/tags: https://github.com/weyoss/redis-smq/releases/latest
- Install stable packages with @latest; pre-release with @next.
Key Features
- 🚀 High-performance message processing
- 🔄 Flexible producer/consumer model with multi-queue producers and consumers
- 🔀 Exchange types (Direct, Topic, Fanout) for publishing to one or multiple queues
- 📬 Two delivery models (Point-to-Point and Pub/Sub) with reliable delivery and configurable retry modes
- 📊 Three queuing strategies (FIFO, LIFO, Priority Queues)
- 🧵 Message handler worker threads for sandboxing and performance
- ️️️️⏱️ Message expiration and consumption timeout
- 🚦 Queue rate limiting for controlling message consumption rates
- ️️️🕰️ Built-in scheduler for delayed and repeating messages
- 🌐 RESTful API and Web UI
- 📦 ESM and CJS support
Use Cases
- Managing background tasks (emails, data processing)
- Scheduling and retrying tasks
- Communication between services in microservices architectures
- Handling real-time events in gaming, IoT, or analytics
Requirements
- Node.js 20+
- Redis server (tested with Redis 7.x)
- One Redis client: ioredis or @redis/client
Installation
Install core packages:
npm i redis-smq@next redis-smq-common@next --saveInstall a Redis client (choose one):
npm install ioredis --save
# or
npm install @redis/client --saveEcosystem
| Package | Description |
|---|---|
| packages/redis-smq/README.md | Core message queue for Node.js |
| packages/redis-smq-common/README.md | Shared components and utilities |
| packages/redis-smq-rest-api/README.md | REST API with OpenAPI v3 and Swagger UI |
| packages/redis-smq-web-server/README.md | Web server to host the UI and in-process/proxied API |
| packages/redis-smq-web-ui/README.md | SPA for monitoring and managing RedisSMQ |
Version compatibility
Always install matching versions of RedisSMQ packages. See version-compatibility.md.
Quick Start (required initialization)
RedisSMQ must be initialized once per process before creating any producers, consumers, or managers.
Option A: Initialize with Redis connection (recommended for most)
import { RedisSMQ } from 'redis-smq';
import { ERedisConfigClient } from 'redis-smq-common';
// Initialize once with Redis connection details
RedisSMQ.initialize(
{
client: ERedisConfigClient.IOREDIS,
options: { host: '127.0.0.1', port: 6379, db: 0 },
},
(err) => {
if (err) {
console.error('Failed to initialize RedisSMQ:', err);
return;
}
// Create components after initialization
const producer = RedisSMQ.createProducer();
const consumer = RedisSMQ.createConsumer();
// Start producer
producer.run((pe) => {
if (pe) return console.error('Producer start failed:', pe);
console.log('Producer ready');
});
// Start consumer
consumer.run((ce) => {
if (ce) return console.error('Consumer start failed:', ce);
console.log('Consumer ready');
});
},
);Option B: Initialize with a full RedisSMQ configuration (persisted in Redis)
Use when you want configuration persisted and shared across processes. On first run, the config is saved. Subsequent processes can initialize normally (using RedisSMQ.initialize).
import { RedisSMQ } from 'redis-smq';
import { ERedisConfigClient, EConsoleLoggerLevel } from 'redis-smq-common';
RedisSMQ.initializeWithConfig(
{
namespace: 'my_project_name',
redis: {
client: ERedisConfigClient.IOREDIS,
options: { host: '127.0.0.1', port: 6379, db: 0 },
},
logger: { enabled: true, options: { logLevel: EConsoleLoggerLevel.INFO } },
messages: { store: false },
eventBus: { enabled: false },
},
(err) => {
if (err) {
console.error('Failed to initialize with config:', err);
return;
}
console.log('RedisSMQ initialized (configuration persisted in Redis)');
},
);Usage
Create a queue, produce a message, and consume it. Ensure RedisSMQ has been initialized first (see Quick Start).
import {
RedisSMQ,
ProducibleMessage,
EQueueType,
EQueueDeliveryModel,
} from 'redis-smq';
// 1) Create a queue
const queueManager = RedisSMQ.createQueueManager();
queueManager.save(
'my_queue',
EQueueType.LIFO_QUEUE,
EQueueDeliveryModel.POINT_TO_POINT,
(err) => {
if (err) return console.error('Queue creation failed:', err);
console.log('Queue created');
},
);
// 2) Produce a message
const producer = RedisSMQ.createProducer();
const msg = new ProducibleMessage()
.setQueue('my_queue')
.setBody('Hello World!');
producer.produce(msg, (err, ids) => {
if (err) return console.error('Produce failed:', err);
console.log(`Produced message IDs: ${ids.join(', ')}`);
});
// 3) Consume messages
const consumer = RedisSMQ.createConsumer();
const handler = (message: any, done: (err?: Error | null) => void) => {
console.log('Received:', message.body);
done(); // Acknowledge
};
consumer.consume('my_queue', handler, (err) => {
if (err) return console.error('Consumer start failed:', err);
console.log('Consuming my_queue...');
});Configuration (optional)
Using the Configuration class directly is optional. After RedisSMQ.initialize(...) or RedisSMQ.initializeWithConfig(...), you can inspect or update the persisted configuration if needed.
import { Configuration } from 'redis-smq';
// Read current config
const current = Configuration.getConfig();
console.log('Current config:', current);
// Update selected parts and persist
Configuration.getInstance().updateConfig(
{ logger: { enabled: true } },
(err) => {
if (err) return console.error('Config update failed:', err);
console.log('Configuration updated');
},
);Docs
- Full documentation: packages/redis-smq/docs/README.md
- REST API: packages/redis-smq-rest-api/README.md
- Web UI: packages/redis-smq-web-ui/README.md
Contributing
We welcome contributions. Please read CONTRIBUTING.md.
License
RedisSMQ is released under the MIT License.