@monque/core 1.3.0 → 1.5.0

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

@@ -16,6 +16,11 @@ import { AggregationTimeoutError, ConnectionError } from '@/shared';
 import { buildSelectorQuery, decodeCursor, encodeCursor } from '../helpers.js';
 import type { SchedulerContext } from './types.js';
 
+interface StatsCacheEntry {
+	data: QueueStats;
+	expiresAt: number;
+}
+
 /**
  * Internal service for job query operations.
  *
@@ -25,6 +30,9 @@ import type { SchedulerContext } from './types.js';
  * @internal Not part of public API - use Monque class methods instead.
  */
 export class JobQueryService {
+	private readonly statsCache = new Map<string, StatsCacheEntry>();
+	private static readonly MAX_CACHE_SIZE = 100;
+
 	constructor(private readonly ctx: SchedulerContext) {}
 
 	/**
@@ -264,12 +272,24 @@ export class JobQueryService {
 		};
 	}
 
+	/**
+	 * Clear all cached getQueueStats() results.
+	 * Called on scheduler stop() for clean state on restart.
+	 * @internal
+	 */
+	clearStatsCache(): void {
+		this.statsCache.clear();
+	}
+
 	/**
 	 * Get aggregate statistics for the job queue.
 	 *
 	 * Uses MongoDB aggregation pipeline for efficient server-side calculation.
 	 * Returns counts per status and optional average processing duration for completed jobs.
 	 *
+	 * Results are cached per unique filter with a configurable TTL (default 5s).
+	 * Set `statsCacheTtlMs: 0` to disable caching.
+	 *
 	 * @param filter - Optional filter to scope statistics by job name
 	 * @returns Promise resolving to queue statistics
 	 * @throws {AggregationTimeoutError} If aggregation exceeds 30 second timeout
@@ -288,6 +308,16 @@ export class JobQueryService {
 	 * ```
 	 */
 	async getQueueStats(filter?: Pick<JobSelector, 'name'>): Promise<QueueStats> {
+		const ttl = this.ctx.options.statsCacheTtlMs;
+		const cacheKey = filter?.name ?? '';
+
+		if (ttl > 0) {
+			const cached = this.statsCache.get(cacheKey);
+			if (cached && cached.expiresAt > Date.now()) {
+				return { ...cached.data };
+			}
+		}
+
 		const matchStage: Document = {};
 
 		if (filter?.name) {
@@ -350,48 +380,63 @@ export class JobQueryService {
 				total: 0,
 			};
 
-			if (!result) {
-				return stats;
-			}
+			if (result) {
+				// Map status counts to stats
+				const statusCounts = result['statusCounts'] as Array<{ _id: string; count: number }>;
+				for (const entry of statusCounts) {
+					const status = entry._id;
+					const count = entry.count;
+
+					switch (status) {
+						case JobStatus.PENDING:
+							stats.pending = count;
+							break;
+						case JobStatus.PROCESSING:
+							stats.processing = count;
+							break;
+						case JobStatus.COMPLETED:
+							stats.completed = count;
+							break;
+						case JobStatus.FAILED:
+							stats.failed = count;
+							break;
+						case JobStatus.CANCELLED:
+							stats.cancelled = count;
+							break;
+					}
+				}
 
-			// Map status counts to stats
-			const statusCounts = result['statusCounts'] as Array<{ _id: string; count: number }>;
-			for (const entry of statusCounts) {
-				const status = entry._id;
-				const count = entry.count;
-
-				switch (status) {
-					case JobStatus.PENDING:
-						stats.pending = count;
-						break;
-					case JobStatus.PROCESSING:
-						stats.processing = count;
-						break;
-					case JobStatus.COMPLETED:
-						stats.completed = count;
-						break;
-					case JobStatus.FAILED:
-						stats.failed = count;
-						break;
-					case JobStatus.CANCELLED:
-						stats.cancelled = count;
-						break;
+				// Extract total
+				const totalResult = result['total'] as Array<{ count: number }>;
+				if (totalResult.length > 0 && totalResult[0]) {
+					stats.total = totalResult[0].count;
 				}
-			}
 
-			// Extract total
-			const totalResult = result['total'] as Array<{ count: number }>;
-			if (totalResult.length > 0 && totalResult[0]) {
-				stats.total = totalResult[0].count;
+				// Extract average processing duration
+				const avgDurationResult = result['avgDuration'] as Array<{ avgMs: number }>;
+				if (avgDurationResult.length > 0 && avgDurationResult[0]) {
+					const avgMs = avgDurationResult[0].avgMs;
+					if (typeof avgMs === 'number' && !Number.isNaN(avgMs)) {
+						stats.avgProcessingDurationMs = Math.round(avgMs);
+					}
+				}
 			}
 
-			// Extract average processing duration
-			const avgDurationResult = result['avgDuration'] as Array<{ avgMs: number }>;
-			if (avgDurationResult.length > 0 && avgDurationResult[0]) {
-				const avgMs = avgDurationResult[0].avgMs;
-				if (typeof avgMs === 'number' && !Number.isNaN(avgMs)) {
-					stats.avgProcessingDurationMs = Math.round(avgMs);
+			// Cache the result if TTL is enabled
+			if (ttl > 0) {
+				// Delete existing entry first so re-insertion moves it to end (Map insertion order = LRU)
+				this.statsCache.delete(cacheKey);
+				// LRU eviction: if cache is still full after removing existing key, evict the oldest entry
+				if (this.statsCache.size >= JobQueryService.MAX_CACHE_SIZE) {
+					const oldestKey = this.statsCache.keys().next().value;
+					if (oldestKey !== undefined) {
+						this.statsCache.delete(oldestKey);
+					}
 				}
+				this.statsCache.set(cacheKey, {
+					data: { ...stats },
+					expiresAt: Date.now() + ttl,
+				});
 			}
 
 			return stats;

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

@@ -1,4 +1,4 @@
-import type { Document } from 'mongodb';
+import { BSON, type Document } from 'mongodb';
 
 import {
 	type EnqueueOptions,
@@ -7,7 +7,7 @@ import {
 	type PersistedJob,
 	type ScheduleOptions,
 } from '@/jobs';
-import { ConnectionError, getNextCronDate, MonqueError } from '@/shared';
+import { ConnectionError, getNextCronDate, MonqueError, PayloadTooLargeError } from '@/shared';
 
 import type { SchedulerContext } from './types.js';
 
@@ -22,6 +22,41 @@ import type { SchedulerContext } from './types.js';
 export class JobScheduler {
 	constructor(private readonly ctx: SchedulerContext) {}
 
+	/**
+	 * Validate that the job data payload does not exceed the configured maximum BSON byte size.
+	 *
+	 * @param data - The job data payload to validate
+	 * @throws {PayloadTooLargeError} If the payload exceeds `maxPayloadSize`
+	 */
+	private validatePayloadSize(data: unknown): void {
+		const maxSize = this.ctx.options.maxPayloadSize;
+		if (maxSize === undefined) {
+			return;
+		}
+
+		let size: number;
+		try {
+			size = BSON.calculateObjectSize({ data } as Document);
+		} catch (error) {
+			const cause = error instanceof Error ? error : new Error(String(error));
+			const sizeError = new PayloadTooLargeError(
+				`Failed to calculate job payload size: ${cause.message}`,
+				-1,
+				maxSize,
+			);
+			sizeError.cause = cause;
+			throw sizeError;
+		}
+
+		if (size > maxSize) {
+			throw new PayloadTooLargeError(
+				`Job payload exceeds maximum size: ${size} bytes > ${maxSize} bytes`,
+				size,
+				maxSize,
+			);
+		}
+	}
+
 	/**
 	 * Enqueue a job for processing.
 	 *
@@ -40,6 +75,7 @@ export class JobScheduler {
 	 * @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
+	 * @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
 	 *
 	 * @example Basic job enqueueing
 	 * ```typescript
@@ -67,6 +103,7 @@ export class JobScheduler {
 	 * ```
 	 */
 	async enqueue<T>(name: string, data: T, options: EnqueueOptions = {}): Promise<PersistedJob<T>> {
+		this.validatePayloadSize(data);
 		const now = new Date();
 		const job: Omit<Job<T>, '_id'> = {
 			name,
@@ -174,6 +211,7 @@ export class JobScheduler {
 	 * @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
+	 * @throws {PayloadTooLargeError} If payload exceeds configured `maxPayloadSize`
 	 *
 	 * @example Hourly cleanup job
 	 * ```typescript
@@ -204,6 +242,8 @@ export class JobScheduler {
 		data: T,
 		options: ScheduleOptions = {},
 	): Promise<PersistedJob<T>> {
+		this.validatePayloadSize(data);
+
 		// Validate cron and get next run date (throws InvalidCronError if invalid)
 		const nextRunAt = getNextCronDate(cron);
 

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

@@ -0,0 +1,154 @@
+import type { DeleteResult } from 'mongodb';
+
+import { JobStatus } from '@/jobs';
+import { toError } from '@/shared';
+
+import type { SchedulerContext } from './types.js';
+
+/**
+ * Default retention check interval (1 hour).
+ */
+const DEFAULT_RETENTION_INTERVAL = 3600_000;
+
+/**
+ * Callbacks for timer-driven operations.
+ *
+ * These are provided by the Monque facade to wire LifecycleManager's timers
+ * to JobProcessor methods without creating a direct dependency.
+ */
+interface TimerCallbacks {
+	/** Poll for pending jobs */
+	poll: () => Promise<void>;
+	/** Update heartbeats for claimed jobs */
+	updateHeartbeats: () => Promise<void>;
+}
+
+/**
+ * Manages scheduler lifecycle timers and job cleanup.
+ *
+ * Owns poll interval, heartbeat interval, cleanup interval, and the
+ * cleanupJobs logic. Extracted from Monque to keep the facade thin.
+ *
+ * @internal Not part of public API.
+ */
+export class LifecycleManager {
+	private readonly ctx: SchedulerContext;
+	private pollIntervalId: ReturnType<typeof setInterval> | null = null;
+	private heartbeatIntervalId: ReturnType<typeof setInterval> | null = null;
+	private cleanupIntervalId: ReturnType<typeof setInterval> | null = null;
+
+	constructor(ctx: SchedulerContext) {
+		this.ctx = ctx;
+	}
+
+	/**
+	 * Start all lifecycle timers.
+	 *
+	 * Sets up poll interval, 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);
+
+		// Start heartbeat interval for claimed jobs
+		this.heartbeatIntervalId = setInterval(() => {
+			callbacks.updateHeartbeats().catch((error: unknown) => {
+				this.ctx.emit('job:error', { error: toError(error) });
+			});
+		}, this.ctx.options.heartbeatInterval);
+
+		// Start cleanup interval if retention is configured
+		if (this.ctx.options.jobRetention) {
+			const interval = this.ctx.options.jobRetention.interval ?? DEFAULT_RETENTION_INTERVAL;
+
+			// Run immediately on start
+			this.cleanupJobs().catch((error: unknown) => {
+				this.ctx.emit('job:error', { error: toError(error) });
+			});
+
+			this.cleanupIntervalId = setInterval(() => {
+				this.cleanupJobs().catch((error: unknown) => {
+					this.ctx.emit('job:error', { error: toError(error) });
+				});
+			}, interval);
+		}
+
+		// Run initial poll immediately to pick up any existing jobs
+		callbacks.poll().catch((error: unknown) => {
+			this.ctx.emit('job:error', { error: toError(error) });
+		});
+	}
+
+	/**
+	 * Stop all lifecycle timers.
+	 *
+	 * Clears poll, heartbeat, and cleanup intervals.
+	 */
+	stopTimers(): void {
+		if (this.cleanupIntervalId) {
+			clearInterval(this.cleanupIntervalId);
+			this.cleanupIntervalId = null;
+		}
+
+		if (this.pollIntervalId) {
+			clearInterval(this.pollIntervalId);
+			this.pollIntervalId = null;
+		}
+
+		if (this.heartbeatIntervalId) {
+			clearInterval(this.heartbeatIntervalId);
+			this.heartbeatIntervalId = null;
+		}
+	}
+
+	/**
+	 * Clean up old completed and failed jobs based on retention policy.
+	 *
+	 * - Removes completed jobs older than `jobRetention.completed`
+	 * - Removes failed jobs older than `jobRetention.failed`
+	 *
+	 * The cleanup runs concurrently for both statuses if configured.
+	 *
+	 * @returns Promise resolving when all deletion operations complete
+	 */
+	async cleanupJobs(): Promise<void> {
+		if (!this.ctx.options.jobRetention) {
+			return;
+		}
+
+		const { completed, failed } = this.ctx.options.jobRetention;
+		const now = Date.now();
+		const deletions: Promise<DeleteResult>[] = [];
+
+		if (completed != null) {
+			const cutoff = new Date(now - completed);
+			deletions.push(
+				this.ctx.collection.deleteMany({
+					status: JobStatus.COMPLETED,
+					updatedAt: { $lt: cutoff },
+				}),
+			);
+		}
+
+		if (failed != null) {
+			const cutoff = new Date(now - failed);
+			deletions.push(
+				this.ctx.collection.deleteMany({
+					status: JobStatus.FAILED,
+					updatedAt: { $lt: cutoff },
+				}),
+			);
+		}
+
+		if (deletions.length > 0) {
+			await Promise.all(deletions);
+		}
+	}
+}

package/src/scheduler/services/types.ts

@@ -19,11 +19,15 @@ export interface ResolvedMonqueOptions
 				| 'maxBackoffDelay'
 				| 'jobRetention'
 				| 'instanceConcurrency'
+				| 'maxPayloadSize'
 				| 'defaultConcurrency'
 				| 'maxConcurrency'
 			>
 		>,
-		Pick<MonqueOptions, 'maxBackoffDelay' | 'jobRetention' | 'instanceConcurrency'> {
+		Pick<
+			MonqueOptions,
+			'maxBackoffDelay' | 'jobRetention' | 'instanceConcurrency' | 'maxPayloadSize'
+		> {
 	// Ensure resolved options use the new naming convention
 	workerConcurrency: number;
 }

package/src/scheduler/types.ts

@@ -162,4 +162,38 @@ export interface MonqueOptions {
 	 * @deprecated Use `instanceConcurrency` instead. Will be removed in a future major version.
 	 */
 	maxConcurrency?: number | undefined;
+
+	/**
+	 * Skip automatic index creation during initialization.
+	 *
+	 * When `true`, `initialize()` will not create MongoDB indexes. Use this in production
+	 * environments where indexes are managed externally (e.g., via migration scripts or DBA
+	 * tooling). See the production checklist for the full list of required indexes.
+	 *
+	 * @default false
+	 */
+	skipIndexCreation?: boolean;
+
+	/**
+	 * Maximum allowed BSON byte size for job data payloads.
+	 *
+	 * When set, `enqueue()`, `now()`, and `schedule()` validate the payload size
+	 * using `BSON.calculateObjectSize()` before insertion. Jobs exceeding this limit
+	 * throw `PayloadTooLargeError`.
+	 *
+	 * When undefined, no size validation occurs.
+	 */
+	maxPayloadSize?: number | undefined;
+
+	/**
+	 * TTL in milliseconds for getQueueStats() result caching.
+	 *
+	 * When set to a positive value, repeated getQueueStats() calls with the same
+	 * filter return cached results instead of re-executing the aggregation pipeline.
+	 * Each unique filter (job name) maintains its own cache entry.
+	 *
+	 * Set to 0 to disable caching entirely.
+	 * @default 5000
+	 */
+	statsCacheTtlMs?: number;
 }

package/src/shared/errors.ts

@@ -223,3 +223,34 @@ export class AggregationTimeoutError extends MonqueError {
 		}
 	}
 }
+
+/**
+ * Error thrown when a job payload exceeds the configured maximum BSON byte size.
+ *
+ * @example
+ * ```typescript
+ * const monque = new Monque(db, { maxPayloadSize: 1_000_000 }); // 1 MB
+ *
+ * try {
+ *   await monque.enqueue('job', hugePayload);
+ * } catch (error) {
+ *   if (error instanceof PayloadTooLargeError) {
+ *     console.error(`Payload ${error.actualSize} bytes exceeds limit ${error.maxSize} bytes`);
+ *   }
+ * }
+ * ```
+ */
+export class PayloadTooLargeError extends MonqueError {
+	constructor(
+		message: string,
+		public readonly actualSize: number,
+		public readonly maxSize: number,
+	) {
+		super(message);
+		this.name = 'PayloadTooLargeError';
+		/* istanbul ignore next -- @preserve captureStackTrace is always available in Node.js */
+		if (Error.captureStackTrace) {
+			Error.captureStackTrace(this, PayloadTooLargeError);
+		}
+	}
+}

package/src/shared/index.ts

@@ -5,6 +5,7 @@ export {
 	InvalidCursorError,
 	JobStateError,
 	MonqueError,
+	PayloadTooLargeError,
 	ShutdownTimeoutError,
 	WorkerRegistrationError,
 } from './errors.js';
@@ -14,5 +15,6 @@ export {
 	DEFAULT_BASE_INTERVAL,
 	DEFAULT_MAX_BACKOFF_DELAY,
 	getNextCronDate,
+	toError,
 	validateCronExpression,
 } from './utils/index.js';

package/src/shared/utils/error.ts

@@ -0,0 +1,33 @@
+/**
+ * Normalize an unknown caught value into a proper `Error` instance.
+ *
+ * In JavaScript, any value can be thrown — strings, numbers, objects, `undefined`, etc.
+ * This function ensures we always have a real `Error` with a proper stack trace and message.
+ *
+ * @param value - The caught value (typically from a `catch` block typed as `unknown`).
+ * @returns The original value if already an `Error`, otherwise a new `Error` wrapping `String(value)`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   riskyOperation();
+ * } catch (error: unknown) {
+ *   const normalized = toError(error);
+ *   console.error(normalized.message);
+ * }
+ * ```
+ *
+ * @internal
+ */
+export function toError(value: unknown): Error {
+	if (value instanceof Error) return value;
+
+	try {
+		return new Error(String(value));
+	} catch (conversionError: unknown) {
+		const detail =
+			conversionError instanceof Error ? conversionError.message : 'unknown conversion failure';
+
+		return new Error(`Unserializable value (${detail})`);
+	}
+}

package/src/shared/utils/index.ts

@@ -5,3 +5,4 @@ export {
 	DEFAULT_MAX_BACKOFF_DELAY,
 } from './backoff.js';
 export { getNextCronDate, validateCronExpression } from './cron.js';
+export { toError } from './error.js';