@monque/core 1.3.0 → 1.5.0

package/dist/index.cjs

@@ -4,6 +4,40 @@ let cron_parser = require("cron-parser");
 let node_crypto = require("node:crypto");
 let node_events = require("node:events");
 
+//#region src/jobs/document-to-persisted-job.ts
+/**
+* Convert a raw MongoDB document to a strongly-typed {@link PersistedJob}.
+*
+* Maps required fields directly and conditionally includes optional fields
+* only when they are present in the document (`!== undefined`).
+*
+* @internal Not part of the public API.
+* @template T - The job data payload type
+* @param doc - The raw MongoDB document with `_id`
+* @returns A strongly-typed PersistedJob object with guaranteed `_id`
+*/
+function documentToPersistedJob(doc) {
+	const job = {
+		_id: doc._id,
+		name: doc["name"],
+		data: doc["data"],
+		status: doc["status"],
+		nextRunAt: doc["nextRunAt"],
+		failCount: doc["failCount"],
+		createdAt: doc["createdAt"],
+		updatedAt: doc["updatedAt"]
+	};
+	if (doc["lockedAt"] !== void 0) job.lockedAt = doc["lockedAt"];
+	if (doc["claimedBy"] !== void 0) job.claimedBy = doc["claimedBy"];
+	if (doc["lastHeartbeat"] !== void 0) job.lastHeartbeat = doc["lastHeartbeat"];
+	if (doc["heartbeatInterval"] !== void 0) job.heartbeatInterval = doc["heartbeatInterval"];
+	if (doc["failReason"] !== void 0) job.failReason = doc["failReason"];
+	if (doc["repeatInterval"] !== void 0) job.repeatInterval = doc["repeatInterval"];
+	if (doc["uniqueKey"] !== void 0) job.uniqueKey = doc["uniqueKey"];
+	return job;
+}
+
+//#endregion
 //#region src/jobs/types.ts
 /**
 * Represents the lifecycle states of a job in the queue.
@@ -446,6 +480,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
@@ -562,6 +622,39 @@ function handleCronParseError(expression, error) {
 	throw new InvalidCronError(expression, `Invalid cron expression "${expression}": ${error instanceof Error ? error.message : "Unknown parsing error"}. Expected 5-field format: "minute hour day-of-month month day-of-week" or predefined expression (e.g. @daily). Example: "0 9 * * 1" (every Monday at 9am)`);
 }
 
+//#endregion
+//#region src/shared/utils/error.ts
+/**
+* Normalize an unknown caught value into a proper `Error` instance.
+*
+* In JavaScript, any value can be thrown — strings, numbers, objects, `undefined`, etc.
+* This function ensures we always have a real `Error` with a proper stack trace and message.
+*
+* @param value - The caught value (typically from a `catch` block typed as `unknown`).
+* @returns The original value if already an `Error`, otherwise a new `Error` wrapping `String(value)`.
+*
+* @example
+* ```ts
+* try {
+*   riskyOperation();
+* } catch (error: unknown) {
+*   const normalized = toError(error);
+*   console.error(normalized.message);
+* }
+* ```
+*
+* @internal
+*/
+function toError(value) {
+	if (value instanceof Error) return value;
+	try {
+		return new Error(String(value));
+	} catch (conversionError) {
+		const detail = conversionError instanceof Error ? conversionError.message : "unknown conversion failure";
+		return /* @__PURE__ */ new Error(`Unserializable value (${detail})`);
+	}
+}
+
 //#endregion
 //#region src/scheduler/helpers.ts
 /**
@@ -711,7 +804,7 @@ var ChangeStreamHandler = class {
 			this.debounceTimer = setTimeout(() => {
 				this.debounceTimer = null;
 				this.onPoll().catch((error) => {
-					this.ctx.emit("job:error", { error });
+					this.ctx.emit("job:error", { error: toError(error) });
 				});
 			}, 100);
 		}
@@ -820,9 +913,8 @@ var JobManager = class {
 		const _id = new mongodb.ObjectId(jobId);
 		const jobDoc = await this.ctx.collection.findOne({ _id });
 		if (!jobDoc) return null;
-		const currentJob = jobDoc;
-		if (currentJob.status === JobStatus.CANCELLED) return this.ctx.documentToPersistedJob(currentJob);
-		if (currentJob.status !== JobStatus.PENDING) throw new JobStateError(`Cannot cancel job in status '${currentJob.status}'`, jobId, currentJob.status, "cancel");
+		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
@@ -907,8 +999,7 @@ var JobManager = class {
 		const _id = new mongodb.ObjectId(jobId);
 		const currentJobDoc = await this.ctx.collection.findOne({ _id });
 		if (!currentJobDoc) return null;
-		const currentJob = currentJobDoc;
-		if (currentJob.status !== JobStatus.PENDING) throw new JobStateError(`Cannot reschedule job in status '${currentJob.status}'`, jobId, currentJob.status, "reschedule");
+		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
@@ -946,14 +1037,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
@@ -965,54 +1057,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 job = doc;
-			const jobId = job._id.toString();
-			if (job.status !== JobStatus.PENDING && job.status !== JobStatus.CANCELLED) {
-				errors.push({
-					jobId,
-					error: `Cannot cancel job in status '${job.status}'`
-				});
-				continue;
-			}
-			if (job.status === JobStatus.CANCELLED) {
-				cancelledIds.push(jobId);
-				continue;
-			}
-			if (await this.ctx.collection.findOneAndUpdate({
-				_id: job._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
@@ -1023,51 +1100,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 job = doc;
-			const jobId = job._id.toString();
-			if (job.status !== JobStatus.FAILED && job.status !== JobStatus.CANCELLED) {
-				errors.push({
-					jobId,
-					error: `Cannot retry job in status '${job.status}'`
-				});
-				continue;
-			}
-			if (await this.ctx.collection.findOneAndUpdate({
-				_id: job._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.
@@ -1091,12 +1156,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);
+		}
 	}
 };
 
@@ -1174,7 +1244,7 @@ var JobProcessor = class {
 					worker.activeJobs.set(job._id.toString(), job);
 					this.processJob(job, worker).catch((error) => {
 						this.ctx.emit("job:error", {
-							error,
+							error: toError(error),
 							job
 						});
 					});
@@ -1226,6 +1296,10 @@ var JobProcessor = class {
 	* both success and failure cases. On success, calls `completeJob()`. On failure,
 	* calls `failJob()` which implements exponential backoff retry logic.
 	*
+	* Events are only emitted when the underlying atomic status transition succeeds,
+	* ensuring event consumers receive reliable, consistent data backed by the actual
+	* database state.
+	*
 	* @param job - The job to process
 	* @param worker - The worker registration containing the handler and active job tracking
 	*/
@@ -1236,38 +1310,50 @@ var JobProcessor = class {
 		try {
 			await worker.handler(job);
 			const duration = Date.now() - startTime;
-			await this.completeJob(job);
-			this.ctx.emit("job:complete", {
-				job,
+			const updatedJob = await this.completeJob(job);
+			if (updatedJob) this.ctx.emit("job:complete", {
+				job: updatedJob,
 				duration
 			});
 		} catch (error) {
 			const err = error instanceof Error ? error : new Error(String(error));
-			await this.failJob(job, err);
-			const willRetry = job.failCount + 1 < this.ctx.options.maxRetries;
-			this.ctx.emit("job:fail", {
-				job,
-				error: err,
-				willRetry
-			});
+			const updatedJob = await this.failJob(job, err);
+			if (updatedJob) {
+				const willRetry = updatedJob.status === JobStatus.PENDING;
+				this.ctx.emit("job:fail", {
+					job: updatedJob,
+					error: err,
+					willRetry
+				});
+			}
 		} finally {
 			worker.activeJobs.delete(jobId);
 		}
 	}
 	/**
-	* Mark a job as completed successfully.
+	* Mark a job as completed successfully using an atomic status transition.
+	*
+	* Uses `findOneAndUpdate` with `status: processing` and `claimedBy: instanceId`
+	* preconditions to ensure the transition only occurs if the job is still owned by this
+	* scheduler instance. Returns `null` if the job was concurrently modified (e.g., reclaimed
+	* by another instance after stale recovery).
 	*
 	* For recurring jobs (with `repeatInterval`), schedules the next run based on the cron
 	* expression and resets `failCount` to 0. For one-time jobs, sets status to `completed`.
 	* Clears `lockedAt` and `failReason` fields in both cases.
 	*
 	* @param job - The job that completed successfully
+	* @returns The updated job document, or `null` if the transition could not be applied
 	*/
 	async completeJob(job) {
-		if (!isPersistedJob(job)) return;
+		if (!isPersistedJob(job)) return null;
 		if (job.repeatInterval) {
 			const nextRunAt = getNextCronDate(job.repeatInterval);
-			await this.ctx.collection.updateOne({ _id: job._id }, {
+			const result = await this.ctx.collection.findOneAndUpdate({
+				_id: job._id,
+				status: JobStatus.PROCESSING,
+				claimedBy: this.ctx.instanceId
+			}, {
 				$set: {
 					status: JobStatus.PENDING,
 					nextRunAt,
@@ -1281,61 +1367,59 @@ var JobProcessor = class {
 					heartbeatInterval: "",
 					failReason: ""
 				}
-			});
-		} else {
-			await this.ctx.collection.updateOne({ _id: job._id }, {
-				$set: {
-					status: JobStatus.COMPLETED,
-					updatedAt: /* @__PURE__ */ new Date()
-				},
-				$unset: {
-					lockedAt: "",
-					claimedBy: "",
-					lastHeartbeat: "",
-					heartbeatInterval: "",
-					failReason: ""
-				}
-			});
-			job.status = JobStatus.COMPLETED;
+			}, { returnDocument: "after" });
+			return result ? this.ctx.documentToPersistedJob(result) : null;
 		}
+		const result = await this.ctx.collection.findOneAndUpdate({
+			_id: job._id,
+			status: JobStatus.PROCESSING,
+			claimedBy: this.ctx.instanceId
+		}, {
+			$set: {
+				status: JobStatus.COMPLETED,
+				updatedAt: /* @__PURE__ */ new Date()
+			},
+			$unset: {
+				lockedAt: "",
+				claimedBy: "",
+				lastHeartbeat: "",
+				heartbeatInterval: "",
+				failReason: ""
+			}
+		}, { returnDocument: "after" });
+		return result ? this.ctx.documentToPersistedJob(result) : null;
 	}
 	/**
-	* Handle job failure with exponential backoff retry logic.
+	* Handle job failure with exponential backoff retry logic using an atomic status transition.
+	*
+	* Uses `findOneAndUpdate` with `status: processing` and `claimedBy: instanceId`
+	* preconditions to ensure the transition only occurs if the job is still owned by this
+	* scheduler instance. Returns `null` if the job was concurrently modified (e.g., reclaimed
+	* by another instance after stale recovery).
 	*
 	* Increments `failCount` and calculates next retry time using exponential backoff:
-	* `nextRunAt = 2^failCount × baseRetryInterval` (capped by optional `maxBackoffDelay`).
+	* `nextRunAt = 2^failCount * baseRetryInterval` (capped by optional `maxBackoffDelay`).
 	*
 	* If `failCount >= maxRetries`, marks job as permanently `failed`. Otherwise, resets
 	* to `pending` status for retry. Stores error message in `failReason` field.
 	*
 	* @param job - The job that failed
 	* @param error - The error that caused the failure
+	* @returns The updated job document, or `null` if the transition could not be applied
 	*/
 	async failJob(job, error) {
-		if (!isPersistedJob(job)) return;
+		if (!isPersistedJob(job)) return null;
 		const newFailCount = job.failCount + 1;
-		if (newFailCount >= this.ctx.options.maxRetries) await this.ctx.collection.updateOne({ _id: job._id }, {
-			$set: {
-				status: JobStatus.FAILED,
-				failCount: newFailCount,
-				failReason: error.message,
-				updatedAt: /* @__PURE__ */ new Date()
-			},
-			$unset: {
-				lockedAt: "",
-				claimedBy: "",
-				lastHeartbeat: "",
-				heartbeatInterval: ""
-			}
-		});
-		else {
-			const nextRunAt = calculateBackoff(newFailCount, this.ctx.options.baseRetryInterval, this.ctx.options.maxBackoffDelay);
-			await this.ctx.collection.updateOne({ _id: job._id }, {
+		if (newFailCount >= this.ctx.options.maxRetries) {
+			const result = await this.ctx.collection.findOneAndUpdate({
+				_id: job._id,
+				status: JobStatus.PROCESSING,
+				claimedBy: this.ctx.instanceId
+			}, {
 				$set: {
-					status: JobStatus.PENDING,
+					status: JobStatus.FAILED,
 					failCount: newFailCount,
 					failReason: error.message,
-					nextRunAt,
 					updatedAt: /* @__PURE__ */ new Date()
 				},
 				$unset: {
@@ -1344,8 +1428,30 @@ var JobProcessor = class {
 					lastHeartbeat: "",
 					heartbeatInterval: ""
 				}
-			});
+			}, { returnDocument: "after" });
+			return result ? this.ctx.documentToPersistedJob(result) : null;
 		}
+		const nextRunAt = calculateBackoff(newFailCount, this.ctx.options.baseRetryInterval, this.ctx.options.maxBackoffDelay);
+		const result = await this.ctx.collection.findOneAndUpdate({
+			_id: job._id,
+			status: JobStatus.PROCESSING,
+			claimedBy: this.ctx.instanceId
+		}, {
+			$set: {
+				status: JobStatus.PENDING,
+				failCount: newFailCount,
+				failReason: error.message,
+				nextRunAt,
+				updatedAt: /* @__PURE__ */ new Date()
+			},
+			$unset: {
+				lockedAt: "",
+				claimedBy: "",
+				lastHeartbeat: "",
+				heartbeatInterval: ""
+			}
+		}, { returnDocument: "after" });
+		return result ? this.ctx.documentToPersistedJob(result) : null;
 	}
 	/**
 	* Update heartbeats for all jobs claimed by this scheduler instance.
@@ -1379,7 +1485,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;
 	}
@@ -1558,11 +1666,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
@@ -1581,6 +1700,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: {
@@ -1604,35 +1729,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) {
@@ -1657,6 +1794,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 = mongodb.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
@@ -1674,6 +1831,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
@@ -1701,6 +1859,7 @@ var JobScheduler = class {
 	* ```
 	*/
 	async enqueue(name, data, options = {}) {
+		this.validatePayloadSize(data);
 		const now = /* @__PURE__ */ new Date();
 		const job = {
 			name,
@@ -1786,6 +1945,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
@@ -1811,6 +1971,7 @@ var JobScheduler = class {
 	* ```
 	*/
 	async schedule(cron, name, data, options = {}) {
+		this.validatePayloadSize(data);
 		const nextRunAt = getNextCronDate(cron);
 		const now = /* @__PURE__ */ new Date();
 		const job = {
@@ -1849,6 +2010,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
 /**
@@ -1935,9 +2204,6 @@ var Monque = class extends node_events.EventEmitter {
 	options;
 	collection = null;
 	workers = /* @__PURE__ */ new Map();
-	pollIntervalId = null;
-	heartbeatIntervalId = null;
-	cleanupIntervalId = null;
 	isRunning = false;
 	isInitialized = false;
 	_scheduler = null;
@@ -1945,6 +2211,7 @@ var Monque = class extends node_events.EventEmitter {
 	_query = null;
 	_processor = null;
 	_changeStreamHandler = null;
+	_lifecycleManager = null;
 	constructor(db, options = {}) {
 		super();
 		this.db = db;
@@ -1961,7 +2228,10 @@ var Monque = class extends node_events.EventEmitter {
 			instanceConcurrency: options.instanceConcurrency ?? options.maxConcurrency,
 			schedulerInstanceId: options.schedulerInstanceId ?? (0, node_crypto.randomUUID)(),
 			heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
-			jobRetention: options.jobRetention
+			jobRetention: options.jobRetention,
+			skipIndexCreation: options.skipIndexCreation ?? false,
+			maxPayloadSize: options.maxPayloadSize,
+			statsCacheTtlMs: options.statsCacheTtlMs ?? 5e3
 		};
 	}
 	/**
@@ -1974,14 +2244,16 @@ var Monque = class extends node_events.EventEmitter {
 		if (this.isInitialized) return;
 		try {
 			this.collection = this.db.collection(this.options.collectionName);
-			await this.createIndexes();
+			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"}`);
@@ -2012,6 +2284,11 @@ var Monque = class extends node_events.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.
 	*/
@@ -2024,7 +2301,7 @@ var Monque = class extends node_events.EventEmitter {
 			workers: this.workers,
 			isRunning: () => this.isRunning,
 			emit: (event, payload) => this.emit(event, payload),
-			documentToPersistedJob: (doc) => this.documentToPersistedJob(doc)
+			documentToPersistedJob: (doc) => documentToPersistedJob(doc)
 		};
 	}
 	/**
@@ -2041,43 +2318,64 @@ var Monque = class extends node_events.EventEmitter {
 	*/
 	async createIndexes() {
 		if (!this.collection) throw new ConnectionError("Collection not initialized");
-		await this.collection.createIndex({
-			status: 1,
-			nextRunAt: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			name: 1,
-			uniqueKey: 1
-		}, {
-			unique: true,
-			partialFilterExpression: {
-				uniqueKey: { $exists: true },
-				status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] }
+		await this.collection.createIndexes([
+			{
+				key: {
+					status: 1,
+					nextRunAt: 1
+				},
+				background: true
 			},
-			background: true
-		});
-		await this.collection.createIndex({
-			name: 1,
-			status: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			claimedBy: 1,
-			status: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			lastHeartbeat: 1,
-			status: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			status: 1,
-			nextRunAt: 1,
-			claimedBy: 1
-		}, { background: true });
-		await this.collection.createIndex({
-			status: 1,
-			lockedAt: 1,
-			lastHeartbeat: 1
-		}, { background: true });
+			{
+				key: {
+					name: 1,
+					uniqueKey: 1
+				},
+				unique: true,
+				partialFilterExpression: {
+					uniqueKey: { $exists: true },
+					status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] }
+				},
+				background: true
+			},
+			{
+				key: {
+					name: 1,
+					status: 1
+				},
+				background: true
+			},
+			{
+				key: {
+					claimedBy: 1,
+					status: 1
+				},
+				background: true
+			},
+			{
+				key: {
+					lastHeartbeat: 1,
+					status: 1
+				},
+				background: true
+			},
+			{
+				key: {
+					status: 1,
+					nextRunAt: 1,
+					claimedBy: 1
+				},
+				background: true
+			},
+			{
+				key: {
+					status: 1,
+					lockedAt: 1,
+					lastHeartbeat: 1
+				},
+				background: true
+			}
+		]);
 	}
 	/**
 	* Recover stale jobs that were left in 'processing' status.
@@ -2105,35 +2403,23 @@ var Monque = class extends node_events.EventEmitter {
 		if (result.modifiedCount > 0) this.emit("stale:recovered", { count: result.modifiedCount });
 	}
 	/**
-	* 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`
+	* Check if another active instance is using the same schedulerInstanceId.
+	* Uses heartbeat staleness to distinguish active instances from crashed ones.
 	*
-	* The cleanup runs concurrently for both statuses if configured.
+	* Called after stale recovery to avoid false positives: stale recovery resets
+	* jobs with old `lockedAt`, so only jobs with recent heartbeats remain.
 	*
-	* @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.
@@ -2153,6 +2439,7 @@ var Monque = class extends node_events.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
@@ -2178,6 +2465,8 @@ var Monque = class extends node_events.EventEmitter {
 	* });
 	* // Subsequent enqueues with same uniqueKey return existing pending/processing job
 	* ```
+	*
+	* @see {@link JobScheduler.enqueue}
 	*/
 	async enqueue(name, data, options = {}) {
 		this.ensureInitialized();
@@ -2210,6 +2499,8 @@ var Monque = class extends node_events.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();
@@ -2235,6 +2526,7 @@ var Monque = class extends node_events.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
@@ -2258,6 +2550,8 @@ var Monque = class extends node_events.EventEmitter {
 	*   recipients: ['analytics@example.com']
 	* });
 	* ```
+	*
+	* @see {@link JobScheduler.schedule}
 	*/
 	async schedule(cron, name, data, options = {}) {
 		this.ensureInitialized();
@@ -2279,6 +2573,8 @@ var Monque = class extends node_events.EventEmitter {
 	* const job = await monque.enqueue('report', { type: 'daily' });
 	* await monque.cancelJob(job._id.toString());
 	* ```
+	*
+	* @see {@link JobManager.cancelJob}
 	*/
 	async cancelJob(jobId) {
 		this.ensureInitialized();
@@ -2301,6 +2597,8 @@ var Monque = class extends node_events.EventEmitter {
 	*   await monque.retryJob(job._id.toString());
 	* });
 	* ```
+	*
+	* @see {@link JobManager.retryJob}
 	*/
 	async retryJob(jobId) {
 		this.ensureInitialized();
@@ -2321,6 +2619,8 @@ var Monque = class extends node_events.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();
@@ -2342,20 +2642,23 @@ var Monque = class extends node_events.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
@@ -2365,20 +2668,23 @@ var Monque = class extends node_events.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
@@ -2387,6 +2693,8 @@ var Monque = class extends node_events.EventEmitter {
 	* });
 	* console.log(`Retried ${result.count} jobs`);
 	* ```
+	*
+	* @see {@link JobManager.retryJobs}
 	*/
 	async retryJobs(filter) {
 		this.ensureInitialized();
@@ -2396,6 +2704,7 @@ var Monque = class extends node_events.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)
@@ -2410,6 +2719,8 @@ var Monque = class extends node_events.EventEmitter {
 	* });
 	* console.log(`Deleted ${result.count} jobs`);
 	* ```
+	*
+	* @see {@link JobManager.deleteJobs}
 	*/
 	async deleteJobs(filter) {
 		this.ensureInitialized();
@@ -2445,6 +2756,8 @@ var Monque = class extends node_events.EventEmitter {
 	*   res.json(job);
 	* });
 	* ```
+	*
+	* @see {@link JobQueryService.getJob}
 	*/
 	async getJob(id) {
 		this.ensureInitialized();
@@ -2491,6 +2804,8 @@ var Monque = class extends node_events.EventEmitter {
 	* const jobs = await monque.getJobs();
 	* const pendingRecurring = jobs.filter(job => isPendingJob(job) && isRecurringJob(job));
 	* ```
+	*
+	* @see {@link JobQueryService.getJobs}
 	*/
 	async getJobs(filter = {}) {
 		this.ensureInitialized();
@@ -2524,6 +2839,8 @@ var Monque = class extends node_events.EventEmitter {
 	*   });
 	* }
 	* ```
+	*
+	* @see {@link JobQueryService.getJobsWithCursor}
 	*/
 	async getJobsWithCursor(options = {}) {
 		this.ensureInitialized();
@@ -2535,6 +2852,9 @@ var Monque = class extends node_events.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
@@ -2551,6 +2871,8 @@ var Monque = class extends node_events.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();
@@ -2677,29 +2999,9 @@ var Monque = class extends node_events.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 });
-			});
-		}, this.options.pollInterval);
-		this.heartbeatIntervalId = setInterval(() => {
-			this.processor.updateHeartbeats().catch((error) => {
-				this.emit("job:error", { 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 });
-			});
-			this.cleanupIntervalId = setInterval(() => {
-				this.cleanupJobs().catch((error) => {
-					this.emit("job:error", { error });
-				});
-			}, interval);
-		}
-		this.processor.poll().catch((error) => {
-			this.emit("job:error", { error });
+		this.lifecycleManager.startTimers({
+			poll: () => this.processor.poll(),
+			updateHeartbeats: () => this.processor.updateHeartbeats()
 		});
 	}
 	/**
@@ -2738,19 +3040,11 @@ var Monque = class extends node_events.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) => {
@@ -2857,37 +3151,6 @@ var Monque = class extends node_events.EventEmitter {
 		return activeJobs;
 	}
 	/**
-	* Convert a MongoDB document to a typed PersistedJob object.
-	*
-	* Maps raw MongoDB document fields to the strongly-typed `PersistedJob<T>` interface,
-	* ensuring type safety and handling optional fields (`lockedAt`, `failReason`, etc.).
-	*
-	* @private
-	* @template T - The job data payload type
-	* @param doc - The raw MongoDB document with `_id`
-	* @returns A strongly-typed PersistedJob object with guaranteed `_id`
-	*/
-	documentToPersistedJob(doc) {
-		const job = {
-			_id: doc._id,
-			name: doc["name"],
-			data: doc["data"],
-			status: doc["status"],
-			nextRunAt: doc["nextRunAt"],
-			failCount: doc["failCount"],
-			createdAt: doc["createdAt"],
-			updatedAt: doc["updatedAt"]
-		};
-		if (doc["lockedAt"] !== void 0) job.lockedAt = doc["lockedAt"];
-		if (doc["claimedBy"] !== void 0) job.claimedBy = doc["claimedBy"];
-		if (doc["lastHeartbeat"] !== void 0) job.lastHeartbeat = doc["lastHeartbeat"];
-		if (doc["heartbeatInterval"] !== void 0) job.heartbeatInterval = doc["heartbeatInterval"];
-		if (doc["failReason"] !== void 0) job.failReason = doc["failReason"];
-		if (doc["repeatInterval"] !== void 0) job.repeatInterval = doc["repeatInterval"];
-		if (doc["uniqueKey"] !== void 0) job.uniqueKey = doc["uniqueKey"];
-		return job;
-	}
-	/**
 	* Type-safe event emitter methods
 	*/
 	emit(event, payload) {
@@ -2916,6 +3179,7 @@ exports.JobStateError = JobStateError;
 exports.JobStatus = JobStatus;
 exports.Monque = Monque;
 exports.MonqueError = MonqueError;
+exports.PayloadTooLargeError = PayloadTooLargeError;
 exports.ShutdownTimeoutError = ShutdownTimeoutError;
 exports.WorkerRegistrationError = WorkerRegistrationError;
 exports.calculateBackoff = calculateBackoff;