Configuration
Learn about all configuration options and how to customize your queues for different use cases.
Quick Navigation
Basic Configuration
Configure your queue with the most commonly used options. All configuration options are optional and have sensible defaults.
import { ReliableQueue } from '@aplanka/reliable-queue';const queue = new ReliableQueue({maxRetries: 3,retryDelay: 1000,exponentialBackoff: true,concurrency: 2,persistent: false,storageKey: 'my-app-queue'});
Retry Behavior
Control how many times failed tasks are retried and the delay between attempts.
Concurrency
Set how many tasks can be processed simultaneously for optimal performance.
Persistence
Enable localStorage persistence to maintain queues across browser sessions.
All Configuration Options
Complete reference for all available configuration options with examples and use cases.
maxRetries
Maximum number of retry attempts before marking a task as failed.
Default: 3
Common Use Cases
0
No retries - fail immediately
3
Standard retry behavior
10
Critical tasks that must succeed
retryDelay
Base delay in milliseconds before retrying a failed task.
Default: 1000
Common Use Cases
500
Fast retries for quick operations
1000
Standard 1 second delay
5000
Longer delays for heavy operations
exponentialBackoff
Whether to use exponential backoff for retry delays (doubles each retry).
Default: true
Common Use Cases
true
Delays: 1s, 2s, 4s, 8s...
false
Delays: 1s, 1s, 1s, 1s...
maxRetryDelay
Maximum delay in milliseconds for exponential backoff (prevents extremely long delays).
Default: 30000
Common Use Cases
10000
Cap at 10 seconds
30000
Standard 30 second cap
300000
Allow up to 5 minute delays
concurrency
Maximum number of tasks that can be processed simultaneously.
Default: 1
Common Use Cases
1
Serial processing (default)
5
Moderate parallelism
20
High throughput processing
persistent
Whether to persist queue state to localStorage (browser only).
Default: false
Common Use Cases
false
In-memory only (default)
true
Survive page refreshes
storageKey
localStorage key for persistent queues (when persistent: true).
Default: 'reliable-queue'
Common Use Cases
'app-queue'
Custom storage key
'user-123-tasks'
User-specific queue
'reliable-queue'
Default storage key
Retry Configuration Deep Dive
Exponential Backoff
Recommended for most use cases. Reduces server load and improves success rates.
Delays: 1s → 2s → 4s → 8s → 16s
Linear Retries
Use when you need consistent timing or for time-sensitive operations.
Delays: 1s → 1s → 1s → 1s → 1s
// Linear retry delays (1s, 1s, 1s)const linearQueue = new ReliableQueue({maxRetries: 3,retryDelay: 1000,exponentialBackoff: false});// Exponential backoff (1s, 2s, 4s, 8s)const exponentialQueue = new ReliableQueue({maxRetries: 4,retryDelay: 1000,exponentialBackoff: true,maxRetryDelay: 10000 // Cap at 10 seconds});// Custom retry logicqueue.setProcessor(async (data, task) => {try {await processTask(data);} catch (error) {// Handle specific error types differentlyif (error.code === 'RATE_LIMIT') {// Longer delay for rate limit errorstask.processAt = Date.now() + 60000; // 1 minutethrow error;}throw error;}});
Concurrency Configuration
Control how many tasks are processed simultaneously to optimize performance for your use case.
// Process one task at a time (default)const serialQueue = new ReliableQueue({concurrency: 1});// Process up to 5 tasks simultaneouslyconst parallelQueue = new ReliableQueue({concurrency: 5});// Different concurrency for different queue typesconst emailQueue = new ReliableQueue({concurrency: 3 // Send 3 emails at once});const imageQueue = new ReliableQueue({concurrency: 1 // Process images one at a time});
Low Concurrency (1-2)
- • CPU-intensive tasks
- • Sequential processing required
- • Limited system resources
Medium Concurrency (3-10)
- • API calls with rate limits
- • File operations
- • Database operations
High Concurrency (10+)
- • Simple HTTP requests
- • Message sending
- • Data validation
Persistence Configuration
Enable persistence to maintain queue state across browser sessions and page refreshes.
// Browser persistence with localStorageconst persistentQueue = new ReliableQueue({persistent: true,storageKey: 'user-tasks' // Custom storage key});// Node.js - persistence is automatically disabledconst nodeQueue = new ReliableQueue({persistent: true // Will be ignored in Node.js});// Check if persistence is activeif (queue.config.persistent) {console.log('Queue will survive page refreshes');}
Important Notes
- • Persistence only works in browser environments (not Node.js)
- • Large task payloads may hit localStorage size limits
- • Tasks in "processing" state are reset to "pending" on reload
- • Different storage keys allow multiple independent queues
Advanced Configuration Examples
Real-world configuration examples for different types of applications and use cases.
import { ReliableQueue, QueueManager } from '@aplanka/reliable-queue';// High-throughput email queueconst emailQueue = new ReliableQueue({maxRetries: 5, // Email delivery is criticalretryDelay: 2000, // Start with 2 second delaysexponentialBackoff: true,maxRetryDelay: 300000, // Max 5 minutes between retriesconcurrency: 10, // Send 10 emails simultaneouslypersistent: true,storageKey: 'email-queue'});// Image processing queueconst imageQueue = new ReliableQueue({maxRetries: 2, // Images can be reprocessed easilyretryDelay: 5000, // Longer initial delayexponentialBackoff: true,maxRetryDelay: 60000, // Max 1 minute between retriesconcurrency: 2, // CPU intensive, limit concurrencypersistent: false // Don't persist large image data});// Background sync queueconst syncQueue = new ReliableQueue({maxRetries: 10, // Keep trying for a long timeretryDelay: 1000,exponentialBackoff: true,maxRetryDelay: 3600000, // Max 1 hour between retriesconcurrency: 1, // Ensure ordered processingpersistent: true,storageKey: 'sync-queue'});
Best Practices by Use Case
Recommended configurations for common use cases based on real-world experience.
Email Delivery
{ maxRetries: 5, retryDelay: 2000, exponentialBackoff: true, concurrency: 10, persistent: true }
High retry count for delivery reliability, good concurrency for throughput, persistent to survive restarts.
Image Processing
{ maxRetries: 2, retryDelay: 5000, exponentialBackoff: true, concurrency: 2, persistent: false }
Lower retries (images can be reprocessed), limited concurrency (CPU intensive), non-persistent (large data).
API Calls
{ maxRetries: 3, retryDelay: 1000, exponentialBackoff: true, concurrency: 5, persistent: true }
Standard config with moderate concurrency for API rate limits, persistent for reliability.
File Uploads
{ maxRetries: 3, retryDelay: 3000, exponentialBackoff: true, concurrency: 3, persistent: true }
Longer initial delay for network issues, limited concurrency to avoid overwhelming server.
Configuration Tips
Performance Tips
- • Start with conservative concurrency and increase gradually
- • Use exponential backoff for external API calls
- • Monitor task completion rates to optimize retry settings
- • Consider separate queues for different task types
Reliability Tips
- • Enable persistence for critical tasks
- • Set appropriate maxRetryDelay to avoid infinite delays
- • Use different storage keys for different user contexts
- • Test queue behavior under error conditions