Job options

Options for one job, given as the second argument of queue.add(data, opts) or as opts of an addBulk item. An option set to undefined counts as not given.

await queue.add({ to: 'ada@example.com' }, { name: 'welcome', priority: 10, delay: '5m' })

In the examples, queue is a Queue<{ to: string }> and data is { to: 'ada@example.com' }.

Add options

Every key of AddOptions.

Identity

NameTypeDefaultMeaning
idstring | ((data: D) => string)the queue's id function, else a UUIDv7The job id, or a synchronous function that makes it from the data.
namestringnone (null)The job name. Picks the handler in process({ name: handler }). 1 to 128 characters from A-Z a-z 0-9 . _ : / -.
idempotencyKeystringnamespace:queue:id:seqStored as job.idempotencyKey. Pass it to outside APIs so a repeated run has no second effect.
await queue.add(data, { id: 'welcome-ada' })
await queue.add(data, { name: 'welcome' })
await queue.add(data, { idempotencyKey: 'order-42-receipt' })

Duplicates

NameTypeDefaultMeaning
onDuplicateDuplicateRule<D>the queue's onDuplicate ('ignore')What to do when the id is taken.
uniqueWhile'pending' | 'retained'the queue's uniqueWhile ('pending')How long the job holds its id.
singletonKeystring | nullnoneAt most one waiting or delayed job per key. null holds nothing.
await queue.add(data, { id: 'welcome-ada', onDuplicate: 'replace' })
await queue.add(data, { id: 'welcome-ada', uniqueWhile: 'retained' })
await queue.add(data, { singletonKey: 'sync:acme' })

DuplicateRule<D> is one of:

RuleWhat happens when the id is taken
'ignore'Nothing is written. The add returns the existing job with added: false.
'replace'A waiting or delayed job gets the new data and the options this add sets.
'reject'The add throws DuplicateJobError.
(existing, incoming) => DMerges the two into new data. The function must be pure: it may run more than once.
await queue.add(data, { id: 'welcome-ada', onDuplicate: (existing, incoming) => ({ ...existing.data, ...incoming }) })

A job that already started is never replaced or merged. The add then reports ignored with existingState: 'active'.

uniqueWhile:

  • 'pending': the id is held while the job is waiting, delayed or active. Once it finishes, a new job may take the id.
  • 'retained': the id is held until the job is deleted, by retention or by remove. Such jobs are kept for retention.retainedAge (default 7 days) unless a rule gives an age.

singletonKey: while another job holds the key, the add returns that job (by: 'singletonKey'). The key is free again once the holder starts.

Timing and order

NameTypeDefaultMeaning
delayDuration0Wait this long before the job can run. At most 100 years.
runAtDate | numbernoneRun at this time (a Date or epoch ms). A past time runs now.
prioritynumber0Higher runs first. A whole number from -2147483648 to 2147483647.
firstbooleanfalsePut the job at the front of its priority level.
await queue.add(data, { delay: '10m' })
await queue.add(data, { runAt: new Date(Date.now() + 60_000) })
await queue.add(data, { priority: 10 })
await queue.add(data, { first: true })

Set delay or runAt, not both. Times use the store's clock. See Durations.

Retries and time limits

NameTypeDefaultMeaning
maxAttemptsnumber3Most attempts, the first one included. At least 1.
backoffBackoffSpecexponential from 1 s, factor 2, full jitter, 1 h capThe wait before each retry. See Retry and backoff.
timeoutDurationthe worker's, else the queue's, else noneAbort ctx.signal with JobTimeoutError this long after the handler starts.
timeoutGraceDurationthe worker's, else the queue's, else '5s'How long a timed-out handler may keep running before the attempt fails anyway. 0 fails at once.
await queue.add(data, { maxAttempts: 5 })
await queue.add(data, { backoff: { type: 'exponential', delay: '2s', maxDelay: '10m' } })
await queue.add(data, { timeout: '30s' })
await queue.add(data, { timeout: '30s', timeoutGrace: '2s' })

The maxAttempts, backoff and timeout values are stored on the job, so every worker uses the same ones.

Retention

NameTypeDefaultMeaning
keep{ completed?: JobKeep; failed?: JobKeep; cancelled?: JobKeep }the queue's retentionHow long this job is kept once finished, per outcome.
await queue.add(data, { keep: { completed: 0, failed: '30d' } })

A JobKeep is true (forever), false or 0 (keep none), a Duration such as '1d', or { age }. A single job has no count. A bare number is refused on a job, because on a queue retention the same number means a count: write '1000ms' or { age: 1000 } for time. A job with its own keep.failed is never dead-lettered. Keep none on a job added with uniqueWhile: 'retained' is an InvalidOptionError. See retention.

Job defaults

JobDefaults is what the queue option defaultJobOptions takes. Each value applies to every add that does not set it.

NameTypeDefaultMeaning
maxAttemptsnumber3Most attempts per job.
backoffBackoffSpecexponential from 1 s, factor 2, full jitter, 1 h capThe wait before each retry.
prioritynumber0Priority of each job. Higher runs first.
new Queue('emails', { defaultJobOptions: { maxAttempts: 5 } })
new Queue('emails', { defaultJobOptions: { backoff: '30s' } })
new Queue('emails', { defaultJobOptions: { priority: 1 } })

Any other key in defaultJobOptions is an InvalidOptionError. onDuplicate and uniqueWhile are queue options instead; id, name, delay, runAt, first, singletonKey and idempotencyKey are per add only.

Order of steps

Every add runs the same steps: resolve options and defaults (id and keys too), the queue filter, serialize the data, check maxPayloadBytes, then one store call. A failed step stores nothing.

Was this page helpful?