Overview
JobOptions (also known as JobsOptions) provides configuration for individual jobs added to a queue.
Interface
interface JobsOptions extends BaseJobOptions {
jobId?: string;
delay?: number;
priority?: number;
attempts?: number;
backoff?: number | BackoffOptions;
lifo?: boolean;
removeOnComplete?: boolean | number | KeepJobs;
removeOnFail?: boolean | number | KeepJobs;
keepLogs?: number;
stackTraceLimit?: number;
sizeLimit?: number;
timestamp?: number;
repeat?: RepeatOptions;
parent?: ParentOptions;
}
Properties
jobId
Override the job ID (must be unique)
await queue.add('task', { data }, {
jobId: 'unique-task-123',
});
delay
Delay in milliseconds before the job can be processed
// Process after 5 seconds
await queue.add('task', { data }, {
delay: 5000,
});
priority
Priority from 0 (highest) to 2,097,152 (lowest)
await queue.add('urgent-task', { data }, {
priority: 1, // Higher priority
});
await queue.add('normal-task', { data }, {
priority: 10, // Lower priority
});
attempts
Total number of attempts to try the job until it completes
await queue.add('task', { data }, {
attempts: 3, // Try up to 3 times
});
backoff
Backoff setting for automatic retries if the job fails
// Simple fixed backoff
await queue.add('task', { data }, {
attempts: 3,
backoff: 5000, // 5 second delay between retries
});
// Exponential backoff with jitter
await queue.add('task', { data }, {
attempts: 5,
backoff: {
type: 'exponential',
delay: 1000,
jitter: 0.2,
},
});
lifo
If true, adds the job to the left of the queue (LIFO) instead of the right (FIFO)
await queue.add('task', { data }, {
lifo: true, // Process this job before older waiting jobs
});
removeOnComplete
removeOnComplete
boolean | number | KeepJobs
If true, removes the job when it successfully completes
// Remove immediately
await queue.add('task', { data }, {
removeOnComplete: true,
});
// Keep last 100 completed jobs
await queue.add('task', { data }, {
removeOnComplete: 100,
});
// Keep completed jobs for 1 hour or max 1000
await queue.add('task', { data }, {
removeOnComplete: {
age: 3600,
count: 1000,
},
});
removeOnFail
removeOnFail
boolean | number | KeepJobs
If true, removes the job when it fails after all attempts
await queue.add('task', { data }, {
removeOnFail: false, // Keep failed jobs (default)
});
await queue.add('task', { data }, {
removeOnFail: {
age: 86400, // Keep for 24 hours
count: 5000,
},
});
keepLogs
Maximum number of log entries to preserve
await queue.add('task', { data }, {
keepLogs: 100, // Keep last 100 log entries
});
stackTraceLimit
Limits the number of stack trace lines recorded
await queue.add('task', { data }, {
stackTraceLimit: 10,
});
sizeLimit
Limits the size in bytes of the job’s data payload (JSON serialized)
await queue.add('task', { data }, {
sizeLimit: 1024 * 100, // 100 KB limit
});
timestamp
timestamp
number
default:"Date.now()"
Timestamp when the job was created
repeat
Repeat configuration for creating recurring jobs
// Deprecated: Use queue.upsertJobScheduler instead
await queue.add('task', { data }, {
repeat: {
pattern: '0 * * * *', // Every hour
},
});
parent
Parent job configuration for creating job dependencies
// Typically used with FlowProducer, not directly
await queue.add('child-task', { data }, {
parent: {
id: 'parent-job-id',
queue: 'bull:parentQueue',
},
});
Examples
Simple Job
Job with Retries
await queue.add('api-call', { endpoint: '/users' }, {
attempts: 3,
backoff: {
type: 'exponential',
delay: 2000,
},
});
Delayed Job
// Send email in 1 hour
await queue.add('reminder', { userId: 123 }, {
delay: 60 * 60 * 1000,
});
High Priority Job
await queue.add('urgent-notification', { message: 'Alert!' }, {
priority: 1,
lifo: true,
});
Job with Auto-Cleanup
await queue.add('temp-task', { data }, {
removeOnComplete: true,
removeOnFail: {
age: 3600, // Keep failed jobs for 1 hour
},
});
BackoffOptions
interface BackoffOptions {
type: string; // 'fixed', 'exponential', or custom
delay?: number; // Delay in milliseconds
jitter?: number; // Jitter factor (0-1)
}
KeepJobs
type KeepJobs = {
age?: number; // Max age in seconds
count?: number; // Max count to keep
};
ParentOptions
interface ParentOptions {
id: string; // Parent job ID
queue: string; // Qualified parent queue key
}
