Worker options

A worker claims jobs from a queue and runs your handler on them. You start one with queue.process(handler, opts). This page lists every option of WorkerOptions and the Worker it returns.

const worker = queue.process(async (job, ctx) => ({ sent: true }), { concurrency: 5 })

WorkerOptions has its own keys, plus every key of PollingOptions, LeaseOptions, TimeoutOptions and ShutdownOptions. Where a queue option of the same name exists, the worker's value wins, then the queue's, then the default below.

In the examples, queue is a Queue<{ to: string }> and handler is a JobHandler.

Running

NameTypeDefaultMeaning
concurrencynumber1Most jobs this worker runs at once. At least 1.
autorunbooleantrueStart claiming at once. With false, call worker.run().
workerIdstringa UUIDv7This worker's id, shown in events, attempt records and the worker list. Not empty.
acknowledgeVolatileStorebooleanfalseSilence the one warning store is not durable; jobs are lost on restart.
queue.process(handler, { concurrency: 10 })
queue.process(handler, { autorun: false })
queue.process(handler, { workerId: 'mailer-1' })
queue.process(handler, { acknowledgeVolatileStore: true })

Retries

NameTypeDefaultMeaning
retryIf(err: Error, job: Job) => boolean | Promise<boolean>none: retry every errorReturn false to fail the job for good with reason 'not-retryable'.
backoffStrategiesRecord<string, BackoffFn>noneCustom backoff functions by name.
unwrapCausebooleantrueAlso look for an UnrecoverableError in the error's cause chain.
queue.process(handler, { retryIf: (err) => err.name !== 'ValidationError' })
queue.process(handler, { backoffStrategies: { 'retry-after': (attempt, error, job, spec) => spec.delay * attempt } })
queue.process(handler, { unwrapCause: false })

The full decision and the backoff maths: Retry and backoff.

Polling

PollingOptions. An idle worker waits between claims. The wait starts at pollMin and grows by pollFactor after each empty claim, up to pollMax. A local add, a finished job or a store notification wakes the worker at once.

NameTypeDefaultMeaning
pollMinDuration100 msShortest wait, and the wait right after a wake-up. At least 1 ms.
pollMaxDuration'5s'Longest wait while idle. At least pollMin.
pollFactornumber2Growth of the wait after each empty claim. Above 1.
pollJitternumber0.2Random spread of each wait, 0 to 1.
notifybooleantrueWake on the store's change notifications, when the store has them.
queue.process(handler, { pollMin: 50 })
queue.process(handler, { pollMax: '30s' })
queue.process(handler, { pollFactor: 1.5 })
queue.process(handler, { pollJitter: 0 })
queue.process(handler, { notify: false })

Leases

LeaseOptions. A claimed job is held by a lease. While the handler runs, the worker renews the lease every third of its length, so a job may run far longer than its lease.

NameTypeDefaultMeaning
leaseDurationDurationthe queue's, else '30s'Lease length. 1 s to 1 d.
leaseDurationByNameRecord<string, Duration>noneLease length per job name. Same range.
queue.process(handler, { leaseDuration: '2m' })
queue.process({ report: async (job) => job.id }, { leaseDurationByName: { report: '15m' } })

For one job name the lease comes from, in order: the worker's leaseDurationByName, the queue's leaseDurationByName, the worker's leaseDuration, the queue's leaseDuration, then 30 s.

When the lease is lost, the worker aborts ctx.signal with LeaseLostError and emits leaseLost. The handler's result is thrown away. A handler that keeps the CPU busy for more than about two thirds of the lease stops the renewals; give that job name a longer lease, or await inside long loops.

Time limits

TimeoutOptions. Also accepted on the queue and on add; for each field the value from add wins, then the worker's, then the queue's.

NameTypeDefaultMeaning
timeoutDurationnoneAbort ctx.signal with JobTimeoutError this long after the handler starts. 1 ms to 2147483647 ms.
timeoutGraceDuration'5s'How long a timed-out handler may keep running. Then the attempt fails with abandoned: true and its late result is ignored. 0 fails at once.
queue.process(handler, { timeout: '2m' })
queue.process(handler, { timeout: '2m', timeoutGrace: 0 })

Shutdown

ShutdownOptions. Also accepted on the queue, as the default for its workers.

NameTypeDefaultMeaning
shutdownTimeoutDuration'25s'How long close() lets running handlers finish normally.
shutdownAbortGraceDuration'2s'After that, ctx.signal aborts with ShutdownError. This is how long close() then waits before it releases the jobs.
queue.process(handler, { shutdownTimeout: '1m' })
queue.process(handler, { shutdownAbortGrace: '5s' })

A released job goes back to waiting at once, with its attempt refunded, so another worker can pick it up.

Upkeep

NameTypeDefaultMeaning
sweepIntervalDuration'5s'How often this pod looks for jobs whose lease expired, ±20 %. 500 ms to 1 d.
sweepBatchnumber100Most expired jobs one sweep recovers, 1 to 1000. Capped to the store's limit, with one warning.
heartbeatIntervalDuration'10s'How often the worker refreshes its record in the worker list. 1 s to 1 d.
hoststringthe machine's host nameThe host shown in the worker list and attempt records. Not empty.
labelsRecord<string, string>{}Tags shown in the worker list. At most 10; each key and value 1 to 64 characters.
queue.process(handler, { sweepInterval: '30s' })
queue.process(handler, { sweepBatch: 500 })
queue.process(handler, { heartbeatInterval: '30s' })
queue.process(handler, { host: 'mailer-pod-7' })
queue.process(handler, { labels: { region: 'eu', team: 'growth' } })

One sweeper runs per queue object: the first worker to run sets its sweepInterval and sweepBatch.

Progress

NameTypeDefaultMeaning
progressIntervalDuration'250ms'Least time between two progress writes of one job. Calls in between are merged; the latest wins.
maxProgressBytesnumber4096Most bytes of the object form of ctx.progress. A larger one rejects with PayloadTooLargeError.
queue.process(handler, { progressInterval: '1s' })
queue.process(handler, { maxProgressBytes: 16_384 })

Handlers

JobHandler<D, R> is (job: Job<D, R>, ctx: JobContext) => R | Promise<R>. It runs once per attempt. What it returns is the job's result; what it throws fails the attempt. See Job and context.

const send: JobHandler<{ to: string }, { sent: true }> = async (job, ctx) => ({ sent: true })

For named jobs pass an object of handlers, one per name: queue.process({ welcome: async (job) => true, digest: async (job) => true }). To type each name's data and result, see Named jobs. Each job name may have one open worker per queue object; a second one throws DuplicateHandlerError. Unnamed workers have no such limit.

Worker

queue.process returns a Worker<D, R>.

MemberTypeMeaning
idstringThe worker id.
concurrencynumberThe concurrency it was started with.
inFlightnumberSlots in flight now: running handlers, out of concurrency. A batch takes one slot.
stateWorkerState'created', 'running', 'stopping' or 'stopped'.
isRunning()booleanstate === 'running'. A paused worker is still running.
run()Promise<void>Start the loop, for autorun: false. Resolves once started. Calling it again while running does nothing.
pause(opts?)Promise<void>Stop taking jobs on this worker only. { waitForActive: true } also waits for the jobs it is running.
resume()voidTake jobs again.
isPaused(scope?)booleanPaused here or, as last seen, on the whole queue. PauseScope 'local' or 'global' asks for one.
close(opts?)Promise<void>Stop this worker. { timeoutMs } replaces shutdownTimeout for this call.
on(event, fn)UnsubscribeListen for a worker event.
once(event, fn)UnsubscribeListen once.
off(event, fn)voidStop listening.
console.log(worker.id, worker.concurrency, worker.inFlight, worker.state, worker.isRunning())
await worker.run()
await worker.pause({ waitForActive: true })
worker.resume()
const pausedHere = worker.isPaused('local')
await worker.close({ timeoutMs: 10_000 })
worker.on('failed', ({ job, reason }) => console.log(job.id, reason))
worker.once('closed', () => console.log('worker stopped'))
worker.off('failed', listener)

close() stops in order: no new claims; running handlers get shutdownTimeout; then ctx.signal aborts with ShutdownError and they get shutdownAbortGrace more; then their jobs are released. It resolves within shutdownTimeout plus shutdownAbortGrace, plus at most one second. Worker events: Events.

Was this page helpful?