bunqueue 2.8.0 → 2.8.2

package/dist/application/operations/ack.js

@@ -78,6 +78,37 @@ export async function ackJob(jobId, result, ctx) {
     }
     latencyTracker.ack.observe((Bun.nanoseconds() - startNs) / 1e6);
 }
+/** Move a permanently-failed job to DLQ (terminal path in failJob). */
+function moveFailedJobToDlq(job, jobId, error, shard, ctx) {
+    const entry = shard.addToDlq(job, "max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */, error ?? null);
+    ctx.jobIndex.set(jobId, { type: 'dlq', queueName: job.queue });
+    ctx.storage?.saveDlqEntry(entry);
+    ctx.storage?.deleteJob(jobId);
+    ctx.totalFailed.value++;
+    if (ctx.perQueueMetrics) {
+        const pq = ctx.perQueueMetrics.get(job.queue);
+        if (pq)
+            pq.totalFailed++;
+        else
+            ctx.perQueueMetrics.set(job.queue, { totalCompleted: 0n, totalFailed: 1n });
+    }
+    throughputTracker.failRate.increment();
+    if (job.customId && ctx.customIdMap)
+        ctx.customIdMap.delete(job.customId);
+    ctx.emitDashboardEvent?.('dlq:added', {
+        queue: job.queue,
+        jobId: String(jobId),
+        reason: "max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */,
+    });
+    if (job.parentId) {
+        ctx.emitDashboardEvent?.('flow:failed', {
+            parentJobId: String(job.parentId),
+            failedChildId: String(jobId),
+            queue: job.queue,
+            error: error ?? 'Max attempts exceeded',
+        });
+    }
+}
 /**
  * Mark job as failed
  */
@@ -135,39 +166,7 @@ export async function failJob(jobId, error, ctx) {
             }
         }
         else {
-            const entry = shard.addToDlq(job, "max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */, error ?? null);
-            ctx.jobIndex.set(jobId, { type: 'dlq', queueName: job.queue });
-            ctx.storage?.saveDlqEntry(entry);
-            ctx.totalFailed.value++;
-            if (ctx.perQueueMetrics) {
-                const pq = ctx.perQueueMetrics.get(job.queue);
-                if (pq) {
-                    pq.totalFailed++;
-                }
-                else {
-                    ctx.perQueueMetrics.set(job.queue, { totalCompleted: 0n, totalFailed: 1n });
-                }
-            }
-            throughputTracker.failRate.increment();
-            // Release customId when job goes to DLQ
-            if (job.customId && ctx.customIdMap) {
-                ctx.customIdMap.delete(job.customId);
-            }
-            // Emit dlq:added dashboard event
-            ctx.emitDashboardEvent?.('dlq:added', {
-                queue: job.queue,
-                jobId: String(jobId),
-                reason: "max_attempts_exceeded" /* FailureReason.MaxAttemptsExceeded */,
-            });
-            // Emit flow:failed if this job is part of a flow
-            if (job.parentId) {
-                ctx.emitDashboardEvent?.('flow:failed', {
-                    parentJobId: String(job.parentId),
-                    failedChildId: String(jobId),
-                    queue: job.queue,
-                    error: error ?? 'Max attempts exceeded',
-                });
-            }
+            moveFailedJobToDlq(job, jobId, error, shard, ctx);
         }
     });
     ctx.broadcast({
@@ -253,4 +252,3 @@ export async function ackJobBatchWithResults(items, ctx) {
     // Step 5: Finalize with results
     finalizeBatchAck(extractedJobs, ctx, true);
 }
-//# sourceMappingURL=ack.js.map

package/dist/application/operations/ackHelpers.d.ts

@@ -82,4 +82,3 @@ export interface FinalizeContext {
  * Finalize batch ack - update indexes, metrics, broadcast, notify
  */
 export declare function finalizeBatchAck<T>(extractedJobs: Array<ExtractedJob<T>>, ctx: FinalizeContext, includeResults: boolean): void;
-//# sourceMappingURL=ackHelpers.d.ts.map

package/dist/application/operations/ackHelpers.js

@@ -204,4 +204,3 @@ export function finalizeBatchAck(extractedJobs, ctx, includeResults) {
         }
     }
 }
-//# sourceMappingURL=ackHelpers.js.map

package/dist/application/operations/index.d.ts

@@ -7,4 +7,3 @@ export * from './ack';
 export * from './queueControl';
 export * from './jobManagement';
 export * from './queryOperations';
-//# sourceMappingURL=index.d.ts.map

package/dist/application/operations/index.js

@@ -7,4 +7,3 @@ export * from './ack';
 export * from './queueControl';
 export * from './jobManagement';
 export * from './queryOperations';
-//# sourceMappingURL=index.js.map

package/dist/application/operations/jobManagement.d.ts

@@ -28,11 +28,10 @@ export declare function updateJobProgress(jobId: JobId, progress: number, ctx: J
 /** Update job data */
 export declare function updateJobData(jobId: JobId, data: unknown, ctx: JobManagementContext): Promise<boolean>;
 /** Change job priority */
-export declare function changeJobPriority(jobId: JobId, priority: number, ctx: JobManagementContext): Promise<boolean>;
+export declare function changeJobPriority(jobId: JobId, priority: number, ctx: JobManagementContext, lifo?: boolean): Promise<boolean>;
 /** Promote delayed job to waiting */
 export declare function promoteJob(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;
 /** Move active job back to delayed */
 export declare function moveJobToDelayed(jobId: JobId, delay: number, ctx: JobManagementContext): Promise<boolean>;
 /** Discard job to DLQ */
 export declare function discardJob(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;
-//# sourceMappingURL=jobManagement.d.ts.map

package/dist/application/operations/jobManagement.js

@@ -128,13 +128,13 @@ async function updateRepeatSuccessor(originalId, data, ctx) {
     });
 }
 /** Change job priority */
-export async function changeJobPriority(jobId, priority, ctx) {
+export async function changeJobPriority(jobId, priority, ctx, lifo) {
     const location = ctx.jobIndex.get(jobId);
     if (location?.type !== 'queue')
         return false;
     return withWriteLock(ctx.shardLocks[location.shardIdx], () => {
         const q = ctx.shards[location.shardIdx].getQueue(location.queueName);
-        return q.updatePriority(jobId, priority);
+        return q.updatePriority(jobId, priority, lifo);
     });
 }
 /** Promote delayed job to waiting */
@@ -227,8 +227,8 @@ export async function discardJob(jobId, ctx) {
             return dlqEntry;
         });
         ctx.storage?.saveDlqEntry(entry);
+        ctx.storage?.deleteJob(jobId);
         return true;
     }
     return false;
 }
-//# sourceMappingURL=jobManagement.js.map

package/dist/application/operations/jobStateTransitions.d.ts

@@ -13,4 +13,3 @@ export declare function moveActiveToWait(jobId: JobId, ctx: JobManagementContext
 export declare function changeWaitingDelay(jobId: JobId, delay: number, ctx: JobManagementContext): Promise<boolean>;
 /** Move active job to waiting-children state */
 export declare function moveToWaitingChildren(jobId: JobId, ctx: JobManagementContext): Promise<boolean>;
-//# sourceMappingURL=jobStateTransitions.d.ts.map

package/dist/application/operations/jobStateTransitions.js

@@ -85,4 +85,3 @@ export async function moveToWaitingChildren(jobId, ctx) {
     });
     return true;
 }
-//# sourceMappingURL=jobStateTransitions.js.map

package/dist/application/operations/pull.d.ts

@@ -34,4 +34,3 @@ export declare function pullJob(queue: string, timeoutMs: number, ctx: PullConte
  * Pull multiple jobs from queue
  */
 export declare function pullJobBatch(queue: string, count: number, timeoutMs: number, ctx: PullContext): Promise<Job[]>;
-//# sourceMappingURL=pull.d.ts.map

package/dist/application/operations/pull.js

@@ -277,4 +277,3 @@ async function tryPullBatchFromShard(queue, idx, count, ctx) {
         return jobs;
     });
 }
-//# sourceMappingURL=pull.js.map

package/dist/application/operations/push.d.ts

@@ -37,4 +37,3 @@ export declare function pushJob(queue: string, input: JobInput, ctx: PushContext
  * NOTE: customId check happens INSIDE lock (safer for concurrent batch inserts)
  */
 export declare function pushJobBatch(queue: string, inputs: JobInput[], ctx: PushContext): Promise<JobId[]>;
-//# sourceMappingURL=push.d.ts.map

package/dist/application/operations/push.js

@@ -240,4 +240,3 @@ export async function pushJobBatch(queue, inputs, ctx) {
     latencyTracker.push.observe((Bun.nanoseconds() - startNs) / 1e6);
     return resultIds;
 }
-//# sourceMappingURL=push.js.map

package/dist/application/operations/queryOperations.d.ts

@@ -46,4 +46,3 @@ export declare function getJobs(queue: string, shardIdx: number, options: {
     end?: number;
     asc?: boolean;
 }, ctx: GetJobsContext): Job[];
-//# sourceMappingURL=queryOperations.d.ts.map

package/dist/application/operations/queryOperations.js

@@ -7,8 +7,19 @@ import { shardIndex } from '../../shared/hash';
 /** Get job by ID */
 export async function getJob(jobId, ctx) {
     const location = ctx.jobIndex.get(jobId);
-    if (!location)
-        return null;
+    if (!location) {
+        // Fallback: jobIndex may not be populated after restart for completed/DLQ jobs.
+        // Consult SQLite directly so getJob survives recovery.
+        if (ctx.storage) {
+            const job = ctx.storage.getJob(jobId);
+            if (job)
+                return job;
+            const dlqEntry = ctx.storage.getDlqEntry(jobId);
+            if (dlqEntry)
+                return dlqEntry.job;
+        }
+        return ctx.completedJobsData.get(jobId) ?? null;
+    }
     switch (location.type) {
         case 'queue': {
             return await withReadLock(ctx.shardLocks[location.shardIdx], () => {
@@ -25,6 +36,9 @@ export async function getJob(jobId, ctx) {
             return ctx.storage?.getJob(jobId) ?? ctx.completedJobsData.get(jobId) ?? null;
         case 'dlq': {
             if (ctx.storage) {
+                const dlqEntry = ctx.storage.getDlqEntry(jobId);
+                if (dlqEntry)
+                    return dlqEntry.job;
                 const job = ctx.storage.getJob(jobId);
                 if (job)
                     return job;
@@ -79,6 +93,26 @@ export function getJobProgress(jobId, ctx) {
         return null;
     return { progress: job.progress, message: job.progressMessage };
 }
+/** Resolve job state from SQLite when jobIndex has no entry (post-restart recovery). */
+function resolveStateFromStorage(jobId, storage) {
+    if (!storage)
+        return 'unknown';
+    if (storage.hasDlqEntry(jobId))
+        return "failed" /* JobState.Failed */;
+    const persisted = storage.getJobStateRaw(jobId);
+    if (persisted === 'completed')
+        return "completed" /* JobState.Completed */;
+    if (persisted === 'active')
+        return "active" /* JobState.Active */;
+    if (persisted !== 'waiting' && persisted !== 'delayed')
+        return 'unknown';
+    const row = storage.getJob(jobId);
+    if (!row)
+        return 'unknown';
+    if (row.runAt > Date.now())
+        return "delayed" /* JobState.Delayed */;
+    return row.priority > 0 ? "prioritized" /* JobState.Prioritized */ : "waiting" /* JobState.Waiting */;
+}
 /** Get job state by ID */
 export async function getJobState(jobId, ctx) {
     const location = ctx.jobIndex.get(jobId);
@@ -87,7 +121,7 @@ export async function getJobState(jobId, ctx) {
         return "completed" /* JobState.Completed */;
     }
     if (!location) {
-        return 'unknown';
+        return resolveStateFromStorage(jobId, ctx.storage);
     }
     switch (location.type) {
         case 'queue': {
@@ -323,4 +357,3 @@ export function getJobs(queue, shardIdx, options, ctx) {
     jobs.sort((a, b) => (asc ? a.createdAt - b.createdAt : b.createdAt - a.createdAt));
     return jobs.slice(start, end);
 }
-//# sourceMappingURL=queryOperations.js.map

package/dist/application/operations/queueControl.d.ts

@@ -2,8 +2,10 @@
  * Queue Control Operations
  * Pause, resume, drain, obliterate, clean, list queues
  */
-import type { JobId } from '../../domain/types/job';
+import type { Job, JobId } from '../../domain/types/job';
 import type { Shard } from '../../domain/queue/shard';
+import type { SqliteStorage } from '../../infrastructure/persistence/sqlite';
+import type { MapLike, SetLike } from '../../shared/lru';
 /** Context for queue control operations */
 export interface QueueControlContext {
     shards: Shard[];
@@ -12,6 +14,12 @@ export interface QueueControlContext {
         shardIdx?: number;
         queueName?: string;
     }>;
+    processingShards?: Map<JobId, Job>[];
+    completedJobs?: SetLike<JobId>;
+    completedJobsData?: MapLike<JobId, Job>;
+    jobResults?: MapLike<JobId, unknown>;
+    jobLogs?: MapLike<JobId, unknown>;
+    storage?: SqliteStorage | null;
 }
 /** Pause a queue */
 export declare function pauseQueue(queue: string, ctx: QueueControlContext): void;
@@ -26,10 +34,13 @@ export declare function obliterateQueue(queue: string, ctx: QueueControlContext)
 /** List all queue names */
 export declare function listAllQueues(ctx: QueueControlContext): string[];
 /**
- * Clean old jobs from queue
- * Uses temporal index for O(log n + k) instead of O(n) full scan
+ * Clean old jobs from queue.
+ * Supported states: waiting/wait, delayed, prioritized, paused, completed, failed.
+ * State='active' is intentionally unsupported: cleaning in-flight jobs races with
+ * the worker's ack path and would leak concurrency/uniqueKey/groupId slots. Use
+ * `fail(jobId)` or `cancelJob(jobId)` to terminate an active job safely.
+ * @returns Array of removed JobIds.
  */
-export declare function cleanQueue(queue: string, graceMs: number, ctx: QueueControlContext, state?: string, limit?: number): number;
+export declare function cleanQueue(queue: string, graceMs: number, ctx: QueueControlContext, state?: string, limit?: number): JobId[];
 /** Get count of jobs in queue */
 export declare function getQueueCount(queue: string, ctx: QueueControlContext): number;
-//# sourceMappingURL=queueControl.d.ts.map

package/dist/application/operations/queueControl.js

@@ -22,9 +22,13 @@ export function isQueuePaused(queue, ctx) {
 export function drainQueue(queue, ctx) {
     const idx = shardIndex(queue);
     const { count, jobIds } = ctx.shards[idx].drain(queue);
-    // Clean up jobIndex for all drained jobs
+    // Clean up jobIndex AND the SQLite row for every drained job so they cannot
+    // resurrect from a stale on-disk row (parity with clean/obliterate).
+    // safeDeleteJob also clears the pending write-buffer entry, so a buffered
+    // (not-yet-flushed) add cannot land on disk after the drain.
     for (const jobId of jobIds) {
         ctx.jobIndex.delete(jobId);
+        safeDeleteJob(ctx, jobId);
     }
     return count;
 }
@@ -43,33 +47,125 @@ export function listAllQueues(ctx) {
     }
     return Array.from(queues);
 }
+/** Normalize BullMQ-compatible state aliases */
+function normalizeCleanState(state) {
+    if (!state)
+        return undefined;
+    if (state === 'wait')
+        return 'waiting';
+    return state;
+}
+function safeDeleteJob(ctx, jobId) {
+    try {
+        ctx.storage?.deleteJob(jobId);
+    }
+    catch {
+        // SQLite write may fail (e.g. SQLITE_FULL). In-memory state already cleared;
+        // orphan row will be GC'd by crash-recovery on restart.
+    }
+}
+function safeDeleteDlqEntry(ctx, jobId) {
+    try {
+        ctx.storage?.deleteDlqEntry(jobId);
+    }
+    catch {
+        // Same rationale as safeDeleteJob.
+    }
+}
+function cleanWaitingLike(queue, graceMs, ctx, maxJobs) {
+    const idx = shardIndex(queue);
+    const shard = ctx.shards[idx];
+    const q = shard.getQueue(queue);
+    const oldJobs = shard.getOldJobs(queue, graceMs, maxJobs);
+    const removed = [];
+    for (const { jobId } of oldJobs) {
+        if (q.has(jobId)) {
+            q.remove(jobId);
+            shard.decrementQueued(jobId);
+            shard.removeFromTemporalIndex(jobId);
+            ctx.jobIndex.delete(jobId);
+            safeDeleteJob(ctx, jobId);
+            removed.push(jobId);
+        }
+    }
+    return removed;
+}
+function cleanCompleted(queue, graceMs, ctx, maxJobs) {
+    if (!ctx.completedJobs || !ctx.completedJobsData)
+        return [];
+    const threshold = Date.now() - graceMs;
+    const toRemove = [];
+    for (const [jid, loc] of ctx.jobIndex) {
+        if (loc.type !== 'completed' || loc.queueName !== queue)
+            continue;
+        const job = ctx.completedJobsData.get(jid) ?? ctx.storage?.getJob(jid) ?? null;
+        const ts = job?.completedAt ?? job?.createdAt ?? 0;
+        if (ts && ts > threshold)
+            continue;
+        toRemove.push(jid);
+        if (toRemove.length >= maxJobs)
+            break;
+    }
+    for (const jid of toRemove) {
+        ctx.completedJobs.delete(jid);
+        ctx.completedJobsData.delete(jid);
+        ctx.jobResults?.delete(jid);
+        ctx.jobLogs?.delete(jid);
+        ctx.jobIndex.delete(jid);
+        safeDeleteJob(ctx, jid);
+    }
+    return toRemove;
+}
+function cleanFailed(queue, graceMs, ctx, maxJobs) {
+    const idx = shardIndex(queue);
+    const shard = ctx.shards[idx];
+    const entries = shard.getDlqEntries(queue);
+    const threshold = Date.now() - graceMs;
+    const toRemove = [];
+    for (const entry of entries) {
+        const ts = entry.enteredAt ?? entry.job.createdAt;
+        if (ts > threshold)
+            continue;
+        toRemove.push(entry.job.id);
+        if (toRemove.length >= maxJobs)
+            break;
+    }
+    for (const jid of toRemove) {
+        shard.removeFromDlq(queue, jid);
+        ctx.jobIndex.delete(jid);
+        ctx.jobResults?.delete(jid);
+        ctx.jobLogs?.delete(jid);
+        safeDeleteDlqEntry(ctx, jid);
+        safeDeleteJob(ctx, jid);
+    }
+    return toRemove;
+}
 /**
- * Clean old jobs from queue
- * Uses temporal index for O(log n + k) instead of O(n) full scan
+ * Clean old jobs from queue.
+ * Supported states: waiting/wait, delayed, prioritized, paused, completed, failed.
+ * State='active' is intentionally unsupported: cleaning in-flight jobs races with
+ * the worker's ack path and would leak concurrency/uniqueKey/groupId slots. Use
+ * `fail(jobId)` or `cancelJob(jobId)` to terminate an active job safely.
+ * @returns Array of removed JobIds.
  */
 export function cleanQueue(queue, graceMs, ctx, state, limit) {
-    const idx = shardIndex(queue);
-    const shard = ctx.shards[idx];
     const maxJobs = limit ?? 1000;
-    let cleaned = 0;
-    if (!state || state === 'waiting' || state === 'delayed') {
-        const q = shard.getQueue(queue);
-        // Use temporal index for efficient lookup of old jobs
-        const oldJobs = shard.getOldJobs(queue, graceMs, maxJobs);
-        for (const { jobId } of oldJobs) {
-            // Verify job still exists in queue before removing
-            if (q.has(jobId)) {
-                q.remove(jobId);
-                // Update counters
-                shard.decrementQueued(jobId);
-                // Remove from temporal index
-                shard.removeFromTemporalIndex(jobId);
-                ctx.jobIndex.delete(jobId);
-                cleaned++;
-            }
-        }
+    const normalized = normalizeCleanState(state);
+    switch (normalized) {
+        case undefined:
+        case 'waiting':
+        case 'delayed':
+        case 'prioritized':
+        case 'paused':
+            return cleanWaitingLike(queue, graceMs, ctx, maxJobs);
+        case 'completed':
+            return cleanCompleted(queue, graceMs, ctx, maxJobs);
+        case 'failed':
+            return cleanFailed(queue, graceMs, ctx, maxJobs);
+        case 'active':
+        default:
+            return [];
     }
-    return cleaned;
 }
 /** Get count of jobs in queue */
 export function getQueueCount(queue, ctx) {
@@ -77,4 +173,3 @@ export function getQueueCount(queue, ctx) {
     const q = ctx.shards[idx].getQueue(queue);
     return q.size;
 }
-//# sourceMappingURL=queueControl.js.map

package/dist/application/queueManager.d.ts

@@ -110,6 +110,13 @@ export declare class QueueManager {
     registerClientJob(clientId: string, jobId: JobId): void;
     unregisterClientJob(clientId: string | undefined, jobId: JobId): void;
     releaseClientJobs(clientId: string): Promise<number>;
+    /**
+     * Force-release client tracking without acquiring queue locks. Last-resort
+     * fallback when releaseClientJobs has exhausted its retry budget — clears
+     * the clientJobs map entry to prevent leaks and resets job heartbeats so
+     * the stall detector recovers orphaned active jobs on its next tick.
+     */
+    forceReleaseClientJobs(clientId: string): number;
     getJob(jobId: JobId): Promise<Job | null>;
     getJobState(jobId: JobId): Promise<string>;
     getResult(jobId: JobId): unknown;
@@ -138,7 +145,7 @@ export declare class QueueManager {
     listQueues(): string[];
     private registerQueueName;
     private unregisterQueueName;
-    clean(queue: string, graceMs: number, state?: string, limit?: number): number;
+    clean(queue: string, graceMs: number, state?: string, limit?: number): JobId[];
     getCountsPerPriority(queue: string): Record<number, number>;
     getJobs(queue: string, options?: {
         state?: string | string[];
@@ -186,7 +193,7 @@ export declare class QueueManager {
     cancel(jobId: JobId): Promise<boolean>;
     updateProgress(jobId: JobId, progress: number, message?: string): Promise<boolean>;
     updateJobData(jobId: JobId, data: unknown): Promise<boolean>;
-    changePriority(jobId: JobId, priority: number): Promise<boolean>;
+    changePriority(jobId: JobId, priority: number, lifo?: boolean): Promise<boolean>;
     promote(jobId: JobId): Promise<boolean>;
     moveToDelayed(jobId: JobId, delay: number): Promise<boolean>;
     changeDelay(jobId: JobId, delay: number): Promise<boolean>;
@@ -236,10 +243,17 @@ export declare class QueueManager {
      */
     private onChildDependencyOption;
     /**
-     * continueParentOnFailure: move parent to queue immediately when a child fails.
+     * continueParentOnFailure: move parent to queue when a child fails.
      * Stores the failure info for getFailedChildrenValues().
      */
     private continueParentOnChildFailure;
+    /**
+     * Move a flow parent from its waiting state into the run queue after a child failure
+     * (continueParentOnFailure / last-dependency resolution). Deferred to the next tick
+     * so the failed child's worker batch drains first — the parent is then picked up on
+     * a subsequent poll rather than racing to completion in the same synchronous cascade.
+     */
+    private promoteParentAfterChildFailure;
     /**
      * removeDependencyOnFailure / ignoreDependencyOnFailure:
      * Remove child from parent's pending deps. If last dep, promote parent.
@@ -312,4 +326,3 @@ export declare class QueueManager {
     compactMemory(): void;
     shutdown(): void;
 }
-//# sourceMappingURL=queueManager.d.ts.map