Queues & job options

A Queue is a named producer. Creating one is local; add() and addBulk() send your jobs to NextMQ, which validates the options and runs them.

Creating a queue#

import { Queue } from '@nextmq/sdk'

type NotifyJob = { userId: string; channel: 'push' | 'sms' }
const notificationQueue = new Queue<NotifyJob>('notifications')

Note

Queue names must be 1-128 characters and may contain only letters, numbers, _, -, and .. Custom jobId values cannot contain : or be integer strings.

Adding jobs#

// Single job
await notificationQueue.add('digest', { userId, channel: 'push' })

// With options
await notificationQueue.add('digest', { userId, channel: 'push' }, {
  delay: 5000,
  attempts: 3,
  backoff: { type: 'exponential', delay: 2000 },
  priority: 1,
})

addBulk

await notificationQueue.addBulk([
  { name: 'digest', data: { userId: 'u_1', channel: 'push' } },
  { name: 'digest', data: { userId: 'u_2', channel: 'sms' }, opts: { delay: 1000 } },
])

Supported job options#

Pass any of these in the third argument to add(). Options that can't survive a remote queue are rejected with a clear error, never silently dropped.

Option	Description
`delay`	Milliseconds to wait before the job becomes eligible to run.
`attempts`	Total times to try the job before it's marked failed.
`backoff`	Retry delay strategy: { type: 'fixed' \| 'exponential', delay }.
`priority`	Lower number runs first.
`jobId`	Custom job id. It cannot contain ':' or be an integer string.
`lifo`	Push to the front of the queue instead of the back.
`keepLogs`	Max number of log lines to retain.
`sizeLimit`	Reject the job if its serialized data exceeds this many bytes.
`removeOnComplete`	Retention for completed jobs — see clamping below.
`removeOnFail`	Retention for failed jobs — see clamping below.
`repeat`	Limited repeatable config; prefer Job Schedulers.
`deduplication`	Collapse duplicate work — see below.

Retention#

NextMQ automatically sets retention defaults, so completed and failed jobs don't pile up and your storage stays bounded. You can override them per job with removeOnComplete, removeOnFail, and keepLogs — see the SDK reference for the specifics.

Deduplication#

Pass a deduplication id to collapse duplicate work within a TTL window — handy when a form can be double-submitted or a request gets retried.

await reportQueue.add('csv', { reportId }, {
  deduplication: { id: `csv-${reportId}`, ttl: 60_000 },
})

Supported fields: id, ttl, extend, replace, and keepLastIfActive. The helpers getDeduplicationJobId and removeDeduplicationKey are available on the queue.

Queue-wide throughput controls#

setGlobalConcurrency and setGlobalRateLimitcap a whole queue's throughput — how many jobs run at once and how many start per window — and you can change them at runtime from the SDK or dashboard with no redeploy. Use them to throttle a queue protecting a shared third-party or AI API; the full method list is in the SDK reference.

Inspecting and maintaining queues#

Queue reads are paged HTTP calls. Use getJobs() or state helpers such as getWaiting() and getFailed() for lists, and count helpers such as getWaitingCount() for counters. Server-side maintenance methods include pause(), resume(), drain(), clean(), retryJobs(), promoteJobs(), and obliterate(). Every Queue method is described in the SDK reference.

Tip

Need recurring jobs? Use Job Schedulers rather than ad-hoc repeat options.

PreviousHow it works NextWorkers & processing