@monque/core 1.3.0 → 1.4.0

package/dist/index.mjs

@@ -3,6 +3,40 @@ import { CronExpressionParser } from "cron-parser";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "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.
@@ -561,6 +595,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
 /**
@@ -710,7 +777,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);
 		}
@@ -819,9 +886,8 @@ var JobManager = class {
 		const _id = new 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
@@ -906,8 +972,7 @@ var JobManager = class {
 		const _id = new 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
@@ -969,21 +1034,20 @@ var JobManager = class {
 		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) {
+			const jobId = doc._id.toString();
+			if (doc["status"] !== JobStatus.PENDING && doc["status"] !== JobStatus.CANCELLED) {
 				errors.push({
 					jobId,
-					error: `Cannot cancel job in status '${job.status}'`
+					error: `Cannot cancel job in status '${doc["status"]}'`
 				});
 				continue;
 			}
-			if (job.status === JobStatus.CANCELLED) {
+			if (doc["status"] === JobStatus.CANCELLED) {
 				cancelledIds.push(jobId);
 				continue;
 			}
 			if (await this.ctx.collection.findOneAndUpdate({
-				_id: job._id,
+				_id: doc._id,
 				status: JobStatus.PENDING
 			}, { $set: {
 				status: JobStatus.CANCELLED,
@@ -1027,17 +1091,16 @@ var JobManager = class {
 		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) {
+			const jobId = doc._id.toString();
+			if (doc["status"] !== JobStatus.FAILED && doc["status"] !== JobStatus.CANCELLED) {
 				errors.push({
 					jobId,
-					error: `Cannot retry job in status '${job.status}'`
+					error: `Cannot retry job in status '${doc["status"]}'`
 				});
 				continue;
 			}
 			if (await this.ctx.collection.findOneAndUpdate({
-				_id: job._id,
+				_id: doc._id,
 				status: { $in: [JobStatus.FAILED, JobStatus.CANCELLED] }
 			}, {
 				$set: {
@@ -1173,7 +1236,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
 						});
 					});
@@ -1225,6 +1288,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
 	*/
@@ -1235,38 +1302,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,
@@ -1280,61 +1359,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: {
@@ -1343,8 +1420,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.
@@ -1960,7 +2059,8 @@ var Monque = class extends EventEmitter {
 			instanceConcurrency: options.instanceConcurrency ?? options.maxConcurrency,
 			schedulerInstanceId: options.schedulerInstanceId ?? randomUUID(),
 			heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
-			jobRetention: options.jobRetention
+			jobRetention: options.jobRetention,
+			skipIndexCreation: options.skipIndexCreation ?? false
 		};
 	}
 	/**
@@ -1973,7 +2073,7 @@ var Monque = class extends 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();
 			const ctx = this.buildContext();
 			this._scheduler = new JobScheduler(ctx);
@@ -2023,7 +2123,7 @@ var Monque = class extends EventEmitter {
 			workers: this.workers,
 			isRunning: () => this.isRunning,
 			emit: (event, payload) => this.emit(event, payload),
-			documentToPersistedJob: (doc) => this.documentToPersistedJob(doc)
+			documentToPersistedJob: (doc) => documentToPersistedJob(doc)
 		};
 	}
 	/**
@@ -2040,43 +2140,64 @@ var Monque = class extends 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.
@@ -2678,27 +2799,27 @@ var Monque = class extends EventEmitter {
 		this.changeStreamHandler.setup();
 		this.pollIntervalId = setInterval(() => {
 			this.processor.poll().catch((error) => {
-				this.emit("job:error", { error });
+				this.emit("job:error", { error: toError(error) });
 			});
 		}, this.options.pollInterval);
 		this.heartbeatIntervalId = setInterval(() => {
 			this.processor.updateHeartbeats().catch((error) => {
-				this.emit("job:error", { 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 });
+				this.emit("job:error", { error: toError(error) });
 			});
 			this.cleanupIntervalId = setInterval(() => {
 				this.cleanupJobs().catch((error) => {
-					this.emit("job:error", { error });
+					this.emit("job:error", { error: toError(error) });
 				});
 			}, interval);
 		}
 		this.processor.poll().catch((error) => {
-			this.emit("job:error", { error });
+			this.emit("job:error", { error: toError(error) });
 		});
 	}
 	/**
@@ -2856,37 +2977,6 @@ var Monque = class extends 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) {