@monque/core 1.1.0 → 1.1.2

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

@@ -0,0 +1,267 @@
+import type { Document } from 'mongodb';
+
+import {
+	type EnqueueOptions,
+	type Job,
+	JobStatus,
+	type PersistedJob,
+	type ScheduleOptions,
+} from '@/jobs';
+import { ConnectionError, getNextCronDate, MonqueError } from '@/shared';
+
+import type { SchedulerContext } from './types.js';
+
+/**
+ * Internal service for job scheduling operations.
+ *
+ * Handles enqueueing new jobs, immediate dispatch, and cron scheduling.
+ * All operations are atomic and support deduplication via uniqueKey.
+ *
+ * @internal Not part of public API - use Monque class methods instead.
+ */
+export class JobScheduler {
+	constructor(private readonly ctx: SchedulerContext) {}
+
+	/**
+	 * Enqueue a job for processing.
+	 *
+	 * Jobs are stored in MongoDB and processed by registered workers. Supports
+	 * delayed execution via `runAt` and deduplication via `uniqueKey`.
+	 *
+	 * When a `uniqueKey` is provided, only one pending or processing job with that key
+	 * can exist. Completed or failed jobs don't block new jobs with the same key.
+	 *
+	 * Failed jobs are automatically retried with exponential backoff up to `maxRetries`
+	 * (default: 10 attempts). The delay between retries is calculated as `2^failCount × baseRetryInterval`.
+	 *
+	 * @template T - The job data payload type (must be JSON-serializable)
+	 * @param name - Job type identifier, must match a registered worker
+	 * @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 {ConnectionError} If database operation fails or scheduler not initialized
+	 *
+	 * @example Basic job enqueueing
+	 * ```typescript
+	 * await monque.enqueue('send-email', {
+	 *   to: 'user@example.com',
+	 *   subject: 'Welcome!',
+	 *   body: 'Thanks for signing up.'
+	 * });
+	 * ```
+	 *
+	 * @example Delayed execution
+	 * ```typescript
+	 * const oneHourLater = new Date(Date.now() + 3600000);
+	 * await monque.enqueue('reminder', { message: 'Check in!' }, {
+	 *   runAt: oneHourLater
+	 * });
+	 * ```
+	 *
+	 * @example Prevent duplicates with unique key
+	 * ```typescript
+	 * await monque.enqueue('sync-user', { userId: '123' }, {
+	 *   uniqueKey: 'sync-user-123'
+	 * });
+	 * // Subsequent enqueues with same uniqueKey return existing pending/processing job
+	 * ```
+	 */
+	async enqueue<T>(name: string, data: T, options: EnqueueOptions = {}): Promise<PersistedJob<T>> {
+		const now = new Date();
+		const job: Omit<Job<T>, '_id'> = {
+			name,
+			data,
+			status: JobStatus.PENDING,
+			nextRunAt: options.runAt ?? now,
+			failCount: 0,
+			createdAt: now,
+			updatedAt: now,
+		};
+
+		if (options.uniqueKey) {
+			job.uniqueKey = options.uniqueKey;
+		}
+
+		try {
+			if (options.uniqueKey) {
+				// Use upsert with $setOnInsert for deduplication (scoped by name + uniqueKey)
+				const result = await this.ctx.collection.findOneAndUpdate(
+					{
+						name,
+						uniqueKey: options.uniqueKey,
+						status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] },
+					},
+					{
+						$setOnInsert: job,
+					},
+					{
+						upsert: true,
+						returnDocument: 'after',
+					},
+				);
+
+				if (!result) {
+					throw new ConnectionError('Failed to enqueue job: findOneAndUpdate returned no document');
+				}
+
+				return this.ctx.documentToPersistedJob<T>(result);
+			}
+
+			const result = await this.ctx.collection.insertOne(job as Document);
+
+			return { ...job, _id: result.insertedId } as PersistedJob<T>;
+		} catch (error) {
+			if (error instanceof ConnectionError) {
+				throw error;
+			}
+			const message = error instanceof Error ? error.message : 'Unknown error during enqueue';
+			throw new ConnectionError(
+				`Failed to enqueue job: ${message}`,
+				error instanceof Error ? { cause: error } : undefined,
+			);
+		}
+	}
+
+	/**
+	 * Enqueue a job for immediate processing.
+	 *
+	 * Convenience method equivalent to `enqueue(name, data, { runAt: new Date() })`.
+	 * Jobs are picked up on the next poll cycle (typically within 1 second based on `pollInterval`).
+	 *
+	 * @template T - The job data payload type (must be JSON-serializable)
+	 * @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 {ConnectionError} If database operation fails or scheduler not initialized
+	 *
+	 * @example Send email immediately
+	 * ```typescript
+	 * await monque.now('send-email', {
+	 *   to: 'admin@example.com',
+	 *   subject: 'Alert',
+	 *   body: 'Immediate attention required'
+	 * });
+	 * ```
+	 *
+	 * @example Process order in background
+	 * ```typescript
+	 * const order = await createOrder(data);
+	 * await monque.now('process-order', { orderId: order.id });
+	 * return order; // Return immediately, processing happens async
+	 * ```
+	 */
+	async now<T>(name: string, data: T): Promise<PersistedJob<T>> {
+		return this.enqueue(name, data, { runAt: new Date() });
+	}
+
+	/**
+	 * Schedule a recurring job with a cron expression.
+	 *
+	 * Creates a job that automatically re-schedules itself based on the cron pattern.
+	 * Uses standard 5-field cron format: minute, hour, day of month, month, day of week.
+	 * Also supports predefined expressions like `@daily`, `@weekly`, `@monthly`, etc.
+	 * After successful completion, the job is reset to `pending` status and scheduled
+	 * for its next run based on the cron expression.
+	 *
+	 * When a `uniqueKey` is provided, only one pending or processing job with that key
+	 * can exist. This prevents duplicate scheduled jobs on application restart.
+	 *
+	 * @template T - The job data payload type (must be JSON-serializable)
+	 * @param cron - Cron expression (5 fields or predefined expression)
+	 * @param name - Job type identifier, must match a registered worker
+	 * @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 {InvalidCronError} If cron expression is invalid
+	 * @throws {ConnectionError} If database operation fails or scheduler not initialized
+	 *
+	 * @example Hourly cleanup job
+	 * ```typescript
+	 * await monque.schedule('0 * * * *', 'cleanup-temp-files', {
+	 *   directory: '/tmp/uploads'
+	 * });
+	 * ```
+	 *
+	 * @example Prevent duplicate scheduled jobs with unique key
+	 * ```typescript
+	 * await monque.schedule('0 * * * *', 'hourly-report', { type: 'sales' }, {
+	 *   uniqueKey: 'hourly-report-sales'
+	 * });
+	 * // Subsequent calls with same uniqueKey return existing pending/processing job
+	 * ```
+	 *
+	 * @example Daily report at midnight (using predefined expression)
+	 * ```typescript
+	 * await monque.schedule('@daily', 'daily-report', {
+	 *   reportType: 'sales',
+	 *   recipients: ['analytics@example.com']
+	 * });
+	 * ```
+	 */
+	async schedule<T>(
+		cron: string,
+		name: string,
+		data: T,
+		options: ScheduleOptions = {},
+	): Promise<PersistedJob<T>> {
+		// Validate cron and get next run date (throws InvalidCronError if invalid)
+		const nextRunAt = getNextCronDate(cron);
+
+		const now = new Date();
+		const job: Omit<Job<T>, '_id'> = {
+			name,
+			data,
+			status: JobStatus.PENDING,
+			nextRunAt,
+			repeatInterval: cron,
+			failCount: 0,
+			createdAt: now,
+			updatedAt: now,
+		};
+
+		if (options.uniqueKey) {
+			job.uniqueKey = options.uniqueKey;
+		}
+
+		try {
+			if (options.uniqueKey) {
+				// Use upsert with $setOnInsert for deduplication (scoped by name + uniqueKey)
+				const result = await this.ctx.collection.findOneAndUpdate(
+					{
+						name,
+						uniqueKey: options.uniqueKey,
+						status: { $in: [JobStatus.PENDING, JobStatus.PROCESSING] },
+					},
+					{
+						$setOnInsert: job,
+					},
+					{
+						upsert: true,
+						returnDocument: 'after',
+					},
+				);
+
+				if (!result) {
+					throw new ConnectionError(
+						'Failed to schedule job: findOneAndUpdate returned no document',
+					);
+				}
+
+				return this.ctx.documentToPersistedJob<T>(result);
+			}
+
+			const result = await this.ctx.collection.insertOne(job as Document);
+
+			return { ...job, _id: result.insertedId } as PersistedJob<T>;
+		} catch (error) {
+			if (error instanceof MonqueError) {
+				throw error;
+			}
+			const message = error instanceof Error ? error.message : 'Unknown error during schedule';
+			throw new ConnectionError(
+				`Failed to schedule job: ${message}`,
+				error instanceof Error ? { cause: error } : undefined,
+			);
+		}
+	}
+}

package/src/scheduler/services/types.ts

@@ -0,0 +1,48 @@
+import type { Collection, Document, WithId } from 'mongodb';
+
+import type { MonqueEventMap } from '@/events';
+import type { PersistedJob } from '@/jobs';
+import type { WorkerRegistration } from '@/workers';
+
+import type { MonqueOptions } from '../types.js';
+
+/**
+ * Resolved Monque options with all defaults applied.
+ *
+ * Required options have their defaults filled in, while truly optional
+ * options (`maxBackoffDelay`, `jobRetention`) remain optional.
+ */
+export interface ResolvedMonqueOptions
+	extends Required<Omit<MonqueOptions, 'maxBackoffDelay' | 'jobRetention'>>,
+		Pick<MonqueOptions, 'maxBackoffDelay' | 'jobRetention'> {}
+/**
+ * Shared context provided to all internal Monque services.
+ *
+ * Contains references to shared state, configuration, and utilities
+ * needed by service methods. Passed to service constructors to enable
+ * access to the collection, options, and event emission.
+ *
+ * @internal Not part of public API.
+ */
+export interface SchedulerContext {
+	/** MongoDB collection for jobs */
+	collection: Collection<Document>;
+
+	/** Resolved scheduler options with defaults applied */
+	options: ResolvedMonqueOptions;
+
+	/** Unique identifier for this scheduler instance (for claiming jobs) */
+	instanceId: string;
+
+	/** Registered workers by job name */
+	workers: Map<string, WorkerRegistration>;
+
+	/** Whether the scheduler is currently running */
+	isRunning: () => boolean;
+
+	/** Type-safe event emitter */
+	emit: <K extends keyof MonqueEventMap>(event: K, payload: MonqueEventMap[K]) => boolean;
+
+	/** Convert MongoDB document to typed PersistedJob */
+	documentToPersistedJob: <T>(doc: WithId<Document>) => PersistedJob<T>;
+}

package/src/scheduler/types.ts

@@ -0,0 +1,123 @@
+/**
+ * Configuration options for the Monque scheduler.
+ *
+ * @example
+ * ```typescript
+ * const monque = new Monque(db, {
+ *   collectionName: 'jobs',
+ *   pollInterval: 1000,
+ *   maxRetries: 10,
+ *   baseRetryInterval: 1000,
+ *   shutdownTimeout: 30000,
+ *   defaultConcurrency: 5,
+ * });
+ * ```
+ */
+export interface MonqueOptions {
+	/**
+	 * Name of the MongoDB collection for storing jobs.
+	 * @default 'monque_jobs'
+	 */
+	collectionName?: string;
+
+	/**
+	 * Interval in milliseconds between polling for new jobs.
+	 * @default 1000
+	 */
+	pollInterval?: number;
+
+	/**
+	 * Maximum number of retry attempts before marking a job as permanently failed.
+	 * @default 10
+	 */
+	maxRetries?: number;
+
+	/**
+	 * Base interval in milliseconds for exponential backoff calculation.
+	 * Actual delay = 2^failCount * baseRetryInterval
+	 * @default 1000
+	 */
+	baseRetryInterval?: number;
+
+	/**
+	 * Maximum delay in milliseconds for exponential backoff.
+	 * If calculated delay exceeds this value, it will be capped.
+	 *
+	 * Defaults to 24 hours to prevent unbounded delays.
+	 * @default 86400000 (24 hours)
+	 */
+	maxBackoffDelay?: number | undefined;
+
+	/**
+	 * Timeout in milliseconds for graceful shutdown.
+	 * @default 30000
+	 */
+	shutdownTimeout?: number;
+
+	/**
+	 * Default number of concurrent jobs per worker.
+	 * @default 5
+	 */
+	defaultConcurrency?: number;
+
+	/**
+	 * Maximum time in milliseconds a job can be in 'processing' status before
+	 * being considered stale and eligible for recovery.
+	 *
+	 * Stale recovery uses `lockedAt` as the source of truth; this is an absolute
+	 * “time locked” limit, not a heartbeat timeout.
+	 * @default 1800000 (30 minutes)
+	 */
+	lockTimeout?: number;
+
+	/**
+	 * Unique identifier for this scheduler instance.
+	 * Used for atomic job claiming - each instance uses this ID to claim jobs.
+	 * Defaults to a randomly generated UUID v4.
+	 * @default crypto.randomUUID()
+	 */
+	schedulerInstanceId?: string;
+
+	/**
+	 * Interval in milliseconds for heartbeat updates during job processing.
+	 * The scheduler periodically updates `lastHeartbeat` for all jobs it is processing
+	 * to indicate liveness for monitoring/debugging.
+	 *
+	 * Note: stale recovery is based on `lockedAt` + `lockTimeout`, not `lastHeartbeat`.
+	 * @default 30000 (30 seconds)
+	 */
+	heartbeatInterval?: number;
+
+	/**
+	 * Whether to recover stale processing jobs on scheduler startup.
+	 * When true, jobs with lockedAt older than lockTimeout will be reset to pending.
+	 * @default true
+	 */
+	recoverStaleJobs?: boolean;
+
+	/**
+	 * Configuration for automatic cleanup of completed and failed jobs.
+	 * If undefined, no cleanup is performed.
+	 */
+	jobRetention?:
+		| {
+				/**
+				 * Age in milliseconds after which completed jobs are deleted.
+				 * Cleaned up based on 'updatedAt' timestamp.
+				 */
+				completed?: number;
+
+				/**
+				 * Age in milliseconds after which failed jobs are deleted.
+				 * Cleaned up based on 'updatedAt' timestamp.
+				 */
+				failed?: number;
+
+				/**
+				 * Interval in milliseconds for running the cleanup job.
+				 * @default 3600000 (1 hour)
+				 */
+				interval?: number;
+		  }
+		| undefined;
+}

package/src/shared/errors.ts

@@ -0,0 +1,225 @@
+import type { Job } from '@/jobs';
+
+/**
+ * Base error class for all Monque-related errors.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await monque.enqueue('job', data);
+ * } catch (error) {
+ *   if (error instanceof MonqueError) {
+ *     console.error('Monque error:', error.message);
+ *   }
+ * }
+ * ```
+ */
+export class MonqueError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = 'MonqueError';
+		// Maintains proper stack trace for where our error was thrown (only available on V8)
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, MonqueError);
+		}
+	}
+}
+
+/**
+ * Error thrown when an invalid cron expression is provided.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await monque.schedule('invalid cron', 'job', data);
+ * } catch (error) {
+ *   if (error instanceof InvalidCronError) {
+ *     console.error('Invalid expression:', error.expression);
+ *   }
+ * }
+ * ```
+ */
+export class InvalidCronError extends MonqueError {
+	constructor(
+		public readonly expression: string,
+		message: string,
+	) {
+		super(message);
+		this.name = 'InvalidCronError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, InvalidCronError);
+		}
+	}
+}
+
+/**
+ * Error thrown when there's a database connection issue.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await monque.enqueue('job', data);
+ * } catch (error) {
+ *   if (error instanceof ConnectionError) {
+ *     console.error('Database connection lost');
+ *   }
+ * }
+ * ```
+ */
+export class ConnectionError extends MonqueError {
+	constructor(message: string, options?: { cause?: Error }) {
+		super(message);
+		this.name = 'ConnectionError';
+		if (options?.cause) {
+			this.cause = options.cause;
+		}
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, ConnectionError);
+		}
+	}
+}
+
+/**
+ * Error thrown when graceful shutdown times out.
+ * Includes information about jobs that were still in progress.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await monque.stop();
+ * } catch (error) {
+ *   if (error instanceof ShutdownTimeoutError) {
+ *     console.error('Incomplete jobs:', error.incompleteJobs.length);
+ *   }
+ * }
+ * ```
+ */
+export class ShutdownTimeoutError extends MonqueError {
+	constructor(
+		message: string,
+		public readonly incompleteJobs: Job[],
+	) {
+		super(message);
+		this.name = 'ShutdownTimeoutError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, ShutdownTimeoutError);
+		}
+	}
+}
+
+/**
+ * Error thrown when attempting to register a worker for a job name
+ * that already has a registered worker, without explicitly allowing replacement.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   monque.register('send-email', handler1);
+ *   monque.register('send-email', handler2); // throws
+ * } catch (error) {
+ *   if (error instanceof WorkerRegistrationError) {
+ *     console.error('Worker already registered for:', error.jobName);
+ *   }
+ * }
+ *
+ * // To intentionally replace a worker:
+ * monque.register('send-email', handler2, { replace: true });
+ * ```
+ */
+export class WorkerRegistrationError extends MonqueError {
+	constructor(
+		message: string,
+		public readonly jobName: string,
+	) {
+		super(message);
+		this.name = 'WorkerRegistrationError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, WorkerRegistrationError);
+		}
+	}
+}
+
+/**
+ * Error thrown when a state transition is invalid.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await monque.cancelJob(jobId);
+ * } catch (error) {
+ *   if (error instanceof JobStateError) {
+ *      console.error(`Cannot cancel job in state: ${error.currentStatus}`);
+ *   }
+ * }
+ * ```
+ */
+export class JobStateError extends MonqueError {
+	constructor(
+		message: string,
+		public readonly jobId: string,
+		public readonly currentStatus: string,
+		public readonly attemptedAction: 'cancel' | 'retry' | 'reschedule',
+	) {
+		super(message);
+		this.name = 'JobStateError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, JobStateError);
+		}
+	}
+}
+
+/**
+ * Error thrown when a pagination cursor is invalid or malformed.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await monque.listJobs({ cursor: 'invalid-cursor' });
+ * } catch (error) {
+ *   if (error instanceof InvalidCursorError) {
+ *     console.error('Invalid cursor provided');
+ *   }
+ * }
+ * ```
+ */
+export class InvalidCursorError extends MonqueError {
+	constructor(message: string) {
+		super(message);
+		this.name = 'InvalidCursorError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, InvalidCursorError);
+		}
+	}
+}
+
+/**
+ * Error thrown when a statistics aggregation times out.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const stats = await monque.getQueueStats();
+ * } catch (error) {
+ *   if (error instanceof AggregationTimeoutError) {
+ *     console.error('Stats took too long to calculate');
+ *   }
+ * }
+ * ```
+ */
+export class AggregationTimeoutError extends MonqueError {
+	constructor(message: string = 'Statistics aggregation exceeded 30 second timeout') {
+		super(message);
+		this.name = 'AggregationTimeoutError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, AggregationTimeoutError);
+		}
+	}
+}

package/src/shared/index.ts

@@ -0,0 +1,18 @@
+export {
+	AggregationTimeoutError,
+	ConnectionError,
+	InvalidCronError,
+	InvalidCursorError,
+	JobStateError,
+	MonqueError,
+	ShutdownTimeoutError,
+	WorkerRegistrationError,
+} from './errors.js';
+export {
+	calculateBackoff,
+	calculateBackoffDelay,
+	DEFAULT_BASE_INTERVAL,
+	DEFAULT_MAX_BACKOFF_DELAY,
+	getNextCronDate,
+	validateCronExpression,
+} from './utils/index.js';