Overview
The JobScheduler class is used for managing repeatable jobs. It allows you to create, update, and remove job schedulers that automatically create jobs at specified intervals.
Constructor
new JobScheduler(
name: string,
opts: RepeatBaseOptions
)
opts
RepeatBaseOptions
required
Configuration options
The JobScheduler is typically accessed through the Queue.jobScheduler property rather than instantiated directly.
Example
import { Queue } from 'bullmq';
const queue = new Queue('myQueue', {
connection: {
host: 'localhost',
port: 6379,
},
});
// Access the job scheduler
const scheduler = await queue.jobScheduler;
// Or use the queue's upsertJobScheduler method
await queue.upsertJobScheduler(
'my-scheduler',
{ pattern: '0 * * * *' }, // Every hour
{
name: 'hourly-report',
data: { type: 'report' },
}
);
Methods
upsertJobScheduler
Creates or updates a job scheduler.
upsertJobScheduler<T, R, N>(
jobSchedulerId: string,
repeatOpts: RepeatOptions,
jobName: N,
jobData: T,
opts: JobSchedulerTemplateOptions,
config: { override: boolean; producerId?: string }
): Promise<Job<T, R, N> | undefined>
Unique identifier for the job scheduler
Repeat configuration options
Name for jobs created by this scheduler
Data for jobs created by this scheduler
opts
JobSchedulerTemplateOptions
required
Job options template
Whether to override existing scheduler
Optional producer identifier
getScheduler
Retrieves a job scheduler by ID.
getScheduler<D>(id: string): Promise<JobSchedulerJson<D> | undefined>
scheduler
JobSchedulerJson | undefined
The job scheduler data or undefined if not found
getJobSchedulers
Gets all job schedulers.
getJobSchedulers<D>(
start?: number,
end?: number,
asc?: boolean
): Promise<JobSchedulerJson<D>[]>
Offset of first scheduler to return
Offset of last scheduler to return
Return in ascending order by next execution time
getSchedulersCount
Gets the number of job schedulers.
getSchedulersCount(): Promise<number>
removeJobScheduler
Removes a job scheduler.
removeJobScheduler(jobSchedulerId: string): Promise<number>
The identifier of the job scheduler to remove
Number of removed schedulers (0 or 1)
RepeatOptions
interface RepeatOptions {
pattern?: string; // Cron pattern (e.g., '0 * * * *')
every?: number; // Repeat every X milliseconds
limit?: number; // Maximum number of iterations
startDate?: Date | string | number; // Start date
endDate?: Date | string | number; // End date
tz?: string; // Timezone (e.g., 'America/New_York')
immediately?: boolean; // Run immediately then repeat
}
JobSchedulerJson
interface JobSchedulerJson<D = any> {
key: string; // Scheduler identifier
name: string; // Job name
next?: number; // Next execution timestamp
iterationCount?: number; // Number of iterations completed
limit?: number; // Maximum iterations
startDate?: number; // Start date timestamp
endDate?: number; // End date timestamp
tz?: string; // Timezone
pattern?: string; // Cron pattern
every?: number; // Interval in milliseconds
offset?: number; // Offset for every interval
template?: {
data?: D; // Job data template
opts?: JobsOptions; // Job options template
};
}
Examples
Cron-based Scheduler
// Run every day at midnight
await queue.upsertJobScheduler(
'daily-cleanup',
{ pattern: '0 0 * * *' },
{
name: 'cleanup',
data: { scope: 'full' },
}
);
Interval-based Scheduler
// Run every 5 minutes
await queue.upsertJobScheduler(
'health-check',
{ every: 5 * 60 * 1000 },
{
name: 'check-health',
data: { service: 'api' },
}
);
Limited Iterations
// Run 10 times, once per hour
await queue.upsertJobScheduler(
'limited-task',
{
pattern: '0 * * * *',
limit: 10,
},
{
name: 'hourly-task',
data: {},
}
);
With Start and End Dates
await queue.upsertJobScheduler(
'campaign',
{
pattern: '0 9 * * *',
startDate: new Date('2024-01-01'),
endDate: new Date('2024-12-31'),
tz: 'America/New_York',
},
{
name: 'daily-campaign',
data: { campaignId: '123' },
}
);
