@queuedash/sdk

@queuedash/sdk

Official SDK for QueueDash - Real-time monitoring for Bull, BullMQ, and Bee-Queue.

Installation

npm install @queuedash/sdk
# or
pnpm add @queuedash/sdk
# or
yarn add @queuedash/sdk

Quick Start

BullMQ

import { Queue } from "bullmq";
import { QueueDashClient, attachToBullMQ } from "@queuedash/sdk";

// Create your queue
const myQueue = new Queue("my-queue", {
  connection: { host: "localhost", port: 6379 },
});

// Initialize QueueDash client
const queueDash = new QueueDashClient({
  apiKey: process.env.QUEUEDASH_API_KEY,
});

// Attach to your queue - that's it!
attachToBullMQ(myQueue, queueDash);

// Jobs are now automatically synced to QueueDash

Bull

import Queue from "bull";
import { QueueDashClient, attachToBull } from "@queuedash/sdk";

const myQueue = new Queue("my-queue", {
  redis: { host: "localhost", port: 6379 },
});

const queueDash = new QueueDashClient({
  apiKey: process.env.QUEUEDASH_API_KEY,
});

attachToBull(myQueue, queueDash);

Bee-Queue

import Queue from "bee-queue";
import { QueueDashClient, attachToBeeQueue } from "@queuedash/sdk";

const myQueue = new Queue("my-queue", {
  redis: { host: "localhost", port: 6379 },
});

const queueDash = new QueueDashClient({
  apiKey: process.env.QUEUEDASH_API_KEY,
});

attachToBeeQueue(myQueue, queueDash);

Configuration

API Key

Get your API key from QueueDash:

• Navigate to your environment settings
• Click "API Keys"
• Generate a new API key

# Set in your environment
QUEUEDASH_API_KEY=sk_live_...

Advanced Options

interface QueueDashClientOptions {
  // Required: Your API key from QueueDash
  apiKey: string;

  // Optional: Batch size for syncing jobs (defaults to 50)
  batchSize?: number;

  // Optional: Flush interval in milliseconds (defaults to 100)
  flushInterval?: number;

  // Optional: Max retry attempts with exponential backoff (defaults to 5)
  maxRetries?: number;

  // Optional: Request timeout in milliseconds (defaults to 30000)
  requestTimeout?: number;

  // Optional: Max jobs to queue in memory (defaults to 10000)
  maxQueueSize?: number;

  // Optional: Error handler called on critical failures
  onError?: (error: Error) => void;
}

Reliability & Robustness

The SDK is production-ready with multiple layers of protection:

Retry Logic

• Automatic retries up to 5 times (configurable)
• Exponential backoff: 1s → 2s → 4s → 8s → 16s → 30s (capped)
• Jobs preserved in local queue until successfully synced

Circuit Breaker

• Opens after 10 consecutive failures to prevent overwhelming the API
• Auto-resets after 60 seconds
• Prevents cascading failures

Memory Protection

• Queue size limit (10,000 jobs default) prevents memory leaks
• Oldest jobs dropped first if limit reached
• Warning logged when queue limit hit

Graceful Shutdown

• SIGTERM/SIGINT handlers flush pending jobs before exit
• Warns if jobs remain unsynced on crash
• No jobs lost during normal shutdown

Request Safety

• 30-second timeout on all HTTP requests
• Duplicate detection prevents same job syncing twice
• Network errors handled gracefully

Features

• Real-time sync: Jobs are synced as events happen
• Smart batching: Events are automatically batched for performance
• Auto-retry: Failed syncs are automatically retried
• Zero config: Works out of the box with sensible defaults
• TypeScript: Full TypeScript support

How It Works

The SDK automatically syncs your queue jobs to QueueDash's SaaS platform at api.queuedash.com. Just provide your API key and you're done - no additional configuration needed!

License

MIT