Your first queue
This page builds a small email queue. It adds three jobs, runs them, reports each outcome, waits until the queue is empty and then closes it.
The code
Save this as first-queue.ts:
import { Queue, UnrecoverableError } from '@sureq/core'
type Email = { to: string; subject: string }
// No `store` option: the queue makes its own in-memory store.
const queue = new Queue<Email, { sent: true }>('emails', {
defaultJobOptions: { maxAttempts: 3 },
})
const worker = queue.process(
async (job) => {
if (!job.data.to.includes('@')) {
throw new UnrecoverableError('invalid address') // fail now, no retry
}
// Send the email here.
return { sent: true }
},
{ concurrency: 5 },
)
worker.on('completed', ({ job, result }) => console.log(job.id, 'completed', result))
worker.on('failed', ({ job, reason, error }) => console.log(job.id, 'failed:', reason, error.message))
worker.on('error', ({ error }) => console.error('worker error', error))
const drained = new Promise<void>((resolve) => queue.on('drained', () => resolve()))
await queue.add({ to: 'ada@example.com', subject: 'Welcome' }, { id: 'welcome-ada' })
await queue.add({ to: 'alan@example.com', subject: 'Welcome' }, { id: 'welcome-alan' })
await queue.add({ to: 'not-an-email', subject: 'Oops' }, { id: 'oops' })
await drained
console.log(await queue.getCounts())
await queue.close()Run it. In a new folder, run npm init -y, then npm install @sureq/core, and add "type": "module" to package.json. Node 22.18 or newer runs a TypeScript file directly (plain type annotations only). On an older Node 22, use a runner such as tsx.
node first-queue.ts
# or
npx tsx first-queue.tsThe output
store is not durable; jobs are lost on restart { queue: 'emails' }
welcome-ada completed { sent: true }
welcome-alan completed { sent: true }
oops failed: unrecoverable invalid address
{
waiting: 0,
delayed: 0,
active: 0,
completed: 2,
failed: 1,
cancelled: 0,
blocked: 0
}What happened
new Queue('emails', ...)made a queue.Emailis the type of the job data, and{ sent: true }is the type of the result.defaultJobOptionssets options for every job added to this queue. Here each job gets at most 3 attempts.queue.process(handler, options)started a worker. The handler runs once per attempt. What it returns is the job's result.concurrency: 5lets up to five jobs run at once.- The first line,
store is not durable; jobs are lost on restart, is a warning the worker logs once when it starts. It is expected with the built-in in-memory store, which loses every job when the process exits. A durable store makes it go away. In tests and local scripts you can silence it with the worker optionacknowledgeVolatileStore: true; see Testing your jobs. queue.add(data, { id })stored each job. Theidis optional; without it SureQ makes one for you.- The third job threw
UnrecoverableError, so it failed at once with reasonunrecoverable. Any other error is retried untilmaxAttemptsis used up. - The worker emits
completedandfailedonce per job. It emitserrorfor problems that are not a job failure, such as a store error. Always listen forerror. - The queue emits
drainedwhen no job is left to run. queue.getCounts()shows how many jobs are in each state.blockedcounts waiting jobs held back by a pause. It is not a seventh state.queue.close()stopped the worker and closed the in-memory store the queue made.
Next
- Learn the words used in these docs: Core concepts.
- Add jobs with delays, priorities and names: Adding jobs.
- Write handlers and tune workers: Processing jobs.
- Control retries: Retries and failures.