JobScheduler

Manage scheduled jobs that repeat at specified intervals

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
)

name · string · required

The name of the queue

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>

jobSchedulerId · string · required

Unique identifier for the job scheduler

repeatOpts · RepeatOptions · required

Repeat configuration options

jobName · string · required

Name for jobs created by this scheduler

jobData · any · required

Data for jobs created by this scheduler

opts · JobSchedulerTemplateOptions · required

Job options template

config.override · boolean · required

Whether to override existing scheduler

config.producerId · string

Optional producer identifier

getScheduler

Retrieves a job scheduler by ID.

getScheduler<D>(id: string): Promise<JobSchedulerJson<D> | undefined>

id · string · required

The job scheduler ID

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>[]>

start · number · default: "0"

Offset of first scheduler to return

end · number · default: "-1"

Offset of last scheduler to return

asc · boolean · default: "false"

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>

jobSchedulerId · string · required

The identifier of the job scheduler to remove

removed · number

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' },
  }
);