@monque/core 1.6.0 → 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.
@@ -1011,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.
@@ -1048,36 +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.notifyPendingJob(job.name, job.nextRunAt);
-		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.
@@ -1098,20 +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");
-		const job = this.ctx.documentToPersistedJob(result);
-		this.ctx.notifyPendingJob(job.name, job.nextRunAt);
-		return job;
+		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.
@@ -1133,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.
@@ -1169,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 {
@@ -1215,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 {
@@ -1287,18 +1374,16 @@ var JobProcessor = class {
 	_isPolling = false;
 	/** Flag to request a re-poll after the current poll finishes */
 	_repollRequested = false;
-	constructor(ctx) {
-		this.ctx = ctx;
-	}
 	/**
-	* 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.
@@ -1309,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);
 	}
 	/**
@@ -1349,27 +1434,49 @@ var JobProcessor = class {
 	*/
 	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);
 		}
 	}
 	/**
@@ -1405,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);
 	}
@@ -1448,6 +1554,8 @@ var JobProcessor = class {
 			}
 		} finally {
 			worker.activeJobs.delete(jobId);
+			this._totalActiveJobs--;
+			this.ctx.notifyJobFinished();
 		}
 	}
 	/**
@@ -1467,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({
@@ -1478,13 +1587,12 @@ var JobProcessor = class {
 					status: JobStatus.PENDING,
 					nextRunAt,
 					failCount: 0,
-					updatedAt: /* @__PURE__ */ new Date()
+					updatedAt: now
 				},
 				$unset: {
 					lockedAt: "",
 					claimedBy: "",
 					lastHeartbeat: "",
-					heartbeatInterval: "",
 					failReason: ""
 				}
 			}, { returnDocument: "after" });
@@ -1500,13 +1608,12 @@ var JobProcessor = class {
 		}, {
 			$set: {
 				status: JobStatus.COMPLETED,
-				updatedAt: /* @__PURE__ */ new Date()
+				updatedAt: now
 			},
 			$unset: {
 				lockedAt: "",
 				claimedBy: "",
 				lastHeartbeat: "",
-				heartbeatInterval: "",
 				failReason: ""
 			}
 		}, { returnDocument: "after" });
@@ -1533,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({
@@ -1544,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;
@@ -1566,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;
@@ -1915,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.
 	*
@@ -1952,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`
 	*
@@ -1981,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 = {
@@ -1992,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,
@@ -2069,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`
@@ -2097,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();
@@ -2110,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,
@@ -2146,6 +2260,10 @@ 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 scheduling, heartbeat interval, cleanup interval, and the
@@ -2230,7 +2348,7 @@ var LifecycleManager = class {
 		if (!this.callbacks) return;
 		this.callbacks.poll().catch((error) => {
 			this.ctx.emit("job:error", { error: toError(error) });
-		}).then(() => {
+		}).finally(() => {
 			this.scheduleNextPoll();
 		});
 	}
@@ -2372,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;
@@ -2380,6 +2506,7 @@ var Monque = class extends EventEmitter {
 	_lifecycleManager = null;
 	constructor(db, options = {}) {
 		super();
+		this.setMaxListeners(20);
 		this.db = db;
 		this.options = {
 			collectionName: options.collectionName ?? DEFAULTS.collectionName,
@@ -2400,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.
@@ -2456,6 +2585,10 @@ 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.
 	*
@@ -2483,6 +2616,7 @@ var Monque = class extends EventEmitter {
 				if (!this.isRunning || !this._changeStreamHandler) return;
 				this._changeStreamHandler.notifyPendingJob(name, nextRunAt);
 			},
+			notifyJobFinished: () => this.onJobFinished(),
 			documentToPersistedJob: (doc) => documentToPersistedJob(doc)
 		};
 	}
@@ -2556,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 }
+				}
+			}] : []
 		]);
 	}
 	/**
@@ -2578,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 });
@@ -2620,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`
 	*
@@ -2652,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);
 	}
 	/**
@@ -2664,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
@@ -2686,6 +2833,7 @@ var Monque = class extends EventEmitter {
 	*/
 	async now(name, data) {
 		this.ensureInitialized();
+		validateJobName(name);
 		return this.scheduler.now(name, data);
 	}
 	/**
@@ -2706,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`
@@ -2737,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);
 	}
 	/**
@@ -3082,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
@@ -3125,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, {
@@ -3228,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);
@@ -3303,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
@@ -3312,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).
@@ -3350,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