Back to Documentation

Configuration

Learn about all configuration options and how to customize your queues for different use cases.

Basic Configuration

Configure your queue with the most commonly used options. All configuration options are optional and have sensible defaults.

Basic Queue Configuration
typescript
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.

number

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.

number

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).

boolean

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).

number

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.

number

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).

boolean

Default: false

Common Use Cases

false

In-memory only (default)

true

Survive page refreshes

storageKey

localStorage key for persistent queues (when persistent: true).

string

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

Retry Configuration Examples
typescript
// 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 logic
queue.setProcessor(async (data, task) => {
try {
await processTask(data);
} catch (error) {
// Handle specific error types differently
if (error.code === 'RATE_LIMIT') {
// Longer delay for rate limit errors
task.processAt = Date.now() + 60000; // 1 minute
throw error;
}
throw error;
}
});

Concurrency Configuration

Control how many tasks are processed simultaneously to optimize performance for your use case.

Concurrency Examples
typescript
// Process one task at a time (default)
const serialQueue = new ReliableQueue({
concurrency: 1
});
// Process up to 5 tasks simultaneously
const parallelQueue = new ReliableQueue({
concurrency: 5
});
// Different concurrency for different queue types
const 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.

Persistence Examples
typescript
// Browser persistence with localStorage
const persistentQueue = new ReliableQueue({
persistent: true,
storageKey: 'user-tasks' // Custom storage key
});
// Node.js - persistence is automatically disabled
const nodeQueue = new ReliableQueue({
persistent: true // Will be ignored in Node.js
});
// Check if persistence is active
if (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.

Production-Ready Queue Configurations
typescript
import { ReliableQueue, QueueManager } from '@aplanka/reliable-queue';
// High-throughput email queue
const emailQueue = new ReliableQueue({
maxRetries: 5, // Email delivery is critical
retryDelay: 2000, // Start with 2 second delays
exponentialBackoff: true,
maxRetryDelay: 300000, // Max 5 minutes between retries
concurrency: 10, // Send 10 emails simultaneously
persistent: true,
storageKey: 'email-queue'
});
// Image processing queue
const imageQueue = new ReliableQueue({
maxRetries: 2, // Images can be reprocessed easily
retryDelay: 5000, // Longer initial delay
exponentialBackoff: true,
maxRetryDelay: 60000, // Max 1 minute between retries
concurrency: 2, // CPU intensive, limit concurrency
persistent: false // Don't persist large image data
});
// Background sync queue
const syncQueue = new ReliableQueue({
maxRetries: 10, // Keep trying for a long time
retryDelay: 1000,
exponentialBackoff: true,
maxRetryDelay: 3600000, // Max 1 hour between retries
concurrency: 1, // Ensure ordered processing
persistent: 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