A Redis-backed job queue built for Bun, inspired by Laravel's Queue system and BullMQ.
Features
- Fast and efficient Redis-backed queue system
- Support for delayed jobs, retries, and prioritization
- Rate limiting capabilities
- Job event tracking
- Reliable job processing with concurrency control
- Typesafe API
Installation
Basic Usage
import { Queue } from 'bun-queue' // Create a queue const emailQueue = new Queue('emails') // Add a job to the queue const job = await emailQueue.add({ to: 'user@example.com', subject: 'Welcome', body: 'Welcome to our platform!' }) console.log(`Job ${job.id} added to the queue`) // Process jobs emailQueue.process(5, async (job) => { const { to, subject, body } = job.data // Update progress await job.updateProgress(10) // Simulate sending email console.log(`Sending email to ${to} with subject: ${subject}`) await new Promise(resolve => setTimeout(resolve, 1000)) await job.updateProgress(100) return { sent: true, timestamp: Date.now() } })
Job Options
// Add a job with options await queue.add( { task: 'process-pdf', url: 'https://example.com/document.pdf' }, { delay: 5000, // delay for 5 seconds attempts: 3, // retry up to 3 times backoff: { type: 'exponential', // 'fixed' or 'exponential' delay: 1000, // milliseconds }, priority: 10, // higher number = higher priority removeOnComplete: true, // remove job when completed lifo: false, // process in FIFO order (default) jobId: 'custom-id', // provide custom job ID } )
Delayed Jobs
// Add a job that will be processed after 30 seconds await queue.add( { task: 'send-reminder' }, { delay: 30000 } )
Job Management
// Get a job by ID const job = await queue.getJob('job-id') // Get jobs by status const waitingJobs = await queue.getJobs('waiting') const activeJobs = await queue.getJobs('active') const completedJobs = await queue.getJobs('completed') const failedJobs = await queue.getJobs('failed') // Get job counts const counts = await queue.getJobCounts() console.log(counts) // { waiting: 5, active: 2, completed: 10, failed: 1, delayed: 3, paused: 0 } // Pause a queue await queue.pause() // Resume a queue await queue.resume() // Retry a failed job const failedJob = await queue.getJob('failed-job-id') await failedJob.retry() // Remove a job await job.remove() // Clear all jobs await queue.empty()
Rate Limiting
import { Queue, RateLimiter } from 'bun-queue' const queue = new Queue('api-calls') // Create a rate limiter (100 jobs per minute) const limiter = new RateLimiter(queue, { max: 100, duration: 60000 }) // Check if rate limited before adding job const { limited, remaining, resetIn } = await limiter.check() if (!limited) { await queue.add({ url: 'https://api.example.com/endpoint' }) console.log(`Job added. ${remaining} requests remaining.`) } else { console.log(`Rate limited. Try again in ${resetIn}ms.`) }
Configuration
import { Queue } from 'bun-queue' // Configure queue with options const queue = new Queue('tasks', { redis: { url: 'redis://username:password@localhost:6379' // Or provide your own client // client: myRedisClient }, prefix: 'myapp', // prefix for Redis keys (default: 'queue') defaultJobOptions: { attempts: 5, backoff: { type: 'exponential', delay: 5000 } } })
Environment Variables
The library reads these environment variables (in order of precedence):
REDIS_URL: Redis connection string- Default is
redis://localhost:6379if not set
Testing
Changelog
Please see our releases page for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Community
For help, discussion about best practices, or any other conversation that would benefit from being searchable:
For casual chit-chat with others using this package:
Join the Stacks Discord Server
Postcardware
"Software that is free, but hopes for a postcard." We love receiving postcards from around the world showing where Stacks is being used! We showcase them on our website too.
Our address: Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎
Sponsors
We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.
License
The MIT License (MIT). Please see LICENSE for more information.
Made with 💙
