@monque/core 1.4.0 → 1.5.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { ObjectId } from "mongodb";
+import { BSON, ObjectId } from "mongodb";
 import { CronExpressionParser } from "cron-parser";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
@@ -479,6 +479,32 @@ var AggregationTimeoutError = class AggregationTimeoutError extends MonqueError
 		if (Error.captureStackTrace) Error.captureStackTrace(this, AggregationTimeoutError);
 	}
 };
+/**
+* Error thrown when a job payload exceeds the configured maximum BSON byte size.
+*
+* @example
+* ```typescript
+* const monque = new Monque(db, { maxPayloadSize: 1_000_000 }); // 1 MB
+*
+* try {
+*   await monque.enqueue('job', hugePayload);
+* } catch (error) {
+*   if (error instanceof PayloadTooLargeError) {
+*     console.error(`Payload ${error.actualSize} bytes exceeds limit ${error.maxSize} bytes`);
+*   }
+* }
+* ```
+*/
+var PayloadTooLargeError = class PayloadTooLargeError extends MonqueError {
+	constructor(message, actualSize, maxSize) {
+		super(message);
+		this.actualSize = actualSize;
+		this.maxSize = maxSize;
+		this.name = "PayloadTooLargeError";
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) Error.captureStackTrace(this, PayloadTooLargeError);
+	}
+};
 
 //#endregion
 //#region src/shared/utils/backoff.ts
@@ -1010,14 +1036,15 @@ var JobManager = class {
 		return false;
 	}
 	/**
-	* Cancel multiple jobs matching the given filter.
+	* Cancel multiple jobs matching the given filter via a single updateMany call.
 	*
-	* Only cancels jobs in 'pending' status. Jobs in other states are collected
-	* as errors in the result. Emits a 'jobs:cancelled' event with the IDs of
+	* Only cancels jobs in 'pending' status — the status guard is applied regardless
+	* of what the filter specifies. Jobs in other states are silently skipped (not
+	* matched by the query). Emits a 'jobs:cancelled' event with the count of
 	* successfully cancelled jobs.
 	*
 	* @param filter - Selector for which jobs to cancel (name, status, date range)
-	* @returns Result with count of cancelled jobs and any errors encountered
+	* @returns Result with count of cancelled jobs (errors array always empty for bulk ops)
 	*
 	* @example Cancel all pending jobs for a queue
 	* ```typescript
@@ -1029,53 +1056,39 @@ var JobManager = class {
 	* ```
 	*/
 	async cancelJobs(filter) {
-		const baseQuery = buildSelectorQuery(filter);
-		const errors = [];
-		const cancelledIds = [];
-		const cursor = this.ctx.collection.find(baseQuery);
-		for await (const doc of cursor) {
-			const jobId = doc._id.toString();
-			if (doc["status"] !== JobStatus.PENDING && doc["status"] !== JobStatus.CANCELLED) {
-				errors.push({
-					jobId,
-					error: `Cannot cancel job in status '${doc["status"]}'`
-				});
-				continue;
-			}
-			if (doc["status"] === JobStatus.CANCELLED) {
-				cancelledIds.push(jobId);
-				continue;
-			}
-			if (await this.ctx.collection.findOneAndUpdate({
-				_id: doc._id,
-				status: JobStatus.PENDING
-			}, { $set: {
+		const query = buildSelectorQuery(filter);
+		if (filter.status !== void 0) {
+			if (!(Array.isArray(filter.status) ? filter.status : [filter.status]).includes(JobStatus.PENDING)) return {
+				count: 0,
+				errors: []
+			};
+		}
+		query["status"] = JobStatus.PENDING;
+		try {
+			const count = (await this.ctx.collection.updateMany(query, { $set: {
 				status: JobStatus.CANCELLED,
 				updatedAt: /* @__PURE__ */ new Date()
-			} }, { returnDocument: "after" })) cancelledIds.push(jobId);
-			else errors.push({
-				jobId,
-				error: "Job status changed during cancellation"
-			});
+			} })).modifiedCount;
+			if (count > 0) this.ctx.emit("jobs:cancelled", { count });
+			return {
+				count,
+				errors: []
+			};
+		} catch (error) {
+			if (error instanceof MonqueError) throw error;
+			throw new ConnectionError(`Failed to cancel jobs: ${error instanceof Error ? error.message : "Unknown error during cancelJobs"}`, error instanceof Error ? { cause: error } : void 0);
 		}
-		if (cancelledIds.length > 0) this.ctx.emit("jobs:cancelled", {
-			jobIds: cancelledIds,
-			count: cancelledIds.length
-		});
-		return {
-			count: cancelledIds.length,
-			errors
-		};
 	}
 	/**
-	* Retry multiple jobs matching the given filter.
+	* Retry multiple jobs matching the given filter via a single pipeline-style updateMany call.
 	*
-	* Only retries jobs in 'failed' or 'cancelled' status. Jobs in other states
-	* are collected as errors in the result. Emits a 'jobs:retried' event with
-	* the IDs of successfully retried jobs.
+	* Only retries jobs in 'failed' or 'cancelled' status — the status guard is applied
+	* regardless of what the filter specifies. Jobs in other states are silently skipped.
+	* Uses `$rand` for per-document staggered `nextRunAt` to avoid thundering herd on retry.
+	* Emits a 'jobs:retried' event with the count of successfully retried jobs.
 	*
 	* @param filter - Selector for which jobs to retry (name, status, date range)
-	* @returns Result with count of retried jobs and any errors encountered
+	* @returns Result with count of retried jobs (errors array always empty for bulk ops)
 	*
 	* @example Retry all failed jobs
 	* ```typescript
@@ -1086,50 +1099,39 @@ var JobManager = class {
 	* ```
 	*/
 	async retryJobs(filter) {
-		const baseQuery = buildSelectorQuery(filter);
-		const errors = [];
-		const retriedIds = [];
-		const cursor = this.ctx.collection.find(baseQuery);
-		for await (const doc of cursor) {
-			const jobId = doc._id.toString();
-			if (doc["status"] !== JobStatus.FAILED && doc["status"] !== JobStatus.CANCELLED) {
-				errors.push({
-					jobId,
-					error: `Cannot retry job in status '${doc["status"]}'`
-				});
-				continue;
-			}
-			if (await this.ctx.collection.findOneAndUpdate({
-				_id: doc._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: ""
-				}
-			}, { returnDocument: "after" })) retriedIds.push(jobId);
-			else errors.push({
-				jobId,
-				error: "Job status changed during retry attempt"
-			});
+		const query = buildSelectorQuery(filter);
+		const retryable = [JobStatus.FAILED, JobStatus.CANCELLED];
+		if (filter.status !== void 0) {
+			const allowed = (Array.isArray(filter.status) ? filter.status : [filter.status]).filter((status) => status === JobStatus.FAILED || status === JobStatus.CANCELLED);
+			if (allowed.length === 0) return {
+				count: 0,
+				errors: []
+			};
+			query["status"] = allowed.length === 1 ? allowed[0] : { $in: allowed };
+		} else query["status"] = { $in: retryable };
+		const spreadWindowMs = 3e4;
+		try {
+			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()
+			} }, { $unset: [
+				"failReason",
+				"lockedAt",
+				"claimedBy",
+				"lastHeartbeat",
+				"heartbeatInterval"
+			] }])).modifiedCount;
+			if (count > 0) this.ctx.emit("jobs:retried", { count });
+			return {
+				count,
+				errors: []
+			};
+		} catch (error) {
+			if (error instanceof MonqueError) throw error;
+			throw new ConnectionError(`Failed to retry jobs: ${error instanceof Error ? error.message : "Unknown error during retryJobs"}`, error instanceof Error ? { cause: error } : void 0);
 		}
-		if (retriedIds.length > 0) this.ctx.emit("jobs:retried", {
-			jobIds: retriedIds,
-			count: retriedIds.length
-		});
-		return {
-			count: retriedIds.length,
-			errors
-		};
 	}
 	/**
 	* Delete multiple jobs matching the given filter.
@@ -1153,12 +1155,17 @@ var JobManager = class {
 	*/
 	async deleteJobs(filter) {
 		const query = buildSelectorQuery(filter);
-		const result = await this.ctx.collection.deleteMany(query);
-		if (result.deletedCount > 0) this.ctx.emit("jobs:deleted", { count: result.deletedCount });
-		return {
-			count: result.deletedCount,
-			errors: []
-		};
+		try {
+			const result = await this.ctx.collection.deleteMany(query);
+			if (result.deletedCount > 0) this.ctx.emit("jobs:deleted", { count: result.deletedCount });
+			return {
+				count: result.deletedCount,
+				errors: []
+			};
+		} catch (error) {
+			if (error instanceof MonqueError) throw error;
+			throw new ConnectionError(`Failed to delete jobs: ${error instanceof Error ? error.message : "Unknown error during deleteJobs"}`, error instanceof Error ? { cause: error } : void 0);
+		}
 	}
 };
 
@@ -1477,7 +1484,9 @@ var JobProcessor = class {
 *
 * @internal Not part of public API - use Monque class methods instead.
 */
-var JobQueryService = class {
+var JobQueryService = class JobQueryService {
+	statsCache = /* @__PURE__ */ new Map();
+	static MAX_CACHE_SIZE = 100;
 	constructor(ctx) {
 		this.ctx = ctx;
 	}
@@ -1656,11 +1665,22 @@ var JobQueryService = class {
 		};
 	}
 	/**
+	* Clear all cached getQueueStats() results.
+	* Called on scheduler stop() for clean state on restart.
+	* @internal
+	*/
+	clearStatsCache() {
+		this.statsCache.clear();
+	}
+	/**
 	* Get aggregate statistics for the job queue.
 	*
 	* Uses MongoDB aggregation pipeline for efficient server-side calculation.
 	* Returns counts per status and optional average processing duration for completed jobs.
 	*
+	* Results are cached per unique filter with a configurable TTL (default 5s).
+	* Set `statsCacheTtlMs: 0` to disable caching.
+	*
 	* @param filter - Optional filter to scope statistics by job name
 	* @returns Promise resolving to queue statistics
 	* @throws {AggregationTimeoutError} If aggregation exceeds 30 second timeout
@@ -1679,6 +1699,12 @@ var JobQueryService = class {
 	* ```
 	*/
 	async getQueueStats(filter) {
+		const ttl = this.ctx.options.statsCacheTtlMs;
+		const cacheKey = filter?.name ?? "";
+		if (ttl > 0) {
+			const cached = this.statsCache.get(cacheKey);
+			if (cached && cached.expiresAt > Date.now()) return { ...cached.data };
+		}
 		const matchStage = {};
 		if (filter?.name) matchStage["name"] = filter.name;
 		const pipeline = [...Object.keys(matchStage).length > 0 ? [{ $match: matchStage }] : [], { $facet: {
@@ -1702,35 +1728,47 @@ var JobQueryService = class {
 				cancelled: 0,
 				total: 0
 			};
-			if (!result) return stats;
-			const statusCounts = result["statusCounts"];
-			for (const entry of statusCounts) {
-				const status = entry._id;
-				const count = entry.count;
-				switch (status) {
-					case JobStatus.PENDING:
-						stats.pending = count;
-						break;
-					case JobStatus.PROCESSING:
-						stats.processing = count;
-						break;
-					case JobStatus.COMPLETED:
-						stats.completed = count;
-						break;
-					case JobStatus.FAILED:
-						stats.failed = count;
-						break;
-					case JobStatus.CANCELLED:
-						stats.cancelled = count;
-						break;
+			if (result) {
+				const statusCounts = result["statusCounts"];
+				for (const entry of statusCounts) {
+					const status = entry._id;
+					const count = entry.count;
+					switch (status) {
+						case JobStatus.PENDING:
+							stats.pending = count;
+							break;
+						case JobStatus.PROCESSING:
+							stats.processing = count;
+							break;
+						case JobStatus.COMPLETED:
+							stats.completed = count;
+							break;
+						case JobStatus.FAILED:
+							stats.failed = count;
+							break;
+						case JobStatus.CANCELLED:
+							stats.cancelled = count;
+							break;
+					}
+				}
+				const totalResult = result["total"];
+				if (totalResult.length > 0 && totalResult[0]) stats.total = totalResult[0].count;
+				const avgDurationResult = result["avgDuration"];
+				if (avgDurationResult.length > 0 && avgDurationResult[0]) {
+					const avgMs = avgDurationResult[0].avgMs;
+					if (typeof avgMs === "number" && !Number.isNaN(avgMs)) stats.avgProcessingDurationMs = Math.round(avgMs);
 				}
 			}
-			const totalResult = result["total"];
-			if (totalResult.length > 0 && totalResult[0]) stats.total = totalResult[0].count;
-			const avgDurationResult = result["avgDuration"];
-			if (avgDurationResult.length > 0 && avgDurationResult[0]) {
-				const avgMs = avgDurationResult[0].avgMs;
-				if (typeof avgMs === "number" && !Number.isNaN(avgMs)) stats.avgProcessingDurationMs = Math.round(avgMs);
+			if (ttl > 0) {
+				this.statsCache.delete(cacheKey);
+				if (this.statsCache.size >= JobQueryService.MAX_CACHE_SIZE) {
+					const oldestKey = this.statsCache.keys().next().value;
+					if (oldestKey !== void 0) this.statsCache.delete(oldestKey);
+				}
+				this.statsCache.set(cacheKey, {
+					data: { ...stats },
+					expiresAt: Date.now() + ttl
+				});
 			}
 			return stats;
 		} catch (error) {
@@ -1755,6 +1793,26 @@ var JobScheduler = class {
 		this.ctx = ctx;
 	}
 	/**
+	* Validate that the job data payload does not exceed the configured maximum BSON byte size.
+	*
+	* @param data - The job data payload to validate
+	* @throws {PayloadTooLargeError} If the payload exceeds `maxPayloadSize`
+	*/
+	validatePayloadSize(data) {
+		const maxSize = this.ctx.options.maxPayloadSize;
+		if (maxSize === void 0) return;
+		let size;
+		try {
+			size = BSON.calculateObjectSize({ data });
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			const sizeError = new PayloadTooLargeError(`Failed to calculate job payload size: ${cause.message}`, -1, maxSize);
+			sizeError.cause = cause;
+			throw sizeError;
+		}
+		if (size > maxSize) throw new PayloadTooLargeError(`Job payload exceeds maximum size: ${size} bytes > ${maxSize} bytes`, size, maxSize);
+	}
+	/**
 	* Enqueue a job for processing.
 	*
 	* Jobs are stored in MongoDB and processed by registered workers. Supports
@@ -1772,6 +1830,7 @@ var JobScheduler = class {
 	* @param options - Scheduling and deduplication options
 	* @returns Promise resolving to the created or existing job document
 	* @throws {ConnectionError} If database operation fails or scheduler not initialized
+	* @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
 	*
 	* @example Basic job enqueueing
 	* ```typescript
@@ -1799,6 +1858,7 @@ var JobScheduler = class {
 	* ```
 	*/
 	async enqueue(name, data, options = {}) {
+		this.validatePayloadSize(data);
 		const now = /* @__PURE__ */ new Date();
 		const job = {
 			name,
@@ -1884,6 +1944,7 @@ var JobScheduler = class {
 	* @returns Promise resolving to the created job document with `repeatInterval` set
 	* @throws {InvalidCronError} If cron expression is invalid
 	* @throws {ConnectionError} If database operation fails or scheduler not initialized
+	* @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
 	*
 	* @example Hourly cleanup job
 	* ```typescript
@@ -1909,6 +1970,7 @@ var JobScheduler = class {
 	* ```
 	*/
 	async schedule(cron, name, data, options = {}) {
+		this.validatePayloadSize(data);
 		const nextRunAt = getNextCronDate(cron);
 		const now = /* @__PURE__ */ new Date();
 		const job = {
@@ -1947,6 +2009,114 @@ var JobScheduler = class {
 	}
 };
 
+//#endregion
+//#region src/scheduler/services/lifecycle-manager.ts
+/**
+* Default retention check interval (1 hour).
+*/
+const DEFAULT_RETENTION_INTERVAL = 36e5;
+/**
+* Manages scheduler lifecycle timers and job cleanup.
+*
+* Owns poll interval, heartbeat interval, cleanup interval, and the
+* cleanupJobs logic. Extracted from Monque to keep the facade thin.
+*
+* @internal Not part of public API.
+*/
+var LifecycleManager = class {
+	ctx;
+	pollIntervalId = null;
+	heartbeatIntervalId = null;
+	cleanupIntervalId = null;
+	constructor(ctx) {
+		this.ctx = ctx;
+	}
+	/**
+	* Start all lifecycle timers.
+	*
+	* Sets up poll interval, 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.heartbeatIntervalId = setInterval(() => {
+			callbacks.updateHeartbeats().catch((error) => {
+				this.ctx.emit("job:error", { error: toError(error) });
+			});
+		}, this.ctx.options.heartbeatInterval);
+		if (this.ctx.options.jobRetention) {
+			const interval = this.ctx.options.jobRetention.interval ?? DEFAULT_RETENTION_INTERVAL;
+			this.cleanupJobs().catch((error) => {
+				this.ctx.emit("job:error", { error: toError(error) });
+			});
+			this.cleanupIntervalId = setInterval(() => {
+				this.cleanupJobs().catch((error) => {
+					this.ctx.emit("job:error", { error: toError(error) });
+				});
+			}, interval);
+		}
+		callbacks.poll().catch((error) => {
+			this.ctx.emit("job:error", { error: toError(error) });
+		});
+	}
+	/**
+	* Stop all lifecycle timers.
+	*
+	* Clears poll, heartbeat, and cleanup intervals.
+	*/
+	stopTimers() {
+		if (this.cleanupIntervalId) {
+			clearInterval(this.cleanupIntervalId);
+			this.cleanupIntervalId = null;
+		}
+		if (this.pollIntervalId) {
+			clearInterval(this.pollIntervalId);
+			this.pollIntervalId = null;
+		}
+		if (this.heartbeatIntervalId) {
+			clearInterval(this.heartbeatIntervalId);
+			this.heartbeatIntervalId = null;
+		}
+	}
+	/**
+	* Clean up old completed and failed jobs based on retention policy.
+	*
+	* - Removes completed jobs older than `jobRetention.completed`
+	* - Removes failed jobs older than `jobRetention.failed`
+	*
+	* The cleanup runs concurrently for both statuses if configured.
+	*
+	* @returns Promise resolving when all deletion operations complete
+	*/
+	async cleanupJobs() {
+		if (!this.ctx.options.jobRetention) return;
+		const { completed, failed } = this.ctx.options.jobRetention;
+		const now = Date.now();
+		const deletions = [];
+		if (completed != null) {
+			const cutoff = new Date(now - completed);
+			deletions.push(this.ctx.collection.deleteMany({
+				status: JobStatus.COMPLETED,
+				updatedAt: { $lt: cutoff }
+			}));
+		}
+		if (failed != null) {
+			const cutoff = new Date(now - failed);
+			deletions.push(this.ctx.collection.deleteMany({
+				status: JobStatus.FAILED,
+				updatedAt: { $lt: cutoff }
+			}));
+		}
+		if (deletions.length > 0) await Promise.all(deletions);
+	}
+};
+
 //#endregion
 //#region src/scheduler/monque.ts
 /**
@@ -2033,9 +2203,6 @@ var Monque = class extends EventEmitter {
 	options;
 	collection = null;
 	workers = /* @__PURE__ */ new Map();
-	pollIntervalId = null;
-	heartbeatIntervalId = null;
-	cleanupIntervalId = null;
 	isRunning = false;
 	isInitialized = false;
 	_scheduler = null;
@@ -2043,6 +2210,7 @@ var Monque = class extends EventEmitter {
 	_query = null;
 	_processor = null;
 	_changeStreamHandler = null;
+	_lifecycleManager = null;
 	constructor(db, options = {}) {
 		super();
 		this.db = db;
@@ -2060,7 +2228,9 @@ var Monque = class extends EventEmitter {
 			schedulerInstanceId: options.schedulerInstanceId ?? randomUUID(),
 			heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
 			jobRetention: options.jobRetention,
-			skipIndexCreation: options.skipIndexCreation ?? false
+			skipIndexCreation: options.skipIndexCreation ?? false,
+			maxPayloadSize: options.maxPayloadSize,
+			statsCacheTtlMs: options.statsCacheTtlMs ?? 5e3
 		};
 	}
 	/**
@@ -2075,12 +2245,14 @@ var Monque = class extends EventEmitter {
 			this.collection = this.db.collection(this.options.collectionName);
 			if (!this.options.skipIndexCreation) await this.createIndexes();
 			if (this.options.recoverStaleJobs) await this.recoverStaleJobs();
+			await this.checkInstanceCollision();
 			const ctx = this.buildContext();
 			this._scheduler = new JobScheduler(ctx);
 			this._manager = new JobManager(ctx);
 			this._query = new JobQueryService(ctx);
 			this._processor = new JobProcessor(ctx);
 			this._changeStreamHandler = new ChangeStreamHandler(ctx, () => this.processor.poll());
+			this._lifecycleManager = new LifecycleManager(ctx);
 			this.isInitialized = true;
 		} catch (error) {
 			throw new ConnectionError(`Failed to initialize Monque: ${error instanceof Error ? error.message : "Unknown error during initialization"}`);
@@ -2111,6 +2283,11 @@ var Monque = class extends EventEmitter {
 		if (!this._changeStreamHandler) throw new ConnectionError("Monque not initialized. Call initialize() first.");
 		return this._changeStreamHandler;
 	}
+	/** @throws {ConnectionError} if not initialized */
+	get lifecycleManager() {
+		if (!this._lifecycleManager) throw new ConnectionError("Monque not initialized. Call initialize() first.");
+		return this._lifecycleManager;
+	}
 	/**
 	* Build the shared context for internal services.
 	*/
@@ -2225,35 +2402,23 @@ var Monque = class extends EventEmitter {
 		if (result.modifiedCount > 0) this.emit("stale:recovered", { count: result.modifiedCount });
 	}
 	/**
-	* Clean up old completed and failed jobs based on retention policy.
+	* Check if another active instance is using the same schedulerInstanceId.
+	* Uses heartbeat staleness to distinguish active instances from crashed ones.
 	*
-	* - Removes completed jobs older than `jobRetention.completed`
-	* - Removes failed jobs older than `jobRetention.failed`
+	* Called after stale recovery to avoid false positives: stale recovery resets
+	* jobs with old `lockedAt`, so only jobs with recent heartbeats remain.
 	*
-	* The cleanup runs concurrently for both statuses if configured.
-	*
-	* @returns Promise resolving when all deletion operations complete
+	* @throws {ConnectionError} If an active instance with the same ID is detected
 	*/
-	async cleanupJobs() {
-		if (!this.collection || !this.options.jobRetention) return;
-		const { completed, failed } = this.options.jobRetention;
-		const now = Date.now();
-		const deletions = [];
-		if (completed) {
-			const cutoff = new Date(now - completed);
-			deletions.push(this.collection.deleteMany({
-				status: JobStatus.COMPLETED,
-				updatedAt: { $lt: cutoff }
-			}));
-		}
-		if (failed) {
-			const cutoff = new Date(now - failed);
-			deletions.push(this.collection.deleteMany({
-				status: JobStatus.FAILED,
-				updatedAt: { $lt: cutoff }
-			}));
-		}
-		if (deletions.length > 0) await Promise.all(deletions);
+	async checkInstanceCollision() {
+		if (!this.collection) return;
+		const aliveThreshold = /* @__PURE__ */ new Date(Date.now() - this.options.heartbeatInterval * 2);
+		const activeJob = await this.collection.findOne({
+			claimedBy: this.options.schedulerInstanceId,
+			status: JobStatus.PROCESSING,
+			lastHeartbeat: { $gte: aliveThreshold }
+		});
+		if (activeJob) throw new ConnectionError(`Another active Monque instance is using schedulerInstanceId "${this.options.schedulerInstanceId}". Found processing job "${activeJob["name"]}" with recent heartbeat. Use a unique schedulerInstanceId or wait for the other instance to stop.`);
 	}
 	/**
 	* Enqueue a job for processing.
@@ -2273,6 +2438,7 @@ var Monque = class extends EventEmitter {
 	* @param options - Scheduling and deduplication options
 	* @returns Promise resolving to the created or existing job document
 	* @throws {ConnectionError} If database operation fails or scheduler not initialized
+	* @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
 	*
 	* @example Basic job enqueueing
 	* ```typescript
@@ -2298,6 +2464,8 @@ var Monque = class extends EventEmitter {
 	* });
 	* // Subsequent enqueues with same uniqueKey return existing pending/processing job
 	* ```
+	*
+	* @see {@link JobScheduler.enqueue}
 	*/
 	async enqueue(name, data, options = {}) {
 		this.ensureInitialized();
@@ -2330,6 +2498,8 @@ var Monque = class extends EventEmitter {
 	* await monque.now('process-order', { orderId: order.id });
 	* return order; // Return immediately, processing happens async
 	* ```
+	*
+	* @see {@link JobScheduler.now}
 	*/
 	async now(name, data) {
 		this.ensureInitialized();
@@ -2355,6 +2525,7 @@ var Monque = class extends EventEmitter {
 	* @returns Promise resolving to the created job document with `repeatInterval` set
 	* @throws {InvalidCronError} If cron expression is invalid
 	* @throws {ConnectionError} If database operation fails or scheduler not initialized
+	* @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
 	*
 	* @example Hourly cleanup job
 	* ```typescript
@@ -2378,6 +2549,8 @@ var Monque = class extends EventEmitter {
 	*   recipients: ['analytics@example.com']
 	* });
 	* ```
+	*
+	* @see {@link JobScheduler.schedule}
 	*/
 	async schedule(cron, name, data, options = {}) {
 		this.ensureInitialized();
@@ -2399,6 +2572,8 @@ var Monque = class extends EventEmitter {
 	* const job = await monque.enqueue('report', { type: 'daily' });
 	* await monque.cancelJob(job._id.toString());
 	* ```
+	*
+	* @see {@link JobManager.cancelJob}
 	*/
 	async cancelJob(jobId) {
 		this.ensureInitialized();
@@ -2421,6 +2596,8 @@ var Monque = class extends EventEmitter {
 	*   await monque.retryJob(job._id.toString());
 	* });
 	* ```
+	*
+	* @see {@link JobManager.retryJob}
 	*/
 	async retryJob(jobId) {
 		this.ensureInitialized();
@@ -2441,6 +2618,8 @@ var Monque = class extends EventEmitter {
 	* const nextHour = new Date(Date.now() + 60 * 60 * 1000);
 	* await monque.rescheduleJob(jobId, nextHour);
 	* ```
+	*
+	* @see {@link JobManager.rescheduleJob}
 	*/
 	async rescheduleJob(jobId, runAt) {
 		this.ensureInitialized();
@@ -2462,20 +2641,23 @@ var Monque = class extends EventEmitter {
 	*   console.log('Job permanently removed');
 	* }
 	* ```
+	*
+	* @see {@link JobManager.deleteJob}
 	*/
 	async deleteJob(jobId) {
 		this.ensureInitialized();
 		return this.manager.deleteJob(jobId);
 	}
 	/**
-	* Cancel multiple jobs matching the given filter.
+	* Cancel multiple jobs matching the given filter via a single updateMany call.
 	*
-	* Only cancels jobs in 'pending' status. Jobs in other states are collected
-	* as errors in the result. Emits a 'jobs:cancelled' event with the IDs of
+	* Only cancels jobs in 'pending' status — the status guard is applied regardless
+	* of what the filter specifies. Jobs in other states are silently skipped (not
+	* matched by the query). Emits a 'jobs:cancelled' event with the count of
 	* successfully cancelled jobs.
 	*
 	* @param filter - Selector for which jobs to cancel (name, status, date range)
-	* @returns Result with count of cancelled jobs and any errors encountered
+	* @returns Result with count of cancelled jobs (errors array always empty for bulk ops)
 	*
 	* @example Cancel all pending jobs for a queue
 	* ```typescript
@@ -2485,20 +2667,23 @@ var Monque = class extends EventEmitter {
 	* });
 	* console.log(`Cancelled ${result.count} jobs`);
 	* ```
+	*
+	* @see {@link JobManager.cancelJobs}
 	*/
 	async cancelJobs(filter) {
 		this.ensureInitialized();
 		return this.manager.cancelJobs(filter);
 	}
 	/**
-	* Retry multiple jobs matching the given filter.
+	* Retry multiple jobs matching the given filter via a single pipeline-style updateMany call.
 	*
-	* Only retries jobs in 'failed' or 'cancelled' status. Jobs in other states
-	* are collected as errors in the result. Emits a 'jobs:retried' event with
-	* the IDs of successfully retried jobs.
+	* Only retries jobs in 'failed' or 'cancelled' status — the status guard is applied
+	* regardless of what the filter specifies. Jobs in other states are silently skipped.
+	* Uses `$rand` for per-document staggered `nextRunAt` to avoid thundering herd on retry.
+	* Emits a 'jobs:retried' event with the count of successfully retried jobs.
 	*
 	* @param filter - Selector for which jobs to retry (name, status, date range)
-	* @returns Result with count of retried jobs and any errors encountered
+	* @returns Result with count of retried jobs (errors array always empty for bulk ops)
 	*
 	* @example Retry all failed jobs
 	* ```typescript
@@ -2507,6 +2692,8 @@ var Monque = class extends EventEmitter {
 	* });
 	* console.log(`Retried ${result.count} jobs`);
 	* ```
+	*
+	* @see {@link JobManager.retryJobs}
 	*/
 	async retryJobs(filter) {
 		this.ensureInitialized();
@@ -2516,6 +2703,7 @@ var Monque = class extends EventEmitter {
 	* Delete multiple jobs matching the given filter.
 	*
 	* Deletes jobs in any status. Uses a batch delete for efficiency.
+	* Emits a 'jobs:deleted' event with the count of deleted jobs.
 	* Does not emit individual 'job:deleted' events to avoid noise.
 	*
 	* @param filter - Selector for which jobs to delete (name, status, date range)
@@ -2530,6 +2718,8 @@ var Monque = class extends EventEmitter {
 	* });
 	* console.log(`Deleted ${result.count} jobs`);
 	* ```
+	*
+	* @see {@link JobManager.deleteJobs}
 	*/
 	async deleteJobs(filter) {
 		this.ensureInitialized();
@@ -2565,6 +2755,8 @@ var Monque = class extends EventEmitter {
 	*   res.json(job);
 	* });
 	* ```
+	*
+	* @see {@link JobQueryService.getJob}
 	*/
 	async getJob(id) {
 		this.ensureInitialized();
@@ -2611,6 +2803,8 @@ var Monque = class extends EventEmitter {
 	* const jobs = await monque.getJobs();
 	* const pendingRecurring = jobs.filter(job => isPendingJob(job) && isRecurringJob(job));
 	* ```
+	*
+	* @see {@link JobQueryService.getJobs}
 	*/
 	async getJobs(filter = {}) {
 		this.ensureInitialized();
@@ -2644,6 +2838,8 @@ var Monque = class extends EventEmitter {
 	*   });
 	* }
 	* ```
+	*
+	* @see {@link JobQueryService.getJobsWithCursor}
 	*/
 	async getJobsWithCursor(options = {}) {
 		this.ensureInitialized();
@@ -2655,6 +2851,9 @@ var Monque = class extends EventEmitter {
 	* Uses MongoDB aggregation pipeline for efficient server-side calculation.
 	* Returns counts per status and optional average processing duration for completed jobs.
 	*
+	* Results are cached per unique filter with a configurable TTL (default 5s).
+	* Set `statsCacheTtlMs: 0` to disable caching.
+	*
 	* @param filter - Optional filter to scope statistics by job name
 	* @returns Promise resolving to queue statistics
 	* @throws {AggregationTimeoutError} If aggregation exceeds 30 second timeout
@@ -2671,6 +2870,8 @@ var Monque = class extends EventEmitter {
 	* const emailStats = await monque.getQueueStats({ name: 'send-email' });
 	* console.log(`${emailStats.total} email jobs in queue`);
 	* ```
+	*
+	* @see {@link JobQueryService.getQueueStats}
 	*/
 	async getQueueStats(filter) {
 		this.ensureInitialized();
@@ -2797,29 +2998,9 @@ var Monque = class extends EventEmitter {
 		if (!this.isInitialized) throw new ConnectionError("Monque not initialized. Call initialize() before start().");
 		this.isRunning = true;
 		this.changeStreamHandler.setup();
-		this.pollIntervalId = setInterval(() => {
-			this.processor.poll().catch((error) => {
-				this.emit("job:error", { error: toError(error) });
-			});
-		}, this.options.pollInterval);
-		this.heartbeatIntervalId = setInterval(() => {
-			this.processor.updateHeartbeats().catch((error) => {
-				this.emit("job:error", { error: toError(error) });
-			});
-		}, this.options.heartbeatInterval);
-		if (this.options.jobRetention) {
-			const interval = this.options.jobRetention.interval ?? DEFAULTS.retentionInterval;
-			this.cleanupJobs().catch((error) => {
-				this.emit("job:error", { error: toError(error) });
-			});
-			this.cleanupIntervalId = setInterval(() => {
-				this.cleanupJobs().catch((error) => {
-					this.emit("job:error", { error: toError(error) });
-				});
-			}, interval);
-		}
-		this.processor.poll().catch((error) => {
-			this.emit("job:error", { error: toError(error) });
+		this.lifecycleManager.startTimers({
+			poll: () => this.processor.poll(),
+			updateHeartbeats: () => this.processor.updateHeartbeats()
 		});
 	}
 	/**
@@ -2858,19 +3039,11 @@ var Monque = class extends EventEmitter {
 	async stop() {
 		if (!this.isRunning) return;
 		this.isRunning = false;
-		await this.changeStreamHandler.close();
-		if (this.cleanupIntervalId) {
-			clearInterval(this.cleanupIntervalId);
-			this.cleanupIntervalId = null;
-		}
-		if (this.pollIntervalId) {
-			clearInterval(this.pollIntervalId);
-			this.pollIntervalId = null;
-		}
-		if (this.heartbeatIntervalId) {
-			clearInterval(this.heartbeatIntervalId);
-			this.heartbeatIntervalId = null;
-		}
+		this._query?.clearStatsCache();
+		try {
+			await this.changeStreamHandler.close();
+		} catch {}
+		this.lifecycleManager.stopTimers();
 		if (this.getActiveJobs().length === 0) return;
 		let checkInterval;
 		const waitForJobs = new Promise((resolve) => {
@@ -2994,5 +3167,5 @@ var Monque = class extends EventEmitter {
 };
 
 //#endregion
-export { AggregationTimeoutError, ConnectionError, CursorDirection, DEFAULT_BASE_INTERVAL, DEFAULT_MAX_BACKOFF_DELAY, InvalidCronError, InvalidCursorError, JobStateError, JobStatus, Monque, MonqueError, 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, JobStateError, JobStatus, Monque, MonqueError, PayloadTooLargeError, ShutdownTimeoutError, WorkerRegistrationError, calculateBackoff, calculateBackoffDelay, getNextCronDate, isCancelledJob, isCompletedJob, isFailedJob, isPendingJob, isPersistedJob, isProcessingJob, isRecurringJob, isValidJobStatus, validateCronExpression };
 //# sourceMappingURL=index.mjs.map