@monque/core 1.1.0 → 1.1.2

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

@@ -0,0 +1,239 @@
+import type { ChangeStream, ChangeStreamDocument, Document } from 'mongodb';
+
+import { JobStatus } from '@/jobs';
+
+import type { SchedulerContext } from './types.js';
+
+/**
+ * Internal service for MongoDB Change Stream lifecycle.
+ *
+ * Provides real-time job notifications when available, with automatic
+ * reconnection and graceful fallback to polling-only mode.
+ *
+ * @internal Not part of public API.
+ */
+export class ChangeStreamHandler {
+	/** MongoDB Change Stream for real-time job notifications */
+	private changeStream: ChangeStream | null = null;
+
+	/** Number of consecutive reconnection attempts */
+	private reconnectAttempts = 0;
+
+	/** Maximum reconnection attempts before falling back to polling-only mode */
+	private readonly maxReconnectAttempts = 3;
+
+	/** Debounce timer for change stream event processing */
+	private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+
+	/** Timer ID for reconnection with exponential backoff */
+	private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+	/** Whether the scheduler is currently using change streams */
+	private usingChangeStreams = false;
+
+	constructor(
+		private readonly ctx: SchedulerContext,
+		private readonly onPoll: () => Promise<void>,
+	) {}
+
+	/**
+	 * Set up MongoDB Change Stream for real-time job notifications.
+	 *
+	 * Change streams provide instant notifications when jobs are inserted or when
+	 * job status changes to pending (e.g., after a retry). This eliminates the
+	 * polling delay for reactive job processing.
+	 *
+	 * The change stream watches for:
+	 * - Insert operations (new jobs)
+	 * - Update operations where status field changes
+	 *
+	 * If change streams are unavailable (e.g., standalone MongoDB), the system
+	 * gracefully falls back to polling-only mode.
+	 */
+	setup(): void {
+		if (!this.ctx.isRunning()) {
+			return;
+		}
+
+		try {
+			// Create change stream with pipeline to filter relevant events
+			const pipeline = [
+				{
+					$match: {
+						$or: [
+							{ operationType: 'insert' },
+							{
+								operationType: 'update',
+								'updateDescription.updatedFields.status': { $exists: true },
+							},
+						],
+					},
+				},
+			];
+
+			this.changeStream = this.ctx.collection.watch(pipeline, {
+				fullDocument: 'updateLookup',
+			});
+
+			// Handle change events
+			this.changeStream.on('change', (change) => {
+				this.handleEvent(change);
+			});
+
+			// Handle errors with reconnection
+			this.changeStream.on('error', (error: Error) => {
+				this.ctx.emit('changestream:error', { error });
+				this.handleError(error);
+			});
+
+			// Mark as connected
+			this.usingChangeStreams = true;
+			this.reconnectAttempts = 0;
+			this.ctx.emit('changestream:connected', undefined);
+		} catch (error) {
+			// Change streams not available (e.g., standalone MongoDB)
+			this.usingChangeStreams = false;
+			const reason = error instanceof Error ? error.message : 'Unknown error';
+			this.ctx.emit('changestream:fallback', { reason });
+		}
+	}
+
+	/**
+	 * Handle a change stream event by triggering a debounced poll.
+	 *
+	 * Events are debounced to prevent "claim storms" when multiple changes arrive
+	 * in rapid succession (e.g., bulk job inserts). A 100ms debounce window
+	 * collects multiple events and triggers a single poll.
+	 *
+	 * @param change - The change stream event document
+	 */
+	handleEvent(change: ChangeStreamDocument<Document>): void {
+		if (!this.ctx.isRunning()) {
+			return;
+		}
+
+		// Trigger poll on insert (new job) or update where status changes
+		const isInsert = change.operationType === 'insert';
+		const isUpdate = change.operationType === 'update';
+
+		// Get fullDocument if available (for insert or with updateLookup option)
+		const fullDocument = 'fullDocument' in change ? change.fullDocument : undefined;
+		const isPendingStatus = fullDocument?.['status'] === JobStatus.PENDING;
+
+		// For inserts: always trigger since new pending jobs need processing
+		// For updates: trigger if status changed to pending (retry/release scenario)
+		const shouldTrigger = isInsert || (isUpdate && isPendingStatus);
+
+		if (shouldTrigger) {
+			// Debounce poll triggers to avoid claim storms
+			if (this.debounceTimer) {
+				clearTimeout(this.debounceTimer);
+			}
+
+			this.debounceTimer = setTimeout(() => {
+				this.debounceTimer = null;
+				this.onPoll().catch((error: unknown) => {
+					this.ctx.emit('job:error', { error: error as Error });
+				});
+			}, 100);
+		}
+	}
+
+	/**
+	 * Handle change stream errors with exponential backoff reconnection.
+	 *
+	 * Attempts to reconnect up to `maxReconnectAttempts` times with
+	 * exponential backoff (base 1000ms). After exhausting retries, falls back to
+	 * polling-only mode.
+	 *
+	 * @param error - The error that caused the change stream failure
+	 */
+	handleError(error: Error): void {
+		if (!this.ctx.isRunning()) {
+			return;
+		}
+
+		this.reconnectAttempts++;
+
+		if (this.reconnectAttempts > this.maxReconnectAttempts) {
+			// Fall back to polling-only mode
+			this.usingChangeStreams = false;
+
+			if (this.reconnectTimer) {
+				clearTimeout(this.reconnectTimer);
+				this.reconnectTimer = null;
+			}
+
+			if (this.changeStream) {
+				this.changeStream.close().catch(() => {});
+				this.changeStream = null;
+			}
+
+			this.ctx.emit('changestream:fallback', {
+				reason: `Exhausted ${this.maxReconnectAttempts} reconnection attempts: ${error.message}`,
+			});
+
+			return;
+		}
+
+		// Exponential backoff: 1s, 2s, 4s
+		const delay = 2 ** (this.reconnectAttempts - 1) * 1000;
+
+		// Clear any existing reconnect timer before scheduling a new one
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+		}
+
+		this.reconnectTimer = setTimeout(() => {
+			this.reconnectTimer = null;
+			if (this.ctx.isRunning()) {
+				// Close existing change stream before reconnecting
+				if (this.changeStream) {
+					this.changeStream.close().catch(() => {});
+					this.changeStream = null;
+				}
+				this.setup();
+			}
+		}, delay);
+	}
+
+	/**
+	 * Close the change stream cursor and emit closed event.
+	 */
+	async close(): Promise<void> {
+		// Clear debounce timer
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+
+		// Clear reconnection timer
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = null;
+		}
+
+		if (this.changeStream) {
+			try {
+				await this.changeStream.close();
+			} catch {
+				// Ignore close errors during shutdown
+			}
+			this.changeStream = null;
+
+			if (this.usingChangeStreams) {
+				this.ctx.emit('changestream:closed', undefined);
+			}
+		}
+
+		this.usingChangeStreams = false;
+		this.reconnectAttempts = 0;
+	}
+
+	/**
+	 * Check if change streams are currently active.
+	 */
+	isActive(): boolean {
+		return this.usingChangeStreams;
+	}
+}

package/src/scheduler/services/index.ts

@@ -0,0 +1,8 @@
+// Services
+export { ChangeStreamHandler } from './change-stream-handler.js';
+export { JobManager } from './job-manager.js';
+export { JobProcessor } from './job-processor.js';
+export { JobQueryService } from './job-query.js';
+export { JobScheduler } from './job-scheduler.js';
+// Types
+export type { ResolvedMonqueOptions, SchedulerContext } from './types.js';

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

@@ -0,0 +1,455 @@
+import { ObjectId, type WithId } from 'mongodb';
+
+import {
+	type BulkOperationResult,
+	type Job,
+	type JobSelector,
+	JobStatus,
+	type PersistedJob,
+} from '@/jobs';
+import { buildSelectorQuery } from '@/scheduler';
+import { JobStateError } from '@/shared';
+
+import type { SchedulerContext } from './types.js';
+
+/**
+ * Internal service for job lifecycle management operations.
+ *
+ * Provides atomic state transitions (cancel, retry, reschedule) and deletion.
+ * Emits appropriate events on each operation.
+ *
+ * @internal Not part of public API - use Monque class methods instead.
+ */
+export class JobManager {
+	constructor(private readonly ctx: SchedulerContext) {}
+
+	/**
+	 * Cancel a pending or scheduled job.
+	 *
+	 * Sets the job status to 'cancelled' and emits a 'job:cancelled' event.
+	 * If the job is already cancelled, this is a no-op and returns the job.
+	 * Cannot cancel jobs that are currently 'processing', 'completed', or 'failed'.
+	 *
+	 * @param jobId - The ID of the job to cancel
+	 * @returns The cancelled job, or null if not found
+	 * @throws {JobStateError} If job is in an invalid state for cancellation
+	 *
+	 * @example Cancel a pending job
+	 * ```typescript
+	 * const job = await monque.enqueue('report', { type: 'daily' });
+	 * await monque.cancelJob(job._id.toString());
+	 * ```
+	 */
+	async cancelJob(jobId: string): Promise<PersistedJob<unknown> | null> {
+		if (!ObjectId.isValid(jobId)) return null;
+
+		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;
+
+		const currentJob = jobDoc as unknown as WithId<Job>;
+
+		if (currentJob.status === JobStatus.CANCELLED) {
+			return this.ctx.documentToPersistedJob(currentJob);
+		}
+
+		if (currentJob.status !== JobStatus.PENDING) {
+			throw new JobStateError(
+				`Cannot cancel job in status '${currentJob.status}'`,
+				jobId,
+				currentJob.status,
+				'cancel',
+			);
+		}
+
+		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',
+			);
+		}
+
+		const job = this.ctx.documentToPersistedJob(result);
+		this.ctx.emit('job:cancelled', { job });
+		return job;
+	}
+
+	/**
+	 * Retry a failed or cancelled job.
+	 *
+	 * Resets the job to 'pending' status, clears failure count/reason, and sets
+	 * nextRunAt to now (immediate retry). Emits a 'job:retried' event.
+	 *
+	 * @param jobId - The ID of the job to retry
+	 * @returns The updated job, or null if not found
+	 * @throws {JobStateError} If job is in an invalid state for retry (must be failed or cancelled)
+	 *
+	 * @example Retry a failed job
+	 * ```typescript
+	 * monque.on('job:fail', async ({ job }) => {
+	 *   console.log(`Job ${job._id} failed, retrying manually...`);
+	 *   await monque.retryJob(job._id.toString());
+	 * });
+	 * ```
+	 */
+	async retryJob(jobId: string): Promise<PersistedJob<unknown> | null> {
+		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',
+			);
+		}
+
+		const previousStatus = currentJob['status'] as 'failed' | 'cancelled';
+
+		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' },
+		);
+
+		if (!result) {
+			throw new JobStateError('Job status changed during retry attempt', jobId, 'unknown', 'retry');
+		}
+
+		const job = this.ctx.documentToPersistedJob(result);
+		this.ctx.emit('job:retried', { job, previousStatus });
+		return job;
+	}
+
+	/**
+	 * Reschedule a pending job to run at a different time.
+	 *
+	 * Only works for jobs in 'pending' status.
+	 *
+	 * @param jobId - The ID of the job to reschedule
+	 * @param runAt - The new Date when the job should run
+	 * @returns The updated job, or null if not found
+	 * @throws {JobStateError} If job is not in pending state
+	 *
+	 * @example Delay a job by 1 hour
+	 * ```typescript
+	 * const nextHour = new Date(Date.now() + 60 * 60 * 1000);
+	 * await monque.rescheduleJob(jobId, nextHour);
+	 * ```
+	 */
+	async rescheduleJob(jobId: string, runAt: Date): Promise<PersistedJob<unknown> | null> {
+		if (!ObjectId.isValid(jobId)) return null;
+
+		const _id = new ObjectId(jobId);
+		const currentJobDoc = await this.ctx.collection.findOne({ _id });
+
+		if (!currentJobDoc) return null;
+
+		const currentJob = currentJobDoc as unknown as WithId<Job>;
+
+		if (currentJob.status !== JobStatus.PENDING) {
+			throw new JobStateError(
+				`Cannot reschedule job in status '${currentJob.status}'`,
+				jobId,
+				currentJob.status,
+				'reschedule',
+			);
+		}
+
+		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',
+			);
+		}
+
+		return this.ctx.documentToPersistedJob(result);
+	}
+
+	/**
+	 * Permanently delete a job.
+	 *
+	 * This action is irreversible. Emits a 'job:deleted' event upon success.
+	 * Can delete a job in any state.
+	 *
+	 * @param jobId - The ID of the job to delete
+	 * @returns true if deleted, false if job not found
+	 *
+	 * @example Delete a cleanup job
+	 * ```typescript
+	 * const deleted = await monque.deleteJob(jobId);
+	 * if (deleted) {
+	 *   console.log('Job permanently removed');
+	 * }
+	 * ```
+	 */
+	async deleteJob(jobId: string): Promise<boolean> {
+		if (!ObjectId.isValid(jobId)) return false;
+
+		const _id = new ObjectId(jobId);
+
+		const result = await this.ctx.collection.deleteOne({ _id });
+
+		if (result.deletedCount > 0) {
+			this.ctx.emit('job:deleted', { jobId });
+			return true;
+		}
+
+		return false;
+	}
+
+	// ─────────────────────────────────────────────────────────────────────────────
+	// Bulk Operations
+	// ─────────────────────────────────────────────────────────────────────────────
+
+	/**
+	 * Cancel multiple jobs matching the given filter.
+	 *
+	 * Only cancels jobs in 'pending' status. Jobs in other states are collected
+	 * as errors in the result. Emits a 'jobs:cancelled' event with the IDs of
+	 * successfully cancelled jobs.
+	 *
+	 * @param filter - Selector for which jobs to cancel (name, status, date range)
+	 * @returns Result with count of cancelled jobs and any errors encountered
+	 *
+	 * @example Cancel all pending jobs for a queue
+	 * ```typescript
+	 * const result = await monque.cancelJobs({
+	 *   name: 'email-queue',
+	 *   status: 'pending'
+	 * });
+	 * console.log(`Cancelled ${result.count} jobs`);
+	 * ```
+	 */
+	async cancelJobs(filter: JobSelector): Promise<BulkOperationResult> {
+		const baseQuery = buildSelectorQuery(filter);
+		const errors: Array<{ jobId: string; error: string }> = [];
+		const cancelledIds: string[] = [];
+
+		// Find all matching jobs and stream them to avoid memory pressure
+		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();
+
+			if (job.status !== JobStatus.PENDING && job.status !== JobStatus.CANCELLED) {
+				errors.push({
+					jobId,
+					error: `Cannot cancel job in status '${job.status}'`,
+				});
+				continue;
+			}
+
+			// Skip already cancelled jobs (idempotent)
+			if (job.status === JobStatus.CANCELLED) {
+				cancelledIds.push(jobId);
+				continue;
+			}
+
+			// Atomically update to cancelled
+			const result = await this.ctx.collection.findOneAndUpdate(
+				{ _id: job._id, status: JobStatus.PENDING },
+				{
+					$set: {
+						status: JobStatus.CANCELLED,
+						updatedAt: new Date(),
+					},
+				},
+				{ returnDocument: 'after' },
+			);
+
+			if (result) {
+				cancelledIds.push(jobId);
+			} else {
+				// Race condition: status changed
+				errors.push({
+					jobId,
+					error: 'Job status changed during cancellation',
+				});
+			}
+		}
+
+		if (cancelledIds.length > 0) {
+			this.ctx.emit('jobs:cancelled', {
+				jobIds: cancelledIds,
+				count: cancelledIds.length,
+			});
+		}
+
+		return {
+			count: cancelledIds.length,
+			errors,
+		};
+	}
+
+	/**
+	 * Retry multiple jobs matching the given filter.
+	 *
+	 * Only retries jobs in 'failed' or 'cancelled' status. Jobs in other states
+	 * are collected as errors in the result. Emits a 'jobs:retried' event with
+	 * the IDs of successfully retried jobs.
+	 *
+	 * @param filter - Selector for which jobs to retry (name, status, date range)
+	 * @returns Result with count of retried jobs and any errors encountered
+	 *
+	 * @example Retry all failed jobs
+	 * ```typescript
+	 * const result = await monque.retryJobs({
+	 *   status: 'failed'
+	 * });
+	 * console.log(`Retried ${result.count} jobs`);
+	 * ```
+	 */
+	async retryJobs(filter: JobSelector): Promise<BulkOperationResult> {
+		const baseQuery = buildSelectorQuery(filter);
+		const errors: Array<{ jobId: string; error: string }> = [];
+		const retriedIds: string[] = [];
+
+		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();
+
+			if (job.status !== JobStatus.FAILED && job.status !== JobStatus.CANCELLED) {
+				errors.push({
+					jobId,
+					error: `Cannot retry job in status '${job.status}'`,
+				});
+				continue;
+			}
+
+			const result = await this.ctx.collection.findOneAndUpdate(
+				{
+					_id: job._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' },
+			);
+
+			if (result) {
+				retriedIds.push(jobId);
+			} else {
+				errors.push({
+					jobId,
+					error: 'Job status changed during retry attempt',
+				});
+			}
+		}
+
+		if (retriedIds.length > 0) {
+			this.ctx.emit('jobs:retried', {
+				jobIds: retriedIds,
+				count: retriedIds.length,
+			});
+		}
+
+		return {
+			count: retriedIds.length,
+			errors,
+		};
+	}
+
+	/**
+	 * Delete multiple jobs matching the given filter.
+	 *
+	 * Deletes jobs in any status. Uses a batch delete for efficiency.
+	 * Emits a 'jobs:deleted' event with the count of deleted jobs.
+	 * Does not emit individual 'job:deleted' events to avoid noise.
+	 *
+	 * @param filter - Selector for which jobs to delete (name, status, date range)
+	 * @returns Result with count of deleted jobs (errors array always empty for delete)
+	 *
+	 * @example Delete old completed jobs
+	 * ```typescript
+	 * const weekAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+	 * const result = await monque.deleteJobs({
+	 *   status: 'completed',
+	 *   olderThan: weekAgo
+	 * });
+	 * console.log(`Deleted ${result.count} jobs`);
+	 * ```
+	 */
+	async deleteJobs(filter: JobSelector): Promise<BulkOperationResult> {
+		const query = buildSelectorQuery(filter);
+
+		// Use deleteMany for efficiency
+		const result = await this.ctx.collection.deleteMany(query);
+
+		if (result.deletedCount > 0) {
+			this.ctx.emit('jobs:deleted', { count: result.deletedCount });
+		}
+
+		return {
+			count: result.deletedCount,
+			errors: [],
+		};
+	}
+}