bunqueue 2.8.32 → 2.8.33

package/README.md

@@ -14,7 +14,7 @@
 
 <p align="center">
   High-performance job queue for Bun. Built for AI agents and automation.<br/>
-  Zero external dependencies. MCP-native. TypeScript-first.
+  Zero external infrastructure. MCP-native. TypeScript-first.
 </p>
 
 <p align="center">
@@ -471,7 +471,8 @@ await app.close(true); // force shutdown
 
 ```typescript
 const counts = await queue.getJobCountsAsync();
-// { waiting, prioritized, active, completed, failed, delayed, paused }
+// { waiting, prioritized, active, completed, failed, delayed,
+//   'waiting-children', paused }
 
 // Failed jobs (those that exhausted their attempts) are enumerable by state —
 // the failed list reflects the same jobs that `failed` counts.
@@ -661,7 +662,7 @@ bunx bunqueue-dashboard
 
 - **MCP server included** — 73 tools, 5 resources, 3 prompts. AI agents get full control out of the box
 - **BullMQ-compatible API** — Same `Queue`, `Worker`, `QueueEvents`
-- **Zero dependencies** — No Redis, no MongoDB
+- **Zero external infrastructure** — No Redis, no MongoDB
 - **Tiny footprint** — 5.5 MB installed, 7 packages (just 2 runtime deps: `croner` + `msgpackr`)
 - **SQLite persistence** — Survives restarts, WAL mode for concurrent access
 - **Up to 630K ops/sec** — [Verified benchmarks](https://bunqueue.dev/guide/benchmarks/)

package/dist/application/backgroundTasks.js

@@ -201,9 +201,11 @@ export function recover(ctx) {
     const now = Date.now();
     // === PHASE 1: Recover active jobs (were processing when server stopped) ===
     // These jobs are considered "stalled" and need to be retried or moved to DLQ
-    let activeOffset = 0;
     while (true) {
-        const activeJobs = ctx.storage.loadActiveJobs(RECOVERY_BATCH_SIZE, activeOffset);
+        // Every successfully handled row leaves state='active' (retry -> waiting, or
+        // delete -> DLQ/discard). Always read the first page: advancing OFFSET over
+        // this shrinking result set would skip up to half of the active rows.
+        const activeJobs = ctx.storage.loadActiveJobs(RECOVERY_BATCH_SIZE, 0);
         if (activeJobs.length === 0)
             break;
         for (const job of activeJobs) {
@@ -248,22 +250,20 @@ export function recover(ctx) {
                 ctx.storage.deleteJob(job.id);
             }
             else {
-                // Retry: put back in queue with backoff (uses backoffConfig if present)
+                // Persist the retry here, but let Phase 2 be the single authoritative
+                // enqueue path. Enqueuing in both phases replaces the priority-queue entry
+                // by ID but increments queued/delayed counters twice.
                 job.runAt = now + calculateBackoff(job);
-                shard.getQueue(job.queue).push(job);
-                const isDelayed = job.runAt > now;
-                shard.incrementQueued(job.id, isDelayed, job.createdAt, job.queue, job.runAt);
-                ctx.jobIndex.set(job.id, { type: 'queue', shardIdx: idx, queueName: job.queue });
                 ctx.storage.updateForRetry(job);
             }
             ctx.registerQueueName(job.queue);
         }
-        activeOffset += activeJobs.length;
         if (activeJobs.length < RECOVERY_BATCH_SIZE)
             break;
     }
     // === PHASE 2: Load pending jobs ===
     let offset = 0;
+    const corruptPendingJobs = [];
     // Load pending jobs in batches to avoid memory spikes
     while (true) {
         const jobs = ctx.storage.loadPendingJobs(RECOVERY_BATCH_SIZE, offset);
@@ -276,7 +276,10 @@ export function recover(ctx) {
             // Route the job to the DLQ rather than enqueuing it as ready (out-of-order
             // execution) or parking it in waitingDeps forever (unbounded leak).
             if (isCorruptDependsOn(job)) {
-                quarantineCorruptDependsOn(ctx, job);
+                // Keep the SQLite pending result set stable until OFFSET pagination has
+                // finished. Deleting this row now shifts a healthy row across the next
+                // page boundary and leaves it absent from the in-memory queue.
+                corruptPendingJobs.push(job);
                 continue;
             }
             // Check if job has unmet dependencies
@@ -313,6 +316,11 @@ export function recover(ctx) {
         if (jobs.length < RECOVERY_BATCH_SIZE)
             break;
     }
+    // Quarantine only after the paginated scan so deletions cannot move page
+    // boundaries. loadDlq() below restores these entries into memory exactly once.
+    for (const job of corruptPendingJobs) {
+        quarantineCorruptDependsOn(ctx, job);
+    }
     // Load DLQ entries
     const dlqEntries = ctx.storage.loadDlq();
     for (const [queue, entries] of dlqEntries) {

package/dist/application/dependencyProcessor.js

@@ -76,7 +76,12 @@ function promoteJobsToQueue(jobsToPromote, shard, ctx, shardIdx) {
         }
     }
     if (jobsToPromote.length > 0) {
-        shard.notify();
+        const promotedByQueue = new Map();
+        for (const job of jobsToPromote) {
+            promotedByQueue.set(job.queue, (promotedByQueue.get(job.queue) ?? 0) + 1);
+        }
+        for (const [queue, count] of promotedByQueue)
+            shard.notifyBatch(queue, count);
         for (const job of jobsToPromote) {
             ctx.dashboardEmit?.('job:dependencies-resolved', { jobId: String(job.id), queue: job.queue });
         }

package/dist/application/dlqManager.js

@@ -274,6 +274,6 @@ function requeueCompletedJob(job, ctx) {
     ctx.completedJobs.delete(job.id);
     ctx.jobResults.delete(job.id);
     ctx.storage?.updateForRetry(job);
-    shard.notify();
+    shard.notify(job.queue);
     return 1;
 }

package/dist/application/lockManager.js

@@ -144,7 +144,7 @@ function requeueExpiredJob(opts) {
     const isDelayed = job.runAt > now;
     shard.incrementQueued(jobId, isDelayed, job.createdAt, job.queue, job.runAt);
     ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
-    shard.notify();
+    shard.notify(job.queue);
     ctx.eventsManager.broadcast({
         eventType: "stalled" /* EventType.Stalled */,
         jobId,

package/dist/application/operations/ack.js

@@ -26,7 +26,11 @@ export async function ackJob(jobId, result, ctx) {
     }
     const idx = shardIndex(job.queue);
     await withWriteLock(ctx.shardLocks[idx], () => {
-        ctx.shards[idx].releaseJobResources(job.queue, job.uniqueKey, job.groupId);
+        const shard = ctx.shards[idx];
+        shard.releaseJobResources(job.queue, job.uniqueKey, job.groupId);
+        // Releasing either queue concurrency or an active FIFO group can make a
+        // parked job eligible. Wake only waiters for this queue.
+        shard.notify(job.queue);
     });
     // Release customId so it can be reused
     if (job.customId && ctx.customIdMap) {
@@ -179,6 +183,9 @@ export async function failJob(jobId, error, ctx, unrecoverable = false, stack) {
         else {
             moveFailedJobToDlq(job, jobId, error, shard, ctx);
         }
+        // Terminal failure and retry both release queue concurrency (and possibly
+        // an active FIFO group), so another job may now be eligible.
+        shard.notify(job.queue);
     });
     ctx.broadcast({
         eventType: 'failed',
@@ -234,6 +241,9 @@ export async function ackJobBatch(jobIds, ctx) {
     // Step 3-4: Group by queue shard and release
     const byQueueShard = groupByQueueShard(extractedJobs);
     await releaseResources(byQueueShard, batchCtx);
+    for (const [idx, jobs] of byQueueShard) {
+        notifyReleasedQueues(ctx.shards[idx], jobs);
+    }
     // Step 5: Finalize
     finalizeBatchAck(extractedJobs, ctx, false);
 }
@@ -260,6 +270,18 @@ export async function ackJobBatchWithResults(items, ctx) {
     // Step 3-4: Group by queue shard and release
     const byQueueShard = groupByQueueShard(extractedJobs);
     await releaseResources(byQueueShard, batchCtx);
+    for (const [idx, jobs] of byQueueShard) {
+        notifyReleasedQueues(ctx.shards[idx], jobs);
+    }
     // Step 5: Finalize with results
     finalizeBatchAck(extractedJobs, ctx, true);
 }
+/** Wake queue-scoped waiters for concurrency/group slots released by a batch. */
+function notifyReleasedQueues(shard, jobs) {
+    const releasedByQueue = new Map();
+    for (const job of jobs) {
+        releasedByQueue.set(job.queue, (releasedByQueue.get(job.queue) ?? 0) + 1);
+    }
+    for (const [queue, count] of releasedByQueue)
+        shard.notifyBatch(queue, count);
+}

package/dist/application/operations/jobManagement.js

@@ -212,7 +212,7 @@ export async function moveJobToDelayed(jobId, delay, ctx) {
         shard.incrementQueued(jobId, isDelayed, job.createdAt, job.queue, job.runAt);
         ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
         // The freed slot may unblock waiting jobs for long-pollers.
-        shard.notify();
+        shard.notify(job.queue);
     });
     // Persist the move so the delay survives a restart: the on-disk row was
     // `state='active'` with the old run_at, which recovery would otherwise treat as a
@@ -270,7 +270,7 @@ export async function discardJob(jobId, ctx) {
                 // lockManager.ts), so the DLQ entry never keeps it.
                 shard.releaseJobResources(validJob.queue, validJob.uniqueKey, validJob.groupId);
                 // The freed slot may unblock waiting jobs for long-pollers.
-                shard.notify();
+                shard.notify(validJob.queue);
             }
             else if (validJob.uniqueKey) {
                 // Queue branch: the waiting job never acquired a slot or group at

package/dist/application/operations/jobStateTransitions.js

@@ -33,7 +33,7 @@ export async function moveActiveToWait(jobId, ctx) {
         shard.getQueue(job.queue).push(job);
         shard.incrementQueued(jobId, false, job.createdAt, job.queue, job.runAt);
         ctx.jobIndex.set(jobId, { type: 'queue', shardIdx: idx, queueName: job.queue });
-        shard.notify();
+        shard.notify(job.queue);
     });
     ctx.eventsManager.broadcast({
         eventType: 'waiting',

package/dist/application/operations/pull.js

@@ -8,65 +8,119 @@ import { shardIndex, processingShardIndex } from '../../shared/hash';
 import { latencyTracker } from '../latencyTracker';
 import { throughputTracker } from '../throughputTracker';
 /**
- * Try to dequeue next ready job from queue
- * Handles: expired skip, ready check, group blocking, timestamps
+ * Dequeue the highest-ranked eligible job without letting a delayed or
+ * group-blocked heap root stall unrelated work.
+ *
+ * The priority heap cannot encode time-varying readiness or active-group
+ * membership in its comparator. Temporarily park ineligible roots, select the
+ * first eligible entry (therefore the best eligible entry in heap order), and
+ * restore every parked job before leaving the shard critical section. Parked
+ * jobs remain logically queued throughout: their shard counters and jobIndex
+ * entries are deliberately untouched.
+ *
+ * Complexity is O((k + 1) log n) time and O(k) scratch space, where k is the
+ * number of higher-ranked ineligible jobs skipped. A separate delayed heap and
+ * per-group eligible-head heap can reduce this to O(log n), but this scan keeps
+ * the existing queue representation and state transitions intact.
  */
 function tryDequeueNextJob(shard, queue, now, ctx) {
     const q = shard.getQueue(queue);
-    const job = q.peek();
-    if (!job)
-        return { status: 'stop' };
-    // Skip expired jobs
-    if (isExpired(job, now)) {
-        q.pop();
-        shard.decrementQueued(job.id);
-        ctx.jobIndex.delete(job.id);
-        ctx.dashboardEmit?.('job:expired', {
-            queue,
-            jobId: String(job.id),
-            ttl: job.ttl,
-            age: now - job.createdAt,
-        });
-        return { status: 'skip' };
-    }
-    // Not ready yet (delayed)
-    if (!isReady(job, now))
-        return { status: 'stop' };
-    // FIFO group blocked
-    if (job.groupId && shard.isGroupActive(queue, job.groupId)) {
-        return { status: 'stop' };
-    }
-    // Dequeue and update
-    q.pop();
-    shard.decrementQueued(job.id);
-    if (job.groupId) {
-        shard.activateGroup(queue, job.groupId);
+    const parked = [];
+    let nextRunAt = null;
+    try {
+        while (true) {
+            const job = q.peek();
+            if (!job)
+                return { status: 'stop', nextRunAt };
+            // Expired entries are not parked: they are genuinely removed from the
+            // logical queue and therefore update counters/index exactly once.
+            if (isExpired(job, now)) {
+                q.pop();
+                shard.decrementQueued(job.id);
+                ctx.jobIndex.delete(job.id);
+                ctx.dashboardEmit?.('job:expired', {
+                    queue,
+                    jobId: String(job.id),
+                    ttl: job.ttl,
+                    age: now - job.createdAt,
+                });
+                continue;
+            }
+            if (!isReady(job, now)) {
+                const delayed = q.pop();
+                if (delayed)
+                    parked.push(delayed);
+                nextRunAt = nextRunAt === null ? job.runAt : Math.min(nextRunAt, job.runAt);
+                continue;
+            }
+            if (job.groupId && shard.isGroupActive(queue, job.groupId)) {
+                const blocked = q.pop();
+                if (blocked)
+                    parked.push(blocked);
+                continue;
+            }
+            // Check capacity only after proving that an eligible job exists. Check
+            // concurrency first because that slot can be returned if rate limiting
+            // rejects; rate-limit tokens have no rollback operation.
+            if (!shard.tryAcquireConcurrency(queue)) {
+                ctx.dashboardEmit?.('concurrency:rejected', { queue });
+                return { status: 'stop', nextRunAt };
+            }
+            if (!shard.tryAcquireRateLimit(queue)) {
+                shard.releaseConcurrency(queue);
+                ctx.dashboardEmit?.('ratelimit:rejected', { queue });
+                return { status: 'stop', nextRunAt };
+            }
+            // Dequeue and update. q.peek() and q.pop() are synchronous under the
+            // shard write lock, so pop returns the same eligible entry selected above.
+            const dequeued = q.pop();
+            if (!dequeued) {
+                shard.releaseConcurrency(queue);
+                return { status: 'stop', nextRunAt };
+            }
+            shard.decrementQueued(dequeued.id);
+            if (dequeued.groupId) {
+                shard.activateGroup(queue, dequeued.groupId);
+            }
+            dequeued.startedAt = now;
+            dequeued.lastHeartbeat = now;
+            if (dequeued.timeline.length < MAX_TIMELINE_ENTRIES) {
+                dequeued.timeline.push({ state: 'active', timestamp: now });
+            }
+            // Make the queue -> processing transition atomic for observers. From the
+            // pop above, the job is no longer findable in the shard queue, so a
+            // jobIndex entry still saying 'queue' would make getJob/getJobState return
+            // a false null/'unknown' for an existing job (JOB -> null -> JOB(active)
+            // flicker), and cleanOrphanedJobIndex would even drop its index entry.
+            // Insert into processingShards and flip the index HERE, in the same
+            // synchronous critical section as the pop (the caller holds the shard
+            // write lock; JS is single-threaded, so no other task can interleave).
+            // Writing processingShards without its RWLock is safe: until this
+            // statement the index said 'queue', so no id-targeted critical section
+            // (ack/fail/discard operate only on ids they find as 'processing') can be
+            // mid-operation on this id; a sync Map.set cannot corrupt a paused
+            // critical section; and lock-free sync access to processingShards is
+            // established practice (stallDetection phases 1/2, collectActiveJobs,
+            // getJobProgress). Acquiring the async RWLock here would instead hold the
+            // hot shard write lock across an await.
+            const procIdx = processingShardIndex(dequeued.id);
+            ctx.processingShards[procIdx].set(dequeued.id, dequeued);
+            ctx.jobIndex.set(dequeued.id, { type: 'processing', shardIdx: procIdx });
+            return { status: 'job', job: dequeued };
+        }
     }
-    job.startedAt = now;
-    job.lastHeartbeat = now;
-    if (job.timeline.length < MAX_TIMELINE_ENTRIES) {
-        job.timeline.push({ state: 'active', timestamp: now });
+    finally {
+        // Restore only the priority-queue membership. The logical queue counters,
+        // temporal index and global jobIndex never changed for parked entries.
+        for (const parkedJob of parked)
+            q.push(parkedJob);
     }
-    // Make the queue -> processing transition atomic for observers. From the
-    // pop above, the job is no longer findable in the shard queue, so a
-    // jobIndex entry still saying 'queue' would make getJob/getJobState return
-    // a false null/'unknown' for an existing job (JOB -> null -> JOB(active)
-    // flicker), and cleanOrphanedJobIndex would even drop its index entry.
-    // Insert into processingShards and flip the index HERE, in the same
-    // synchronous critical section as the pop (the caller holds the shard
-    // write lock; JS is single-threaded, so no other task can interleave).
-    // Writing processingShards without its RWLock is safe: until this
-    // statement the index said 'queue', so no id-targeted critical section
-    // (ack/fail/discard operate only on ids they find as 'processing') can be
-    // mid-operation on this id; a sync Map.set cannot corrupt a paused
-    // critical section; and lock-free sync access to processingShards is
-    // established practice (stallDetection phases 1/2, collectActiveJobs,
-    // getJobProgress). Acquiring the async RWLock here would instead hold the
-    // hot shard write lock across an await.
-    const procIdx = processingShardIndex(job.id);
-    ctx.processingShards[procIdx].set(job.id, job);
-    ctx.jobIndex.set(job.id, { type: 'processing', shardIdx: procIdx });
-    return { status: 'job', job };
+}
+/** Wait until either a notification arrives, the next delay matures, or the pull deadline. */
+async function waitForNextCandidate(shard, queue, deadline, now, nextRunAt) {
+    const remaining = deadline - now;
+    const untilNextRun = nextRunAt === null ? remaining : Math.max(1, nextRunAt - now);
+    await shard.waitForJob(queue, Math.min(remaining, untilNextRun));
 }
 /**
  * Finish the handoff of a dequeued job: persist active state and broadcast.
@@ -141,7 +195,7 @@ async function requeueJob(job, queue, idx, ctx) {
         shard.getQueue(queue).push(job);
         shard.incrementQueued(job.id, false, job.createdAt, queue, job.runAt);
         ctx.jobIndex.set(job.id, { type: 'queue', shardIdx: idx, queueName: queue });
-        shard.notify();
+        shard.notify(queue);
         requeued = true;
     });
     if (!requeued)
@@ -163,7 +217,8 @@ export async function pullJob(queue, timeoutMs, ctx) {
     const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : 0;
     const idx = shardIndex(queue);
     while (true) {
-        const job = await tryPullFromShard(queue, idx, ctx);
+        const attempt = await tryPullFromShard(queue, idx, ctx);
+        const job = attempt.job;
         if (job) {
             let delivered = false;
             try {
@@ -186,9 +241,7 @@ export async function pullJob(queue, timeoutMs, ctx) {
         if (deadline === 0 || now >= deadline) {
             return null;
         }
-        // Wait for notification or timeout
-        const remaining = deadline - now;
-        await ctx.shards[idx].waitForJob(remaining);
+        await waitForNextCandidate(ctx.shards[idx], queue, deadline, now, attempt.nextRunAt);
     }
 }
 /**
@@ -199,27 +252,13 @@ async function tryPullFromShard(queue, idx, ctx) {
         const shard = ctx.shards[idx];
         const state = shard.getState(queue);
         if (state.paused) {
-            return null;
-        }
-        if (!shard.tryAcquireRateLimit(queue)) {
-            ctx.dashboardEmit?.('ratelimit:rejected', { queue });
-            return null;
-        }
-        if (!shard.tryAcquireConcurrency(queue)) {
-            ctx.dashboardEmit?.('concurrency:rejected', { queue });
-            return null;
+            return { job: null, nextRunAt: null };
         }
         const now = Date.now();
-        while (true) {
-            const result = tryDequeueNextJob(shard, queue, now, ctx);
-            if (result.status === 'job')
-                return result.job;
-            if (result.status === 'stop') {
-                shard.releaseConcurrency(queue);
-                return null;
-            }
-            // status === 'skip': continue loop
-        }
+        const result = tryDequeueNextJob(shard, queue, now, ctx);
+        return result.status === 'job'
+            ? { job: result.job, nextRunAt: null }
+            : { job: null, nextRunAt: result.nextRunAt };
     });
 }
 /**
@@ -230,7 +269,8 @@ export async function pullJobBatch(queue, count, timeoutMs, ctx) {
     const deadline = timeoutMs > 0 ? Date.now() + timeoutMs : 0;
     const idx = shardIndex(queue);
     while (true) {
-        const jobs = await tryPullBatchFromShard(queue, idx, count, ctx);
+        const attempt = await tryPullBatchFromShard(queue, idx, count, ctx);
+        const jobs = attempt.jobs;
         if (jobs.length > 0) {
             let delivered;
             try {
@@ -260,9 +300,7 @@ export async function pullJobBatch(queue, count, timeoutMs, ctx) {
         if (deadline === 0 || now >= deadline) {
             return [];
         }
-        // Wait for notification or timeout
-        const remaining = deadline - now;
-        await ctx.shards[idx].waitForJob(remaining);
+        await waitForNextCandidate(ctx.shards[idx], queue, deadline, now, attempt.nextRunAt);
     }
 }
 /**
@@ -274,28 +312,19 @@ async function tryPullBatchFromShard(queue, idx, count, ctx) {
         const state = shard.getState(queue);
         const jobs = [];
         if (state.paused)
-            return jobs;
+            return { jobs, nextRunAt: null };
         const now = Date.now();
+        let nextRunAt = null;
         while (jobs.length < count) {
-            // Check limits per job
-            if (!shard.tryAcquireRateLimit(queue)) {
-                break;
-            }
-            if (!shard.tryAcquireConcurrency(queue)) {
-                break;
-            }
             const result = tryDequeueNextJob(shard, queue, now, ctx);
             if (result.status === 'job') {
                 jobs.push(result.job);
             }
             else {
-                // 'stop' or 'skip': release the concurrency slot since no job was taken
-                shard.releaseConcurrency(queue);
-                if (result.status === 'stop')
-                    break;
-                // 'skip': continue loop to try next job
+                nextRunAt = result.nextRunAt;
+                break;
             }
         }
-        return jobs;
+        return { jobs, nextRunAt };
     });
 }

package/dist/application/operations/push.js

@@ -212,7 +212,7 @@ export async function pushJob(queue, input, ctx) {
         }
         // Insert to shard
         insertJobToShard(job, queue, shard, idx, ctx);
-        shard.notify();
+        shard.notify(queue);
         result = { job, persisted: true };
     });
     if (!result) {
@@ -274,7 +274,7 @@ export async function pushJobBatch(queue, inputs, ctx) {
             resultIds.push(job.id);
         }
         if (jobsToInsert.length > 0) {
-            shard.notifyBatch(jobsToInsert.length);
+            shard.notifyBatch(queue, jobsToInsert.length);
         }
     });
     if (jobsToInsert.length > 0) {