@monque/core 1.6.0 → 1.7.0

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

@@ -19,20 +19,16 @@ export class JobProcessor {
 	/** Flag to request a re-poll after the current poll finishes */
 	private _repollRequested = false;
 
-	constructor(private readonly ctx: SchedulerContext) {}
-
 	/**
-	 * Get the total number of active jobs across all workers.
+	 * O(1) counter tracking the total number of active jobs across all workers.
 	 *
-	 * Used for instance-level throttling when `instanceConcurrency` is configured.
+	 * Incremented when a job is added to `worker.activeJobs` in `_doPoll`,
+	 * decremented in the `processJob` finally block. Replaces the previous
+	 * O(workers) loop in `getTotalActiveJobs()` for instance-level throttling.
 	 */
-	private getTotalActiveJobs(): number {
-		let total = 0;
-		for (const worker of this.ctx.workers.values()) {
-			total += worker.activeJobs.size;
-		}
-		return total;
-	}
+	private _totalActiveJobs = 0;
+
+	constructor(private readonly ctx: SchedulerContext) {}
 
 	/**
 	 * Get the number of available slots considering the global instanceConcurrency limit.
@@ -47,8 +43,7 @@ export class JobProcessor {
 			return workerAvailableSlots;
 		}
 
-		const totalActive = this.getTotalActiveJobs();
-		const globalAvailable = instanceConcurrency - totalActive;
+		const globalAvailable = instanceConcurrency - this._totalActiveJobs;
 
 		return Math.min(workerAvailableSlots, globalAvailable);
 	}
@@ -100,7 +95,7 @@ export class JobProcessor {
 		// Early exit if global instanceConcurrency is reached
 		const { instanceConcurrency } = this.ctx.options;
 
-		if (instanceConcurrency !== undefined && this.getTotalActiveJobs() >= instanceConcurrency) {
+		if (instanceConcurrency !== undefined && this._totalActiveJobs >= instanceConcurrency) {
 			return;
 		}
 
@@ -125,31 +120,57 @@ export class JobProcessor {
 				return;
 			}
 
-			// Try to acquire jobs up to available slots
+			// Try to acquire jobs up to available slots in parallel
+			if (!this.ctx.isRunning()) {
+				return;
+			}
+
+			const acquisitionPromises: Promise<void>[] = [];
 			for (let i = 0; i < availableSlots; i++) {
-				if (!this.ctx.isRunning()) {
-					return;
-				}
-
-				// Re-check global limit before each acquisition
-				if (instanceConcurrency !== undefined && this.getTotalActiveJobs() >= instanceConcurrency) {
-					return;
-				}
-
-				const job = await this.acquireJob(name);
-
-				if (job) {
-					// Add to activeJobs immediately to correctly track concurrency
-					worker.activeJobs.set(job._id.toString(), job);
-
-					this.processJob(job, worker).catch((error: unknown) => {
-						this.ctx.emit('job:error', { error: toError(error), job });
-					});
-				} else {
-					// No more jobs available for this worker
-					break;
-				}
+				acquisitionPromises.push(
+					this.acquireJob(name)
+						.then(async (job) => {
+							if (!job) {
+								return;
+							}
+
+							if (this.ctx.isRunning()) {
+								// Add to activeJobs immediately to correctly track concurrency
+								worker.activeJobs.set(job._id.toString(), job);
+								this._totalActiveJobs++;
+
+								this.processJob(job, worker).catch((error: unknown) => {
+									this.ctx.emit('job:error', { error: toError(error), job });
+								});
+							} else {
+								// Revert claim if shut down while acquiring
+								try {
+									await this.ctx.collection.updateOne(
+										{ _id: job._id, status: JobStatus.PROCESSING, claimedBy: this.ctx.instanceId },
+										{
+											$set: {
+												status: JobStatus.PENDING,
+												updatedAt: new Date(),
+											},
+											$unset: {
+												lockedAt: '',
+												claimedBy: '',
+												lastHeartbeat: '',
+											},
+										},
+									);
+								} catch (error) {
+									this.ctx.emit('job:error', { error: toError(error) });
+								}
+							}
+						})
+						.catch((error: unknown) => {
+							this.ctx.emit('job:error', { error: toError(error) });
+						}),
+				);
 			}
+
+			await Promise.allSettled(acquisitionPromises);
 		}
 	}
 
@@ -197,10 +218,6 @@ export class JobProcessor {
 			},
 		);
 
-		if (!this.ctx.isRunning()) {
-			return null;
-		}
-
 		if (!result) {
 			return null;
 		}
@@ -248,6 +265,8 @@ export class JobProcessor {
 			}
 		} finally {
 			worker.activeJobs.delete(jobId);
+			this._totalActiveJobs--;
+			this.ctx.notifyJobFinished();
 		}
 	}
 
@@ -271,6 +290,8 @@ export class JobProcessor {
 			return null;
 		}
 
+		const now = new Date();
+
 		if (job.repeatInterval) {
 			// Recurring job - schedule next run
 			const nextRunAt = getNextCronDate(job.repeatInterval);
@@ -281,13 +302,12 @@ export class JobProcessor {
 						status: JobStatus.PENDING,
 						nextRunAt,
 						failCount: 0,
-						updatedAt: new Date(),
+						updatedAt: now,
 					},
 					$unset: {
 						lockedAt: '',
 						claimedBy: '',
 						lastHeartbeat: '',
-						heartbeatInterval: '',
 						failReason: '',
 					},
 				},
@@ -309,13 +329,12 @@ export class JobProcessor {
 			{
 				$set: {
 					status: JobStatus.COMPLETED,
-					updatedAt: new Date(),
+					updatedAt: now,
 				},
 				$unset: {
 					lockedAt: '',
 					claimedBy: '',
 					lastHeartbeat: '',
-					heartbeatInterval: '',
 					failReason: '',
 				},
 			},
@@ -353,6 +372,7 @@ export class JobProcessor {
 			return null;
 		}
 
+		const now = new Date();
 		const newFailCount = job.failCount + 1;
 
 		if (newFailCount >= this.ctx.options.maxRetries) {
@@ -364,13 +384,12 @@ export class JobProcessor {
 						status: JobStatus.FAILED,
 						failCount: newFailCount,
 						failReason: error.message,
-						updatedAt: new Date(),
+						updatedAt: now,
 					},
 					$unset: {
 						lockedAt: '',
 						claimedBy: '',
 						lastHeartbeat: '',
-						heartbeatInterval: '',
 					},
 				},
 				{ returnDocument: 'after' },
@@ -394,13 +413,12 @@ export class JobProcessor {
 					failCount: newFailCount,
 					failReason: error.message,
 					nextRunAt,
-					updatedAt: new Date(),
+					updatedAt: now,
 				},
 				$unset: {
 					lockedAt: '',
 					claimedBy: '',
 					lastHeartbeat: '',
-					heartbeatInterval: '',
 				},
 			},
 			{ returnDocument: 'after' },

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

@@ -7,7 +7,14 @@ import {
 	type PersistedJob,
 	type ScheduleOptions,
 } from '@/jobs';
-import { ConnectionError, getNextCronDate, MonqueError, PayloadTooLargeError } from '@/shared';
+import {
+	ConnectionError,
+	getNextCronDate,
+	MonqueError,
+	PayloadTooLargeError,
+	validateJobName,
+	validateUniqueKey,
+} from '@/shared';
 
 import type { SchedulerContext } from './types.js';
 
@@ -22,6 +29,14 @@ import type { SchedulerContext } from './types.js';
 export class JobScheduler {
 	constructor(private readonly ctx: SchedulerContext) {}
 
+	private validateJobIdentifiers(name: string, uniqueKey?: string): void {
+		validateJobName(name);
+
+		if (uniqueKey !== undefined) {
+			validateUniqueKey(uniqueKey);
+		}
+	}
+
 	/**
 	 * Validate that the job data payload does not exceed the configured maximum BSON byte size.
 	 *
@@ -74,6 +89,7 @@ export class JobScheduler {
 	 * @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`
 	 *
@@ -103,6 +119,7 @@ export class JobScheduler {
 	 * ```
 	 */
 	async enqueue<T>(name: string, data: T, options: EnqueueOptions = {}): Promise<PersistedJob<T>> {
+		this.validateJobIdentifiers(name, options.uniqueKey);
 		this.validatePayloadSize(data);
 		const now = new Date();
 		const job: Omit<Job<T>, '_id'> = {
@@ -115,12 +132,12 @@ export class JobScheduler {
 			updatedAt: now,
 		};
 
-		if (options.uniqueKey) {
+		if (options.uniqueKey !== undefined) {
 			job.uniqueKey = options.uniqueKey;
 		}
 
 		try {
-			if (options.uniqueKey) {
+			if (options.uniqueKey !== undefined) {
 				// Use upsert with $setOnInsert for deduplication (scoped by name + uniqueKey)
 				const result = await this.ctx.collection.findOneAndUpdate(
 					{
@@ -216,6 +233,7 @@ export class JobScheduler {
 	 * @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`
@@ -249,6 +267,7 @@ export class JobScheduler {
 		data: T,
 		options: ScheduleOptions = {},
 	): Promise<PersistedJob<T>> {
+		this.validateJobIdentifiers(name, options.uniqueKey);
 		this.validatePayloadSize(data);
 
 		// Validate cron and get next run date (throws InvalidCronError if invalid)
@@ -266,12 +285,12 @@ export class JobScheduler {
 			updatedAt: now,
 		};
 
-		if (options.uniqueKey) {
+		if (options.uniqueKey !== undefined) {
 			job.uniqueKey = options.uniqueKey;
 		}
 
 		try {
-			if (options.uniqueKey) {
+			if (options.uniqueKey !== undefined) {
 				// Use upsert with $setOnInsert for deduplication (scoped by name + uniqueKey)
 				const result = await this.ctx.collection.findOneAndUpdate(
 					{

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

@@ -10,6 +10,11 @@ import type { SchedulerContext } from './types.js';
  */
 const DEFAULT_RETENTION_INTERVAL = 3600_000;
 
+/**
+ * Statuses that are eligible for cleanup by the retention policy.
+ */
+export const CLEANUP_STATUSES = [JobStatus.COMPLETED, JobStatus.FAILED] as const;
+
 /**
  * Callbacks for timer-driven operations.
  *
@@ -133,7 +138,7 @@ export class LifecycleManager {
 			.catch((error: unknown) => {
 				this.ctx.emit('job:error', { error: toError(error) });
 			})
-			.then(() => {
+			.finally(() => {
 				this.scheduleNextPoll();
 			});
 	}

package/src/scheduler/services/types.ts

@@ -63,6 +63,9 @@ export interface SchedulerContext {
 	/** Notify the local scheduler about a pending job transition */
 	notifyPendingJob: (name: string, nextRunAt: Date) => void;
 
+	/** Notify that a job has finished processing (for reactive shutdown drain) */
+	notifyJobFinished: () => void;
+
 	/** Convert MongoDB document to typed PersistedJob */
 	documentToPersistedJob: <T>(doc: WithId<Document>) => PersistedJob<T>;
 }

package/src/shared/errors.ts

@@ -199,6 +199,35 @@ export class InvalidCursorError extends MonqueError {
 	}
 }
 
+/**
+ * Error thrown when a public job identifier fails validation.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await monque.enqueue('invalid job name', {});
+ * } catch (error) {
+ *   if (error instanceof InvalidJobIdentifierError) {
+ *     console.error(`Invalid ${error.field}: ${error.message}`);
+ *   }
+ * }
+ * ```
+ */
+export class InvalidJobIdentifierError extends MonqueError {
+	constructor(
+		public readonly field: 'name' | 'uniqueKey',
+		public readonly value: string,
+		message: string,
+	) {
+		super(message);
+		this.name = 'InvalidJobIdentifierError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, InvalidJobIdentifierError);
+		}
+	}
+}
+
 /**
  * Error thrown when a statistics aggregation times out.
  *

package/src/shared/index.ts

@@ -3,6 +3,7 @@ export {
 	ConnectionError,
 	InvalidCronError,
 	InvalidCursorError,
+	InvalidJobIdentifierError,
 	JobStateError,
 	MonqueError,
 	PayloadTooLargeError,
@@ -17,4 +18,6 @@ export {
 	getNextCronDate,
 	toError,
 	validateCronExpression,
+	validateJobName,
+	validateUniqueKey,
 } from './utils/index.js';

package/src/shared/utils/index.ts

@@ -6,3 +6,4 @@ export {
 } from './backoff.js';
 export { getNextCronDate, validateCronExpression } from './cron.js';
 export { toError } from './error.js';
+export { validateJobName, validateUniqueKey } from './job-identifiers.js';

package/src/shared/utils/job-identifiers.ts

@@ -0,0 +1,71 @@
+import { InvalidJobIdentifierError } from '../errors.js';
+
+const JOB_NAME_PATTERN = /^[^\s\p{Cc}]+$/u;
+const CONTROL_CHARACTER_PATTERN = /\p{Cc}/u;
+
+const MAX_JOB_NAME_LENGTH = 255;
+const MAX_UNIQUE_KEY_LENGTH = 1024;
+
+/**
+ * Validate a public job name before it is registered or scheduled.
+ *
+ * @param name - The job name to validate
+ * @throws {InvalidJobIdentifierError} If the job name is empty, too long, or contains unsupported characters
+ */
+export function validateJobName(name: string): void {
+	if (name.length === 0 || name.trim().length === 0) {
+		throw new InvalidJobIdentifierError(
+			'name',
+			name,
+			'Job name cannot be empty or whitespace only.',
+		);
+	}
+
+	if (name.length > MAX_JOB_NAME_LENGTH) {
+		throw new InvalidJobIdentifierError(
+			'name',
+			name,
+			`Job name cannot exceed ${MAX_JOB_NAME_LENGTH} characters.`,
+		);
+	}
+
+	if (!JOB_NAME_PATTERN.test(name)) {
+		throw new InvalidJobIdentifierError(
+			'name',
+			name,
+			'Job name cannot contain whitespace or control characters.',
+		);
+	}
+}
+
+/**
+ * Validate a deduplication key before it is stored or used in a unique query.
+ *
+ * @param uniqueKey - The unique key to validate
+ * @throws {InvalidJobIdentifierError} If the key is empty, too long, or contains control characters
+ */
+export function validateUniqueKey(uniqueKey: string): void {
+	if (uniqueKey.length === 0 || uniqueKey.trim().length === 0) {
+		throw new InvalidJobIdentifierError(
+			'uniqueKey',
+			uniqueKey,
+			'Unique key cannot be empty or whitespace only.',
+		);
+	}
+
+	if (uniqueKey.length > MAX_UNIQUE_KEY_LENGTH) {
+		throw new InvalidJobIdentifierError(
+			'uniqueKey',
+			uniqueKey,
+			`Unique key cannot exceed ${MAX_UNIQUE_KEY_LENGTH} characters.`,
+		);
+	}
+
+	if (CONTROL_CHARACTER_PATTERN.test(uniqueKey)) {
+		throw new InvalidJobIdentifierError(
+			'uniqueKey',
+			uniqueKey,
+			'Unique key cannot contain control characters.',
+		);
+	}
+}