@monque/core 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@monque/core",
-	"version": "1.6.0",
+	"version": "1.7.0",
 	"description": "MongoDB-backed job scheduler with atomic locking, exponential backoff, and cron scheduling",
 	"author": "Maurice de Bruyn <debruyn.maurice@gmail.com>",
 	"repository": {
@@ -76,13 +76,13 @@
 	},
 	"devDependencies": {
 		"@faker-js/faker": "^10.3.0",
-		"@testcontainers/mongodb": "^11.12.0",
+		"@testcontainers/mongodb": "^11.13.0",
 		"@total-typescript/ts-reset": "^0.6.1",
 		"@types/node": "^22.19.15",
 		"@vitest/coverage-v8": "^4.1.0",
 		"fishery": "^2.4.0",
 		"mongodb": "^7.1.0",
-		"tsdown": "^0.21.2",
+		"tsdown": "^0.21.4",
 		"vitest": "^4.1.0"
 	}
 }

package/src/index.ts

@@ -41,11 +41,14 @@ export {
 	getNextCronDate,
 	InvalidCronError,
 	InvalidCursorError,
+	InvalidJobIdentifierError,
 	JobStateError,
 	MonqueError,
 	PayloadTooLargeError,
 	ShutdownTimeoutError,
 	validateCronExpression,
+	validateJobName,
+	validateUniqueKey,
 	WorkerRegistrationError,
 } from '@/shared';
 // Types - Workers

package/src/scheduler/monque.ts

@@ -18,11 +18,18 @@ import {
 	type QueueStats,
 	type ScheduleOptions,
 } from '@/jobs';
-import { ConnectionError, ShutdownTimeoutError, WorkerRegistrationError } from '@/shared';
+import {
+	ConnectionError,
+	ShutdownTimeoutError,
+	validateJobName,
+	validateUniqueKey,
+	WorkerRegistrationError,
+} from '@/shared';
 import type { WorkerOptions, WorkerRegistration } from '@/workers';
 
 import {
 	ChangeStreamHandler,
+	CLEANUP_STATUSES,
 	JobManager,
 	JobProcessor,
 	JobQueryService,
@@ -122,6 +129,15 @@ export class Monque extends EventEmitter {
 	private isRunning = false;
 	private isInitialized = false;
 
+	/**
+	 * Resolve function for the reactive shutdown drain promise.
+	 * Set during stop() when active jobs need to finish; called by
+	 * onJobFinished() when the last active job completes.
+	 *
+	 * @private
+	 */
+	private _drainResolve: (() => void) | null = null;
+
 	// Internal services (initialized in initialize())
 	private _scheduler: JobScheduler | null = null;
 	private _manager: JobManager | null = null;
@@ -132,6 +148,7 @@ export class Monque extends EventEmitter {
 
 	constructor(db: Db, options: MonqueOptions = {}) {
 		super();
+		this.setMaxListeners(20);
 		this.db = db;
 		this.options = {
 			collectionName: options.collectionName ?? DEFAULTS.collectionName,
@@ -153,6 +170,17 @@ export class Monque extends EventEmitter {
 			maxPayloadSize: options.maxPayloadSize,
 			statsCacheTtlMs: options.statsCacheTtlMs ?? 5000,
 		};
+
+		if (options.defaultConcurrency !== undefined) {
+			console.warn(
+				'[@monque/core] "defaultConcurrency" is deprecated and will be removed in a future major version. Use "workerConcurrency" instead.',
+			);
+		}
+		if (options.maxConcurrency !== undefined) {
+			console.warn(
+				'[@monque/core] "maxConcurrency" is deprecated and will be removed in a future major version. Use "instanceConcurrency" instead.',
+			);
+		}
 	}
 
 	/**
@@ -259,6 +287,14 @@ export class Monque extends EventEmitter {
 		return this._lifecycleManager;
 	}
 
+	private validateSchedulingIdentifiers(name: string, uniqueKey?: string): void {
+		validateJobName(name);
+
+		if (uniqueKey !== undefined) {
+			validateUniqueKey(uniqueKey);
+		}
+	}
+
 	/**
 	 * Handle a change-stream-triggered poll and reset the safety poll timer.
 	 *
@@ -294,6 +330,7 @@ export class Monque extends EventEmitter {
 
 				this._changeStreamHandler.notifyPendingJob(name, nextRunAt);
 			},
+			notifyJobFinished: () => this.onJobFinished(),
 			documentToPersistedJob: <T>(doc: WithId<Document>) => documentToPersistedJob<T>(doc),
 		};
 	}
@@ -341,6 +378,20 @@ export class Monque extends EventEmitter {
 			{ 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 },
+			// Index for efficient lifecycle manager cleanup when jobRetention is configured.
+			// Allows fast queries for deleteMany({ status, updatedAt: { $lt: cutoff } }).
+			...(this.options.jobRetention
+				? [
+						{
+							key: { status: 1, updatedAt: 1 } as const,
+							background: true,
+							partialFilterExpression: {
+								status: { $in: CLEANUP_STATUSES },
+								updatedAt: { $exists: true },
+							},
+						},
+					]
+				: []),
 		]);
 	}
 
@@ -370,7 +421,6 @@ export class Monque extends EventEmitter {
 					lockedAt: '',
 					claimedBy: '',
 					lastHeartbeat: '',
-					heartbeatInterval: '',
 				},
 			},
 		);
@@ -437,6 +487,7 @@ export class Monque extends EventEmitter {
 	 * @param data - Job payload, will be passed to the worker handler
 	 * @param options - Scheduling and deduplication options
 	 * @returns Promise resolving to the created or existing job document
+	 * @throws {InvalidJobIdentifierError} If `name` or `uniqueKey` fails public identifier validation
 	 * @throws {ConnectionError} If database operation fails or scheduler not initialized
 	 * @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
 	 *
@@ -469,6 +520,7 @@ export class Monque extends EventEmitter {
 	 */
 	async enqueue<T>(name: string, data: T, options: EnqueueOptions = {}): Promise<PersistedJob<T>> {
 		this.ensureInitialized();
+		this.validateSchedulingIdentifiers(name, options.uniqueKey);
 		return this.scheduler.enqueue(name, data, options);
 	}
 
@@ -482,6 +534,7 @@ export class Monque extends EventEmitter {
 	 * @param name - Job type identifier, must match a registered worker
 	 * @param data - Job payload, will be passed to the worker handler
 	 * @returns Promise resolving to the created job document
+	 * @throws {InvalidJobIdentifierError} If `name` fails public identifier validation
 	 * @throws {ConnectionError} If database operation fails or scheduler not initialized
 	 *
 	 * @example Send email immediately
@@ -504,6 +557,7 @@ export class Monque extends EventEmitter {
 	 */
 	async now<T>(name: string, data: T): Promise<PersistedJob<T>> {
 		this.ensureInitialized();
+		validateJobName(name);
 		return this.scheduler.now(name, data);
 	}
 
@@ -525,6 +579,7 @@ export class Monque extends EventEmitter {
 	 * @param data - Job payload, will be passed to the worker handler on each run
 	 * @param options - Scheduling options (uniqueKey for deduplication)
 	 * @returns Promise resolving to the created job document with `repeatInterval` set
+	 * @throws {InvalidJobIdentifierError} If `name` or `uniqueKey` fails public identifier validation
 	 * @throws {InvalidCronError} If cron expression is invalid
 	 * @throws {ConnectionError} If database operation fails or scheduler not initialized
 	 * @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
@@ -561,6 +616,7 @@ export class Monque extends EventEmitter {
 		options: ScheduleOptions = {},
 	): Promise<PersistedJob<T>> {
 		this.ensureInitialized();
+		this.validateSchedulingIdentifiers(name, options.uniqueKey);
 		return this.scheduler.schedule(cron, name, data, options);
 	}
 
@@ -930,6 +986,7 @@ export class Monque extends EventEmitter {
 	 * @param options - Worker configuration
 	 * @param options.concurrency - Maximum concurrent jobs for this worker (default: `defaultConcurrency`)
 	 * @param options.replace - When `true`, replace existing worker instead of throwing error
+	 * @throws {InvalidJobIdentifierError} If `name` fails public identifier validation
 	 * @throws {WorkerRegistrationError} When a worker is already registered for `name` and `replace` is not `true`
 	 *
 	 * @example Basic email worker
@@ -973,6 +1030,7 @@ export class Monque extends EventEmitter {
 	 * ```
 	 */
 	register<T>(name: string, handler: JobHandler<T>, options: WorkerOptions = {}): void {
+		validateJobName(name);
 		const concurrency = options.concurrency ?? this.options.workerConcurrency;
 
 		// Check for existing worker and throw unless replace is explicitly true
@@ -1116,20 +1174,14 @@ export class Monque extends EventEmitter {
 		}
 
 		// Wait for all active jobs to complete (with timeout)
-		const activeJobs = this.getActiveJobs();
-		if (activeJobs.length === 0) {
+		if (this.getActiveJobCount() === 0) {
 			return;
 		}
 
-		// Create a promise that resolves when all jobs are done
-		let checkInterval: ReturnType<typeof setInterval> | undefined;
+		// Reactive drain: resolve when the last active job finishes.
+		// onJobFinished() is called from processJob's finally block.
 		const waitForJobs = new Promise<undefined>((resolve) => {
-			checkInterval = setInterval(() => {
-				if (this.getActiveJobs().length === 0) {
-					clearInterval(checkInterval);
-					resolve(undefined);
-				}
-			}, 100);
+			this._drainResolve = () => resolve(undefined);
 		});
 
 		// Race between job completion and timeout
@@ -1137,15 +1189,9 @@ export class Monque extends EventEmitter {
 			setTimeout(() => resolve('timeout'), this.options.shutdownTimeout);
 		});
 
-		let result: undefined | 'timeout';
+		const result = await Promise.race([waitForJobs, timeout]);
 
-		try {
-			result = await Promise.race([waitForJobs, timeout]);
-		} finally {
-			if (checkInterval) {
-				clearInterval(checkInterval);
-			}
-		}
+		this._drainResolve = null;
 
 		if (result === 'timeout') {
 			const incompleteJobs = this.getActiveJobsList();
@@ -1212,6 +1258,18 @@ export class Monque extends EventEmitter {
 	// Private Helpers
 	// ─────────────────────────────────────────────────────────────────────────────
 
+	/**
+	 * Called when a job finishes processing. If a shutdown drain is pending
+	 * and no active jobs remain, resolves the drain promise.
+	 *
+	 * @private
+	 */
+	private onJobFinished(): void {
+		if (this._drainResolve && this.getActiveJobCount() === 0) {
+			this._drainResolve();
+		}
+	}
+
 	/**
 	 * Ensure the scheduler is initialized before operations.
 	 *
@@ -1225,17 +1283,20 @@ export class Monque extends EventEmitter {
 	}
 
 	/**
-	 * Get array of active job IDs across all workers.
+	 * Get total count of active jobs across all workers.
+	 *
+	 * Returns only the count (O(workers)) instead of allocating
+	 * a throw-away array of IDs, since callers only need `.length`.
 	 *
 	 * @private
-	 * @returns Array of job ID strings currently being processed
+	 * @returns Number of jobs currently being processed
 	 */
-	private getActiveJobs(): string[] {
-		const activeJobs: string[] = [];
+	private getActiveJobCount(): number {
+		let count = 0;
 		for (const worker of this.workers.values()) {
-			activeJobs.push(...worker.activeJobs.keys());
+			count += worker.activeJobs.size;
 		}
-		return activeJobs;
+		return count;
 	}
 
 	/**

package/src/scheduler/services/index.ts

@@ -4,6 +4,6 @@ export { JobManager } from './job-manager.js';
 export { JobProcessor } from './job-processor.js';
 export { JobQueryService } from './job-query.js';
 export { JobScheduler } from './job-scheduler.js';
-export { LifecycleManager } from './lifecycle-manager.js';
+export { CLEANUP_STATUSES, LifecycleManager } from './lifecycle-manager.js';
 // Types
 export type { ResolvedMonqueOptions, SchedulerContext } from './types.js';

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

@@ -39,47 +39,48 @@ export class JobManager {
 
 		const _id = new ObjectId(jobId);
 
-		// Fetch job first to allow emitting the full job object in the event
-		const jobDoc = await this.ctx.collection.findOne({ _id });
-		if (!jobDoc) return null;
+		try {
+			const now = new Date();
+			const result = await this.ctx.collection.findOneAndUpdate(
+				{ _id, status: JobStatus.PENDING },
+				{
+					$set: {
+						status: JobStatus.CANCELLED,
+						updatedAt: now,
+					},
+				},
+				{ returnDocument: 'after' },
+			);
 
-		if (jobDoc['status'] === JobStatus.CANCELLED) {
-			return this.ctx.documentToPersistedJob(jobDoc);
-		}
+			if (!result) {
+				const jobDoc = await this.ctx.collection.findOne({ _id });
+				if (!jobDoc) return null;
 
-		if (jobDoc['status'] !== JobStatus.PENDING) {
-			throw new JobStateError(
-				`Cannot cancel job in status '${jobDoc['status']}'`,
-				jobId,
-				jobDoc['status'],
-				'cancel',
-			);
-		}
+				if (jobDoc['status'] === JobStatus.CANCELLED) {
+					return this.ctx.documentToPersistedJob(jobDoc);
+				}
 
-		const result = await this.ctx.collection.findOneAndUpdate(
-			{ _id, status: JobStatus.PENDING },
-			{
-				$set: {
-					status: JobStatus.CANCELLED,
-					updatedAt: new Date(),
-				},
-			},
-			{ returnDocument: 'after' },
-		);
-
-		if (!result) {
-			// Race condition: job changed state between check and update
-			throw new JobStateError(
-				'Job status changed during cancellation attempt',
-				jobId,
-				'unknown',
-				'cancel',
+				throw new JobStateError(
+					`Cannot cancel job in status '${jobDoc['status']}'`,
+					jobId,
+					jobDoc['status'],
+					'cancel',
+				);
+			}
+
+			const job = this.ctx.documentToPersistedJob(result);
+			this.ctx.emit('job:cancelled', { job });
+			return job;
+		} catch (error) {
+			if (error instanceof MonqueError) {
+				throw error;
+			}
+			const message = error instanceof Error ? error.message : 'Unknown error during cancelJob';
+			throw new ConnectionError(
+				`Failed to cancel job: ${message}`,
+				error instanceof Error ? { cause: error } : undefined,
 			);
 		}
-
-		const job = this.ctx.documentToPersistedJob(result);
-		this.ctx.emit('job:cancelled', { job });
-		return job;
 	}
 
 	/**
@@ -104,52 +105,69 @@ export class JobManager {
 		if (!ObjectId.isValid(jobId)) return null;
 
 		const _id = new ObjectId(jobId);
-		const currentJob = await this.ctx.collection.findOne({ _id });
-
-		if (!currentJob) return null;
 
-		if (currentJob['status'] !== JobStatus.FAILED && currentJob['status'] !== JobStatus.CANCELLED) {
-			throw new JobStateError(
-				`Cannot retry job in status '${currentJob['status']}'`,
-				jobId,
-				currentJob['status'],
-				'retry',
+		try {
+			const now = new Date();
+			const result = await this.ctx.collection.findOneAndUpdate(
+				{
+					_id,
+					status: { $in: [JobStatus.FAILED, JobStatus.CANCELLED] },
+				},
+				{
+					$set: {
+						status: JobStatus.PENDING,
+						failCount: 0,
+						nextRunAt: now,
+						updatedAt: now,
+					},
+					$unset: {
+						failReason: '',
+						lockedAt: '',
+						claimedBy: '',
+						lastHeartbeat: '',
+					},
+				},
+				{ returnDocument: 'before' },
 			);
-		}
 
-		const previousStatus = currentJob['status'] as 'failed' | 'cancelled';
+			if (!result) {
+				const currentJob = await this.ctx.collection.findOne({ _id });
+				if (!currentJob) return null;
 
-		const result = await this.ctx.collection.findOneAndUpdate(
-			{
-				_id,
-				status: { $in: [JobStatus.FAILED, JobStatus.CANCELLED] },
-			},
-			{
-				$set: {
-					status: JobStatus.PENDING,
-					failCount: 0,
-					nextRunAt: new Date(),
-					updatedAt: new Date(),
-				},
-				$unset: {
-					failReason: '',
-					lockedAt: '',
-					claimedBy: '',
-					lastHeartbeat: '',
-					heartbeatInterval: '',
-				},
-			},
-			{ returnDocument: 'after' },
-		);
+				throw new JobStateError(
+					`Cannot retry job in status '${currentJob['status']}'`,
+					jobId,
+					currentJob['status'],
+					'retry',
+				);
+			}
 
-		if (!result) {
-			throw new JobStateError('Job status changed during retry attempt', jobId, 'unknown', 'retry');
+			const previousStatus = result['status'] as 'failed' | 'cancelled';
+
+			const updatedDoc = { ...result };
+			updatedDoc['status'] = JobStatus.PENDING;
+			updatedDoc['failCount'] = 0;
+			updatedDoc['nextRunAt'] = now;
+			updatedDoc['updatedAt'] = now;
+			delete updatedDoc['failReason'];
+			delete updatedDoc['lockedAt'];
+			delete updatedDoc['claimedBy'];
+			delete updatedDoc['lastHeartbeat'];
+
+			const job = this.ctx.documentToPersistedJob(updatedDoc);
+			this.ctx.notifyPendingJob(job.name, job.nextRunAt);
+			this.ctx.emit('job:retried', { job, previousStatus });
+			return job;
+		} catch (error) {
+			if (error instanceof MonqueError) {
+				throw error;
+			}
+			const message = error instanceof Error ? error.message : 'Unknown error during retryJob';
+			throw new ConnectionError(
+				`Failed to retry job: ${message}`,
+				error instanceof Error ? { cause: error } : undefined,
+			);
 		}
-
-		const job = this.ctx.documentToPersistedJob(result);
-		this.ctx.notifyPendingJob(job.name, job.nextRunAt);
-		this.ctx.emit('job:retried', { job, previousStatus });
-		return job;
 	}
 
 	/**
@@ -172,42 +190,45 @@ export class JobManager {
 		if (!ObjectId.isValid(jobId)) return null;
 
 		const _id = new ObjectId(jobId);
-		const currentJobDoc = await this.ctx.collection.findOne({ _id });
-
-		if (!currentJobDoc) return null;
 
-		if (currentJobDoc['status'] !== JobStatus.PENDING) {
-			throw new JobStateError(
-				`Cannot reschedule job in status '${currentJobDoc['status']}'`,
-				jobId,
-				currentJobDoc['status'],
-				'reschedule',
+		try {
+			const now = new Date();
+			const result = await this.ctx.collection.findOneAndUpdate(
+				{ _id, status: JobStatus.PENDING },
+				{
+					$set: {
+						nextRunAt: runAt,
+						updatedAt: now,
+					},
+				},
+				{ returnDocument: 'after' },
 			);
-		}
 
-		const result = await this.ctx.collection.findOneAndUpdate(
-			{ _id, status: JobStatus.PENDING },
-			{
-				$set: {
-					nextRunAt: runAt,
-					updatedAt: new Date(),
-				},
-			},
-			{ returnDocument: 'after' },
-		);
-
-		if (!result) {
-			throw new JobStateError(
-				'Job status changed during reschedule attempt',
-				jobId,
-				'unknown',
-				'reschedule',
+			if (!result) {
+				const currentJobDoc = await this.ctx.collection.findOne({ _id });
+				if (!currentJobDoc) return null;
+
+				throw new JobStateError(
+					`Cannot reschedule job in status '${currentJobDoc['status']}'`,
+					jobId,
+					currentJobDoc['status'],
+					'reschedule',
+				);
+			}
+
+			const job = this.ctx.documentToPersistedJob(result);
+			this.ctx.notifyPendingJob(job.name, job.nextRunAt);
+			return job;
+		} catch (error) {
+			if (error instanceof MonqueError) {
+				throw error;
+			}
+			const message = error instanceof Error ? error.message : 'Unknown error during rescheduleJob';
+			throw new ConnectionError(
+				`Failed to reschedule job: ${message}`,
+				error instanceof Error ? { cause: error } : undefined,
 			);
 		}
-
-		const job = this.ctx.documentToPersistedJob(result);
-		this.ctx.notifyPendingJob(job.name, job.nextRunAt);
-		return job;
 	}
 
 	/**
@@ -232,14 +253,25 @@ export class JobManager {
 
 		const _id = new ObjectId(jobId);
 
-		const result = await this.ctx.collection.deleteOne({ _id });
+		try {
+			const result = await this.ctx.collection.deleteOne({ _id });
 
-		if (result.deletedCount > 0) {
-			this.ctx.emit('job:deleted', { jobId });
-			return true;
-		}
+			if (result.deletedCount > 0) {
+				this.ctx.emit('job:deleted', { jobId });
+				return true;
+			}
 
-		return false;
+			return false;
+		} catch (error) {
+			if (error instanceof MonqueError) {
+				throw error;
+			}
+			const message = error instanceof Error ? error.message : 'Unknown error during deleteJob';
+			throw new ConnectionError(
+				`Failed to delete job: ${message}`,
+				error instanceof Error ? { cause: error } : undefined,
+			);
+		}
 	}
 
 	// ─────────────────────────────────────────────────────────────────────────────
@@ -279,10 +311,11 @@ export class JobManager {
 		query['status'] = JobStatus.PENDING;
 
 		try {
+			const now = new Date();
 			const result = await this.ctx.collection.updateMany(query, {
 				$set: {
 					status: JobStatus.CANCELLED,
-					updatedAt: new Date(),
+					updatedAt: now,
 				},
 			});
 
@@ -346,19 +379,20 @@ export class JobManager {
 		const spreadWindowMs = 30_000; // 30s max spread for staggered retry
 
 		try {
+			const now = new Date();
 			const result = await this.ctx.collection.updateMany(query, [
 				{
 					$set: {
 						status: JobStatus.PENDING,
 						failCount: 0,
 						nextRunAt: {
-							$add: [new Date(), { $multiply: [{ $rand: {} }, spreadWindowMs] }],
+							$add: [now, { $multiply: [{ $rand: {} }, spreadWindowMs] }],
 						},
-						updatedAt: new Date(),
+						updatedAt: now,
 					},
 				},
 				{
-					$unset: ['failReason', 'lockedAt', 'claimedBy', 'lastHeartbeat', 'heartbeatInterval'],
+					$unset: ['failReason', 'lockedAt', 'claimedBy', 'lastHeartbeat'],
 				},
 			]);