@monque/core 1.5.2 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@monque/core",
-	"version": "1.5.2",
+	"version": "1.7.0",
 	"description": "MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling",
 	"author": "Maurice de Bruyn <debruyn.maurice@gmail.com>",
 	"repository": {
@@ -16,7 +16,7 @@
 	"sideEffects": false,
 	"type": "module",
 	"engines": {
-		"node": ">=22.0.0"
+		"node": ">=22.12.0"
 	},
 	"publishConfig": {
 		"access": "public"
@@ -76,13 +76,13 @@
 	},
 	"devDependencies": {
 		"@faker-js/faker": "^10.3.0",
-		"@testcontainers/mongodb": "^11.12.0",
+		"@testcontainers/mongodb": "^11.13.0",
 		"@total-typescript/ts-reset": "^0.6.1",
 		"@types/node": "^22.19.15",
-		"@vitest/coverage-v8": "^4.0.18",
+		"@vitest/coverage-v8": "^4.1.0",
 		"fishery": "^2.4.0",
 		"mongodb": "^7.1.0",
-		"tsdown": "^0.21.1",
-		"vitest": "^4.0.18"
+		"tsdown": "^0.21.4",
+		"vitest": "^4.1.0"
 	}
 }

package/src/index.ts

@@ -41,11 +41,14 @@ export {
 	getNextCronDate,
 	InvalidCronError,
 	InvalidCursorError,
+	InvalidJobIdentifierError,
 	JobStateError,
 	MonqueError,
 	PayloadTooLargeError,
 	ShutdownTimeoutError,
 	validateCronExpression,
+	validateJobName,
+	validateUniqueKey,
 	WorkerRegistrationError,
 } from '@/shared';
 // Types - Workers

package/src/scheduler/monque.ts

@@ -18,11 +18,18 @@ import {
 	type QueueStats,
 	type ScheduleOptions,
 } from '@/jobs';
-import { ConnectionError, ShutdownTimeoutError, WorkerRegistrationError } from '@/shared';
+import {
+	ConnectionError,
+	ShutdownTimeoutError,
+	validateJobName,
+	validateUniqueKey,
+	WorkerRegistrationError,
+} from '@/shared';
 import type { WorkerOptions, WorkerRegistration } from '@/workers';
 
 import {
 	ChangeStreamHandler,
+	CLEANUP_STATUSES,
 	JobManager,
 	JobProcessor,
 	JobQueryService,
@@ -39,6 +46,7 @@ import type { MonqueOptions } from './types.js';
 const DEFAULTS = {
 	collectionName: 'monque_jobs',
 	pollInterval: 1000,
+	safetyPollInterval: 30_000,
 	maxRetries: 10,
 	baseRetryInterval: 1000,
 	shutdownTimeout: 30000,
@@ -121,6 +129,15 @@ export class Monque extends EventEmitter {
 	private isRunning = false;
 	private isInitialized = false;
 
+	/**
+	 * Resolve function for the reactive shutdown drain promise.
+	 * Set during stop() when active jobs need to finish; called by
+	 * onJobFinished() when the last active job completes.
+	 *
+	 * @private
+	 */
+	private _drainResolve: (() => void) | null = null;
+
 	// Internal services (initialized in initialize())
 	private _scheduler: JobScheduler | null = null;
 	private _manager: JobManager | null = null;
@@ -131,10 +148,12 @@ export class Monque extends EventEmitter {
 
 	constructor(db: Db, options: MonqueOptions = {}) {
 		super();
+		this.setMaxListeners(20);
 		this.db = db;
 		this.options = {
 			collectionName: options.collectionName ?? DEFAULTS.collectionName,
 			pollInterval: options.pollInterval ?? DEFAULTS.pollInterval,
+			safetyPollInterval: options.safetyPollInterval ?? DEFAULTS.safetyPollInterval,
 			maxRetries: options.maxRetries ?? DEFAULTS.maxRetries,
 			baseRetryInterval: options.baseRetryInterval ?? DEFAULTS.baseRetryInterval,
 			shutdownTimeout: options.shutdownTimeout ?? DEFAULTS.shutdownTimeout,
@@ -151,6 +170,17 @@ export class Monque extends EventEmitter {
 			maxPayloadSize: options.maxPayloadSize,
 			statsCacheTtlMs: options.statsCacheTtlMs ?? 5000,
 		};
+
+		if (options.defaultConcurrency !== undefined) {
+			console.warn(
+				'[@monque/core] "defaultConcurrency" is deprecated and will be removed in a future major version. Use "workerConcurrency" instead.',
+			);
+		}
+		if (options.maxConcurrency !== undefined) {
+			console.warn(
+				'[@monque/core] "maxConcurrency" is deprecated and will be removed in a future major version. Use "instanceConcurrency" instead.',
+			);
+		}
 	}
 
 	/**
@@ -186,7 +216,9 @@ export class Monque extends EventEmitter {
 			this._manager = new JobManager(ctx);
 			this._query = new JobQueryService(ctx);
 			this._processor = new JobProcessor(ctx);
-			this._changeStreamHandler = new ChangeStreamHandler(ctx, () => this.processor.poll());
+			this._changeStreamHandler = new ChangeStreamHandler(ctx, (targetNames) =>
+				this.handleChangeStreamPoll(targetNames),
+			);
 			this._lifecycleManager = new LifecycleManager(ctx);
 
 			this.isInitialized = true;
@@ -255,6 +287,26 @@ export class Monque extends EventEmitter {
 		return this._lifecycleManager;
 	}
 
+	private validateSchedulingIdentifiers(name: string, uniqueKey?: string): void {
+		validateJobName(name);
+
+		if (uniqueKey !== undefined) {
+			validateUniqueKey(uniqueKey);
+		}
+	}
+
+	/**
+	 * Handle a change-stream-triggered poll and reset the safety poll timer.
+	 *
+	 * Used as the `onPoll` callback for {@link ChangeStreamHandler}. Runs a
+	 * targeted poll for the given worker names, then resets the adaptive safety
+	 * poll timer so it doesn't fire redundantly.
+	 */
+	private async handleChangeStreamPoll(targetNames?: ReadonlySet<string>): Promise<void> {
+		await this.processor.poll(targetNames);
+		this.lifecycleManager.resetPollTimer();
+	}
+
 	/**
 	 * Build the shared context for internal services.
 	 */
@@ -271,6 +323,14 @@ export class Monque extends EventEmitter {
 			isRunning: () => this.isRunning,
 			emit: <K extends keyof MonqueEventMap>(event: K, payload: MonqueEventMap[K]) =>
 				this.emit(event, payload),
+			notifyPendingJob: (name: string, nextRunAt: Date) => {
+				if (!this.isRunning || !this._changeStreamHandler) {
+					return;
+				}
+
+				this._changeStreamHandler.notifyPendingJob(name, nextRunAt);
+			},
+			notifyJobFinished: () => this.onJobFinished(),
 			documentToPersistedJob: <T>(doc: WithId<Document>) => documentToPersistedJob<T>(doc),
 		};
 	}
@@ -318,6 +378,20 @@ export class Monque extends EventEmitter {
 			{ key: { status: 1, nextRunAt: 1, claimedBy: 1 }, background: true },
 			// Expanded index that supports recovery scans (status + lockedAt) plus heartbeat monitoring patterns.
 			{ key: { status: 1, lockedAt: 1, lastHeartbeat: 1 }, background: true },
+			// Index for efficient lifecycle manager cleanup when jobRetention is configured.
+			// Allows fast queries for deleteMany({ status, updatedAt: { $lt: cutoff } }).
+			...(this.options.jobRetention
+				? [
+						{
+							key: { status: 1, updatedAt: 1 } as const,
+							background: true,
+							partialFilterExpression: {
+								status: { $in: CLEANUP_STATUSES },
+								updatedAt: { $exists: true },
+							},
+						},
+					]
+				: []),
 		]);
 	}
 
@@ -347,7 +421,6 @@ export class Monque extends EventEmitter {
 					lockedAt: '',
 					claimedBy: '',
 					lastHeartbeat: '',
-					heartbeatInterval: '',
 				},
 			},
 		);
@@ -414,6 +487,7 @@ export class Monque extends EventEmitter {
 	 * @param data - Job payload, will be passed to the worker handler
 	 * @param options - Scheduling and deduplication options
 	 * @returns Promise resolving to the created or existing job document
+	 * @throws {InvalidJobIdentifierError} If `name` or `uniqueKey` fails public identifier validation
 	 * @throws {ConnectionError} If database operation fails or scheduler not initialized
 	 * @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
 	 *
@@ -446,6 +520,7 @@ export class Monque extends EventEmitter {
 	 */
 	async enqueue<T>(name: string, data: T, options: EnqueueOptions = {}): Promise<PersistedJob<T>> {
 		this.ensureInitialized();
+		this.validateSchedulingIdentifiers(name, options.uniqueKey);
 		return this.scheduler.enqueue(name, data, options);
 	}
 
@@ -459,6 +534,7 @@ export class Monque extends EventEmitter {
 	 * @param name - Job type identifier, must match a registered worker
 	 * @param data - Job payload, will be passed to the worker handler
 	 * @returns Promise resolving to the created job document
+	 * @throws {InvalidJobIdentifierError} If `name` fails public identifier validation
 	 * @throws {ConnectionError} If database operation fails or scheduler not initialized
 	 *
 	 * @example Send email immediately
@@ -481,6 +557,7 @@ export class Monque extends EventEmitter {
 	 */
 	async now<T>(name: string, data: T): Promise<PersistedJob<T>> {
 		this.ensureInitialized();
+		validateJobName(name);
 		return this.scheduler.now(name, data);
 	}
 
@@ -502,6 +579,7 @@ export class Monque extends EventEmitter {
 	 * @param data - Job payload, will be passed to the worker handler on each run
 	 * @param options - Scheduling options (uniqueKey for deduplication)
 	 * @returns Promise resolving to the created job document with `repeatInterval` set
+	 * @throws {InvalidJobIdentifierError} If `name` or `uniqueKey` fails public identifier validation
 	 * @throws {InvalidCronError} If cron expression is invalid
 	 * @throws {ConnectionError} If database operation fails or scheduler not initialized
 	 * @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
@@ -538,6 +616,7 @@ export class Monque extends EventEmitter {
 		options: ScheduleOptions = {},
 	): Promise<PersistedJob<T>> {
 		this.ensureInitialized();
+		this.validateSchedulingIdentifiers(name, options.uniqueKey);
 		return this.scheduler.schedule(cron, name, data, options);
 	}
 
@@ -907,6 +986,7 @@ export class Monque extends EventEmitter {
 	 * @param options - Worker configuration
 	 * @param options.concurrency - Maximum concurrent jobs for this worker (default: `defaultConcurrency`)
 	 * @param options.replace - When `true`, replace existing worker instead of throwing error
+	 * @throws {InvalidJobIdentifierError} If `name` fails public identifier validation
 	 * @throws {WorkerRegistrationError} When a worker is already registered for `name` and `replace` is not `true`
 	 *
 	 * @example Basic email worker
@@ -950,6 +1030,7 @@ export class Monque extends EventEmitter {
 	 * ```
 	 */
 	register<T>(name: string, handler: JobHandler<T>, options: WorkerOptions = {}): void {
+		validateJobName(name);
 		const concurrency = options.concurrency ?? this.options.workerConcurrency;
 
 		// Check for existing worker and throw unless replace is explicitly true
@@ -1032,6 +1113,7 @@ export class Monque extends EventEmitter {
 		this.lifecycleManager.startTimers({
 			poll: () => this.processor.poll(),
 			updateHeartbeats: () => this.processor.updateHeartbeats(),
+			isChangeStreamActive: () => this.changeStreamHandler.isActive(),
 		});
 	}
 
@@ -1092,20 +1174,14 @@ export class Monque extends EventEmitter {
 		}
 
 		// Wait for all active jobs to complete (with timeout)
-		const activeJobs = this.getActiveJobs();
-		if (activeJobs.length === 0) {
+		if (this.getActiveJobCount() === 0) {
 			return;
 		}
 
-		// Create a promise that resolves when all jobs are done
-		let checkInterval: ReturnType<typeof setInterval> | undefined;
+		// Reactive drain: resolve when the last active job finishes.
+		// onJobFinished() is called from processJob's finally block.
 		const waitForJobs = new Promise<undefined>((resolve) => {
-			checkInterval = setInterval(() => {
-				if (this.getActiveJobs().length === 0) {
-					clearInterval(checkInterval);
-					resolve(undefined);
-				}
-			}, 100);
+			this._drainResolve = () => resolve(undefined);
 		});
 
 		// Race between job completion and timeout
@@ -1113,15 +1189,9 @@ export class Monque extends EventEmitter {
 			setTimeout(() => resolve('timeout'), this.options.shutdownTimeout);
 		});
 
-		let result: undefined | 'timeout';
+		const result = await Promise.race([waitForJobs, timeout]);
 
-		try {
-			result = await Promise.race([waitForJobs, timeout]);
-		} finally {
-			if (checkInterval) {
-				clearInterval(checkInterval);
-			}
-		}
+		this._drainResolve = null;
 
 		if (result === 'timeout') {
 			const incompleteJobs = this.getActiveJobsList();
@@ -1188,6 +1258,18 @@ export class Monque extends EventEmitter {
 	// Private Helpers
 	// ─────────────────────────────────────────────────────────────────────────────
 
+	/**
+	 * Called when a job finishes processing. If a shutdown drain is pending
+	 * and no active jobs remain, resolves the drain promise.
+	 *
+	 * @private
+	 */
+	private onJobFinished(): void {
+		if (this._drainResolve && this.getActiveJobCount() === 0) {
+			this._drainResolve();
+		}
+	}
+
 	/**
 	 * Ensure the scheduler is initialized before operations.
 	 *
@@ -1201,17 +1283,20 @@ export class Monque extends EventEmitter {
 	}
 
 	/**
-	 * Get array of active job IDs across all workers.
+	 * Get total count of active jobs across all workers.
+	 *
+	 * Returns only the count (O(workers)) instead of allocating
+	 * a throw-away array of IDs, since callers only need `.length`.
 	 *
 	 * @private
-	 * @returns Array of job ID strings currently being processed
+	 * @returns Number of jobs currently being processed
 	 */
-	private getActiveJobs(): string[] {
-		const activeJobs: string[] = [];
+	private getActiveJobCount(): number {
+		let count = 0;
 		for (const worker of this.workers.values()) {
-			activeJobs.push(...worker.activeJobs.keys());
+			count += worker.activeJobs.size;
 		}
-		return activeJobs;
+		return count;
 	}
 
 	/**

package/src/scheduler/services/change-stream-handler.ts

@@ -5,12 +5,22 @@ import { toError } from '@/shared';
 
 import type { SchedulerContext } from './types.js';
 
+/** Minimum poll interval floor to prevent tight loops (ms) */
+const MIN_POLL_INTERVAL = 100;
+
+/** Grace period after nextRunAt before scheduling a wakeup poll (ms) */
+const POLL_GRACE_PERIOD = 200;
+
 /**
  * Internal service for MongoDB Change Stream lifecycle.
  *
  * Provides real-time job notifications when available, with automatic
  * reconnection and graceful fallback to polling-only mode.
  *
+ * Leverages the full document from change stream events to:
+ * - Trigger **targeted polls** for specific workers (using the job `name`)
+ * - Schedule **precise wakeup timers** for future-dated jobs (using `nextRunAt`)
+ *
  * @internal Not part of public API.
  */
 export class ChangeStreamHandler {
@@ -32,9 +42,18 @@ export class ChangeStreamHandler {
 	/** Whether the scheduler is currently using change streams */
 	private usingChangeStreams = false;
 
+	/** Job names collected during the current debounce window for targeted polling */
+	private pendingTargetNames: Set<string> = new Set();
+
+	/** Wakeup timer for the earliest known future job */
+	private wakeupTimer: ReturnType<typeof setTimeout> | null = null;
+
+	/** Time of the currently scheduled wakeup */
+	private wakeupTime: Date | null = null;
+
 	constructor(
 		private readonly ctx: SchedulerContext,
-		private readonly onPoll: () => Promise<void>,
+		private readonly onPoll: (targetNames?: ReadonlySet<string>) => Promise<void>,
 	) {}
 
 	/**
@@ -67,7 +86,10 @@ export class ChangeStreamHandler {
 							{ operationType: 'insert' },
 							{
 								operationType: 'update',
-								'updateDescription.updatedFields.status': { $exists: true },
+								$or: [
+									{ 'updateDescription.updatedFields.status': { $exists: true } },
+									{ 'updateDescription.updatedFields.nextRunAt': { $exists: true } },
+								],
 							},
 						],
 					},
@@ -102,11 +124,20 @@ export class ChangeStreamHandler {
 	}
 
 	/**
-	 * Handle a change stream event by triggering a debounced poll.
+	 * Handle a change stream event using the full document for intelligent routing.
+	 *
+	 * For **immediate jobs** (`nextRunAt <= now`): collects the job name and triggers
+	 * a debounced targeted poll for only the relevant workers.
+	 *
+	 * For **future jobs** (`nextRunAt > now`): schedules a precise wakeup timer so
+	 * the job is picked up near its scheduled time without blind polling.
 	 *
-	 * Events are debounced to prevent "claim storms" when multiple changes arrive
-	 * in rapid succession (e.g., bulk job inserts). A 100ms debounce window
-	 * collects multiple events and triggers a single poll.
+	 * For **completed/failed jobs** (slot freed): triggers a targeted re-poll for that
+	 * worker so the next pending job is picked up immediately, maintaining continuous
+	 * throughput without waiting for the safety poll interval.
+	 *
+	 * Falls back to a full poll (no target names) if the document is missing
+	 * required fields.
 	 *
 	 * @param change - The change stream event document
 	 */
@@ -121,25 +152,121 @@ export class ChangeStreamHandler {
 
 		// Get fullDocument if available (for insert or with updateLookup option)
 		const fullDocument = 'fullDocument' in change ? change.fullDocument : undefined;
-		const isPendingStatus = fullDocument?.['status'] === JobStatus.PENDING;
+		const currentStatus = fullDocument?.['status'] as string | undefined;
+		const isPendingStatus = currentStatus === JobStatus.PENDING;
+
+		// A completed/failed status change means a concurrency slot was freed.
+		// Trigger a re-poll so the next pending job is picked up immediately,
+		// rather than waiting for the safety poll interval.
+		const isSlotFreed =
+			isUpdate && (currentStatus === JobStatus.COMPLETED || currentStatus === JobStatus.FAILED);
 
 		// For inserts: always trigger since new pending jobs need processing
-		// For updates: trigger if status changed to pending (retry/release scenario)
-		const shouldTrigger = isInsert || (isUpdate && isPendingStatus);
+		// For updates to pending: trigger (retry/release/recurring reschedule)
+		// For updates to completed/failed: trigger (concurrency slot freed)
+		const shouldTrigger = isInsert || (isUpdate && isPendingStatus) || isSlotFreed;
 
-		if (shouldTrigger) {
-			// Debounce poll triggers to avoid claim storms
-			if (this.debounceTimer) {
-				clearTimeout(this.debounceTimer);
+		if (!shouldTrigger) {
+			return;
+		}
+
+		// Slot-freed events: targeted poll for that worker to pick up waiting jobs
+		if (isSlotFreed) {
+			const jobName = fullDocument?.['name'] as string | undefined;
+			if (jobName) {
+				this.pendingTargetNames.add(jobName);
 			}
+			this.debouncedPoll();
+			return;
+		}
+
+		// Extract job metadata from the full document for smart routing
+		const jobName = fullDocument?.['name'] as string | undefined;
+		const nextRunAt = fullDocument?.['nextRunAt'] as Date | undefined;
+
+		if (jobName && nextRunAt) {
+			this.notifyPendingJob(jobName, nextRunAt);
+			return;
+		}
+
+		// Immediate job or missing metadata — collect for targeted/full poll
+		if (jobName) {
+			this.pendingTargetNames.add(jobName);
+		}
+		this.debouncedPoll();
+	}
+
+	/**
+	 * Notify the handler about a pending job created or updated by this process.
+	 *
+	 * Reuses the same routing logic as change stream events so local writes don't
+	 * depend on the MongoDB change stream cursor already being fully ready.
+	 *
+	 * @param jobName - Worker name for targeted polling
+	 * @param nextRunAt - When the job becomes eligible for processing
+	 */
+	notifyPendingJob(jobName: string, nextRunAt: Date): void {
+		if (!this.ctx.isRunning()) {
+			return;
+		}
 
-			this.debounceTimer = setTimeout(() => {
-				this.debounceTimer = null;
-				this.onPoll().catch((error: unknown) => {
-					this.ctx.emit('job:error', { error: toError(error) });
-				});
-			}, 100);
+		if (nextRunAt.getTime() > Date.now()) {
+			this.scheduleWakeup(nextRunAt);
+			return;
 		}
+
+		this.pendingTargetNames.add(jobName);
+		this.debouncedPoll();
+	}
+
+	/**
+	 * Schedule a debounced poll with collected target names.
+	 *
+	 * Collects job names from multiple change stream events during the debounce
+	 * window, then triggers a single targeted poll for only those workers.
+	 */
+	private debouncedPoll(): void {
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+		}
+
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = null;
+			const names = this.pendingTargetNames.size > 0 ? new Set(this.pendingTargetNames) : undefined;
+			this.pendingTargetNames.clear();
+			this.onPoll(names).catch((error: unknown) => {
+				this.ctx.emit('job:error', { error: toError(error) });
+			});
+		}, 100);
+	}
+
+	/**
+	 * Schedule a wakeup timer for a future-dated job.
+	 *
+	 * Maintains a single timer set to the earliest known future job's `nextRunAt`.
+	 * When the timer fires, triggers a full poll to pick up all due jobs.
+	 *
+	 * @param nextRunAt - When the future job should become ready
+	 */
+	private scheduleWakeup(nextRunAt: Date): void {
+		// Only update if this job is earlier than the current wakeup
+		if (this.wakeupTime && nextRunAt >= this.wakeupTime) {
+			return;
+		}
+
+		this.clearWakeupTimer();
+		this.wakeupTime = nextRunAt;
+
+		const delay = Math.max(nextRunAt.getTime() - Date.now() + POLL_GRACE_PERIOD, MIN_POLL_INTERVAL);
+
+		this.wakeupTimer = setTimeout(() => {
+			this.wakeupTime = null;
+			this.wakeupTimer = null;
+			// Full poll — there may be multiple jobs due at this time
+			this.onPoll().catch((error: unknown) => {
+				this.ctx.emit('job:error', { error: toError(error) });
+			});
+		}, delay);
 	}
 
 	/**
@@ -158,12 +285,15 @@ export class ChangeStreamHandler {
 
 		this.reconnectAttempts++;
 
-		if (this.reconnectAttempts > this.maxReconnectAttempts) {
-			// Fall back to polling-only mode
-			this.usingChangeStreams = false;
+		// Immediately reset active state: clears stale debounce/wakeup timers,
+		// closes the broken cursor, and sets isActive() to false so the lifecycle
+		// manager switches to fast polling during backoff.
+		this.resetActiveState();
+		this.closeChangeStream();
 
+		if (this.reconnectAttempts > this.maxReconnectAttempts) {
+			// Permanent fallback to polling-only mode
 			this.clearReconnectTimer();
-			this.closeChangeStream();
 
 			this.ctx.emit('changestream:fallback', {
 				reason: `Exhausted ${this.maxReconnectAttempts} reconnection attempts: ${error.message}`,
@@ -211,6 +341,32 @@ export class ChangeStreamHandler {
 		this.reconnectTimer = null;
 	}
 
+	/**
+	 * Reset all active change stream state: clear debounce timer, wakeup timer,
+	 * pending target names, and mark as inactive.
+	 *
+	 * Does NOT close the cursor (callers handle sync vs async close) or clear
+	 * the reconnect timer/attempts (callers manage reconnection lifecycle).
+	 */
+	private resetActiveState(): void {
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+
+		this.pendingTargetNames.clear();
+		this.clearWakeupTimer();
+		this.usingChangeStreams = false;
+	}
+
+	private clearWakeupTimer(): void {
+		if (this.wakeupTimer) {
+			clearTimeout(this.wakeupTimer);
+			this.wakeupTimer = null;
+		}
+		this.wakeupTime = null;
+	}
+
 	private closeChangeStream(): void {
 		if (!this.changeStream) {
 			return;
@@ -224,13 +380,10 @@ export class ChangeStreamHandler {
 	 * Close the change stream cursor and emit closed event.
 	 */
 	async close(): Promise<void> {
-		// Clear debounce timer
-		if (this.debounceTimer) {
-			clearTimeout(this.debounceTimer);
-			this.debounceTimer = null;
-		}
+		const wasActive = this.usingChangeStreams;
 
-		// Clear reconnection timer
+		// Clear all active state (debounce, wakeup, pending names, flag)
+		this.resetActiveState();
 		this.clearReconnectTimer();
 
 		if (this.changeStream) {
@@ -241,12 +394,11 @@ export class ChangeStreamHandler {
 			}
 			this.changeStream = null;
 
-			if (this.usingChangeStreams) {
+			if (wasActive) {
 				this.ctx.emit('changestream:closed', undefined);
 			}
 		}
 
-		this.usingChangeStreams = false;
 		this.reconnectAttempts = 0;
 	}
 

package/src/scheduler/services/index.ts

@@ -4,6 +4,6 @@ export { JobManager } from './job-manager.js';
 export { JobProcessor } from './job-processor.js';
 export { JobQueryService } from './job-query.js';
 export { JobScheduler } from './job-scheduler.js';
-export { LifecycleManager } from './lifecycle-manager.js';
+export { CLEANUP_STATUSES, LifecycleManager } from './lifecycle-manager.js';
 // Types
 export type { ResolvedMonqueOptions, SchedulerContext } from './types.js';