@basaltkit/queue 1.2.1 → 1.3.0

package/dist/drivers/bullmq.d.ts

@@ -3,6 +3,26 @@ import type { AddJobOptions, JobExecutor, QueueDriver, QueueStats } from '../dri
 export interface BullmqDriverOptions {
     /** Redis URL (redis://... or rediss://...) or ioredis connection options. */
     connection: string | ConnectionOptions;
+    /**
+     * Infra errors from BullMQ's Worker/Queue emitters (e.g. Redis down). BullMQ
+     * emits these as EventEmitter 'error' events — unhandled, they CRASH the
+     * process. Default: logged via console.error with full context — observable,
+     * never fatal, never silent. (Same pattern as realtime's onBridgeError.)
+     */
+    onError?: (error: unknown, info: {
+        queue: string;
+        source: 'worker' | 'queue';
+    }) => void;
+    /**
+     * A job exhausted its retries (BullMQ 'failed'). Default: console.error —
+     * without this, exhausted jobs were only visible by polling queue stats.
+     */
+    onJobFailed?: (info: {
+        queue: string;
+        job: string;
+        jobId?: string;
+        error: unknown;
+    }) => void;
 }
 export declare class BullmqQueueDriver implements QueueDriver {
     readonly name = "bullmq";
@@ -16,6 +36,8 @@ export declare class BullmqQueueDriver implements QueueDriver {
     private readonly queues;
     private readonly workers;
     private executor;
+    private readonly onError;
+    private readonly onJobFailed;
     constructor(options: BullmqDriverOptions);
     setExecutor(executor: JobExecutor): void;
     add(queue: string, jobName: string, data: unknown, options: AddJobOptions): Promise<void>;

package/dist/drivers/bullmq.js

@@ -19,11 +19,19 @@ export class BullmqQueueDriver {
     queues = new Map();
     workers = [];
     executor;
+    onError;
+    onJobFailed;
     constructor(options) {
         this.connection =
             typeof options.connection === 'string'
                 ? parseRedisUrl(options.connection)
                 : options.connection;
+        this.onError =
+            options.onError ??
+                ((error, info) => console.error(`[basalt:queue] bullmq ${info.source} error (queue "${info.queue}"):`, error));
+        this.onJobFailed =
+            options.onJobFailed ??
+                ((info) => console.error(`[basalt:queue] job "${info.job}"${info.jobId ? ` (id ${info.jobId})` : ''} on queue "${info.queue}" failed permanently:`, info.error));
     }
     setExecutor(executor) {
         this.executor = executor;
@@ -41,10 +49,20 @@ export class BullmqQueueDriver {
         });
     }
     startWorker(queue, options = {}) {
-        this.workers.push(new Worker(queue, async (job) => this.executor?.(job.name, job.data), {
+        const worker = new Worker(queue, async (job) => this.executor?.(job.name, job.data), {
             connection: this.connection,
             concurrency: options.concurrency ?? 1,
+        });
+        // Without these listeners an emitted 'error' crashes the process (Node
+        // EventEmitter semantics) and exhausted jobs fail invisibly (Q-2).
+        worker.on('error', (error) => this.onError(error, { queue, source: 'worker' }));
+        worker.on('failed', (job, error) => this.onJobFailed({
+            queue,
+            job: job?.name ?? '(unknown)',
+            ...(job?.id !== undefined ? { jobId: String(job.id) } : {}),
+            error,
         }));
+        this.workers.push(worker);
     }
     async stats(queue) {
         const c = await this.queue(queue).getJobCounts('waiting', 'active', 'completed', 'failed', 'delayed');
@@ -74,6 +92,7 @@ export class BullmqQueueDriver {
         let queue = this.queues.get(name);
         if (!queue) {
             queue = new Queue(name, { connection: this.connection });
+            queue.on('error', (error) => this.onError(error, { queue: name, source: 'queue' }));
             this.queues.set(name, queue);
         }
         return queue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/queue",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Basalt queues on top of BullMQ: declarative jobs with Zod payloads, context propagation (tenant/requestId) to workers and a sync driver for tests.",
   "license": "MIT",
   "type": "module",
@@ -15,7 +15,7 @@
   ],
   "dependencies": {
     "bullmq": "^6.2.1",
-    "@basaltkit/core": "^1.1.2",
+    "@basaltkit/core": "^1.3.0",
     "@basaltkit/events": "^1.0.1"
   },
   "devDependencies": {