@monque/core 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@monque/core",
-	"version": "1.3.0",
+	"version": "1.4.0",
 	"description": "MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling",
 	"author": "Maurice de Bruyn <debruyn.maurice@gmail.com>",
 	"repository": {
@@ -78,7 +78,7 @@
 		"@faker-js/faker": "^10.3.0",
 		"@testcontainers/mongodb": "^11.12.0",
 		"@total-typescript/ts-reset": "^0.6.1",
-		"@types/node": "^22.19.11",
+		"@types/node": "^22.19.13",
 		"@vitest/coverage-v8": "^4.0.18",
 		"fishery": "^2.4.0",
 		"mongodb": "^7.1.0",

package/src/jobs/document-to-persisted-job.ts

@@ -0,0 +1,52 @@
+import type { Document, WithId } from 'mongodb';
+
+import type { JobStatusType, PersistedJob } from './types.js';
+
+/**
+ * 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`
+ */
+export function documentToPersistedJob<T>(doc: WithId<Document>): PersistedJob<T> {
+	const job: PersistedJob<T> = {
+		_id: doc._id,
+		name: doc['name'] as string,
+		data: doc['data'] as T,
+		status: doc['status'] as JobStatusType,
+		nextRunAt: doc['nextRunAt'] as Date,
+		failCount: doc['failCount'] as number,
+		createdAt: doc['createdAt'] as Date,
+		updatedAt: doc['updatedAt'] as Date,
+	};
+
+	// Only set optional properties if they exist
+	if (doc['lockedAt'] !== undefined) {
+		job.lockedAt = doc['lockedAt'] as Date | null;
+	}
+	if (doc['claimedBy'] !== undefined) {
+		job.claimedBy = doc['claimedBy'] as string | null;
+	}
+	if (doc['lastHeartbeat'] !== undefined) {
+		job.lastHeartbeat = doc['lastHeartbeat'] as Date | null;
+	}
+	if (doc['heartbeatInterval'] !== undefined) {
+		job.heartbeatInterval = doc['heartbeatInterval'] as number;
+	}
+	if (doc['failReason'] !== undefined) {
+		job.failReason = doc['failReason'] as string;
+	}
+	if (doc['repeatInterval'] !== undefined) {
+		job.repeatInterval = doc['repeatInterval'] as string;
+	}
+	if (doc['uniqueKey'] !== undefined) {
+		job.uniqueKey = doc['uniqueKey'] as string;
+	}
+
+	return job;
+}

package/src/jobs/index.ts

@@ -1,3 +1,5 @@
+// Mapper
+export { documentToPersistedJob } from './document-to-persisted-job.js';
 // Guards
 export {
 	isCancelledJob,

package/src/scheduler/monque.ts

@@ -7,18 +7,18 @@ import {
 	type BulkOperationResult,
 	type CursorOptions,
 	type CursorPage,
+	documentToPersistedJob,
 	type EnqueueOptions,
 	type GetJobsFilter,
 	type Job,
 	type JobHandler,
 	type JobSelector,
 	JobStatus,
-	type JobStatusType,
 	type PersistedJob,
 	type QueueStats,
 	type ScheduleOptions,
 } from '@/jobs';
-import { ConnectionError, ShutdownTimeoutError, WorkerRegistrationError } from '@/shared';
+import { ConnectionError, ShutdownTimeoutError, toError, WorkerRegistrationError } from '@/shared';
 import type { WorkerOptions, WorkerRegistration } from '@/workers';
 
 import {
@@ -148,6 +148,7 @@ export class Monque extends EventEmitter {
 			schedulerInstanceId: options.schedulerInstanceId ?? randomUUID(),
 			heartbeatInterval: options.heartbeatInterval ?? DEFAULTS.heartbeatInterval,
 			jobRetention: options.jobRetention,
+			skipIndexCreation: options.skipIndexCreation ?? false,
 		};
 	}
 
@@ -165,8 +166,10 @@ export class Monque extends EventEmitter {
 		try {
 			this.collection = this.db.collection(this.options.collectionName);
 
-			// Create indexes for efficient queries
-			await this.createIndexes();
+			// Create indexes for efficient queries (unless externally managed)
+			if (!this.options.skipIndexCreation) {
+				await this.createIndexes();
+			}
 
 			// Recover stale jobs if enabled
 			if (this.options.recoverStaleJobs) {
@@ -254,7 +257,7 @@ export class Monque extends EventEmitter {
 			isRunning: () => this.isRunning,
 			emit: <K extends keyof MonqueEventMap>(event: K, payload: MonqueEventMap[K]) =>
 				this.emit(event, payload),
-			documentToPersistedJob: <T>(doc: WithId<Document>) => this.documentToPersistedJob<T>(doc),
+			documentToPersistedJob: <T>(doc: WithId<Document>) => documentToPersistedJob<T>(doc),
 		};
 	}
 	/**
@@ -274,14 +277,13 @@ export class Monque extends EventEmitter {
 			throw new ConnectionError('Collection not initialized');
 		}
 
-		// Compound index for job polling - status + nextRunAt for efficient queries
-		await this.collection.createIndex({ status: 1, nextRunAt: 1 }, { background: true });
-
-		// Partial unique index for deduplication - scoped by name + uniqueKey
-		// Only enforced where uniqueKey exists and status is pending/processing
-		await this.collection.createIndex(
-			{ name: 1, uniqueKey: 1 },
+		await this.collection.createIndexes([
+			// Compound index for job polling - status + nextRunAt for efficient queries
+			{ key: { status: 1, nextRunAt: 1 }, background: true },
+			// Partial unique index for deduplication - scoped by name + uniqueKey
+			// Only enforced where uniqueKey exists and status is pending/processing
 			{
+				key: { name: 1, uniqueKey: 1 },
 				unique: true,
 				partialFilterExpression: {
 					uniqueKey: { $exists: true },
@@ -289,31 +291,20 @@ export class Monque extends EventEmitter {
 				},
 				background: true,
 			},
-		);
-
-		// Index for job lookup by name
-		await this.collection.createIndex({ name: 1, status: 1 }, { background: true });
-
-		// Compound index for finding jobs claimed by a specific scheduler instance.
-		// Used for heartbeat updates and cleanup on shutdown.
-		await this.collection.createIndex({ claimedBy: 1, status: 1 }, { background: true });
-
-		// Compound index for monitoring/debugging via heartbeat timestamps.
-		// Note: stale recovery uses lockedAt + lockTimeout as the source of truth.
-		await this.collection.createIndex({ lastHeartbeat: 1, status: 1 }, { background: true });
-
-		// Compound index for atomic claim queries.
-		// Optimizes the findOneAndUpdate query that claims unclaimed pending jobs.
-		await this.collection.createIndex(
-			{ status: 1, nextRunAt: 1, claimedBy: 1 },
-			{ background: true },
-		);
-
-		// Expanded index that supports recovery scans (status + lockedAt) plus heartbeat monitoring patterns.
-		await this.collection.createIndex(
-			{ status: 1, lockedAt: 1, lastHeartbeat: 1 },
-			{ background: true },
-		);
+			// Index for job lookup by name
+			{ key: { name: 1, status: 1 }, background: true },
+			// Compound index for finding jobs claimed by a specific scheduler instance.
+			// Used for heartbeat updates and cleanup on shutdown.
+			{ key: { claimedBy: 1, status: 1 }, background: true },
+			// Compound index for monitoring/debugging via heartbeat timestamps.
+			// Note: stale recovery uses lockedAt + lockTimeout as the source of truth.
+			{ key: { lastHeartbeat: 1, status: 1 }, background: true },
+			// Compound index for atomic claim queries.
+			// Optimizes the findOneAndUpdate query that claims unclaimed pending jobs.
+			{ key: { status: 1, nextRunAt: 1, claimedBy: 1 }, background: true },
+			// Expanded index that supports recovery scans (status + lockedAt) plus heartbeat monitoring patterns.
+			{ key: { status: 1, lockedAt: 1, lastHeartbeat: 1 }, background: true },
+		]);
 	}
 
 	/**
@@ -1001,14 +992,14 @@ export class Monque extends EventEmitter {
 		// Set up polling as backup (runs at configured interval)
 		this.pollIntervalId = setInterval(() => {
 			this.processor.poll().catch((error: unknown) => {
-				this.emit('job:error', { error: error as Error });
+				this.emit('job:error', { error: toError(error) });
 			});
 		}, this.options.pollInterval);
 
 		// Start heartbeat interval for claimed jobs
 		this.heartbeatIntervalId = setInterval(() => {
 			this.processor.updateHeartbeats().catch((error: unknown) => {
-				this.emit('job:error', { error: error as Error });
+				this.emit('job:error', { error: toError(error) });
 			});
 		}, this.options.heartbeatInterval);
 
@@ -1018,19 +1009,19 @@ export class Monque extends EventEmitter {
 
 			// Run immediately on start
 			this.cleanupJobs().catch((error: unknown) => {
-				this.emit('job:error', { error: error as Error });
+				this.emit('job:error', { error: toError(error) });
 			});
 
 			this.cleanupIntervalId = setInterval(() => {
 				this.cleanupJobs().catch((error: unknown) => {
-					this.emit('job:error', { error: error as Error });
+					this.emit('job:error', { error: toError(error) });
 				});
 			}, interval);
 		}
 
 		// Run initial poll immediately to pick up any existing jobs
 		this.processor.poll().catch((error: unknown) => {
-			this.emit('job:error', { error: error as Error });
+			this.emit('job:error', { error: toError(error) });
 		});
 	}
 
@@ -1232,55 +1223,6 @@ export class Monque 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`
-	 */
-	private documentToPersistedJob<T>(doc: WithId<Document>): PersistedJob<T> {
-		const job: PersistedJob<T> = {
-			_id: doc._id,
-			name: doc['name'] as string,
-			data: doc['data'] as T,
-			status: doc['status'] as JobStatusType,
-			nextRunAt: doc['nextRunAt'] as Date,
-			failCount: doc['failCount'] as number,
-			createdAt: doc['createdAt'] as Date,
-			updatedAt: doc['updatedAt'] as Date,
-		};
-
-		// Only set optional properties if they exist
-		if (doc['lockedAt'] !== undefined) {
-			job.lockedAt = doc['lockedAt'] as Date | null;
-		}
-		if (doc['claimedBy'] !== undefined) {
-			job.claimedBy = doc['claimedBy'] as string | null;
-		}
-		if (doc['lastHeartbeat'] !== undefined) {
-			job.lastHeartbeat = doc['lastHeartbeat'] as Date | null;
-		}
-		if (doc['heartbeatInterval'] !== undefined) {
-			job.heartbeatInterval = doc['heartbeatInterval'] as number;
-		}
-		if (doc['failReason'] !== undefined) {
-			job.failReason = doc['failReason'] as string;
-		}
-		if (doc['repeatInterval'] !== undefined) {
-			job.repeatInterval = doc['repeatInterval'] as string;
-		}
-		if (doc['uniqueKey'] !== undefined) {
-			job.uniqueKey = doc['uniqueKey'] as string;
-		}
-
-		return job;
-	}
-
 	/**
 	 * Type-safe event emitter methods
 	 */

package/src/scheduler/services/change-stream-handler.ts

@@ -1,6 +1,7 @@
 import type { ChangeStream, ChangeStreamDocument, Document } from 'mongodb';
 
 import { JobStatus } from '@/jobs';
+import { toError } from '@/shared';
 
 import type { SchedulerContext } from './types.js';
 
@@ -133,7 +134,7 @@ export class ChangeStreamHandler {
 			this.debounceTimer = setTimeout(() => {
 				this.debounceTimer = null;
 				this.onPoll().catch((error: unknown) => {
-					this.ctx.emit('job:error', { error: error as Error });
+					this.ctx.emit('job:error', { error: toError(error) });
 				});
 			}, 100);
 		}

package/src/scheduler/services/job-manager.ts

@@ -1,12 +1,6 @@
-import { ObjectId, type WithId } from 'mongodb';
-
-import {
-	type BulkOperationResult,
-	type Job,
-	type JobSelector,
-	JobStatus,
-	type PersistedJob,
-} from '@/jobs';
+import { ObjectId } from 'mongodb';
+
+import { type BulkOperationResult, type JobSelector, JobStatus, type PersistedJob } from '@/jobs';
 import { buildSelectorQuery } from '@/scheduler';
 import { JobStateError } from '@/shared';
 
@@ -49,17 +43,15 @@ export class JobManager {
 		const jobDoc = await this.ctx.collection.findOne({ _id });
 		if (!jobDoc) return null;
 
-		const currentJob = jobDoc as unknown as WithId<Job>;
-
-		if (currentJob.status === JobStatus.CANCELLED) {
-			return this.ctx.documentToPersistedJob(currentJob);
+		if (jobDoc['status'] === JobStatus.CANCELLED) {
+			return this.ctx.documentToPersistedJob(jobDoc);
 		}
 
-		if (currentJob.status !== JobStatus.PENDING) {
+		if (jobDoc['status'] !== JobStatus.PENDING) {
 			throw new JobStateError(
-				`Cannot cancel job in status '${currentJob.status}'`,
+				`Cannot cancel job in status '${jobDoc['status']}'`,
 				jobId,
-				currentJob.status,
+				jobDoc['status'],
 				'cancel',
 			);
 		}
@@ -183,13 +175,11 @@ export class JobManager {
 
 		if (!currentJobDoc) return null;
 
-		const currentJob = currentJobDoc as unknown as WithId<Job>;
-
-		if (currentJob.status !== JobStatus.PENDING) {
+		if (currentJobDoc['status'] !== JobStatus.PENDING) {
 			throw new JobStateError(
-				`Cannot reschedule job in status '${currentJob.status}'`,
+				`Cannot reschedule job in status '${currentJobDoc['status']}'`,
 				jobId,
-				currentJob.status,
+				currentJobDoc['status'],
 				'reschedule',
 			);
 		}
@@ -281,26 +271,25 @@ export class JobManager {
 		const cursor = this.ctx.collection.find(baseQuery);
 
 		for await (const doc of cursor) {
-			const job = doc as unknown as WithId<Job>;
-			const jobId = job._id.toString();
+			const jobId = doc._id.toString();
 
-			if (job.status !== JobStatus.PENDING && job.status !== JobStatus.CANCELLED) {
+			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;
 			}
 
 			// Skip already cancelled jobs (idempotent)
-			if (job.status === JobStatus.CANCELLED) {
+			if (doc['status'] === JobStatus.CANCELLED) {
 				cancelledIds.push(jobId);
 				continue;
 			}
 
 			// Atomically update to cancelled
 			const result = await this.ctx.collection.findOneAndUpdate(
-				{ _id: job._id, status: JobStatus.PENDING },
+				{ _id: doc._id, status: JobStatus.PENDING },
 				{
 					$set: {
 						status: JobStatus.CANCELLED,
@@ -360,20 +349,19 @@ export class JobManager {
 		const cursor = this.ctx.collection.find(baseQuery);
 
 		for await (const doc of cursor) {
-			const job = doc as unknown as WithId<Job>;
-			const jobId = job._id.toString();
+			const jobId = doc._id.toString();
 
-			if (job.status !== JobStatus.FAILED && job.status !== JobStatus.CANCELLED) {
+			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;
 			}
 
 			const result = await this.ctx.collection.findOneAndUpdate(
 				{
-					_id: job._id,
+					_id: doc._id,
 					status: { $in: [JobStatus.FAILED, JobStatus.CANCELLED] },
 				},
 				{

package/src/scheduler/services/job-processor.ts

@@ -1,5 +1,5 @@
 import { isPersistedJob, type Job, JobStatus, type PersistedJob } from '@/jobs';
-import { calculateBackoff, getNextCronDate } from '@/shared';
+import { calculateBackoff, getNextCronDate, toError } from '@/shared';
 import type { WorkerRegistration } from '@/workers';
 
 import type { SchedulerContext } from './types.js';
@@ -117,7 +117,7 @@ export class JobProcessor {
 					worker.activeJobs.set(job._id.toString(), job);
 
 					this.processJob(job, worker).catch((error: unknown) => {
-						this.ctx.emit('job:error', { error: error as Error, job });
+						this.ctx.emit('job:error', { error: toError(error), job });
 					});
 				} else {
 					// No more jobs available for this worker
@@ -189,6 +189,10 @@ export class JobProcessor {
 	 * 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
 	 */
@@ -202,39 +206,50 @@ export class JobProcessor {
 
 			// Job completed successfully
 			const duration = Date.now() - startTime;
-			await this.completeJob(job);
-			this.ctx.emit('job:complete', { job, duration });
+			const updatedJob = await this.completeJob(job);
+
+			if (updatedJob) {
+				this.ctx.emit('job:complete', { job: updatedJob, duration });
+			}
 		} catch (error) {
 			// Job failed
 			const err = error instanceof Error ? error : new Error(String(error));
-			await this.failJob(job, err);
+			const updatedJob = await this.failJob(job, err);
 
-			const willRetry = job.failCount + 1 < this.ctx.options.maxRetries;
-			this.ctx.emit('job:fail', { job, error: err, willRetry });
+			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: Job): Promise<void> {
+	async completeJob(job: Job): Promise<PersistedJob | null> {
 		if (!isPersistedJob(job)) {
-			return;
+			return null;
 		}
 
 		if (job.repeatInterval) {
 			// Recurring job - schedule next run
 			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,
@@ -250,52 +265,63 @@ export class JobProcessor {
 						failReason: '',
 					},
 				},
+				{ returnDocument: 'after' },
 			);
-		} else {
-			// One-time job - mark as completed
-			await this.ctx.collection.updateOne(
-				{ _id: job._id },
-				{
-					$set: {
-						status: JobStatus.COMPLETED,
-						updatedAt: new Date(),
-					},
-					$unset: {
-						lockedAt: '',
-						claimedBy: '',
-						lastHeartbeat: '',
-						heartbeatInterval: '',
-						failReason: '',
-					},
-				},
-			);
-			job.status = JobStatus.COMPLETED;
+
+			return result ? this.ctx.documentToPersistedJob(result) : null;
 		}
+
+		// One-time job - mark as completed
+		const result = await this.ctx.collection.findOneAndUpdate(
+			{ _id: job._id, status: JobStatus.PROCESSING, claimedBy: this.ctx.instanceId },
+			{
+				$set: {
+					status: JobStatus.COMPLETED,
+					updatedAt: 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: Job, error: Error): Promise<void> {
+	async failJob(job: Job, error: Error): Promise<PersistedJob | null> {
 		if (!isPersistedJob(job)) {
-			return;
+			return null;
 		}
 
 		const newFailCount = job.failCount + 1;
 
 		if (newFailCount >= this.ctx.options.maxRetries) {
 			// Permanent failure
-			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.FAILED,
@@ -310,34 +336,40 @@ export class JobProcessor {
 						heartbeatInterval: '',
 					},
 				},
-			);
-		} else {
-			// Schedule retry with exponential backoff
-			const nextRunAt = calculateBackoff(
-				newFailCount,
-				this.ctx.options.baseRetryInterval,
-				this.ctx.options.maxBackoffDelay,
+				{ returnDocument: 'after' },
 			);
 
-			await this.ctx.collection.updateOne(
-				{ _id: job._id },
-				{
-					$set: {
-						status: JobStatus.PENDING,
-						failCount: newFailCount,
-						failReason: error.message,
-						nextRunAt,
-						updatedAt: new Date(),
-					},
-					$unset: {
-						lockedAt: '',
-						claimedBy: '',
-						lastHeartbeat: '',
-						heartbeatInterval: '',
-					},
-				},
-			);
+			return result ? this.ctx.documentToPersistedJob(result) : null;
 		}
+
+		// Schedule retry with exponential backoff
+		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: new Date(),
+				},
+				$unset: {
+					lockedAt: '',
+					claimedBy: '',
+					lastHeartbeat: '',
+					heartbeatInterval: '',
+				},
+			},
+			{ returnDocument: 'after' },
+		);
+
+		return result ? this.ctx.documentToPersistedJob(result) : null;
 	}
 
 	/**

package/src/scheduler/types.ts

@@ -162,4 +162,15 @@ export interface MonqueOptions {
 	 * @deprecated Use `instanceConcurrency` instead. Will be removed in a future major version.
 	 */
 	maxConcurrency?: number | undefined;
+
+	/**
+	 * Skip automatic index creation during initialization.
+	 *
+	 * When `true`, `initialize()` will not create MongoDB indexes. Use this in production
+	 * environments where indexes are managed externally (e.g., via migration scripts or DBA
+	 * tooling). See the production checklist for the full list of required indexes.
+	 *
+	 * @default false
+	 */
+	skipIndexCreation?: boolean;
 }