README.md

💡 Note: You are viewing the next branch with upcoming features. For stable releases, check the master branch.

✨ Features

• 📬 Reliable delivery with retries
• 📊 Multiple queue types: FIFO, LIFO, Priority
• 🔀 Flexible routing: Direct/Topic/Fanout exchanges + Direct queue publishing
• 👥 Pub/Sub & Point-to-Point delivery models with native consumer groups
• 🚦 Queue-level rate limiting
• ⏰ Built-in scheduler: delays, CRON, repeating
• 🔒 Queue state management: pause/stop/resume + audit
• ⏱️ Message TTL & consumption timeouts
• 🚀 High-throughput design with atomic Lua scripts
• 📦 Batch acks & Batch unacks — 99% fewer Redis calls
• 🧵 Worker threads for CPU-heavy handlers
• 🔄 Multi-queue producers & consumers with multiplexing support
• 📡 Event bus for real-time internal events
• 🌐 REST API with OpenAPI + Swagger
• 📊 Web UI for live management
• 🎯 Process-wide API — initialize once, factory methods, single shutdown
• 🔄 Dual callback & promise support
• 📦 ESM + CJS module support
• 📖 TypeScript-first with rich docs

🎯 Use Cases

• Background jobs: emails, reports, data processing
• Task scheduling with automatic retries
• Microservices communication
• Real-time event processing for gaming, IoT, analytics

📋 Requirements

• Node.js 20+
• Redis 4+
• Choose one Redis client: ioredis or @redis/client

🚀 Quick Start

1. Install

# Core packages
npm install redis-smq@next redis-smq-common@next --save

# Pick a Redis client
npm install ioredis --save
# OR
npm install @redis/client --save

2. Initialize (once per process)

import { RedisSMQ } from 'redis-smq';
import { ERedisConfigClient } from 'redis-smq-common';

// Simple initialization
RedisSMQ.initialize(
  {
    client: ERedisConfigClient.IOREDIS,
    options: { host: '127.0.0.1', port: 6379 }
  },
  (err) => {
    if (err) console.error('RedisSMQ init failed:', err);
  }
);

3. Create a Queue

import { RedisSMQ, EQueueType, EQueueDeliveryModel } from 'redis-smq';

const queueManager = RedisSMQ.createQueueManager();
queueManager.save(
  'my_queue',
  EQueueType.LIFO_QUEUE,
  EQueueDeliveryModel.POINT_TO_POINT,
  (err) => {
    if (err) console.error('Queue creation failed:', err);
    else console.log('✅ Queue created');
  }
);

4. Produce a Message

import { RedisSMQ, ProducibleMessage } from 'redis-smq';

const producer = RedisSMQ.createProducer();
producer.run((err) => {
  if (err) return console.error('Producer failed:', err);
  
  const msg = new ProducibleMessage()
    .setQueue('my_queue')
    .setBody('Hello World!');
  
  producer.produce(msg, (err, ids) => {
    if (err) console.error('Send failed:', err);
    else console.log(`📨 Sent message: ${ids.join(', ')}`);
  });
});

5. Consume Messages

import { RedisSMQ } from 'redis-smq';

const consumer = RedisSMQ.createConsumer();
consumer.run((err) => {
  if (err) return console.error('Consumer failed:', err);
  
  const handler = (message, done) => {
    console.log('📥 Received:', message.body);
    done(); // Acknowledge
  };
  
  consumer.consume('my_queue', handler, (err) => {
    if (err) console.error('Consume failed:', err);
    else console.log('👂 Listening on my_queue...');
  });
});

🧩 Using Promises

import { RedisSMQ, EQueueType, EQueueDeliveryModel } from 'redis-smq';

try {
  // Initialize RedisSMQ
  await RedisSMQ.initialize({
    client: ERedisConfigClient.IOREDIS,
    options: { host: 'localhost', port: 6379 }
  });
  
  // Create a Queue
  const queueManager = RedisSMQ.createQueueManager();
  await queueManager.save(
    'my_queue',
    EQueueType.LIFO_QUEUE,
    EQueueDeliveryModel.POINT_TO_POINT,
  );

  // Create and start a producer
  const producer = RedisSMQ.createProducer();
  await producer.run();

  // Send a message
  const message = new ProducibleMessage()
    .setQueue('my-queue')
    .setBody({ hello: 'world' });
  
  const messageIds = await producer.produce(message);
  console.log('Message published:', messageIds);

  // Create and start a consumer
  const consumer = RedisSMQ.createConsumer();
  await consumer.run();

  // Consume messages
  await consumer.consume('my-queue', async (message) => {
    console.log('Received:', message.getBody());
    // Successful acknowledgement 
  });
} catch (err) {
  console.error('Error:', err);
}

See Dual Callback & Promise Support.

📦 Packages

Package	Description
redis-smq	Core message queue library
redis-smq-common	Shared utilities
redis-smq-rest-api	REST API with Swagger UI
redis-smq-web-ui	Web dashboard
redis-smq-web-server	Web server for UI & API
redis-smq-benchmarks	Performance testing

🔗 Version Compatibility: Always use matching versions. See version compatibility guide.

📚 Documentation

• Full Documentation - Complete API reference and guides
• REST API - API endpoints and usage
• Web UI - Dashboard setup and features

🤝 Contributing

We welcome contributions! Please read CONTRIBUTING.md for guidelines.

📄 License

RedisSMQ is released under the MIT License.