@spec calculate_next_millis(repeat_opts(), non_neg_integer()) ::
  non_neg_integer() | nil

Calculates the next execution time for a repeat configuration.

Parameters

• repeat_opts - Repeat options with pattern or every
• reference_time - Reference time in milliseconds (default: now)

Returns

• The next execution time in milliseconds, or nil if no next time

Examples

# Next minute
next = BullMQ.JobScheduler.calculate_next_millis(%{every: 60_000}, now)

# Next cron execution
next = BullMQ.JobScheduler.calculate_next_millis(%{pattern: "0 * * * *"}, now)

@spec count(pid() | atom(), String.t(), keyword()) ::
  {:ok, non_neg_integer()} | {:error, term()}

Gets the count of job schedulers for a queue.

Examples

{:ok, count} = BullMQ.JobScheduler.count(conn, "my_queue")
# => {:ok, 5}

@spec get(pid() | atom(), String.t(), String.t(), keyword()) ::
  {:ok, scheduler_json() | nil} | {:error, term()}

Gets a job scheduler by ID.

Parameters

• conn - Redis connection
• queue_name - Queue name
• scheduler_id - The scheduler ID
• opts - Options (prefix)

Returns

• {:ok, scheduler} - The scheduler data
• {:ok, nil} - Scheduler not found
• {:error, reason} - Redis error

Examples

{:ok, scheduler} = BullMQ.JobScheduler.get(conn, "my_queue", "daily_report")
# => %{
#   key: "daily_report",
#   name: "daily_report",
#   pattern: "0 9 * * *",
#   next: 1699999999000,
#   iteration_count: 5,
#   template: %{data: %{}, opts: %{}}
# }

@spec list(pid() | atom(), String.t(), keyword()) ::
  {:ok, [scheduler_json()]} | {:error, term()}

Lists all job schedulers for a queue.

Parameters

• conn - Redis connection
• queue_name - Queue name
• opts - Options:
  • :start - Start index (default: 0)
  • :end - End index (default: -1 for all)
  • :asc - Sort ascending (default: false)
  • :prefix - Key prefix (default: "bull")

Returns

• {:ok, schedulers} - List of scheduler data
• {:error, reason} - Redis error

Examples

{:ok, schedulers} = BullMQ.JobScheduler.list(conn, "my_queue")
{:ok, first_10} = BullMQ.JobScheduler.list(conn, "my_queue", start: 0, end: 9)

@spec remove(pid() | atom(), String.t(), String.t(), keyword()) ::
  {:ok, boolean()} | {:error, term()}

Removes a job scheduler and its next scheduled job.

Parameters

• conn - Redis connection
• queue_name - Queue name
• scheduler_id - The scheduler ID to remove
• opts - Options (prefix)

Returns

• {:ok, true} - Scheduler was removed
• {:ok, false} - Scheduler not found
• {:error, reason} - Redis error

Examples

{:ok, true} = BullMQ.JobScheduler.remove(conn, "my_queue", "daily_report")

@spec remove_by_key(pid() | atom(), String.t(), String.t(), keyword()) ::
  {:ok, boolean()} | {:error, term()}

Removes a job scheduler by its key (alias for remove/4).

For backwards compatibility with the "repeatable jobs" API.

@spec upsert(
  pid() | atom(),
  String.t(),
  String.t(),
  repeat_opts(),
  String.t(),
  map(),
  keyword()
) :: {:ok, BullMQ.Job.t()} | {:error, atom()}

Creates or updates a job scheduler.

If a scheduler with the given ID already exists, it will be updated. The scheduler will create a delayed job for the next scheduled execution.

Parameters

• conn - Redis connection
• queue_name - Queue name
• scheduler_id - Unique identifier for the scheduler
• repeat_opts - Repeat configuration (pattern, every, limit, etc.)
• job_name - Name for the jobs created by this scheduler
• job_data - Data to be passed to each job
• opts - Job options (priority, attempts, backoff, etc.)

Returns

• {:ok, job} - The job struct for the next scheduled execution
• {:error, :both_pattern_and_every} - Both pattern and every specified
• {:error, :no_pattern_or_every} - Neither pattern nor every specified
• {:error, :immediately_with_start_date} - Both immediately and start_date specified
• {:error, :limit_reached} - Job has reached its iteration limit
• {:error, :end_date_reached} - Job has passed its end date
• {:error, :job_id_collision} - A job with the same ID already exists in a non-updatable state
• {:error, :job_slots_busy} - Both current and next time slots have jobs

Examples

# Every day at 9 AM
{:ok, job} = BullMQ.JobScheduler.upsert(conn, "emails", "daily_digest",
  %{pattern: "0 9 * * *"},
  "send_digest",
  %{recipient: "all"},
  priority: 10
)

# Every 5 minutes, limited to 100 executions
{:ok, job} = BullMQ.JobScheduler.upsert(conn, "health", "heartbeat",
  %{every: 300_000, limit: 100},
  "ping",
  %{timestamp: true},
  []
)

# Start immediately then repeat every hour
{:ok, job} = BullMQ.JobScheduler.upsert(conn, "sync", "data_sync",
  %{pattern: "0 * * * *", immediately: true},
  "sync_data",
  %{},
  []
)