Background Jobs - Volt Documentation

Complete queue example

index.ts

import { Volt, JobQueue } from 'voltts';

const queue = new JobQueue({ concurrency: 2 });
queue.define('receipt', (job) => ({ orderId: job.data.orderId, generated: true }));
const app = new Volt();
app.onStop(() => queue.stop());
app.post('/receipts', (c) => {
  const job = queue.add('receipt', { orderId: 'order-1' }, { attempts: 3, backoffDelayMs: 100 });
  return c.json({ id: job.id }, 202);
});
app.get('/jobs/:id', (c) => {
  const job = queue.getJob(c.params.id);
  if (!job) return c.json({ error: 'Job not found' }, 404);
  return c.json({ id: job.id, status: job.status, result: job.result });
});
if (globalThis._importMeta_.main) app.listen(3000);
export default app;

Enqueue a job

bash

bun run index.ts
curl -i -X POST http://localhost:3000/receipts
# Use the returned id:
curl http://localhost:3000/jobs/REPLACE_WITH_JOB_ID

The queue runs two handlers concurrently, retries failed jobs up to three attempts, and reports pending, running, completed, or failed. waitForJob(id) is useful in tests; avoid waiting for background work in the API request that enqueues it.

Durability and shutdown

JobQueue is an in-process memory queue. It does not persist jobs, coordinate workers across processes, or currently enforce the priority option. stop() pauses scheduling; it does not await all active jobs. Use a durable external queue for work that must survive a process restart.