@monque/core 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@monque/core",
-	"version": "1.2.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": {
@@ -72,17 +72,17 @@
 		"cron-parser": "^5.5.0"
 	},
 	"peerDependencies": {
-		"mongodb": "catalog:"
+		"mongodb": "^7.1.0"
 	},
 	"devDependencies": {
-		"@faker-js/faker": "^10.2.0",
-		"@testcontainers/mongodb": "catalog:",
-		"@total-typescript/ts-reset": "catalog:",
-		"@types/node": "catalog:",
-		"@vitest/coverage-v8": "catalog:",
+		"@faker-js/faker": "^10.3.0",
+		"@testcontainers/mongodb": "^11.12.0",
+		"@total-typescript/ts-reset": "^0.6.1",
+		"@types/node": "^22.19.13",
+		"@vitest/coverage-v8": "^4.0.18",
 		"fishery": "^2.4.0",
-		"mongodb": "catalog:",
-		"tsdown": "catalog:",
-		"vitest": "catalog:"
+		"mongodb": "^7.1.0",
+		"tsdown": "^0.20.3",
+		"vitest": "^4.0.18"
 	}
 }

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] },
 				},
 				{