{"_id":"@aetherframework/queue-module","_rev":"9-736f753c3a03e6ab4cbd350bb2e860c7","name":"@aetherframework/queue-module","dist-tags":{"latest":"1.0.7"},"versions":{"1.0.5":{"name":"@aetherframework/queue-module","version":"1.0.5","keywords":["queue","factory-pattern","no-dependencies","cluster","enterprise"],"author":{"name":"Aether Framework Team"},"license":"MIT","_id":"@aetherframework/queue-module@1.0.5","maintainers":[{"name":"aetherframework","email":"aetherjs@outlook.com"}],"homepage":"https://www.aetherjs.org","bugs":{"url":"https://github.com/aetherjs/aetherframework-queue-module/issues","email":"support@aetherjs.org"},"dist":{"shasum":"2e22424e50f69da96d44f5fe76c42e4d17e7e991","tarball":"https://registry.npmjs.org/@aetherframework/queue-module/-/queue-module-1.0.5.tgz","fileCount":26,"integrity":"sha512-Msmhf7bqIwO07qBY7JL24BVIFv75yKse9IXkKmfFsQxa7C7VIIqeHDZa/je23QZUV4aGEDvD3Z+F0bm2IjzadA==","signatures":[{"sig":"MEYCIQDsZb7mJcu4QF6K0YTzJD4YnaSaFtUKMeyICOn7hmnhHgIhAISNP30VElNkyoNYd3Oa73sBJkFEnV6JeCJlSIwDEfYn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":186107},"main":"index.js","type":"module","engines":{"node":">=18.0.0"},"scripts":{"test":"node examples/basic-usage.js","start:multi":"node examples/multi-node.js","start:enterprise":"node examples/enterprise-usage.js"},"_npmUser":{"name":"aetherframework","email":"aetherjs@outlook.com"},"repository":{"url":"git+https://github.com/aetherjs/aetherframework-queue-module.git","type":"git"},"_npmVersion":"10.9.3","description":"Enterprise-grade queue system with factory pattern and no third-party dependencies","directories":{},"_nodeVersion":"22.18.0","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","jsdoc":"^4.0.0","eslint":"^8.0.0","prettier":"^3.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/queue-module_1.0.5_1780653353454_0.6311102064193896","host":"s3://npm-registry-packages-npm-production"}},"1.0.6":{"name":"@aetherframework/queue-module","version":"1.0.6","keywords":["queue","factory-pattern","no-dependencies","cluster","enterprise"],"author":{"name":"Aether Framework Team"},"license":"MIT","_id":"@aetherframework/queue-module@1.0.6","maintainers":[{"name":"aetherframework","email":"aetherjs@outlook.com"}],"homepage":"https://www.aetherjs.org","bugs":{"url":"https://github.com/aetherjs/aetherframework-queue-module/issues","email":"support@aetherjs.org"},"dist":{"shasum":"2d89abfe1b2b2a7fd53843a3893e261dfa2f3aec","tarball":"https://registry.npmjs.org/@aetherframework/queue-module/-/queue-module-1.0.6.tgz","fileCount":4,"integrity":"sha512-Efp4efUfXzbhmeDsyg7tnuuCG4TIXuj5e2kcwEnDXqhLnDfi8/QhY4M5p67n+RC+84/PYsg9um/89XGKmMKH2g==","signatures":[{"sig":"MEUCIQDg1KvrisvlWN57W2sFcXoQn8u6r08esyG9J3n4w6SGCwIgIwbaNCsnRO5miRkVnTPkpszLwADNzfy2U+I2SKmMQks=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":15553},"main":"index.js","type":"module","engines":{"node":">=18.0.0"},"scripts":{"test":"node examples/basic-usage.js","start:multi":"node examples/multi-node.js","start:enterprise":"node examples/enterprise-usage.js"},"_npmUser":{"name":"aetherframework","email":"aetherjs@outlook.com"},"repository":{"url":"git+https://github.com/aetherjs/aetherframework-queue-module.git","type":"git"},"_npmVersion":"10.9.3","description":"Enterprise-grade queue system with factory pattern and no third-party dependencies","directories":{},"_nodeVersion":"22.18.0","_hasShrinkwrap":false,"devDependencies":{"jest":"^29.0.0","jsdoc":"^4.0.0","eslint":"^8.0.0","prettier":"^3.0.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/queue-module_1.0.6_1780931970022_0.4236334295775743","host":"s3://npm-registry-packages-npm-production"}},"1.0.7":{"name":"@aetherframework/queue-module","version":"1.0.7","description":"Enterprise-grade queue system with factory pattern and no third-party dependencies","type":"module","main":"index.js","scripts":{"test":"node examples/basic-usage.js","start:multi":"node examples/multi-node.js","start:enterprise":"node examples/enterprise-usage.js"},"keywords":["queue","factory-pattern","no-dependencies","cluster","enterprise"],"devDependencies":{"@types/node":"^20.0.0","eslint":"^8.0.0","jest":"^29.0.0","jsdoc":"^4.0.0","prettier":"^3.0.0"},"engines":{"node":">=18.0.0"},"author":{"name":"Aether Framework Team"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/aetherjs/aetherframework-queue-module.git"},"bugs":{"url":"https://github.com/aetherjs/aetherframework-queue-module/issues","email":"support@aetherjs.org"},"homepage":"https://www.aetherjs.org","_id":"@aetherframework/queue-module@1.0.7","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-X67UatSJ3PK4Aimou58ZyemzxfbFHZuPh/tqz0TDrRs/BEq1IwZFIFXoWNK1E3oqNeUiSuvsdnLFtAAlN1ezNg==","shasum":"99558136a2b9e6d74f1d00f5cf9c4d08089cb334","tarball":"https://registry.npmjs.org/@aetherframework/queue-module/-/queue-module-1.0.7.tgz","fileCount":31,"unpackedSize":250444,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFTP0SQ/j6ZepDsHgueU9I+TUPECR7ESCW6lY896uJoaAiEAhxk0RwkxUUCV9Jj/WPeiOO0L4soKwULVebQzUG6HG2c="}]},"_npmUser":{"name":"aetherframework","email":"aetherjs@outlook.com"},"directories":{},"maintainers":[{"name":"aetherframework","email":"aetherjs@outlook.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/queue-module_1.0.7_1780933778274_0.11244240433445496"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-05T09:55:53.223Z","modified":"2026-06-08T15:49:38.511Z","1.0.0":"2026-06-05T09:48:36.442Z","1.0.1":"2026-06-05T09:49:28.751Z","1.0.3":"2026-06-05T09:52:03.143Z","1.0.5":"2026-06-05T09:55:53.595Z","1.0.6":"2026-06-08T15:19:30.148Z","1.0.7":"2026-06-08T15:49:38.416Z"},"bugs":{"url":"https://github.com/aetherjs/aetherframework-queue-module/issues","email":"support@aetherjs.org"},"author":{"name":"Aether Framework Team"},"license":"MIT","homepage":"https://www.aetherjs.org","keywords":["queue","factory-pattern","no-dependencies","cluster","enterprise"],"repository":{"type":"git","url":"git+https://github.com/aetherjs/aetherframework-queue-module.git"},"description":"Enterprise-grade queue system with factory pattern and no third-party dependencies","maintainers":[{"name":"aetherframework","email":"aetherjs@outlook.com"}],"readme":"Aetherframework queue-module - Modern Node.js Queue System\r\n\r\n📦 Installation\r\n\r\nInstall the queue module via npm:\r\n\r\n```bash\r\nnpm install @aetherframework/queue-module\r\n```\r\n\r\n🚀 Quick Start\r\n\r\nBasic Usage with ES Module Syntax\r\n\r\n```javascript\r\n// Import the QueueFactory using ES module syntax\r\nimport QueueFactory from '@aetherframework/queue-module';\r\n\r\n// Initialize with memory driver (zero dependencies, fastest setup)\r\nconst factory = new QueueFactory({\r\n  defaultDriver: 'memory',\r\n  defaultConfig: {\r\n    concurrency: 5,      // Number of concurrent jobs\r\n    maxRetries: 3,       // Maximum retry attempts\r\n    timeout: 30000       // Job timeout in milliseconds\r\n  }\r\n});\r\n\r\n// Create a queue instance\r\nconst queue = factory.createQueue({ \r\n  name: 'my-first-queue' \r\n});\r\n\r\n// Register a job handler\r\nqueue.process('greet', async (job) => {\r\n  console.log(`Hello ${job.data.name}!`);\r\n  return { \r\n    greeted: true, \r\n    timestamp: Date.now() \r\n  };\r\n});\r\n\r\n// Add a job to the queue\r\nawait queue.add({\r\n  handlerName: 'greet',\r\n  data: { name: 'World' }\r\n});\r\n\r\n// Start processing jobs\r\nqueue.start();\r\n```\r\n\r\n📚 API Reference\r\n\r\nCore Exports\r\n\r\nThe module provides the following exports:\r\n\r\n```javascript\r\n// Main factory class\r\nimport QueueFactory from '@aetherframework/queue-module';\r\n\r\n// Individual component imports\r\nimport { \r\n  QueueFactory,\r\n  registerDriver,\r\n  loadConfig,\r\n  QueueError,\r\n  createJobLogger,\r\n  createRateLimiter,\r\n  createRetryManager,\r\n  createMetricsCollector,\r\n  createCircuitBreaker,\r\n  serializers,\r\n  validators\r\n} from '@aetherframework/queue-module';\r\n```\r\n\r\nAvailable Components\r\n\r\n| Component | Description | Import Path |\r\n|-----------|-------------|-------------|\r\n| QueueFactory | Main factory class for creating queues | `@aetherframework/queue-module` |\r\n| registerDriver | Register custom queue drivers | `@aetherframework/queue-module` |\r\n| loadConfig | Configuration loader utility | `@aetherframework/queue-module` |\r\n| QueueError | Custom error class for queue operations | `@aetherframework/queue-module` |\r\n| createJobLogger | Middleware for job logging | `@aetherframework/queue-module` |\r\n| createRateLimiter | Middleware for rate limiting | `@aetherframework/queue-module` |\r\n| createRetryManager | Middleware for retry logic | `@aetherframework/queue-module` |\r\n| createMetricsCollector | Middleware for metrics collection | `@aetherframework/queue-module` |\r\n| createCircuitBreaker | Middleware for circuit breaking | `@aetherframework/queue-module` |\r\n| serializers | Job serialization utilities | `@aetherframework/queue-module` |\r\n| validators | Validation utilities | `@aetherframework/queue-module` |\r\n\r\n🛠️ Driver Configuration Examples\r\n\r\n1. Memory Driver (Development/Testing)\r\n\r\n```javascript\r\nimport QueueFactory from '@aetherframework/queue-module';\r\n\r\nconst factory = new QueueFactory({ \r\n  defaultDriver: 'memory'\r\n});\r\n\r\nconst memoryQueue = factory.createQueue({\r\n  name: 'user-activity-tracker',\r\n  driver: 'memory',\r\n  driverConfig: {\r\n    maxSize: 10000,     // Maximum queue size\r\n    persist: false      // Transient (clears on restart)\r\n  }\r\n});\r\n\r\n// Performance: 250,000+ TPS\r\n// Perfect for: Analytics events, user session data, click tracking\r\n```\r\n\r\n2. Shared-Memory Driver (Multi-Process)\r\n\r\n```javascript\r\nimport QueueFactory from '@aetherframework/queue-module';\r\nimport os from 'os';\r\n\r\nconst factory = new QueueFactory({ \r\n  defaultDriver: 'shared-memory' \r\n});\r\n\r\nconst sharedMemoryQueue = factory.createQueue({\r\n  name: 'pdf-processing-queue',\r\n  driver: 'shared-memory',\r\n  driverConfig: {\r\n    sharedPath: '/tmp/pdf-queue',  // Shared directory across processes\r\n    persist: true,                 // Persist across restarts\r\n    maxSize: 50000,                // Larger queue size\r\n    lockTimeout: 5000              // 5-second lock timeout\r\n  }\r\n});\r\n\r\n// Use with Node.js cluster for maximum CPU utilization\r\nconst cpuCount = os.cpus().length;\r\nfor (let i = 0; i < cpuCount; i++) {\r\n  // Each worker processes jobs from shared memory\r\n}\r\n\r\n// Performance: 200,000+ TPS per cluster\r\n// Perfect for: Image processing, PDF generation, real-time notifications\r\n```\r\n\r\n3. Redis Driver (Production)\r\n\r\n```javascript\r\nimport QueueFactory from '@aetherframework/queue-module';\r\n\r\nconst factory = new QueueFactory({ \r\n  defaultDriver: 'redis' \r\n});\r\n\r\nconst redisQueue = factory.createQueue({\r\n  name: 'email-campaign-queue',\r\n  driver: 'redis',\r\n  driverConfig: {\r\n    url: 'redis://production-redis-cluster:6379',\r\n    password: process.env.REDIS_PASSWORD,  // Use environment variables\r\n    db: 1,                                 // Separate queue databases\r\n    keyPrefix: 'campaign:',                // Namespace your keys\r\n    connectionTimeout: 10000               // 10-second timeout\r\n  }\r\n});\r\n\r\n// Features: Automatic failover, replication, persistence\r\n// Perfect for: Multi-region deployments, containerized environments\r\n// Performance: 50,000-100,000+ TPS\r\n```\r\n\r\n4. File Driver (Persistent Storage)\r\n\r\n```javascript\r\nimport QueueFactory from '@aetherframework/queue-module';\r\n\r\nconst factory = new QueueFactory({ \r\n  defaultDriver: 'file' \r\n});\r\n\r\nconst fileQueue = factory.createQueue({\r\n  name: 'data-backup-queue',\r\n  driver: 'file',\r\n  driverConfig: {\r\n    dataDir: './data/queue-storage',  // Directory for queue files\r\n    maxSize: 100000,                   // Larger capacity for storage\r\n    flushInterval: 1000                 // Flush to disk every second\r\n  }\r\n});\r\n\r\n// Features: Built-in persistence, human-readable files, easy debugging\r\n// Perfect for: Cold storage, auditing, regulatory compliance backups\r\n```\r\n\r\n🔧 Advanced Usage\r\n\r\nMiddleware Integration\r\n\r\n```javascript\r\nimport QueueFactory, { \r\n  createJobLogger, \r\n  createRateLimiter, \r\n  createRetryManager \r\n} from '@aetherframework/queue-module';\r\n\r\nconst factory = new QueueFactory({\r\n  defaultDriver: 'redis',\r\n  middleware: [\r\n    createJobLogger({ level: 'info' }),      // Log all job operations\r\n    createRateLimiter({ maxJobsPerSecond: 100 }), // Rate limiting\r\n    createRetryManager({ maxRetries: 3, backoff: 'exponential' }) // Retry logic\r\n  ]\r\n});\r\n\r\nconst queue = factory.createQueue({ name: 'production-queue' });\r\n```\r\n\r\nError Handling\r\n\r\n```javascript\r\nimport QueueFactory, { QueueError } from '@aetherframework/queue-module';\r\n\r\nconst factory = new QueueFactory();\r\nconst queue = factory.createQueue({ name: 'error-handling-queue' });\r\n\r\nqueue.process('critical-task', async (job) => {\r\n  try {\r\n    return await processCriticalTask(job.data);\r\n  } catch (error) {\r\n    // Custom error handling\r\n    if (error instanceof QueueError) {\r\n      console.error('Queue error:', error.message);\r\n    }\r\n    throw error; // Will trigger retry logic if configured\r\n  }\r\n});\r\n```\r\n\r\nEvent Handling\r\n\r\n```javascript\r\nimport QueueFactory from '@aetherframework/queue-module';\r\n\r\nconst factory = new QueueFactory();\r\nconst queue = factory.createQueue({ name: 'event-driven-queue' });\r\n\r\n// Listen to queue events\r\nqueue.on('jobAdded', (job) => {\r\n  console.log(`Job ${job.id} added to queue`);\r\n});\r\n\r\nqueue.on('jobStarted', (job) => {\r\n  console.log(`Job ${job.id} started processing`);\r\n});\r\n\r\nqueue.on('jobCompleted', (job, result) => {\r\n  console.log(`Job ${job.id} completed with result:`, result);\r\n});\r\n\r\nqueue.on('jobFailed', (job, error) => {\r\n  console.error(`Job ${job.id} failed:`, error.message);\r\n});\r\n\r\nqueue.on('queueEmpty', () => {\r\n  console.log('Queue is empty');\r\n});\r\n```\r\n\r\n📊 Performance Comparison\r\n\r\n| Driver | TPS Range | Use Case | Setup Complexity |\r\n|--------|-----------|----------|-----------------|\r\n| Memory | 250,000+ TPS | Development, Single Process | ⭐ |\r\n| Shared-Memory | 200,000+ TPS per cluster | Multi-Process Single Server | ⭐⭐ |\r\n| Redis | 50,000-100,000+ TPS | Distributed Production | ⭐⭐⭐ |\r\n| File | 10,000-50,000 TPS | Persistence/Backup | ⭐⭐ |\r\n\r\n🎯 Best Practices\r\n\r\nDevelopment Environment\r\n\r\n```javascript\r\n// .env file for development\r\nQUEUE_DRIVER=memory\r\nQUEUE_CONCURRENCY=5\r\nMEMORY_DRIVER_MAX_SIZE=10000\r\nMEMORY_DRIVER_PERSIST=false\r\n```\r\n\r\nProduction Environment\r\n\r\n```javascript\r\n// .env file for production\r\nQUEUE_DRIVER=redis\r\nREDIS_URL=redis://production-redis-cluster:6379\r\nREDIS_DB=0\r\nREDIS_PASSWORD=${REDIS_PASSWORD}\r\nREDIS_KEY_PREFIX=queue:\r\nQUEUE_CONCURRENCY=10\r\nQUEUE_MAX_RETRIES=5\r\nQUEUE_TIMEOUT=60000\r\n```\r\n\r\nHybrid Architecture\r\n\r\n```javascript\r\nimport QueueFactory from '@aetherframework/queue-module';\r\n\r\n// Use different drivers for different purposes\r\nconst factory = new QueueFactory({\r\n  defaultDriver: 'redis',                // Production default\r\n  drivers: {\r\n    redis: { url: process.env.REDIS_URL },\r\n    memory: { maxSize: 5000 },          // In-memory cache queue\r\n    file: { dataDir: './queue-backup' } // Backup storage\r\n  }\r\n});\r\n\r\n// High-speed real-time events\r\nconst analyticsQueue = factory.createQueue({\r\n  name: 'analytics-events',\r\n  driver: 'memory',                      // Memory for speed\r\n  maxSize: 1000                          // Keep recent events only\r\n});\r\n\r\n// Reliable email delivery\r\nconst emailQueue = factory.createQueue({\r\n  name: 'email-queue',\r\n  driver: 'redis'                        // Redis for persistence\r\n});\r\n\r\n// Monthly report generation\r\nconst reportsQueue = factory.createQueue({\r\n  name: 'monthly-reports',\r\n  driver: 'file'                         // File for large, infrequent jobs\r\n});\r\n```\r\n\r\n🔍 Monitoring and Metrics\r\n\r\n```javascript\r\nimport QueueFactory, { createMetricsCollector } from '@aetherframework/queue-module';\r\n\r\nconst factory = new QueueFactory({\r\n  defaultDriver: 'redis',\r\n  middleware: [\r\n    createMetricsCollector({\r\n      enabled: true,\r\n      interval: 60000, // Collect metrics every minute\r\n      metrics: ['throughput', 'latency', 'queueSize', 'errorRate']\r\n    })\r\n  ]\r\n});\r\n\r\nconst queue = factory.createQueue({ name: 'monitored-queue' });\r\n\r\n// Get queue statistics\r\nconst stats = queue.getStats();\r\nconsole.log('Queue Statistics:', {\r\n  activeJobs: stats.activeJobs,\r\n  pendingJobs: stats.pendingJobs,\r\n  completedJobs: stats.completedJobs,\r\n  failedJobs: stats.failedJobs,\r\n  throughput: stats.throughput,\r\n  averageLatency: stats.averageLatency\r\n});\r\n```\r\n\r\n🚀 Scalability Examples\r\n\r\nMulti-Process Cluster\r\n\r\n```javascript\r\nimport QueueFactory from '@aetherframework/queue-module';\r\nimport cluster from 'cluster';\r\nimport os from 'os';\r\n\r\nif (cluster.isPrimary) {\r\n  const cpuCount = os.cpus().length;\r\n  console.log(`Starting ${cpuCount} workers`);\r\n  for (let i = 0; i < cpuCount; i++) {\r\n    cluster.fork();\r\n  }\r\n} else {\r\n  const factory = new QueueFactory({ defaultDriver: 'shared-memory' });\r\n  const queue = factory.createQueue({ name: 'cpu-intensive-tasks' });\r\n  queue.start();\r\n  // Process ~200,000 jobs per second across all cores\r\n}\r\n```\r\n\r\nAuto-scaling with Redis\r\n\r\n```javascript\r\nimport QueueFactory from '@aetherframework/queue-module';\r\n\r\nconst factory = new QueueFactory({\r\n  defaultDriver: 'redis',\r\n  defaultConfig: {\r\n    redis: { url: process.env.REDIS_CLUSTER_URL },\r\n    autoScale: true,      // Enable auto-scaling\r\n    minWorkers: 2,        // Minimum number of workers\r\n    maxWorkers: 10,       // Maximum number of workers\r\n    scaleThreshold: 100    // Scale up when queue depth > 100\r\n  }\r\n});\r\n\r\nconst queue = factory.createQueue({ name: 'auto-scaling-queue' });\r\n// Automatically scale workers based on queue depth\r\n```\r\n\r\n📄 License\r\n\r\nMIT © Aether Framework\r\n\r\n---\r\n\r\nThis updated README provides comprehensive documentation for installing and using the `@aetherframework/queue-module` with proper ES module syntax and English comments. The module offers a high-performance, scalable queue system with multiple driver options for different use cases, from development to production environments.","readmeFilename":"README.md"}