@monque/core 1.5.2 → 1.7.0

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(
 					{
@@ -141,12 +158,19 @@ export class JobScheduler {
 					throw new ConnectionError('Failed to enqueue job: findOneAndUpdate returned no document');
 				}
 
-				return this.ctx.documentToPersistedJob<T>(result);
+				const persistedJob = this.ctx.documentToPersistedJob<T>(result);
+				if (persistedJob.status === JobStatus.PENDING) {
+					this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
+				}
+
+				return persistedJob;
 			}
 
 			const result = await this.ctx.collection.insertOne(job as Document);
+			const persistedJob = { ...job, _id: result.insertedId } as PersistedJob<T>;
+			this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
 
-			return { ...job, _id: result.insertedId } as PersistedJob<T>;
+			return persistedJob;
 		} catch (error) {
 			if (error instanceof ConnectionError) {
 				throw error;
@@ -209,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`
@@ -242,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)
@@ -259,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(
 					{
@@ -287,12 +313,19 @@ export class JobScheduler {
 					);
 				}
 
-				return this.ctx.documentToPersistedJob<T>(result);
+				const persistedJob = this.ctx.documentToPersistedJob<T>(result);
+				if (persistedJob.status === JobStatus.PENDING) {
+					this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
+				}
+
+				return persistedJob;
 			}
 
 			const result = await this.ctx.collection.insertOne(job as Document);
+			const persistedJob = { ...job, _id: result.insertedId } as PersistedJob<T>;
+			this.ctx.notifyPendingJob(persistedJob.name, persistedJob.nextRunAt);
 
-			return { ...job, _id: result.insertedId } as PersistedJob<T>;
+			return persistedJob;
 		} catch (error) {
 			if (error instanceof MonqueError) {
 				throw error;

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.
  *
@@ -21,19 +26,26 @@ interface TimerCallbacks {
 	poll: () => Promise<void>;
 	/** Update heartbeats for claimed jobs */
 	updateHeartbeats: () => Promise<void>;
+	/** Whether change streams are currently active */
+	isChangeStreamActive: () => boolean;
 }
 
 /**
  * Manages scheduler lifecycle timers and job cleanup.
  *
- * Owns poll interval, heartbeat interval, cleanup interval, and the
+ * Owns poll scheduling, heartbeat interval, cleanup interval, and the
  * cleanupJobs logic. Extracted from Monque to keep the facade thin.
  *
+ * Uses adaptive poll scheduling: when change streams are active, polls at
+ * `safetyPollInterval` (safety net only). When change streams are inactive,
+ * polls at `pollInterval` (primary discovery mechanism).
+ *
  * @internal Not part of public API.
  */
 export class LifecycleManager {
 	private readonly ctx: SchedulerContext;
-	private pollIntervalId: ReturnType<typeof setInterval> | null = null;
+	private callbacks: TimerCallbacks | null = null;
+	private pollTimeoutId: ReturnType<typeof setTimeout> | null = null;
 	private heartbeatIntervalId: ReturnType<typeof setInterval> | null = null;
 	private cleanupIntervalId: ReturnType<typeof setInterval> | null = null;
 
@@ -44,18 +56,13 @@ export class LifecycleManager {
 	/**
 	 * Start all lifecycle timers.
 	 *
-	 * Sets up poll interval, heartbeat interval, and (if configured)
+	 * Sets up adaptive poll scheduling, heartbeat interval, and (if configured)
 	 * cleanup interval. Runs an initial poll immediately.
 	 *
 	 * @param callbacks - Functions to invoke on each timer tick
 	 */
 	startTimers(callbacks: TimerCallbacks): void {
-		// Set up polling as backup (runs at configured interval)
-		this.pollIntervalId = setInterval(() => {
-			callbacks.poll().catch((error: unknown) => {
-				this.ctx.emit('job:error', { error: toError(error) });
-			});
-		}, this.ctx.options.pollInterval);
+		this.callbacks = callbacks;
 
 		// Start heartbeat interval for claimed jobs
 		this.heartbeatIntervalId = setInterval(() => {
@@ -80,26 +87,26 @@ export class LifecycleManager {
 			}, interval);
 		}
 
-		// Run initial poll immediately to pick up any existing jobs
-		callbacks.poll().catch((error: unknown) => {
-			this.ctx.emit('job:error', { error: toError(error) });
-		});
+		// Run initial poll immediately, then schedule the next one adaptively
+		this.executePollAndScheduleNext();
 	}
 
 	/**
 	 * Stop all lifecycle timers.
 	 *
-	 * Clears poll, heartbeat, and cleanup intervals.
+	 * Clears poll timeout, heartbeat interval, and cleanup interval.
 	 */
 	stopTimers(): void {
+		this.callbacks = null;
+
 		if (this.cleanupIntervalId) {
 			clearInterval(this.cleanupIntervalId);
 			this.cleanupIntervalId = null;
 		}
 
-		if (this.pollIntervalId) {
-			clearInterval(this.pollIntervalId);
-			this.pollIntervalId = null;
+		if (this.pollTimeoutId) {
+			clearTimeout(this.pollTimeoutId);
+			this.pollTimeoutId = null;
 		}
 
 		if (this.heartbeatIntervalId) {
@@ -108,6 +115,59 @@ export class LifecycleManager {
 		}
 	}
 
+	/**
+	 * Reset the poll timer to reschedule the next poll.
+	 *
+	 * Called after change-stream-triggered polls to ensure the safety poll timer
+	 * is recalculated (not fired redundantly from an old schedule).
+	 */
+	resetPollTimer(): void {
+		this.scheduleNextPoll();
+	}
+
+	/**
+	 * Execute a poll and schedule the next one adaptively.
+	 */
+	private executePollAndScheduleNext(): void {
+		if (!this.callbacks) {
+			return;
+		}
+
+		this.callbacks
+			.poll()
+			.catch((error: unknown) => {
+				this.ctx.emit('job:error', { error: toError(error) });
+			})
+			.finally(() => {
+				this.scheduleNextPoll();
+			});
+	}
+
+	/**
+	 * Schedule the next poll using adaptive timing.
+	 *
+	 * When change streams are active, uses `safetyPollInterval` (longer, safety net only).
+	 * When change streams are inactive, uses `pollInterval` (shorter, primary discovery).
+	 */
+	private scheduleNextPoll(): void {
+		if (this.pollTimeoutId) {
+			clearTimeout(this.pollTimeoutId);
+			this.pollTimeoutId = null;
+		}
+
+		if (!this.ctx.isRunning() || !this.callbacks) {
+			return;
+		}
+
+		const delay = this.callbacks.isChangeStreamActive()
+			? this.ctx.options.safetyPollInterval
+			: this.ctx.options.pollInterval;
+
+		this.pollTimeoutId = setTimeout(() => {
+			this.executePollAndScheduleNext();
+		}, delay);
+	}
+
 	/**
 	 * Clean up old completed and failed jobs based on retention policy.
 	 *

package/src/scheduler/services/types.ts

@@ -30,6 +30,7 @@ export interface ResolvedMonqueOptions
 		> {
 	// Ensure resolved options use the new naming convention
 	workerConcurrency: number;
+	safetyPollInterval: number;
 }
 /**
  * Shared context provided to all internal Monque services.
@@ -59,6 +60,12 @@ export interface SchedulerContext {
 	/** Type-safe event emitter */
 	emit: <K extends keyof MonqueEventMap>(event: K, payload: MonqueEventMap[K]) => boolean;
 
+	/** 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/scheduler/types.ts

@@ -196,4 +196,18 @@ export interface MonqueOptions {
 	 * @default 5000
 	 */
 	statsCacheTtlMs?: number;
+
+	/**
+	 * Interval in milliseconds between safety polls when change streams are active.
+	 *
+	 * When change streams are connected, the scheduler uses them as the primary
+	 * notification mechanism and only polls at this longer interval as a safety net
+	 * to catch any missed events. When change streams are unavailable, the scheduler
+	 * falls back to the standard `pollInterval`.
+	 *
+	 * This is separate from `heartbeatInterval`, which updates job liveness signals.
+	 *
+	 * @default 30000 (30 seconds)
+	 */
+	safetyPollInterval?: number;
 }

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.',
+		);
+	}
+}