bunqueue 1.9.9 → 2.0.1

package/dist/client/worker/worker.d.ts

@@ -4,6 +4,7 @@
  */
 import { EventEmitter } from 'events';
 import type { WorkerOptions, Processor } from '../types';
+import type { Job as InternalJob } from '../../domain/types/job';
 /**
  * Worker class for processing jobs
  */
@@ -16,25 +17,141 @@ export declare class Worker<T = unknown, R = unknown> extends EventEmitter {
     private readonly tcpPool;
     private readonly ackBatcher;
     private running;
+    private paused;
     private closing;
+    private closed;
     private activeJobs;
     private pollTimer;
     private consecutiveErrors;
     private readonly activeJobIds;
     private readonly pulledJobIds;
     private readonly jobTokens;
+    private readonly cancelledJobs;
     private heartbeatTimer;
     private readonly workerId;
     private pendingJobs;
     private pendingJobsHead;
     private processingScheduled;
+    private readonly limiter;
+    private limiterTokens;
+    private lastDrainedEmit;
+    private stalledUnsubscribe;
     constructor(name: string, processor: Processor<T, R>, opts?: WorkerOptions);
     /** Start processing */
     run(): void;
+    /** Subscribe to stalled events from QueueManager (BullMQ v5 compatible) */
+    private subscribeToStalledEvents;
     /** Pause processing */
     pause(): void;
     /** Resume processing */
     resume(): void;
+    /** Check if worker is currently running */
+    isRunning(): boolean;
+    /** Check if worker is paused */
+    isPaused(): boolean;
+    /** Check if worker is closed */
+    isClosed(): boolean;
+    /**
+     * Wait until the worker is ready (BullMQ v5 compatible).
+     * In embedded mode, resolves immediately.
+     * In TCP mode, waits for connection to be established.
+     */
+    waitUntilReady(): Promise<void>;
+    /**
+     * Mark a job for cancellation (BullMQ v5 compatible).
+     * The job will be failed with the given reason when it completes processing.
+     * Returns true if the job was found and marked for cancellation.
+     */
+    cancelJob(jobId: string, reason?: string): boolean;
+    /**
+     * Mark all active jobs for cancellation (BullMQ v5 compatible).
+     */
+    cancelAllJobs(reason?: string): void;
+    /**
+     * Check if a job has been marked for cancellation.
+     * Can be called from within a processor to check if the job should stop.
+     */
+    isJobCancelled(jobId: string): boolean;
+    /**
+     * Check if rate limiter allows processing another job.
+     * Returns true if we can process, false if rate limited.
+     */
+    private canProcessWithinLimit;
+    /**
+     * Record a job completion for rate limiting.
+     */
+    private recordJobForLimiter;
+    /**
+     * Get time until rate limiter allows next job (ms).
+     * Returns 0 if not rate limited.
+     */
+    private getTimeUntilNextSlot;
+    /**
+     * Get rate limiter info (for debugging/monitoring).
+     */
+    getRateLimiterInfo(): {
+        current: number;
+        max: number;
+        duration: number;
+    } | null;
+    /**
+     * Apply rate limiting to this worker (BullMQ v5 compatible).
+     * The worker will not process jobs until the rate limit expires.
+     *
+     * @param expireTimeMs - Time in milliseconds until rate limit expires
+     */
+    rateLimit(expireTimeMs: number): void;
+    /** Rate limit expiration timestamp (internal) */
+    private rateLimitExpiration;
+    /**
+     * Check if worker is currently rate limited.
+     */
+    isRateLimited(): boolean;
+    /**
+     * Manually start the stalled job check timer (BullMQ v5 compatible).
+     * The check will run once immediately and then every stalledInterval ms.
+     * In bunqueue, stall detection is handled automatically by the manager/server.
+     */
+    startStalledCheckTimer(): Promise<void>;
+    /**
+     * Delay processing for a specified time (BullMQ v5 compatible).
+     * The worker will not pick up new jobs during this delay.
+     *
+     * @param milliseconds - Time to delay in ms (default: 0)
+     * @param abortController - Optional AbortController to cancel the delay
+     */
+    delay(milliseconds?: number, abortController?: AbortController): Promise<void>;
+    /**
+     * Get the next job from the queue (BullMQ v5 compatible).
+     * This is for manual job processing - typically you'd use the processor callback instead.
+     *
+     * @param token - Lock token for job ownership
+     * @param opts - Options (currently unused, for API compatibility)
+     * @returns The next job or undefined if queue is empty
+     */
+    getNextJob(token?: string, _opts?: {
+        block?: boolean;
+    }): Promise<InternalJob | undefined>;
+    /**
+     * Manually process a job (BullMQ v5 compatible).
+     * This is for advanced use cases where you need manual control over job processing.
+     *
+     * @param job - The job to process
+     * @param token - Lock token for job ownership
+     * @param fetchNextCallback - Optional callback to fetch next job after completion
+     * @returns The processed job or void
+     */
+    processJobManually(job: InternalJob, token?: string, fetchNextCallback?: () => Promise<InternalJob | undefined>): Promise<InternalJob | undefined>;
+    /**
+     * Extend locks on multiple jobs (BullMQ v5 compatible).
+     * Used to prevent jobs from being considered stalled during long processing.
+     *
+     * @param jobIds - Array of job IDs to extend locks for
+     * @param tokens - Array of lock tokens corresponding to each job
+     * @param duration - Duration in milliseconds to extend the lock
+     * @returns Number of locks successfully extended
+     */
+    extendJobLocks(jobIds: string[], tokens: string[], duration: number): Promise<number>;
     /** Close worker gracefully */
     close(force?: boolean): Promise<void>;
     private startHeartbeat;

package/dist/client/worker/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/client/worker/worker.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAGtC,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAqB,MAAM,UAAU,CAAC;AAQ5E;;GAEG;AACH,qBAAa,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,CAAE,SAAQ,YAAY;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAwB;IAC7C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkB;IAC5C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAU;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IACnD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IAExC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,iBAAiB,CAAK;IAI9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA0B;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAkC;IAC5D,OAAO,CAAC,cAAc,CAA+C;IAGrE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAGlC,OAAO,CAAC,WAAW,CAAyD;IAC5E,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,mBAAmB,CAAS;gBAExB,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,GAAE,aAAkB;IA+C9E,uBAAuB;IACvB,GAAG,IAAI,IAAI;IAYX,uBAAuB;IACvB,KAAK,IAAI,IAAI;IAQb,wBAAwB;IACxB,MAAM,IAAI,IAAI;IAId,8BAA8B;IACxB,KAAK,CAAC,KAAK,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAwCzC,OAAO,CAAC,cAAc;YAIR,aAAa;IAiC3B,OAAO,CAAC,IAAI;YAYE,UAAU;IAqCxB,kDAAkD;IAClD,OAAO,CAAC,kBAAkB;IAY1B,OAAO,CAAC,cAAc;YAWR,SAAS;YAQT,YAAY;YAwBZ,OAAO;IA2CrB,OAAO,CAAC,QAAQ;IA2ChB,OAAO,CAAC,eAAe;CAoBxB"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../../../src/client/worker/worker.ts"],"names":[],"mappings":"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"}

package/dist/client/worker/worker.js

@@ -21,7 +21,9 @@ export class Worker extends EventEmitter {
     tcpPool;
     ackBatcher;
     running = false;
+    paused = false;
     closing = false;
+    closed = false;
     activeJobs = 0;
     pollTimer = null;
     consecutiveErrors = 0;
@@ -30,6 +32,7 @@ export class Worker extends EventEmitter {
     activeJobIds = new Set();
     pulledJobIds = new Set(); // All pulled jobs (for heartbeat)
     jobTokens = new Map(); // jobId -> lockToken
+    cancelledJobs = new Set(); // Jobs marked for cancellation
     heartbeatTimer = null;
     // Unique worker ID for lock ownership
     workerId;
@@ -37,6 +40,13 @@ export class Worker extends EventEmitter {
     pendingJobs = [];
     pendingJobsHead = 0;
     processingScheduled = false; // Prevent multiple setImmediate calls
+    // Rate limiter state (BullMQ v5 compatible)
+    limiter;
+    limiterTokens = []; // Timestamps of recent job completions
+    // Drained event tracking
+    lastDrainedEmit = 0;
+    // Stalled event subscription (BullMQ v5 compatible)
+    stalledUnsubscribe = null;
     constructor(name, processor, opts = {}) {
         super();
         this.name = name;
@@ -55,6 +65,8 @@ export class Worker extends EventEmitter {
             // Lock-based ownership: disable for high-throughput scenarios where stall detection is sufficient
             useLocks: opts.useLocks ?? true,
         };
+        // Initialize rate limiter if provided
+        this.limiter = opts.limiter ?? null;
         this.ackBatcher = new AckBatcher({
             batchSize: opts.batchSize ?? 10,
             interval: WORKER_CONSTANTS.DEFAULT_ACK_INTERVAL,
@@ -81,19 +93,41 @@ export class Worker extends EventEmitter {
     }
     /** Start processing */
     run() {
-        if (this.running)
+        if (this.running || this.closed)
             return;
         this.running = true;
+        this.paused = false;
         this.closing = false;
         this.emit('ready');
+        // Subscribe to stalled events in embedded mode (BullMQ v5)
+        if (this.embedded && !this.stalledUnsubscribe) {
+            this.subscribeToStalledEvents();
+        }
         if (!this.embedded && this.opts.heartbeatInterval > 0) {
             this.startHeartbeat();
         }
         this.poll();
     }
+    /** Subscribe to stalled events from QueueManager (BullMQ v5 compatible) */
+    subscribeToStalledEvents() {
+        if (!this.embedded)
+            return;
+        const manager = getSharedManager();
+        this.stalledUnsubscribe = manager.subscribe((event) => {
+            if (event.queue !== this.name)
+                return;
+            if (event.eventType === "stalled" /* EventType.Stalled */) {
+                // Emit stalled event (BullMQ v5 format: jobId, prev)
+                this.emit('stalled', event.jobId, 'active');
+            }
+        });
+    }
     /** Pause processing */
     pause() {
+        if (!this.running)
+            return;
         this.running = false;
+        this.paused = true;
         if (this.pollTimer) {
             clearTimeout(this.pollTimer);
             this.pollTimer = null;
@@ -101,12 +135,325 @@ export class Worker extends EventEmitter {
     }
     /** Resume processing */
     resume() {
+        if (this.closed)
+            return;
+        this.paused = false;
         this.run();
     }
+    /** Check if worker is currently running */
+    isRunning() {
+        return this.running;
+    }
+    /** Check if worker is paused */
+    isPaused() {
+        return this.paused && !this.closed;
+    }
+    /** Check if worker is closed */
+    isClosed() {
+        return this.closed;
+    }
+    /**
+     * Wait until the worker is ready (BullMQ v5 compatible).
+     * In embedded mode, resolves immediately.
+     * In TCP mode, waits for connection to be established.
+     */
+    async waitUntilReady() {
+        if (this.embedded) {
+            // Embedded mode is always ready
+            return;
+        }
+        if (this.tcpPool) {
+            // Wait for TCP connection by sending a ping
+            await this.tcpPool.send({ cmd: 'Ping' });
+        }
+    }
+    /**
+     * Mark a job for cancellation (BullMQ v5 compatible).
+     * The job will be failed with the given reason when it completes processing.
+     * Returns true if the job was found and marked for cancellation.
+     */
+    cancelJob(jobId, reason) {
+        if (this.activeJobIds.has(jobId)) {
+            this.cancelledJobs.add(jobId);
+            this.emit('cancelled', { jobId, reason: reason ?? 'Job cancelled by worker' });
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Mark all active jobs for cancellation (BullMQ v5 compatible).
+     */
+    cancelAllJobs(reason) {
+        for (const jobId of this.activeJobIds) {
+            this.cancelledJobs.add(jobId);
+            this.emit('cancelled', { jobId, reason: reason ?? 'All jobs cancelled' });
+        }
+    }
+    /**
+     * Check if a job has been marked for cancellation.
+     * Can be called from within a processor to check if the job should stop.
+     */
+    isJobCancelled(jobId) {
+        return this.cancelledJobs.has(jobId);
+    }
+    /**
+     * Check if rate limiter allows processing another job.
+     * Returns true if we can process, false if rate limited.
+     */
+    canProcessWithinLimit() {
+        if (!this.limiter)
+            return true;
+        const now = Date.now();
+        const windowStart = now - this.limiter.duration;
+        // Remove expired tokens
+        this.limiterTokens = this.limiterTokens.filter((t) => t > windowStart);
+        // Check if we have capacity
+        return this.limiterTokens.length < this.limiter.max;
+    }
+    /**
+     * Record a job completion for rate limiting.
+     */
+    recordJobForLimiter() {
+        if (!this.limiter)
+            return;
+        this.limiterTokens.push(Date.now());
+    }
+    /**
+     * Get time until rate limiter allows next job (ms).
+     * Returns 0 if not rate limited.
+     */
+    getTimeUntilNextSlot() {
+        if (!this.limiter)
+            return 0;
+        const now = Date.now();
+        const windowStart = now - this.limiter.duration;
+        // Remove expired tokens
+        this.limiterTokens = this.limiterTokens.filter((t) => t > windowStart);
+        if (this.limiterTokens.length < this.limiter.max) {
+            return 0;
+        }
+        // Find oldest token and calculate when it expires
+        const oldestToken = Math.min(...this.limiterTokens);
+        return oldestToken + this.limiter.duration - now;
+    }
+    /**
+     * Get rate limiter info (for debugging/monitoring).
+     */
+    getRateLimiterInfo() {
+        if (!this.limiter)
+            return null;
+        const now = Date.now();
+        const windowStart = now - this.limiter.duration;
+        const currentTokens = this.limiterTokens.filter((t) => t > windowStart).length;
+        return {
+            current: currentTokens,
+            max: this.limiter.max,
+            duration: this.limiter.duration,
+        };
+    }
+    /**
+     * Apply rate limiting to this worker (BullMQ v5 compatible).
+     * The worker will not process jobs until the rate limit expires.
+     *
+     * @param expireTimeMs - Time in milliseconds until rate limit expires
+     */
+    rateLimit(expireTimeMs) {
+        if (expireTimeMs <= 0)
+            return;
+        // Fill rate limiter tokens to block processing
+        if (this.limiter) {
+            const now = Date.now();
+            // Add enough tokens to block for the specified time
+            for (let i = 0; i < this.limiter.max; i++) {
+                this.limiterTokens.push(now + expireTimeMs - this.limiter.duration);
+            }
+        }
+        // Store rate limit expiration
+        this.rateLimitExpiration = Date.now() + expireTimeMs;
+    }
+    /** Rate limit expiration timestamp (internal) */
+    rateLimitExpiration = 0;
+    /**
+     * Check if worker is currently rate limited.
+     */
+    isRateLimited() {
+        return Date.now() < this.rateLimitExpiration;
+    }
+    /**
+     * Manually start the stalled job check timer (BullMQ v5 compatible).
+     * The check will run once immediately and then every stalledInterval ms.
+     * In bunqueue, stall detection is handled automatically by the manager/server.
+     */
+    async startStalledCheckTimer() {
+        // In bunqueue, stall detection is handled automatically by:
+        // - Embedded mode: QueueManager.checkStalledJobs() runs periodically
+        // - TCP mode: Server-side stall detection
+        // This method is a no-op for API compatibility
+    }
+    /**
+     * Delay processing for a specified time (BullMQ v5 compatible).
+     * The worker will not pick up new jobs during this delay.
+     *
+     * @param milliseconds - Time to delay in ms (default: 0)
+     * @param abortController - Optional AbortController to cancel the delay
+     */
+    async delay(milliseconds = 0, abortController) {
+        if (milliseconds <= 0)
+            return;
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(resolve, milliseconds);
+            if (abortController) {
+                abortController.signal.addEventListener('abort', () => {
+                    clearTimeout(timeout);
+                    reject(new Error('Delay aborted'));
+                });
+            }
+        });
+    }
+    // ============================================================================
+    // BullMQ v5 Manual Job Control Methods
+    // ============================================================================
+    /**
+     * Get the next job from the queue (BullMQ v5 compatible).
+     * This is for manual job processing - typically you'd use the processor callback instead.
+     *
+     * @param token - Lock token for job ownership
+     * @param opts - Options (currently unused, for API compatibility)
+     * @returns The next job or undefined if queue is empty
+     */
+    async getNextJob(token, _opts) {
+        if (this.closed)
+            return undefined;
+        if (this.embedded) {
+            const manager = getSharedManager();
+            if (this.opts.useLocks) {
+                const { job, token: lockToken } = await manager.pullWithLock(this.name, this.workerId, 0);
+                if (job && lockToken) {
+                    const jobIdStr = String(job.id);
+                    this.pulledJobIds.add(jobIdStr);
+                    this.jobTokens.set(jobIdStr, lockToken);
+                }
+                return job ?? undefined;
+            }
+            const job = await manager.pull(this.name, 0);
+            if (job) {
+                this.pulledJobIds.add(String(job.id));
+            }
+            return job ?? undefined;
+        }
+        // TCP mode
+        if (!this.tcp)
+            return undefined;
+        const cmd = {
+            cmd: 'PULL',
+            queue: this.name,
+            timeout: 0,
+        };
+        if (this.opts.useLocks) {
+            cmd.owner = this.workerId;
+            if (token)
+                cmd.token = token;
+        }
+        const response = await this.tcp.send(cmd);
+        if (!response.ok || !response.job)
+            return undefined;
+        const job = parseJobFromResponse(response.job, this.name);
+        const jobIdStr = String(job.id);
+        this.pulledJobIds.add(jobIdStr);
+        if (this.opts.useLocks && response.token) {
+            this.jobTokens.set(jobIdStr, response.token);
+        }
+        return job;
+    }
+    /**
+     * Manually process a job (BullMQ v5 compatible).
+     * This is for advanced use cases where you need manual control over job processing.
+     *
+     * @param job - The job to process
+     * @param token - Lock token for job ownership
+     * @param fetchNextCallback - Optional callback to fetch next job after completion
+     * @returns The processed job or void
+     */
+    async processJobManually(job, token, fetchNextCallback) {
+        if (this.closed)
+            return undefined;
+        const jobIdStr = String(job.id);
+        this.activeJobs++;
+        this.activeJobIds.add(jobIdStr);
+        this.pulledJobIds.add(jobIdStr);
+        if (this.opts.useLocks && token) {
+            this.jobTokens.set(jobIdStr, token);
+        }
+        try {
+            await processJob(job, {
+                name: this.name,
+                processor: this.processor,
+                embedded: this.embedded,
+                tcp: this.tcp,
+                ackBatcher: this.ackBatcher,
+                emitter: this,
+                token: this.opts.useLocks ? token : undefined,
+            });
+            // Fetch next job if callback provided
+            if (fetchNextCallback) {
+                return await fetchNextCallback();
+            }
+        }
+        finally {
+            this.activeJobs--;
+            this.activeJobIds.delete(jobIdStr);
+            this.pulledJobIds.delete(jobIdStr);
+            this.cancelledJobs.delete(jobIdStr);
+            if (this.opts.useLocks) {
+                this.jobTokens.delete(jobIdStr);
+            }
+            this.recordJobForLimiter();
+        }
+    }
+    /**
+     * Extend locks on multiple jobs (BullMQ v5 compatible).
+     * Used to prevent jobs from being considered stalled during long processing.
+     *
+     * @param jobIds - Array of job IDs to extend locks for
+     * @param tokens - Array of lock tokens corresponding to each job
+     * @param duration - Duration in milliseconds to extend the lock
+     * @returns Number of locks successfully extended
+     */
+    async extendJobLocks(jobIds, tokens, duration) {
+        if (this.closed || jobIds.length === 0)
+            return 0;
+        if (jobIds.length !== tokens.length) {
+            throw new Error('jobIds and tokens arrays must have the same length');
+        }
+        if (this.embedded) {
+            const manager = getSharedManager();
+            let extended = 0;
+            for (let i = 0; i < jobIds.length; i++) {
+                const success = await manager.extendLock(jobIds[i], tokens[i], duration);
+                if (success)
+                    extended++;
+            }
+            return extended;
+        }
+        // TCP mode
+        if (!this.tcp)
+            return 0;
+        const response = await this.tcp.send({
+            cmd: 'ExtendLocks',
+            ids: jobIds,
+            tokens,
+            duration,
+        });
+        const extended = response.extended;
+        return extended ?? 0;
+    }
     /** Close worker gracefully */
     async close(force = false) {
+        if (this.closed)
+            return;
         this.closing = true;
         this.running = false;
+        this.paused = false;
         if (this.pollTimer) {
             clearTimeout(this.pollTimer);
             this.pollTimer = null;
@@ -129,14 +476,22 @@ export class Worker extends EventEmitter {
         this.ackBatcher.stop();
         // Small delay to ensure TCP responses are processed
         await new Promise((r) => setTimeout(r, 100));
+        // Unsubscribe from stalled events
+        if (this.stalledUnsubscribe) {
+            this.stalledUnsubscribe();
+            this.stalledUnsubscribe = null;
+        }
         // Clear tracking sets
         this.activeJobIds.clear();
         this.pulledJobIds.clear();
         this.jobTokens.clear();
+        this.cancelledJobs.clear();
         this.pendingJobs = [];
         this.pendingJobsHead = 0;
         if (this.tcpPool)
             this.tcpPool.close();
+        this.closed = true;
+        this.closing = false;
         this.emit('closed');
     }
     startHeartbeat() {
@@ -187,6 +542,14 @@ export class Worker extends EventEmitter {
             }, 10);
             return;
         }
+        // Check rate limiter
+        if (!this.canProcessWithinLimit()) {
+            const waitTime = this.getTimeUntilNextSlot();
+            this.pollTimer = setTimeout(() => {
+                this.poll();
+            }, Math.max(waitTime, 10));
+            return;
+        }
         void this.tryProcess();
     }
     async tryProcess() {
@@ -196,9 +559,9 @@ export class Worker extends EventEmitter {
             let item = this.getBufferedJob();
             if (!item) {
                 const items = await this.pullBatch();
-                // Re-check closing after async operation (can be modified during await)
+                // Re-check state after async operation (can be modified during await)
                 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-                if (this.closing)
+                if (!this.running || this.closing)
                     return;
                 if (items.length > 0) {
                     // Register ALL pulled jobs for heartbeat tracking immediately
@@ -213,6 +576,12 @@ export class Worker extends EventEmitter {
                 this.startJob(item.job, item.token);
             }
             else {
+                // Emit drained event when queue is empty (throttled to avoid spam)
+                const now = Date.now();
+                if (now - this.lastDrainedEmit > 1000) {
+                    this.lastDrainedEmit = now;
+                    this.emit('drained');
+                }
                 const waitTime = this.opts.pollTimeout > 0 ? 10 : 50;
                 this.pollTimer = setTimeout(() => {
                     this.poll();
@@ -335,9 +704,12 @@ export class Worker extends EventEmitter {
             this.activeJobs--;
             this.activeJobIds.delete(jobIdStr);
             this.pulledJobIds.delete(jobIdStr); // Remove from heartbeat tracking
+            this.cancelledJobs.delete(jobIdStr); // Clean up cancellation flag
             if (this.opts.useLocks) {
                 this.jobTokens.delete(jobIdStr); // Clean up token
             }
+            // Record job completion for rate limiter
+            this.recordJobForLimiter();
             if (this.running && !this.closing)
                 this.poll();
         });