bunqueue 2.8.31 → 2.8.33

package/dist/infrastructure/server/handlers/pushBatchValidation.js

@@ -0,0 +1,70 @@
+/**
+ * PUSHB Validation
+ * Per-job validation for batch pushes with PUSH parity: the same
+ * validateJobData/validateJobOptions bounds and the same dependsOn
+ * existence gate handlePush enforces (core.ts).
+ */
+import { validateJobData, validateJobOptions } from '../protocol';
+/**
+ * Validate every job of a PUSHB batch. Returns an error message naming the
+ * offending index, or null when the whole batch is valid.
+ *
+ * The dependsOn gate is EXTENDED beyond the PUSH one: a dependency may also
+ * reference ANY OTHER job of the same batch via its custom id (the only ids
+ * a client can know before the batch is applied). Order within the batch is
+ * deliberately irrelevant: the default-on auto-batcher groups concurrent
+ * add() calls in arbitrary order, so a child can legitimately precede its
+ * parent in the array, and the readiness layer (waitingDeps) resolves the
+ * chain once the whole batch is applied. Self-references are rejected, they
+ * can never resolve. jobIndex/completedJobs/depCompletions are hoisted out
+ * of the loop because PUSHB is the bulk hot path.
+ */
+export function validatePushBatchJobs(jobs, ctx) {
+    const jobIndex = ctx.queueManager.getJobIndex();
+    const completedJobs = ctx.queueManager.getCompletedJobs();
+    const depCompletions = ctx.queueManager.getDepCompletions();
+    // Custom ids of ALL jobs in this batch: they become real job ids the
+    // moment the batch is applied. Allocated lazily (most batches have neither
+    // custom ids nor dependencies).
+    let batchIds = null;
+    for (const job of jobs) {
+        if (job.customId) {
+            batchIds ??= new Set();
+            batchIds.add(job.customId);
+        }
+    }
+    for (let i = 0; i < jobs.length; i++) {
+        const job = jobs[i];
+        const dataError = validateJobData(job.data);
+        if (dataError)
+            return `jobs[${i}]: ${dataError}`;
+        const optionsError = validateJobOptions({
+            priority: job.priority,
+            delay: job.delay,
+            timeout: job.timeout,
+            maxAttempts: job.maxAttempts,
+            backoff: job.backoff,
+            ttl: job.ttl,
+        });
+        if (optionsError)
+            return `jobs[${i}]: ${optionsError}`;
+        if (job.dependsOn && job.dependsOn.length > 0) {
+            for (const depId of job.dependsOn) {
+                const key = String(depId);
+                if (key === job.customId) {
+                    return `jobs[${i}]: Job cannot depend on itself: ${key}`;
+                }
+                const exists = jobIndex.has(depId) ||
+                    completedJobs.has(depId) ||
+                    // removeOnComplete parents leave only a bare completion id behind;
+                    // the gate must honor it exactly like PUSH does.
+                    depCompletions.has(depId) ||
+                    (batchIds?.has(key) ?? false);
+                if (!exists) {
+                    return `jobs[${i}]: Dependency job not found: ${key}`;
+                }
+            }
+        }
+    }
+    return null;
+}

package/dist/infrastructure/server/queueCountsScheduler.d.ts

@@ -0,0 +1,13 @@
+import type { QueueManager } from '../../application/queueManager';
+import type { QueueJobCounts } from '../../application/queueStatsAggregator';
+/** Coalesce high-volume job events into one queue-count aggregation per tick. */
+export declare class QueueCountsScheduler {
+    private readonly queueManager;
+    private readonly emit;
+    private readonly pendingQueues;
+    private timer;
+    constructor(queueManager: QueueManager, emit: (queue: string, counts: QueueJobCounts) => void);
+    schedule(queue: string): void;
+    stop(): void;
+    private flush;
+}

package/dist/infrastructure/server/queueCountsScheduler.js

@@ -0,0 +1,35 @@
+const COUNTS_COALESCE_MS = 10;
+/** Coalesce high-volume job events into one queue-count aggregation per tick. */
+export class QueueCountsScheduler {
+    queueManager;
+    emit;
+    pendingQueues = new Set();
+    timer = null;
+    constructor(queueManager, emit) {
+        this.queueManager = queueManager;
+        this.emit = emit;
+    }
+    schedule(queue) {
+        this.pendingQueues.add(queue);
+        this.timer ??= setTimeout(() => this.flush(), COUNTS_COALESCE_MS);
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.pendingQueues.clear();
+    }
+    flush() {
+        this.timer = null;
+        if (this.pendingQueues.size === 0)
+            return;
+        const queues = Array.from(this.pendingQueues);
+        this.pendingQueues.clear();
+        const countsByQueue = this.queueManager.getQueueJobCountsBatch(queues);
+        for (const queue of queues) {
+            const counts = countsByQueue.get(queue);
+            if (counts)
+                this.emit(queue, counts);
+        }
+    }
+}

package/dist/infrastructure/server/sseHandler.d.ts

@@ -30,6 +30,7 @@ export declare class SseHandler {
     private healthInterval;
     private storageInterval;
     private queueManager;
+    private queueCountsScheduler;
     private readonly eventBuffer;
     /** Get client count */
     get size(): number;

package/dist/infrastructure/server/sseHandler.js

@@ -13,6 +13,7 @@
  */
 import { throughputTracker } from '../../application/throughputTracker';
 import { uuid } from '../../shared/hash';
+import { QueueCountsScheduler } from './queueCountsScheduler';
 const textEncoder = new TextEncoder();
 /** Tuning constants */
 const MAX_CLIENTS = 1000;
@@ -45,6 +46,7 @@ export class SseHandler {
     healthInterval = null;
     storageInterval = null;
     queueManager = null;
+    queueCountsScheduler = null;
     eventBuffer = [];
     /** Get client count */
     get size() {
@@ -54,6 +56,17 @@ export class SseHandler {
     /** Start heartbeat + periodic broadcasts (stats, health, storage) */
     startBroadcasts(qm) {
         this.queueManager = qm;
+        this.queueCountsScheduler ??= new QueueCountsScheduler(qm, (queue, counts) => {
+            this.sendTypedEvent('queue:counts', {
+                queue,
+                waiting: counts.waiting,
+                prioritized: counts.prioritized,
+                active: counts.active,
+                completed: counts.completed,
+                failed: counts.failed,
+                delayed: counts.delayed,
+            });
+        });
         this.heartbeatTimer ??= setInterval(() => {
             this.sendHeartbeat();
         }, HEARTBEAT_MS);
@@ -78,6 +91,8 @@ export class SseHandler {
     }
     /** Stop all timers */
     stopTimers() {
+        this.queueCountsScheduler?.stop();
+        this.queueCountsScheduler = null;
         if (this.heartbeatTimer) {
             clearInterval(this.heartbeatTimer);
             this.heartbeatTimer = null;
@@ -154,19 +169,9 @@ export class SseHandler {
         }
         for (const clientId of disconnected)
             this.clients.delete(clientId);
-        // Emit queue:counts on every job state change (mirrors wsHandler)
-        if (this.queueManager) {
-            const counts = this.queueManager.getQueueJobCounts(event.queue);
-            this.sendTypedEvent('queue:counts', {
-                queue: event.queue,
-                waiting: counts.waiting,
-                prioritized: counts.prioritized,
-                active: counts.active,
-                completed: counts.completed,
-                failed: counts.failed,
-                delayed: counts.delayed,
-            });
-        }
+        // Counts are eventually exact, but coalesced so a PUSHB does not perform
+        // one full queue scan per inserted job.
+        this.queueCountsScheduler?.schedule(event.queue);
     }
     // ── Dashboard / system event broadcasting ──────────────────
     /** Emit a typed event (dashboard events: worker, queue control, DLQ, etc.) */

package/dist/infrastructure/server/wsHandler.d.ts

@@ -28,7 +28,7 @@ export declare class WsHandler {
     private statsInterval;
     private healthInterval;
     private storageInterval;
-    private queueManager;
+    private queueCountsScheduler;
     droppedMessages: number;
     get size(): number;
     /** Check if a new connection can be accepted */

package/dist/infrastructure/server/wsHandler.js

@@ -14,6 +14,7 @@
 import { handleCommand } from './handler';
 import { parseCommand, serializeResponse, errorResponse } from './protocol';
 import { throughputTracker } from '../../application/throughputTracker';
+import { QueueCountsScheduler } from './queueCountsScheduler';
 const textDecoder = new TextDecoder();
 /** Old eventType → new event name */
 const EVENT_MAP = {
@@ -170,7 +171,7 @@ export class WsHandler {
     statsInterval = null;
     healthInterval = null;
     storageInterval = null;
-    queueManager = null;
+    queueCountsScheduler = null;
     droppedMessages = 0;
     get size() {
         return this.clients.size;
@@ -196,7 +197,17 @@ export class WsHandler {
     }
     /** Start periodic broadcasts */
     startBroadcasts(qm) {
-        this.queueManager = qm;
+        this.queueCountsScheduler ??= new QueueCountsScheduler(qm, (queue, counts) => {
+            this.emit('queue:counts', {
+                queue,
+                waiting: counts.waiting,
+                prioritized: counts.prioritized,
+                active: counts.active,
+                completed: counts.completed,
+                failed: counts.failed,
+                delayed: counts.delayed,
+            });
+        });
         this.statsInterval ??= setInterval(() => {
             if (this.clients.size > 0)
                 this.broadcastStats(qm);
@@ -212,6 +223,8 @@ export class WsHandler {
     }
     /** Stop periodic broadcasts */
     stopBroadcasts() {
+        this.queueCountsScheduler?.stop();
+        this.queueCountsScheduler = null;
         if (this.statsInterval) {
             clearInterval(this.statsInterval);
             this.statsInterval = null;
@@ -338,19 +351,9 @@ export class WsHandler {
         }
         for (const id of dead)
             this.clients.delete(id);
-        // Emit queue:counts on every job state change
-        if (this.queueManager) {
-            const counts = this.queueManager.getQueueJobCounts(event.queue);
-            this.emit('queue:counts', {
-                queue: event.queue,
-                waiting: counts.waiting,
-                prioritized: counts.prioritized,
-                active: counts.active,
-                completed: counts.completed,
-                failed: counts.failed,
-                delayed: counts.delayed,
-            });
-        }
+        // Counts are eventually exact, but coalesced so a PUSHB does not perform
+        // one full queue scan per inserted job.
+        this.queueCountsScheduler?.schedule(event.queue);
     }
     // ── Connection lifecycle ─────────────────────────────────
     onOpen(ws) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "bunqueue",
-  "version": "2.8.31",
-  "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external dependencies.",
+  "version": "2.8.33",
+  "description": "High-performance job queue for Bun & AI agents. SQLite persistence, cron scheduling, priorities, retries, DLQ, webhooks, native MCP server. Zero external infrastructure.",
   "type": "module",
   "main": "dist/main.js",
   "types": "dist/main.d.ts",
@@ -146,4 +146,4 @@
   "engines": {
     "bun": ">=1.3.9"
   }
-}
+}