The Job API

Read job state, control jobs from a queue, and report progress and logs from inside a processor. Every call talks to NextMQ over HTTP.

Fetching jobs#

const job = await exports.getJob(jobId)
const state = await job.getState()        // 'waiting' | 'active' | 'completed' | ...
await job.refresh()                        // re-fetch latest state

const recent = await exports.getJobs(['waiting', 'active'], 0, 20)
const counts = await exports.getJobCounts() // { waiting, active, completed, failed, ... }
const total  = await exports.count()

Reporting from inside a processor#

Inside a worker processor, use the job handle to stream progress and logs back as the work runs.

export const exportWorker = new Worker('exports', async (job) => {
  await job.log('starting export')
  await job.updateProgress(10)

  const rows = await fetchRows(job.data)
  await job.updateProgress(60)

  await job.updateData({ ...job.data, rowCount: rows.length })
  return { url: await uploadCsv(rows) }
})

Acting on jobs#

Method	What it does
`retry()`	Move a failed job back to waiting to try again.
`promote()`	Promote a delayed job so it runs now.
`changeDelay(ms)`	Reschedule a delayed job.
`changePriority(opts)`	Change a waiting job's priority.
`remove()`	Delete the job from the queue.
`updateData(data)`	Replace the job's data payload.
`updateProgress(n)`	Report progress (number or object).
`log(line)`	Append a log line (retained up to keepLogs).

const job = await exports.getJob(jobId)

await job.changePriority({ priority: 1 })
await job.promote()
await job.retry()
await job.remove()

Parents & child values

For flow parents, read child return values with getChildrenValues(). A child's parent reference is on job.parent and job.parentKey.

const values = await job.getChildrenValues()
// { '<childQueue>:<childJobId>': returnValue, ... }

const parentRef = job.parent     // { id, queueKey } | undefined

Waiting for completion#

waitUntilFinished()polls until the job reaches a terminal state. It's a convenience over re-fetching the job — there's no long-lived connection involved.

const job = await exports.add('csv', { reportId })

const result = await job.waitUntilFinished({
  timeoutMs: 30_000,
  pollIntervalMs: 1000,
})

Note

Native QueueEventspub/sub isn't available — a serverless function can't hold the live connection it needs. Polling with waitUntilFinished() is the supported way to detect completion. See Coming from BullMQ.

← PreviousWorkers & processing Next →Configuration