High-Performance Job Queue for Bun

Quick Start

Embedded Mode

import { Queue, Worker } from 'bunqueue/client';

// Create a queue
const queue = new Queue('emails', { embedded: true });

// Add jobs
await queue.add('welcome', {
  to: 'user@example.com',
  template: 'welcome'
});

// Process jobs
const worker = new Worker('emails', async (job) => {
  await sendEmail(job.data);
  return { sent: true };
}, { embedded: true });

worker.on('completed', (job) => console.log(`✓ ${job.id}`));

Server Mode

# First, start the server
bunqueue start --data-path ./data/queue.db

// Then, in your application
import { Queue, Worker } from 'bunqueue/client';

// Create a queue (connects to localhost:6789)
const queue = new Queue('emails');

// Add jobs
await queue.add('welcome', {
  to: 'user@example.com',
  template: 'welcome'
});

// Process jobs
const worker = new Worker('emails', async (job) => {
  await sendEmail(job.data);
  return { sent: true };
});

worker.on('completed', (job) => console.log(`✓ ${job.id}`));

Docker

FROM oven/bun:latest
WORKDIR /app
RUN bun add bunqueue
COPY . .
CMD ["bunqueue", "start"]

docker run -p 6789:6789 -p 6790:6790 \
  -v ./data:/app/data \
  -e DATA_PATH=/app/data/queue.db \
  bunqueue

---

Why bunqueue?

Blazing Fast

Built on Bun’s native SQLite with WAL mode. Optimized data structures deliver sub-millisecond latency at scale.

Zero Dependencies

No Redis, no external services. Just Bun and SQLite. Deploy anywhere in seconds.

Production Ready

Stall detection, dead letter queues, automatic retries, rate limiting, and S3 backups built-in.

BullMQ Compatible

Familiar API for easy migration. Drop-in replacement for most BullMQ use cases.

---

Deployment Modes

bunqueue offers two deployment modes to fit your architecture. Choose based on your use case.

Embedded Mode

Run bunqueue directly inside your application process. Zero network overhead, instant setup.

Best for:

• Single-process applications
• Serverless / Edge functions
• Prototyping and development
• Simple background job processing

TCP Server Mode

Run bunqueue as a standalone server. Multiple clients connect via TCP protocol.

Best for:

• Microservices architecture
• Multiple worker processes
• Language-agnostic clients (HTTP/TCP API)
• Centralized job management

Mode Comparison

Aspect	Embedded	TCP Server
Setup	Zero config	Run bunqueue start
Network	None (in-process)	TCP :6789 / HTTP :6790
Option	embedded: true	Default (no option)
Persistence	DATA_PATH env var	--data-path flag
Scaling	Single process	Multiple clients
Latency	Lowest (~μs)	Low (~ms)

Embedded Mode

import { Queue, Worker } from 'bunqueue/client';

// Both Queue and Worker must have embedded: true
const queue = new Queue('tasks', { embedded: true });

const worker = new Worker('tasks', async (job) => {
  return await processJob(job.data);
}, { embedded: true });

TCP Server Mode

# Terminal 1: Start the server
bunqueue start --data-path ./data/queue.db

// Terminal 2: Your application connects to the server
import { Queue, Worker } from 'bunqueue/client';

// No embedded option = connects to localhost:6789
const queue = new Queue('tasks');
const worker = new Worker('tasks', async (job) => {
  return await processJob(job.data);
});

Mode Mismatch

Queue and Worker must use the same mode. Mixing embedded Queue with TCP Worker (or vice versa) causes connection timeouts.

Learn more about deployment modes →

---

Performance

Measured on Mac Studio M1 Max, 32GB RAM. Run bun run bench for your hardware.

50-150K ops/sec

Push throughput with batch operations

< 1ms p99

Sub-millisecond latency

~50MB base

Minimal memory footprint

< 100ms

Cold start time

Run benchmarks yourself →

---

Features

Priority Queues

Process high-priority jobs first with configurable priority levels.

Delayed Jobs

Schedule jobs to run at a specific time or after a delay.

Retries & Backoff

Automatic retries with exponential backoff on failure.

Rate Limiting

Control job processing rate per queue or globally.

Stall Detection

Automatic recovery of jobs that become unresponsive.

Dead Letter Queue

Advanced DLQ with metadata, filtering, and auto-retry.

Cron Jobs

Schedule recurring jobs with cron expressions or intervals.

Parent-Child Flows

Create job hierarchies with dependencies.

Progress Tracking

Real-time progress updates and job logs.

Webhooks

HTTP callbacks for job events.

S3 Backup

Automated backups to any S3-compatible storage.

Prometheus Metrics

Built-in metrics endpoint for monitoring.

---

Enterprise Ready

High Availability SQLite WAL mode with S3 backup for disaster recovery.

Observability Prometheus metrics, structured logs, and webhooks.

Security Token-based authentication and rate limiting.

TypeScript Full type safety with comprehensive type definitions.