@monque/core 1.5.2 → 1.7.0

package/dist/index.mjs

@@ -454,6 +454,30 @@ var InvalidCursorError = class InvalidCursorError extends MonqueError {
 	}
 };
 /**
+* Error thrown when a public job identifier fails validation.
+*
+* @example
+* ```typescript
+* try {
+*   await monque.enqueue('invalid job name', {});
+* } catch (error) {
+*   if (error instanceof InvalidJobIdentifierError) {
+*     console.error(`Invalid ${error.field}: ${error.message}`);
+*   }
+* }
+* ```
+*/
+var InvalidJobIdentifierError = class InvalidJobIdentifierError extends MonqueError {
+	constructor(field, value, message) {
+		super(message);
+		this.field = field;
+		this.value = value;
+		this.name = "InvalidJobIdentifierError";
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) Error.captureStackTrace(this, InvalidJobIdentifierError);
+	}
+};
+/**
 * Error thrown when a statistics aggregation times out.
 *
 * @example
@@ -647,6 +671,34 @@ function toError(value) {
 	}
 }
 //#endregion
+//#region src/shared/utils/job-identifiers.ts
+const JOB_NAME_PATTERN = /^[^\s\p{Cc}]+$/u;
+const CONTROL_CHARACTER_PATTERN = /\p{Cc}/u;
+const MAX_JOB_NAME_LENGTH = 255;
+const MAX_UNIQUE_KEY_LENGTH = 1024;
+/**
+* Validate a public job name before it is registered or scheduled.
+*
+* @param name - The job name to validate
+* @throws {InvalidJobIdentifierError} If the job name is empty, too long, or contains unsupported characters
+*/
+function validateJobName(name) {
+	if (name.length === 0 || name.trim().length === 0) throw new InvalidJobIdentifierError("name", name, "Job name cannot be empty or whitespace only.");
+	if (name.length > MAX_JOB_NAME_LENGTH) throw new InvalidJobIdentifierError("name", name, `Job name cannot exceed ${MAX_JOB_NAME_LENGTH} characters.`);
+	if (!JOB_NAME_PATTERN.test(name)) throw new InvalidJobIdentifierError("name", name, "Job name cannot contain whitespace or control characters.");
+}
+/**
+* Validate a deduplication key before it is stored or used in a unique query.
+*
+* @param uniqueKey - The unique key to validate
+* @throws {InvalidJobIdentifierError} If the key is empty, too long, or contains control characters
+*/
+function validateUniqueKey(uniqueKey) {
+	if (uniqueKey.length === 0 || uniqueKey.trim().length === 0) throw new InvalidJobIdentifierError("uniqueKey", uniqueKey, "Unique key cannot be empty or whitespace only.");
+	if (uniqueKey.length > MAX_UNIQUE_KEY_LENGTH) throw new InvalidJobIdentifierError("uniqueKey", uniqueKey, `Unique key cannot exceed ${MAX_UNIQUE_KEY_LENGTH} characters.`);
+	if (CONTROL_CHARACTER_PATTERN.test(uniqueKey)) throw new InvalidJobIdentifierError("uniqueKey", uniqueKey, "Unique key cannot contain control characters.");
+}
+//#endregion
 //#region src/scheduler/helpers.ts
 /**
 * Build a MongoDB query filter from a JobSelector.
@@ -713,12 +765,20 @@ function decodeCursor(cursor) {
 }
 //#endregion
 //#region src/scheduler/services/change-stream-handler.ts
+/** 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.
 */
 var ChangeStreamHandler = class {
@@ -734,6 +794,12 @@ var ChangeStreamHandler = class {
 	reconnectTimer = null;
 	/** Whether the scheduler is currently using change streams */
 	usingChangeStreams = false;
+	/** Job names collected during the current debounce window for targeted polling */
+	pendingTargetNames = /* @__PURE__ */ new Set();
+	/** Wakeup timer for the earliest known future job */
+	wakeupTimer = null;
+	/** Time of the currently scheduled wakeup */
+	wakeupTime = null;
 	constructor(ctx, onPoll) {
 		this.ctx = ctx;
 		this.onPoll = onPoll;
@@ -758,7 +824,7 @@ var ChangeStreamHandler = class {
 		try {
 			this.changeStream = this.ctx.collection.watch([{ $match: { $or: [{ operationType: "insert" }, {
 				operationType: "update",
-				"updateDescription.updatedFields.status": { $exists: true }
+				$or: [{ "updateDescription.updatedFields.status": { $exists: true } }, { "updateDescription.updatedFields.nextRunAt": { $exists: true } }]
 			}] } }], { fullDocument: "updateLookup" });
 			this.changeStream.on("change", (change) => {
 				this.handleEvent(change);
@@ -777,11 +843,20 @@ var ChangeStreamHandler = class {
 		}
 	}
 	/**
-	* 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
 	*/
@@ -789,16 +864,81 @@ var ChangeStreamHandler = class {
 		if (!this.ctx.isRunning()) return;
 		const isInsert = change.operationType === "insert";
 		const isUpdate = change.operationType === "update";
-		const isPendingStatus = ("fullDocument" in change ? change.fullDocument : void 0)?.["status"] === JobStatus.PENDING;
-		if (isInsert || isUpdate && isPendingStatus) {
-			if (this.debounceTimer) clearTimeout(this.debounceTimer);
-			this.debounceTimer = setTimeout(() => {
-				this.debounceTimer = null;
-				this.onPoll().catch((error) => {
-					this.ctx.emit("job:error", { error: toError(error) });
-				});
-			}, 100);
+		const fullDocument = "fullDocument" in change ? change.fullDocument : void 0;
+		const currentStatus = fullDocument?.["status"];
+		const isPendingStatus = currentStatus === JobStatus.PENDING;
+		const isSlotFreed = isUpdate && (currentStatus === JobStatus.COMPLETED || currentStatus === JobStatus.FAILED);
+		if (!(isInsert || isUpdate && isPendingStatus || isSlotFreed)) return;
+		if (isSlotFreed) {
+			const jobName = fullDocument?.["name"];
+			if (jobName) this.pendingTargetNames.add(jobName);
+			this.debouncedPoll();
+			return;
+		}
+		const jobName = fullDocument?.["name"];
+		const nextRunAt = fullDocument?.["nextRunAt"];
+		if (jobName && nextRunAt) {
+			this.notifyPendingJob(jobName, nextRunAt);
+			return;
+		}
+		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, nextRunAt) {
+		if (!this.ctx.isRunning()) return;
+		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.
+	*/
+	debouncedPoll() {
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = null;
+			const names = this.pendingTargetNames.size > 0 ? new Set(this.pendingTargetNames) : void 0;
+			this.pendingTargetNames.clear();
+			this.onPoll(names).catch((error) => {
+				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
+	*/
+	scheduleWakeup(nextRunAt) {
+		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;
+			this.onPoll().catch((error) => {
+				this.ctx.emit("job:error", { error: toError(error) });
+			});
+		}, delay);
 	}
 	/**
 	* Handle change stream errors with exponential backoff reconnection.
@@ -812,10 +952,10 @@ var ChangeStreamHandler = class {
 	handleError(error) {
 		if (!this.ctx.isRunning()) return;
 		this.reconnectAttempts++;
+		this.resetActiveState();
+		this.closeChangeStream();
 		if (this.reconnectAttempts > this.maxReconnectAttempts) {
-			this.usingChangeStreams = false;
 			this.clearReconnectTimer();
-			this.closeChangeStream();
 			this.ctx.emit("changestream:fallback", { reason: `Exhausted ${this.maxReconnectAttempts} reconnection attempts: ${error.message}` });
 			return;
 		}
@@ -838,6 +978,29 @@ var ChangeStreamHandler = class {
 		clearTimeout(this.reconnectTimer);
 		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).
+	*/
+	resetActiveState() {
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+		this.pendingTargetNames.clear();
+		this.clearWakeupTimer();
+		this.usingChangeStreams = false;
+	}
+	clearWakeupTimer() {
+		if (this.wakeupTimer) {
+			clearTimeout(this.wakeupTimer);
+			this.wakeupTimer = null;
+		}
+		this.wakeupTime = null;
+	}
 	closeChangeStream() {
 		if (!this.changeStream) return;
 		this.changeStream.close().catch(() => {});
@@ -847,19 +1010,16 @@ var ChangeStreamHandler = class {
 	* Close the change stream cursor and emit closed event.
 	*/
 	async close() {
-		if (this.debounceTimer) {
-			clearTimeout(this.debounceTimer);
-			this.debounceTimer = null;
-		}
+		const wasActive = this.usingChangeStreams;
+		this.resetActiveState();
 		this.clearReconnectTimer();
 		if (this.changeStream) {
 			try {
 				await this.changeStream.close();
 			} catch {}
 			this.changeStream = null;
-			if (this.usingChangeStreams) this.ctx.emit("changestream:closed", void 0);
+			if (wasActive) this.ctx.emit("changestream:closed", void 0);
 		}
-		this.usingChangeStreams = false;
 		this.reconnectAttempts = 0;
 	}
 	/**
@@ -903,21 +1063,28 @@ var JobManager = class {
 	async cancelJob(jobId) {
 		if (!ObjectId.isValid(jobId)) return null;
 		const _id = new ObjectId(jobId);
-		const jobDoc = await this.ctx.collection.findOne({ _id });
-		if (!jobDoc) return null;
-		if (jobDoc["status"] === JobStatus.CANCELLED) return this.ctx.documentToPersistedJob(jobDoc);
-		if (jobDoc["status"] !== JobStatus.PENDING) throw new JobStateError(`Cannot cancel job in status '${jobDoc["status"]}'`, jobId, jobDoc["status"], "cancel");
-		const result = await this.ctx.collection.findOneAndUpdate({
-			_id,
-			status: JobStatus.PENDING
-		}, { $set: {
-			status: JobStatus.CANCELLED,
-			updatedAt: /* @__PURE__ */ new Date()
-		} }, { returnDocument: "after" });
-		if (!result) throw new JobStateError("Job status changed during cancellation attempt", jobId, "unknown", "cancel");
-		const job = this.ctx.documentToPersistedJob(result);
-		this.ctx.emit("job:cancelled", { job });
-		return job;
+		try {
+			const now = /* @__PURE__ */ new Date();
+			const result = await this.ctx.collection.findOneAndUpdate({
+				_id,
+				status: JobStatus.PENDING
+			}, { $set: {
+				status: JobStatus.CANCELLED,
+				updatedAt: now
+			} }, { returnDocument: "after" });
+			if (!result) {
+				const jobDoc = await this.ctx.collection.findOne({ _id });
+				if (!jobDoc) return null;
+				if (jobDoc["status"] === JobStatus.CANCELLED) return this.ctx.documentToPersistedJob(jobDoc);
+				throw new JobStateError(`Cannot cancel job in status '${jobDoc["status"]}'`, jobId, jobDoc["status"], "cancel");
+			}
+			const job = this.ctx.documentToPersistedJob(result);
+			this.ctx.emit("job:cancelled", { job });
+			return job;
+		} catch (error) {
+			if (error instanceof MonqueError) throw error;
+			throw new ConnectionError(`Failed to cancel job: ${error instanceof Error ? error.message : "Unknown error during cancelJob"}`, error instanceof Error ? { cause: error } : void 0);
+		}
 	}
 	/**
 	* Retry a failed or cancelled job.
@@ -940,35 +1107,51 @@ var JobManager = class {
 	async retryJob(jobId) {
 		if (!ObjectId.isValid(jobId)) return null;
 		const _id = new ObjectId(jobId);
-		const currentJob = await this.ctx.collection.findOne({ _id });
-		if (!currentJob) return null;
-		if (currentJob["status"] !== JobStatus.FAILED && currentJob["status"] !== JobStatus.CANCELLED) throw new JobStateError(`Cannot retry job in status '${currentJob["status"]}'`, jobId, currentJob["status"], "retry");
-		const previousStatus = currentJob["status"];
-		const result = await this.ctx.collection.findOneAndUpdate({
-			_id,
-			status: { $in: [JobStatus.FAILED, JobStatus.CANCELLED] }
-		}, {
-			$set: {
-				status: JobStatus.PENDING,
-				failCount: 0,
-				nextRunAt: /* @__PURE__ */ new Date(),
-				updatedAt: /* @__PURE__ */ new Date()
-			},
-			$unset: {
-				failReason: "",
-				lockedAt: "",
-				claimedBy: "",
-				lastHeartbeat: "",
-				heartbeatInterval: ""
+		try {
+			const now = /* @__PURE__ */ new Date();
+			const result = await this.ctx.collection.findOneAndUpdate({
+				_id,
+				status: { $in: [JobStatus.FAILED, JobStatus.CANCELLED] }
+			}, {
+				$set: {
+					status: JobStatus.PENDING,
+					failCount: 0,
+					nextRunAt: now,
+					updatedAt: now
+				},
+				$unset: {
+					failReason: "",
+					lockedAt: "",
+					claimedBy: "",
+					lastHeartbeat: ""
+				}
+			}, { returnDocument: "before" });
+			if (!result) {
+				const currentJob = await this.ctx.collection.findOne({ _id });
+				if (!currentJob) return null;
+				throw new JobStateError(`Cannot retry job in status '${currentJob["status"]}'`, jobId, currentJob["status"], "retry");
 			}
-		}, { returnDocument: "after" });
-		if (!result) throw new JobStateError("Job status changed during retry attempt", jobId, "unknown", "retry");
-		const job = this.ctx.documentToPersistedJob(result);
-		this.ctx.emit("job:retried", {
-			job,
-			previousStatus
-		});
-		return job;
+			const previousStatus = result["status"];
+			const updatedDoc = { ...result };
+			updatedDoc["status"] = JobStatus.PENDING;
+			updatedDoc["failCount"] = 0;
+			updatedDoc["nextRunAt"] = now;
+			updatedDoc["updatedAt"] = now;
+			delete updatedDoc["failReason"];
+			delete updatedDoc["lockedAt"];
+			delete updatedDoc["claimedBy"];
+			delete updatedDoc["lastHeartbeat"];
+			const job = this.ctx.documentToPersistedJob(updatedDoc);
+			this.ctx.notifyPendingJob(job.name, job.nextRunAt);
+			this.ctx.emit("job:retried", {
+				job,
+				previousStatus
+			});
+			return job;
+		} catch (error) {
+			if (error instanceof MonqueError) throw error;
+			throw new ConnectionError(`Failed to retry job: ${error instanceof Error ? error.message : "Unknown error during retryJob"}`, error instanceof Error ? { cause: error } : void 0);
+		}
 	}
 	/**
 	* Reschedule a pending job to run at a different time.
@@ -989,18 +1172,27 @@ var JobManager = class {
 	async rescheduleJob(jobId, runAt) {
 		if (!ObjectId.isValid(jobId)) return null;
 		const _id = new ObjectId(jobId);
-		const currentJobDoc = await this.ctx.collection.findOne({ _id });
-		if (!currentJobDoc) return null;
-		if (currentJobDoc["status"] !== JobStatus.PENDING) throw new JobStateError(`Cannot reschedule job in status '${currentJobDoc["status"]}'`, jobId, currentJobDoc["status"], "reschedule");
-		const result = await this.ctx.collection.findOneAndUpdate({
-			_id,
-			status: JobStatus.PENDING
-		}, { $set: {
-			nextRunAt: runAt,
-			updatedAt: /* @__PURE__ */ new Date()
-		} }, { returnDocument: "after" });
-		if (!result) throw new JobStateError("Job status changed during reschedule attempt", jobId, "unknown", "reschedule");
-		return this.ctx.documentToPersistedJob(result);
+		try {
+			const now = /* @__PURE__ */ new Date();
+			const result = await this.ctx.collection.findOneAndUpdate({
+				_id,
+				status: JobStatus.PENDING
+			}, { $set: {
+				nextRunAt: runAt,
+				updatedAt: now
+			} }, { returnDocument: "after" });
+			if (!result) {
+				const currentJobDoc = await this.ctx.collection.findOne({ _id });
+				if (!currentJobDoc) return null;
+				throw new JobStateError(`Cannot reschedule job in status '${currentJobDoc["status"]}'`, jobId, currentJobDoc["status"], "reschedule");
+			}
+			const job = this.ctx.documentToPersistedJob(result);
+			this.ctx.notifyPendingJob(job.name, job.nextRunAt);
+			return job;
+		} catch (error) {
+			if (error instanceof MonqueError) throw error;
+			throw new ConnectionError(`Failed to reschedule job: ${error instanceof Error ? error.message : "Unknown error during rescheduleJob"}`, error instanceof Error ? { cause: error } : void 0);
+		}
 	}
 	/**
 	* Permanently delete a job.
@@ -1022,11 +1214,16 @@ var JobManager = class {
 	async deleteJob(jobId) {
 		if (!ObjectId.isValid(jobId)) return false;
 		const _id = new ObjectId(jobId);
-		if ((await this.ctx.collection.deleteOne({ _id })).deletedCount > 0) {
-			this.ctx.emit("job:deleted", { jobId });
-			return true;
+		try {
+			if ((await this.ctx.collection.deleteOne({ _id })).deletedCount > 0) {
+				this.ctx.emit("job:deleted", { jobId });
+				return true;
+			}
+			return false;
+		} catch (error) {
+			if (error instanceof MonqueError) throw error;
+			throw new ConnectionError(`Failed to delete job: ${error instanceof Error ? error.message : "Unknown error during deleteJob"}`, error instanceof Error ? { cause: error } : void 0);
 		}
-		return false;
 	}
 	/**
 	* Cancel multiple jobs matching the given filter via a single updateMany call.
@@ -1058,9 +1255,10 @@ var JobManager = class {
 		}
 		query["status"] = JobStatus.PENDING;
 		try {
+			const now = /* @__PURE__ */ new Date();
 			const count = (await this.ctx.collection.updateMany(query, { $set: {
 				status: JobStatus.CANCELLED,
-				updatedAt: /* @__PURE__ */ new Date()
+				updatedAt: now
 			} })).modifiedCount;
 			if (count > 0) this.ctx.emit("jobs:cancelled", { count });
 			return {
@@ -1104,17 +1302,17 @@ var JobManager = class {
 		} else query["status"] = { $in: retryable };
 		const spreadWindowMs = 3e4;
 		try {
+			const now = /* @__PURE__ */ new Date();
 			const count = (await this.ctx.collection.updateMany(query, [{ $set: {
 				status: JobStatus.PENDING,
 				failCount: 0,
-				nextRunAt: { $add: [/* @__PURE__ */ new Date(), { $multiply: [{ $rand: {} }, spreadWindowMs] }] },
-				updatedAt: /* @__PURE__ */ new Date()
+				nextRunAt: { $add: [now, { $multiply: [{ $rand: {} }, spreadWindowMs] }] },
+				updatedAt: now
 			} }, { $unset: [
 				"failReason",
 				"lockedAt",
 				"claimedBy",
-				"lastHeartbeat",
-				"heartbeatInterval"
+				"lastHeartbeat"
 			] }])).modifiedCount;
 			if (count > 0) this.ctx.emit("jobs:retried", { count });
 			return {
@@ -1174,18 +1372,18 @@ var JobManager = class {
 var JobProcessor = class {
 	/** Guard flag to prevent concurrent poll() execution */
 	_isPolling = false;
-	constructor(ctx) {
-		this.ctx = ctx;
-	}
+	/** Flag to request a re-poll after the current poll finishes */
+	_repollRequested = false;
 	/**
-	* Get the total number of active jobs across all workers.
+	* O(1) counter tracking the total number of active jobs across all workers.
 	*
-	* Used for instance-level throttling when `instanceConcurrency` is configured.
+	* Incremented when a job is added to `worker.activeJobs` in `_doPoll`,
+	* decremented in the `processJob` finally block. Replaces the previous
+	* O(workers) loop in `getTotalActiveJobs()` for instance-level throttling.
 	*/
-	getTotalActiveJobs() {
-		let total = 0;
-		for (const worker of this.ctx.workers.values()) total += worker.activeJobs.size;
-		return total;
+	_totalActiveJobs = 0;
+	constructor(ctx) {
+		this.ctx = ctx;
 	}
 	/**
 	* Get the number of available slots considering the global instanceConcurrency limit.
@@ -1196,7 +1394,7 @@ var JobProcessor = class {
 	getGloballyAvailableSlots(workerAvailableSlots) {
 		const { instanceConcurrency } = this.ctx.options;
 		if (instanceConcurrency === void 0) return workerAvailableSlots;
-		const globalAvailable = instanceConcurrency - this.getTotalActiveJobs();
+		const globalAvailable = instanceConcurrency - this._totalActiveJobs;
 		return Math.min(workerAvailableSlots, globalAvailable);
 	}
 	/**
@@ -1206,12 +1404,27 @@ var JobProcessor = class {
 	* attempts to acquire jobs up to the worker's available concurrency slots.
 	* Aborts early if the scheduler is stopping (`isRunning` is false) or if
 	* the instance-level `instanceConcurrency` limit is reached.
+	*
+	* If a poll is requested while one is already running, it is queued and
+	* executed as a full poll after the current one finishes. This prevents
+	* change-stream-triggered polls from being silently dropped.
+	*
+	* @param targetNames - Optional set of worker names to poll. When provided, only the
+	* specified workers are checked. Used by change stream handler for targeted polling.
 	*/
-	async poll() {
-		if (!this.ctx.isRunning() || this._isPolling) return;
+	async poll(targetNames) {
+		if (!this.ctx.isRunning()) return;
+		if (this._isPolling) {
+			this._repollRequested = true;
+			return;
+		}
 		this._isPolling = true;
 		try {
-			await this._doPoll();
+			do {
+				this._repollRequested = false;
+				await this._doPoll(targetNames);
+				targetNames = void 0;
+			} while (this._repollRequested && this.ctx.isRunning());
 		} finally {
 			this._isPolling = false;
 		}
@@ -1219,28 +1432,51 @@ var JobProcessor = class {
 	/**
 	* Internal poll implementation.
 	*/
-	async _doPoll() {
+	async _doPoll(targetNames) {
 		const { instanceConcurrency } = this.ctx.options;
-		if (instanceConcurrency !== void 0 && this.getTotalActiveJobs() >= instanceConcurrency) return;
+		if (instanceConcurrency !== void 0 && this._totalActiveJobs >= instanceConcurrency) return;
 		for (const [name, worker] of this.ctx.workers) {
+			if (targetNames && !targetNames.has(name)) continue;
 			const workerAvailableSlots = worker.concurrency - worker.activeJobs.size;
 			if (workerAvailableSlots <= 0) continue;
 			const availableSlots = this.getGloballyAvailableSlots(workerAvailableSlots);
 			if (availableSlots <= 0) return;
-			for (let i = 0; i < availableSlots; i++) {
-				if (!this.ctx.isRunning()) return;
-				if (instanceConcurrency !== void 0 && this.getTotalActiveJobs() >= instanceConcurrency) return;
-				const job = await this.acquireJob(name);
-				if (job) {
+			if (!this.ctx.isRunning()) return;
+			const acquisitionPromises = [];
+			for (let i = 0; i < availableSlots; i++) acquisitionPromises.push(this.acquireJob(name).then(async (job) => {
+				if (!job) return;
+				if (this.ctx.isRunning()) {
 					worker.activeJobs.set(job._id.toString(), job);
+					this._totalActiveJobs++;
 					this.processJob(job, worker).catch((error) => {
 						this.ctx.emit("job:error", {
 							error: toError(error),
 							job
 						});
 					});
-				} else break;
-			}
+				} else try {
+					await this.ctx.collection.updateOne({
+						_id: job._id,
+						status: JobStatus.PROCESSING,
+						claimedBy: this.ctx.instanceId
+					}, {
+						$set: {
+							status: JobStatus.PENDING,
+							updatedAt: /* @__PURE__ */ new Date()
+						},
+						$unset: {
+							lockedAt: "",
+							claimedBy: "",
+							lastHeartbeat: ""
+						}
+					});
+				} catch (error) {
+					this.ctx.emit("job:error", { error: toError(error) });
+				}
+			}).catch((error) => {
+				this.ctx.emit("job:error", { error: toError(error) });
+			}));
+			await Promise.allSettled(acquisitionPromises);
 		}
 	}
 	/**
@@ -1276,7 +1512,6 @@ var JobProcessor = class {
 			sort: { nextRunAt: 1 },
 			returnDocument: "after"
 		});
-		if (!this.ctx.isRunning()) return null;
 		if (!result) return null;
 		return this.ctx.documentToPersistedJob(result);
 	}
@@ -1319,6 +1554,8 @@ var JobProcessor = class {
 			}
 		} finally {
 			worker.activeJobs.delete(jobId);
+			this._totalActiveJobs--;
+			this.ctx.notifyJobFinished();
 		}
 	}
 	/**
@@ -1338,6 +1575,7 @@ var JobProcessor = class {
 	*/
 	async completeJob(job) {
 		if (!isPersistedJob(job)) return null;
+		const now = /* @__PURE__ */ new Date();
 		if (job.repeatInterval) {
 			const nextRunAt = getNextCronDate(job.repeatInterval);
 			const result = await this.ctx.collection.findOneAndUpdate({
@@ -1349,17 +1587,19 @@ var JobProcessor = class {
 					status: JobStatus.PENDING,
 					nextRunAt,
 					failCount: 0,
-					updatedAt: /* @__PURE__ */ new Date()
+					updatedAt: now
 				},
 				$unset: {
 					lockedAt: "",
 					claimedBy: "",
 					lastHeartbeat: "",
-					heartbeatInterval: "",
 					failReason: ""
 				}
 			}, { returnDocument: "after" });
-			return result ? this.ctx.documentToPersistedJob(result) : null;
+			if (!result) return null;
+			const persistedJob = this.ctx.documentToPersistedJob(result);
+			this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
+			return persistedJob;
 		}
 		const result = await this.ctx.collection.findOneAndUpdate({
 			_id: job._id,
@@ -1368,17 +1608,17 @@ var JobProcessor = class {
 		}, {
 			$set: {
 				status: JobStatus.COMPLETED,
-				updatedAt: /* @__PURE__ */ new Date()
+				updatedAt: now
 			},
 			$unset: {
 				lockedAt: "",
 				claimedBy: "",
 				lastHeartbeat: "",
-				heartbeatInterval: "",
 				failReason: ""
 			}
 		}, { returnDocument: "after" });
-		return result ? this.ctx.documentToPersistedJob(result) : null;
+		if (!result) return null;
+		return this.ctx.documentToPersistedJob(result);
 	}
 	/**
 	* Handle job failure with exponential backoff retry logic using an atomic status transition.
@@ -1400,6 +1640,7 @@ var JobProcessor = class {
 	*/
 	async failJob(job, error) {
 		if (!isPersistedJob(job)) return null;
+		const now = /* @__PURE__ */ new Date();
 		const newFailCount = job.failCount + 1;
 		if (newFailCount >= this.ctx.options.maxRetries) {
 			const result = await this.ctx.collection.findOneAndUpdate({
@@ -1411,13 +1652,12 @@ var JobProcessor = class {
 					status: JobStatus.FAILED,
 					failCount: newFailCount,
 					failReason: error.message,
-					updatedAt: /* @__PURE__ */ new Date()
+					updatedAt: now
 				},
 				$unset: {
 					lockedAt: "",
 					claimedBy: "",
-					lastHeartbeat: "",
-					heartbeatInterval: ""
+					lastHeartbeat: ""
 				}
 			}, { returnDocument: "after" });
 			return result ? this.ctx.documentToPersistedJob(result) : null;
@@ -1433,13 +1673,12 @@ var JobProcessor = class {
 				failCount: newFailCount,
 				failReason: error.message,
 				nextRunAt,
-				updatedAt: /* @__PURE__ */ new Date()
+				updatedAt: now
 			},
 			$unset: {
 				lockedAt: "",
 				claimedBy: "",
-				lastHeartbeat: "",
-				heartbeatInterval: ""
+				lastHeartbeat: ""
 			}
 		}, { returnDocument: "after" });
 		return result ? this.ctx.documentToPersistedJob(result) : null;
@@ -1782,6 +2021,10 @@ var JobScheduler = class {
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
+	validateJobIdentifiers(name, uniqueKey) {
+		validateJobName(name);
+		if (uniqueKey !== void 0) validateUniqueKey(uniqueKey);
+	}
 	/**
 	* Validate that the job data payload does not exceed the configured maximum BSON byte size.
 	*
@@ -1819,6 +2062,7 @@ var JobScheduler = class {
 	* @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`
 	*
@@ -1848,6 +2092,7 @@ var JobScheduler = class {
 	* ```
 	*/
 	async enqueue(name, data, options = {}) {
+		this.validateJobIdentifiers(name, options.uniqueKey);
 		this.validatePayloadSize(data);
 		const now = /* @__PURE__ */ new Date();
 		const job = {
@@ -1859,9 +2104,9 @@ var JobScheduler = class {
 			createdAt: now,
 			updatedAt: now
 		};
-		if (options.uniqueKey) job.uniqueKey = options.uniqueKey;
+		if (options.uniqueKey !== void 0) job.uniqueKey = options.uniqueKey;
 		try {
-			if (options.uniqueKey) {
+			if (options.uniqueKey !== void 0) {
 				const result = await this.ctx.collection.findOneAndUpdate({
 					name,
 					uniqueKey: options.uniqueKey,
@@ -1871,13 +2116,17 @@ var JobScheduler = class {
 					returnDocument: "after"
 				});
 				if (!result) throw new ConnectionError("Failed to enqueue job: findOneAndUpdate returned no document");
-				return this.ctx.documentToPersistedJob(result);
+				const persistedJob = this.ctx.documentToPersistedJob(result);
+				if (persistedJob.status === JobStatus.PENDING) this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
+				return persistedJob;
 			}
 			const result = await this.ctx.collection.insertOne(job);
-			return {
+			const persistedJob = {
 				...job,
 				_id: result.insertedId
 			};
+			this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
+			return persistedJob;
 		} catch (error) {
 			if (error instanceof ConnectionError) throw error;
 			throw new ConnectionError(`Failed to enqueue job: ${error instanceof Error ? error.message : "Unknown error during enqueue"}`, error instanceof Error ? { cause: error } : void 0);
@@ -1932,6 +2181,7 @@ var JobScheduler = class {
 	* @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`
@@ -1960,6 +2210,7 @@ var JobScheduler = class {
 	* ```
 	*/
 	async schedule(cron, name, data, options = {}) {
+		this.validateJobIdentifiers(name, options.uniqueKey);
 		this.validatePayloadSize(data);
 		const nextRunAt = getNextCronDate(cron);
 		const now = /* @__PURE__ */ new Date();
@@ -1973,9 +2224,9 @@ var JobScheduler = class {
 			createdAt: now,
 			updatedAt: now
 		};
-		if (options.uniqueKey) job.uniqueKey = options.uniqueKey;
+		if (options.uniqueKey !== void 0) job.uniqueKey = options.uniqueKey;
 		try {
-			if (options.uniqueKey) {
+			if (options.uniqueKey !== void 0) {
 				const result = await this.ctx.collection.findOneAndUpdate({
 					name,
 					uniqueKey: options.uniqueKey,
@@ -1985,13 +2236,17 @@ var JobScheduler = class {
 					returnDocument: "after"
 				});
 				if (!result) throw new ConnectionError("Failed to schedule job: findOneAndUpdate returned no document");
-				return this.ctx.documentToPersistedJob(result);
+				const persistedJob = this.ctx.documentToPersistedJob(result);
+				if (persistedJob.status === JobStatus.PENDING) this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
+				return persistedJob;
 			}
 			const result = await this.ctx.collection.insertOne(job);
-			return {
+			const persistedJob = {
 				...job,
 				_id: result.insertedId
 			};
+			this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
+			return persistedJob;
 		} catch (error) {
 			if (error instanceof MonqueError) throw error;
 			throw new ConnectionError(`Failed to schedule job: ${error instanceof Error ? error.message : "Unknown error during schedule"}`, error instanceof Error ? { cause: error } : void 0);
@@ -2005,16 +2260,25 @@ var JobScheduler = class {
 */
 const DEFAULT_RETENTION_INTERVAL = 36e5;
 /**
+* Statuses that are eligible for cleanup by the retention policy.
+*/
+const CLEANUP_STATUSES = [JobStatus.COMPLETED, JobStatus.FAILED];
+/**
 * Manages scheduler lifecycle timers and job cleanup.
 *
-* Owns poll interval, heartbeat interval, cleanup interval, and the
+* Owns poll scheduling, heartbeat interval, cleanup interval, and the
 * cleanupJobs logic. Extracted from Monque to keep the facade thin.
 *
+* Uses adaptive poll scheduling: when change streams are active, polls at
+* `safetyPollInterval` (safety net only). When change streams are inactive,
+* polls at `pollInterval` (primary discovery mechanism).
+*
 * @internal Not part of public API.
 */
 var LifecycleManager = class {
 	ctx;
-	pollIntervalId = null;
+	callbacks = null;
+	pollTimeoutId = null;
 	heartbeatIntervalId = null;
 	cleanupIntervalId = null;
 	constructor(ctx) {
@@ -2023,17 +2287,13 @@ var LifecycleManager = class {
 	/**
 	* Start all lifecycle timers.
 	*
-	* Sets up poll interval, heartbeat interval, and (if configured)
+	* Sets up adaptive poll scheduling, heartbeat interval, and (if configured)
 	* cleanup interval. Runs an initial poll immediately.
 	*
 	* @param callbacks - Functions to invoke on each timer tick
 	*/
 	startTimers(callbacks) {
-		this.pollIntervalId = setInterval(() => {
-			callbacks.poll().catch((error) => {
-				this.ctx.emit("job:error", { error: toError(error) });
-			});
-		}, this.ctx.options.pollInterval);
+		this.callbacks = callbacks;
 		this.heartbeatIntervalId = setInterval(() => {
 			callbacks.updateHeartbeats().catch((error) => {
 				this.ctx.emit("job:error", { error: toError(error) });
@@ -2050,23 +2310,22 @@ var LifecycleManager = class {
 				});
 			}, interval);
 		}
-		callbacks.poll().catch((error) => {
-			this.ctx.emit("job:error", { error: toError(error) });
-		});
+		this.executePollAndScheduleNext();
 	}
 	/**
 	* Stop all lifecycle timers.
 	*
-	* Clears poll, heartbeat, and cleanup intervals.
+	* Clears poll timeout, heartbeat interval, and cleanup interval.
 	*/
 	stopTimers() {
+		this.callbacks = null;
 		if (this.cleanupIntervalId) {
 			clearInterval(this.cleanupIntervalId);
 			this.cleanupIntervalId = null;
 		}
-		if (this.pollIntervalId) {
-			clearInterval(this.pollIntervalId);
-			this.pollIntervalId = null;
+		if (this.pollTimeoutId) {
+			clearTimeout(this.pollTimeoutId);
+			this.pollTimeoutId = null;
 		}
 		if (this.heartbeatIntervalId) {
 			clearInterval(this.heartbeatIntervalId);
@@ -2074,6 +2333,43 @@ var LifecycleManager = class {
 		}
 	}
 	/**
+	* Reset the poll timer to reschedule the next poll.
+	*
+	* Called after change-stream-triggered polls to ensure the safety poll timer
+	* is recalculated (not fired redundantly from an old schedule).
+	*/
+	resetPollTimer() {
+		this.scheduleNextPoll();
+	}
+	/**
+	* Execute a poll and schedule the next one adaptively.
+	*/
+	executePollAndScheduleNext() {
+		if (!this.callbacks) return;
+		this.callbacks.poll().catch((error) => {
+			this.ctx.emit("job:error", { error: toError(error) });
+		}).finally(() => {
+			this.scheduleNextPoll();
+		});
+	}
+	/**
+	* Schedule the next poll using adaptive timing.
+	*
+	* When change streams are active, uses `safetyPollInterval` (longer, safety net only).
+	* When change streams are inactive, uses `pollInterval` (shorter, primary discovery).
+	*/
+	scheduleNextPoll() {
+		if (this.pollTimeoutId) {
+			clearTimeout(this.pollTimeoutId);
+			this.pollTimeoutId = null;
+		}
+		if (!this.ctx.isRunning() || !this.callbacks) return;
+		const delay = this.callbacks.isChangeStreamActive() ? this.ctx.options.safetyPollInterval : this.ctx.options.pollInterval;
+		this.pollTimeoutId = setTimeout(() => {
+			this.executePollAndScheduleNext();
+		}, delay);
+	}
+	/**
 	* Clean up old completed and failed jobs based on retention policy.
 	*
 	* - Removes completed jobs older than `jobRetention.completed`
@@ -2113,6 +2409,7 @@ var LifecycleManager = class {
 const DEFAULTS = {
 	collectionName: "monque_jobs",
 	pollInterval: 1e3,
+	safetyPollInterval: 3e4,
 	maxRetries: 10,
 	baseRetryInterval: 1e3,
 	shutdownTimeout: 3e4,
@@ -2193,6 +2490,14 @@ var Monque = class extends EventEmitter {
 	workers = /* @__PURE__ */ new Map();
 	isRunning = false;
 	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
+	*/
+	_drainResolve = null;
 	_scheduler = null;
 	_manager = null;
 	_query = null;
@@ -2201,10 +2506,12 @@ var Monque = class extends EventEmitter {
 	_lifecycleManager = null;
 	constructor(db, options = {}) {
 		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,
@@ -2220,6 +2527,8 @@ var Monque = class extends EventEmitter {
 			maxPayloadSize: options.maxPayloadSize,
 			statsCacheTtlMs: options.statsCacheTtlMs ?? 5e3
 		};
+		if (options.defaultConcurrency !== void 0) console.warn("[@monque/core] \"defaultConcurrency\" is deprecated and will be removed in a future major version. Use \"workerConcurrency\" instead.");
+		if (options.maxConcurrency !== void 0) console.warn("[@monque/core] \"maxConcurrency\" is deprecated and will be removed in a future major version. Use \"instanceConcurrency\" instead.");
 	}
 	/**
 	* Initialize the scheduler by setting up the MongoDB collection and indexes.
@@ -2239,7 +2548,7 @@ var Monque = class 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;
 		} catch (error) {
@@ -2276,6 +2585,21 @@ var Monque = class extends EventEmitter {
 		if (!this._lifecycleManager) throw new ConnectionError("Monque not initialized. Call initialize() first.");
 		return this._lifecycleManager;
 	}
+	validateSchedulingIdentifiers(name, uniqueKey) {
+		validateJobName(name);
+		if (uniqueKey !== void 0) 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.
+	*/
+	async handleChangeStreamPoll(targetNames) {
+		await this.processor.poll(targetNames);
+		this.lifecycleManager.resetPollTimer();
+	}
 	/**
 	* Build the shared context for internal services.
 	*/
@@ -2288,6 +2612,11 @@ var Monque = class extends EventEmitter {
 			workers: this.workers,
 			isRunning: () => this.isRunning,
 			emit: (event, payload) => this.emit(event, payload),
+			notifyPendingJob: (name, nextRunAt) => {
+				if (!this.isRunning || !this._changeStreamHandler) return;
+				this._changeStreamHandler.notifyPendingJob(name, nextRunAt);
+			},
+			notifyJobFinished: () => this.onJobFinished(),
 			documentToPersistedJob: (doc) => documentToPersistedJob(doc)
 		};
 	}
@@ -2361,7 +2690,18 @@ var Monque = class extends EventEmitter {
 					lastHeartbeat: 1
 				},
 				background: true
-			}
+			},
+			...this.options.jobRetention ? [{
+				key: {
+					status: 1,
+					updatedAt: 1
+				},
+				background: true,
+				partialFilterExpression: {
+					status: { $in: CLEANUP_STATUSES },
+					updatedAt: { $exists: true }
+				}
+			}] : []
 		]);
 	}
 	/**
@@ -2383,8 +2723,7 @@ var Monque = class extends EventEmitter {
 			$unset: {
 				lockedAt: "",
 				claimedBy: "",
-				lastHeartbeat: "",
-				heartbeatInterval: ""
+				lastHeartbeat: ""
 			}
 		});
 		if (result.modifiedCount > 0) this.emit("stale:recovered", { count: result.modifiedCount });
@@ -2425,6 +2764,7 @@ var Monque = class 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`
 	*
@@ -2457,6 +2797,7 @@ var Monque = class extends EventEmitter {
 	*/
 	async enqueue(name, data, options = {}) {
 		this.ensureInitialized();
+		this.validateSchedulingIdentifiers(name, options.uniqueKey);
 		return this.scheduler.enqueue(name, data, options);
 	}
 	/**
@@ -2469,6 +2810,7 @@ var Monque = class 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
@@ -2491,6 +2833,7 @@ var Monque = class extends EventEmitter {
 	*/
 	async now(name, data) {
 		this.ensureInitialized();
+		validateJobName(name);
 		return this.scheduler.now(name, data);
 	}
 	/**
@@ -2511,6 +2854,7 @@ var Monque = class 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`
@@ -2542,6 +2886,7 @@ var Monque = class extends EventEmitter {
 	*/
 	async schedule(cron, name, data, options = {}) {
 		this.ensureInitialized();
+		this.validateSchedulingIdentifiers(name, options.uniqueKey);
 		return this.scheduler.schedule(cron, name, data, options);
 	}
 	/**
@@ -2887,6 +3232,7 @@ var Monque = class 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
@@ -2930,6 +3276,7 @@ var Monque = class extends EventEmitter {
 	* ```
 	*/
 	register(name, handler, options = {}) {
+		validateJobName(name);
 		const concurrency = options.concurrency ?? this.options.workerConcurrency;
 		if (this.workers.has(name) && options.replace !== true) throw new WorkerRegistrationError(`Worker already registered for job name "${name}". Use { replace: true } to replace.`, name);
 		this.workers.set(name, {
@@ -2988,7 +3335,8 @@ var Monque = class extends EventEmitter {
 		this.changeStreamHandler.setup();
 		this.lifecycleManager.startTimers({
 			poll: () => this.processor.poll(),
-			updateHeartbeats: () => this.processor.updateHeartbeats()
+			updateHeartbeats: () => this.processor.updateHeartbeats(),
+			isChangeStreamActive: () => this.changeStreamHandler.isActive()
 		});
 	}
 	/**
@@ -3032,25 +3380,15 @@ var Monque = class extends EventEmitter {
 		try {
 			await this.changeStreamHandler.close();
 		} catch {}
-		if (this.getActiveJobs().length === 0) return;
-		let checkInterval;
+		if (this.getActiveJobCount() === 0) return;
 		const waitForJobs = new Promise((resolve) => {
-			checkInterval = setInterval(() => {
-				if (this.getActiveJobs().length === 0) {
-					clearInterval(checkInterval);
-					resolve(void 0);
-				}
-			}, 100);
+			this._drainResolve = () => resolve(void 0);
 		});
 		const timeout = new Promise((resolve) => {
 			setTimeout(() => resolve("timeout"), this.options.shutdownTimeout);
 		});
-		let result;
-		try {
-			result = await Promise.race([waitForJobs, timeout]);
-		} finally {
-			if (checkInterval) clearInterval(checkInterval);
-		}
+		const result = await Promise.race([waitForJobs, timeout]);
+		this._drainResolve = null;
 		if (result === "timeout") {
 			const incompleteJobs = this.getActiveJobsList();
 			const error = new ShutdownTimeoutError(`Shutdown timed out after ${this.options.shutdownTimeout}ms with ${incompleteJobs.length} incomplete jobs`, incompleteJobs);
@@ -3107,6 +3445,15 @@ var Monque = class extends EventEmitter {
 		return this.isRunning && this.isInitialized && this.collection !== null;
 	}
 	/**
+	* Called when a job finishes processing. If a shutdown drain is pending
+	* and no active jobs remain, resolves the drain promise.
+	*
+	* @private
+	*/
+	onJobFinished() {
+		if (this._drainResolve && this.getActiveJobCount() === 0) this._drainResolve();
+	}
+	/**
 	* Ensure the scheduler is initialized before operations.
 	*
 	* @private
@@ -3116,15 +3463,18 @@ var Monque = class extends EventEmitter {
 		if (!this.isInitialized || !this.collection) throw new ConnectionError("Monque not initialized. Call initialize() first.");
 	}
 	/**
-	* 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
 	*/
-	getActiveJobs() {
-		const activeJobs = [];
-		for (const worker of this.workers.values()) activeJobs.push(...worker.activeJobs.keys());
-		return activeJobs;
+	getActiveJobCount() {
+		let count = 0;
+		for (const worker of this.workers.values()) count += worker.activeJobs.size;
+		return count;
 	}
 	/**
 	* Get list of active job documents (for shutdown timeout error).
@@ -3154,6 +3504,6 @@ var Monque = class extends EventEmitter {
 	}
 };
 //#endregion
-export { AggregationTimeoutError, ConnectionError, CursorDirection, DEFAULT_BASE_INTERVAL, DEFAULT_MAX_BACKOFF_DELAY, InvalidCronError, InvalidCursorError, JobStateError, JobStatus, Monque, MonqueError, PayloadTooLargeError, ShutdownTimeoutError, WorkerRegistrationError, calculateBackoff, calculateBackoffDelay, getNextCronDate, isCancelledJob, isCompletedJob, isFailedJob, isPendingJob, isPersistedJob, isProcessingJob, isRecurringJob, isValidJobStatus, validateCronExpression };
+export { AggregationTimeoutError, ConnectionError, CursorDirection, DEFAULT_BASE_INTERVAL, DEFAULT_MAX_BACKOFF_DELAY, InvalidCronError, InvalidCursorError, InvalidJobIdentifierError, JobStateError, JobStatus, Monque, MonqueError, PayloadTooLargeError, ShutdownTimeoutError, WorkerRegistrationError, calculateBackoff, calculateBackoffDelay, getNextCronDate, isCancelledJob, isCompletedJob, isFailedJob, isPendingJob, isPersistedJob, isProcessingJob, isRecurringJob, isValidJobStatus, validateCronExpression, validateJobName, validateUniqueKey };
 
 //# sourceMappingURL=index.mjs.map