@radzor/background-job

Persistent background job queue with retries, scheduling, and concurrency control. Built on BullMQ (Redis) or pg-boss (PostgreSQL). Supports delayed jobs, cron-scheduled jobs, priority queues, and dead letter queues.

Automationv0.1.0typescriptServerqueuejobsbackgroundbullmqpg-bossrediscronretryasyncby Radzor

Install

View source on GitHub →

$npx radzor@latest add background-job

⚠ Constraints: Call process() once per queue at application startup, not inside request handlers. Job payloads must be JSON-serializable. pg-boss creates its own schema in PostgreSQL — no migration needed. BullMQ requires a Redis 6.2+ instance.

Inputs

Name	Type	Default	Description
driver	'bullmq' \| 'pg-boss'	pg-boss	Queue driver. bullmq requires Redis. pg-boss uses your existing PostgreSQL database.
connection*	string	—	Redis URL (bullmq) or PostgreSQL connection string (pg-boss).
concurrency	number	5	Maximum number of jobs processed in parallel.
maxAttempts	number	3	Maximum retry attempts before a job moves to the dead letter queue.
backoffMs	number	1000	Initial delay in milliseconds for exponential backoff between retries.

driver'bullmq' | 'pg-boss'

Queue driver. bullmq requires Redis. pg-boss uses your existing PostgreSQL database.

{ "llm": { "constraints": "Call process() once per queue at application startup, not inside request handlers. Job payloads must be JSON-serializable. pg-boss creates its own schema in PostgreSQL — no migration needed. BullMQ requires a Redis 6.2+ instance.", "usageExamples": "llm/examples.md", "integrationPrompt": "llm/integration.md" }, "name": "@radzor/background-job", "tags": [ "queue", "jobs", "background", "bullmq", "pg-boss", "redis", "cron", "retry", "async" ], "events": [ { "name": "onJobCompleted", "payload": { "jobId": "string", "queue": "string", "durationMs": "number" }, "description": "Fired when a job completes successfully." }, { "name": "onJobFailed", "payload": { "error": "string", "jobId": "string", "queue": "string", "attempt": "number" }, "description": "Fired when a job fails after all retry attempts." }, { "name": "onJobRetry", "payload": { "jobId": "string", "attempt": "number", "nextDelayMs": "number" }, "description": "Fired when a job is scheduled for retry." } ], "inputs": [ { "name": "driver", "type": "'bullmq' | 'pg-boss'", "default": "pg-boss", "required": false, "description": "Queue driver. bullmq requires Redis. pg-boss uses your existing PostgreSQL database." }, { "name": "connection", "type": "string", "required": true, "description": "Redis URL (bullmq) or PostgreSQL connection string (pg-boss)." }, { "name": "concurrency", "type": "number", "default": 5, "required": false, "description": "Maximum number of jobs processed in parallel." }, { "name": "maxAttempts", "type": "number", "default": 3, "required": false, "description": "Maximum retry attempts before a job moves to the dead letter queue." }, { "name": "backoffMs", "type": "number", "default": 1000, "required": false, "description": "Initial delay in milliseconds for exponential backoff between retries." } ], "radzor": "1.0.0", "actions": [ { "name": "enqueue", "params": [ { "name": "queue", "type": "string", "description": "Queue name." }, { "name": "payload", "type": "unknown", "description": "Serializable job data." }, { "name": "options", "type": "EnqueueOptions", "required": false, "description": "delay (ms), priority, repeat (cron), jobId." } ], "returns": "Promise<string>", "description": "Add a job to the queue. Returns the job ID." }, { "name": "process", "params": [ { "name": "queue", "type": "string", "description": "Queue name to process." }, { "name": "handler", "type": "(payload: unknown, jobId: string) => Promise<unknown>", "description": "Async function that processes the job payload." } ], "returns": "void", "description": "Register a worker function for a queue. Call once at startup." }, { "name": "getJob", "params": [ { "name": "jobId", "type": "string", "description": "Job ID to look up." } ], "returns": "Promise<JobResult | null>", "description": "Get the current status and result of a specific job." }, { "name": "cancel", "params": [ { "name": "jobId", "type": "string", "description": "ID of the job to cancel." } ], "returns": "Promise<boolean>", "description": "Cancel a waiting or delayed job. Returns false if already active." }, { "name": "getStats", "params": [ { "name": "queue", "type": "string", "required": false, "description": "Queue name." } ], "returns": "Promise<QueueStats>", "description": "Get queue statistics." } ], "outputs": [ { "name": "jobResult", "type": "JobResult", "fields": [ { "name": "id", "type": "string" }, { "name": "queue", "type": "string" }, { "name": "status", "type": "\"active\" | \"completed\" | \"failed\" | \"cancelled\" | \"retry\" | \"created\"" }, { "name": "data", "type": "unknown" }, { "name": "output", "type": "unknown", "required": false }, { "name": "attempt", "type": "number" }, { "name": "createdOn", "type": "Date" }, { "name": "completedOn", "type": "Date", "required": false } ], "description": "Job execution result with id, status, output data, and attempt count." }, { "name": "queueStats", "type": "QueueStats", "fields": [ { "name": "waiting", "type": "number" }, { "name": "active", "type": "number" }, { "name": "completed", "type": "number" }, { "name": "failed", "type": "number" }, { "name": "delayed", "type": "number" } ], "description": "Queue statistics: waiting, active, completed, failed, delayed counts." } ], "runtime": "server", "version": "0.1.0", "category": "automation", "languages": [ "typescript" ], "description": "Persistent background job queue with retries, scheduling, and concurrency control. Built on BullMQ (Redis) or pg-boss (PostgreSQL). Supports delayed jobs, cron-scheduled jobs, priority queues, and dead letter queues.", "dependencies": { "packages": { "pg-boss": "^10.0.0" } }, "composability": { "connectsTo": [ { "event": "onJobFailed", "description": "Alert team when a background job fails.", "compatibleWith": [ "@radzor/slack-bot.action.sendMessage.text", "@radzor/email-send.action.send.message" ] }, { "event": "onJobCompleted", "description": "Notify on job completion.", "compatibleWith": [ "@radzor/email-send.action.send.message" ] } ] } }

@radzor/background-job

Install

Inputs

Outputs

Actions

Events

Composability

radzor.manifest.json

Version History

Name	Type	Description
jobResult	JobResult	Job execution result with id, status, output data, and attempt count. .idstring .queuestring .status"active" \| "completed" \| "failed" \| "cancelled" \| "retry" \| "created" .dataunknown .outputunknown(optional) .attemptnumber .createdOnDate .completedOnDate(optional)
queueStats	QueueStats	Queue statistics: waiting, active, completed, failed, delayed counts. .waitingnumber .activenumber .completednumber .failednumber .delayednumber